인스턴스 속성 업데이트

Google Cloud CLI 또는 Compute Engine API에서 단일 요청을 사용하여 여러 인스턴스 속성을 업데이트하고 필요한 경우 인스턴스를 다시 시작할 수 있습니다. update 메서드는 업데이트된 인스턴스 속성을 검증하는 로직을 처리하고 업데이트를 성공적으로 완료하는 데 필요한 리소스를 사용할 수 있는지 확인합니다. 요청에 잘못된 속성이 포함되어 있거나 요청된 리소스를 사용할 수 없는 경우 요청은 오류를 반환하고 인스턴스를 변경하지 않습니다. 그러면 인스턴스가 부분적 업데이트로부터 보호되며, 인스턴스가 중지되고 다시 시작하기 위해 리소스에 액세스할 수 없게 되는 상황을 방지할 수 있습니다.

시작하기 전에

  • 아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인하는 프로세스입니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음과 같이 Compute Engine에 인증하면 됩니다.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공하는 사용자 인증 정보를 사용합니다.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      자세한 내용은 Google Cloud 인증 문서의 REST 사용 인증을 참조하세요.

제한사항

  • gcloud CLI 또는 Compute Engine API를 통한 인스턴스 업데이트 요청은 PATCH 시맨틱스를 지원하지 않습니다. 업데이트 요청의 인스턴스 리소스에는 인스턴스의 모든 속성이 포함되어야 합니다. 업데이트 요청의 인스턴스 구성에서 누락된 속성은 인스턴스에서 삭제된 것으로 간주됩니다.
  • 특정 속성 목록만 업데이트할 수 있습니다.
  • 인스턴스를 단독 테넌시로 변경하거나 단독 테넌시를 인스턴스로 변경할 수는 없습니다.
  • 한 예약에서 다른 예약으로 인스턴스를 변경할 수는 있지만 업데이트 프로세스를 사용하여 인스턴스를 예약과 연결하거나 분리할 수는 없습니다.
  • 인스턴스에 로컬 SSD가 연결되어 있는 경우 인스턴스를 다시 시작해야 하는 속성 업데이트는 불가능합니다. 인스턴스를 삭제한 후 다시 만들어야 합니다. VM을 삭제하기 전에 중요한 데이터를 로컬 SSD에서 영구 디스크나 다른 VM으로 마이그레이션해야 합니다.
  • 인스턴스가 베타 Compute Engine API에서만 사용할 수 있는 리소스를 사용하는 경우 올바른 버전의 instances.update 메서드를 사용하여 이러한 속성을 업데이트해야 합니다. 예를 들어 베타 Compute Engine API를 사용하여 인스턴스를 만들고 베타 API만 인식할 수 있는 리소스로 인스턴스를 구성하는 경우에도 instances.update 메서드의 베타 버전을 사용하여 이러한 리소스를 업데이트해야 합니다. instances.update 메서드의 v1 버전은 인스턴스가 사용하는 베타 리소스를 인식하지 못하므로 업데이트 프로세스 중에 이러한 베타 리소스를 인스턴스 구성에서 삭제합니다. 이는 알파 API의 리소스에도 적용됩니다.

권한

인스턴스를 업데이트하려면 compute.instances.update 권한이 있어야 합니다. 이 권한은 여러 기존 Identity and Access Management(IAM) 역할에 포함되어 있습니다. 또한 인스턴스에서 수정하려는 리소스를 사용할 수 있는 권한이 있어야 합니다. 예를 들어 인스턴스에 디스크를 추가하려면 다음 권한이 있어야 합니다.

  • 업데이트할 인스턴스에 대한 compute.instances.update 권한.
  • 기존 디스크에 대한 compute.disks.use 권한 또는 새 디스크를 만들려는 프로젝트에 대한 compute.disks.create 권한.

권장사항

인스턴스 업데이트 인터페이스를 가장 효과적으로 사용하려면 다음 권장사항을 따르세요.

  • 가능하면 같은 버전의 Compute Engine API를 일관되게 사용하여 인스턴스를 생성, 설정, 업데이트합니다. 이렇게 하면 한 가지 버전의 API에서만 사용할 수 있는 인스턴스 리소스를 업데이트하고 수정할 수 있습니다.
  • instances.update 메서드를 사용하여 관리형 인스턴스 그룹(MIG)의 인스턴스를 업데이트할 수도 있지만 대부분의 상황에서는 그룹의 인스턴스 템플릿을 변경하고 해당 업데이트를 MIG에 롤아웃하는 것이 좋습니다.

업데이트할 수 있는 속성

update 메서드를 통해 특정 인스턴스 속성 집합만 변경할 수 있습니다. 일부 속성을 업데이트하려면 인스턴스를 다시 시작해야 합니다. 인스턴스에서 실수로 다시 시작되는 것을 방지하려면 인스턴스에서 수행할 수 있는 작업을 요청에 정의해야 합니다. 요청에 다음 작업 중 하나를 지정할 수 있습니다.

  • NO_EFFECT: 업데이트 요청은 요청이 유효하고 리소스가 사용 가능한지 확인하지만 업데이트를 실행하지는 않습니다. 실제 업데이트를 시작하지 않고 명령어를 테스트하려면 이 명령어를 사용하세요.
  • REFRESH: 수정된 인스턴스 속성이 인스턴스 다시 시작을 필요로 하지 않는 경우에만 업데이트 요청이 실행됩니다. 요청이 유효하지만 다시 시작이 필요한 경우 INFEASIBLE 오류가 반환됩니다.
  • RESTART: 업데이트하려면 인스턴스를 다시 시작해야 하는 경우 인스턴스가 다시 시작됩니다.

업데이트하려면 RESTART가 필요한 속성:

  • reservationAffinity
  • disks - 부팅 디스크
    • disks.deviceName - 모든 디스크
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

업데이트에 REFRESH만 필요한 속성:

  • canIpForward
  • deletionProtection
  • description
  • disks - 비부팅 디스크 속성(deviceName 제외)
  • labels
  • metadata
  • nodeAffinities
  • tags

인스턴스 속성 업데이트

다음 단계에 따라 인스턴스를 업데이트합니다.

  1. 기존 인스턴스 구성 속성을 내보냅니다.
  2. 인스턴스 구성의 속성을 수정합니다.
  3. NO_EFFECT를 중단을 가장 많이 유발하는 작업으로 지정하여 테스트 요청을 실행합니다. 인스턴스 구성의 잘못된 필드와 변경사항을 적용하는 데 필요한 작업이 응답에 표시됩니다.
  4. 구성이 허용되는 경우 인스턴스 업데이트를 요청하고 인스턴스 업데이트에서 허용되는 가장 많이 중단을 유발하는 작업을 지정합니다.

요청이 다음 요구사항을 충족하는 경우에만 업데이트 프로세스가 시작됩니다.

  • 요청의 인스턴스 fingerprint 속성이 업데이트할 인스턴스의 fingerprint와 일치해야 합니다. 이렇게 하면 동일한 인스턴스의 동시 업데이트 요청이 서로 덮어쓰기되지 않습니다.
  • 업데이트 요청의 속성이 유효해야 합니다.
  • 요청한 리소스를 사용할 수 있어야 합니다.
  • 요청의 속성이 인스턴스 다시 시작을 필요로 하는 경우 요청에 RESTART를 허용되는 작업으로 지정해야 합니다.

요구사항이 충족되면 인스턴스 업데이트 프로세스가 시작됩니다. 그렇지 않으면 기존 인스턴스나 구성이 변경되지 않습니다.

gcloud CLI 또는 Compute Engine API를 사용하여 업데이트를 시작할 수 있습니다.

gcloud

  1. instances export 명령어를 사용하여 기존 인스턴스 속성을 내보냅니다.

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    다음을 바꿉니다.

    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.
    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • FILE_PATH: 로컬 워크스테이션에 인스턴스 구성 파일을 저장할 출력 경로입니다.

  2. 내보낸 인스턴스 구성 파일에서 하나 이상의 속성을 수정하려면 텍스트 편집기를 사용합니다. 업데이트할 수 있는 속성은 업데이트 가능한 속성 목록을 참조하세요. 예를 들어 인스턴스의 머신 유형을 변경하려면 machineType 속성을 변경합니다.

    ⋮
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
⋮

    다음을 바꿉니다.

    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • MACHINE_TYPE: 인스턴스의 머신 유형입니다. 예를 들면 n1-standard-2입니다.

  3. instances update-from-file 명령어를 사용하여 대상 인스턴스의 테스트 업데이트를 실행합니다. --most-disruptive-allowed-action=NO_EFFECT 플래그를 지정합니다. 응답은 잘못 구성된 속성을 식별하고 업데이트를 적용하려면 RESTART 또는 REFRESH 작업이 필요한지 여부를 표시합니다.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    다음을 바꿉니다.

    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.
    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • FILE_PATH: 로컬 워크스테이션의 수정된 인스턴스 구성 파일 경로입니다.

  4. instances update-from-file 명령어를 사용하여 대상 인스턴스를 업데이트합니다. 인스턴스를 다시 시작해야 하는 속성을 업데이트하는 경우 --most-disruptive-allowed-action=RESTART 플래그를 포함합니다. 다시 시작할 필요가 없는 속성의 경우 --most-disruptive-allowed-action=REFRESH 플래그를 지정합니다. 다시 시작이 필요한 속성은 업데이트 가능한 속성 목록을 참조하세요.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    다음을 바꿉니다.

    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.
    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • FILE_PATH: 로컬 워크스테이션의 수정된 인스턴스 구성 파일 경로입니다.
    • ALLOWED_ACTION: 업데이트가 중단을 얼마나 유발할 수 있는지 정의합니다. 인스턴스가 완전히 다시 시작되도록 하려면 RESTART를 지정합니다. 수정된 속성이 인스턴스 다시 시작을 필요로 하지 않는 경우에만 REFRESH를 사용하여 인스턴스를 업데이트하세요.

업데이트 요청이 유효하고 필요한 리소스를 사용할 수 있는 경우 인스턴스 업데이트 프로세스가 시작됩니다. 감사 로그를 확인하여 이 작업의 상태를 모니터링할 수 있습니다. 업데이트에 다시 시작이 필요하고 명령어에서 RESTART를 허용하는 경우 인스턴스가 다시 시작되고 변경사항이 적용됩니다.

REST

  1. Compute Engine API의 instances.get 메서드를 사용하여 기존 인스턴스 속성을 내보냅니다.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    다음을 바꿉니다.

    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.

    이 요청은 인스턴스 리소스 정의를 반환합니다.

  2. 응답에서 인스턴스 리소스 속성을 수정합니다. 업데이트할 수 있는 속성은 업데이트 가능한 속성 목록을 참조하세요. 예를 들어 인스턴스의 머신 유형을 변경하려면 machineType 속성을 변경합니다. 여러 속성을 변경할 수 있습니다.

    {
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ⋮
}

    다음을 바꿉니다.

    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • MACHINE_TYPE: 인스턴스의 머신 유형입니다. 예를 들면 n1-standard-2입니다.

  3. Compute Engine API의 instances.update 메서드를 사용하고 most_disruptive_allowed_action=NO_EFFECT를 지정하여 대상 인스턴스의 테스트 업데이트를 실행합니다. 응답은 잘못 구성된 속성을 식별하고 업데이트를 적용하려면 RESTART 또는 REFRESH 작업이 필요한지 표시합니다.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    다음을 바꿉니다.

    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.

  4. Compute Engine API의 instances.update 메서드를 사용하여 대상 인스턴스를 업데이트합니다. 인스턴스 다시 시작이 필요한 속성을 업데이트하는 경우 업데이트 도중 인스턴스가 다시 시작될 수 있음을 나타내기 위해 ?most_disruptive_allowed_action=RESTART 쿼리 매개변수를 포함합니다. 다시 시작이 필요 없는 속성의 경우 ?most_disruptive_allowed_action=REFRESH 쿼리 매개변수를 지정합니다. 다시 시작이 필요한 속성은 업데이트 가능한 속성 목록을 참조하세요. 수정한 인스턴스 리소스의 전체 본문을 포함하세요. 다음 예시의 본문은 머신 유형을 n1-standard-2로 변경합니다.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    다음을 바꿉니다.

    • PROJECT_ID: 이 요청의 프로젝트 ID입니다.
    • ZONE: 이 인스턴스의 영역입니다.
    • INSTANCE_NAME: 내보낼 인스턴스의 이름입니다.
    • ALLOWED_ACTION: 업데이트가 중단을 얼마나 유발할 수 있는지 정의합니다. 인스턴스가 완전히 다시 시작되도록 하려면 RESTART를 지정합니다. 수정된 속성이 인스턴스 다시 시작을 필요로 하지 않는 경우에만 REFRESH를 사용하여 인스턴스를 업데이트하세요.

업데이트 요청이 유효하고 필요한 리소스를 사용할 수 있는 경우 인스턴스 업데이트 프로세스가 시작됩니다. 감사 로그를 확인하여 이 작업의 상태를 모니터링할 수 있습니다. 업데이트에 다시 시작이 필요하고 명령어에서 RESTART를 허용하는 경우 인스턴스가 다시 시작되고 변경사항이 적용됩니다.

다음 단계