Azure Metadata 서비스: Windows VM의 예약된 이벤트Azure Metadata Service: Scheduled Events for Windows VMs

예약된 이벤트는 애플리케이션이 가상 머신 유지 관리를 준비할 시간을 부여하는 Azure 메타데이터 서비스입니다.Scheduled Events is an Azure Metadata Service that gives your application time to prepare for virtual machine maintenance. 향후 유지 관리 이벤트(예: 재부팅)에 대한 정보를 제공하여 애플리케이션이 이에 대비하고 서비스 중단을 제한할 수 있도록 합니다.It provides information about upcoming maintenance events (e.g. reboot) so your application can prepare for them and limit disruption. 이 기능은 Windows와 Linux 모두에서 PaaS 및 IaaS를 포함한 모든 Azure Virtual Machine 유형에 사용할 수 있습니다.It is available for all Azure Virtual Machine types including PaaS and IaaS on both Windows and Linux.

Linux에서 예약된 이벤트에 대한 자세한 내용은 Linux VM에 예약된 이벤트를 참조하세요.For information about Scheduled Events on Linux, see Scheduled Events for Linux VMs.

참고

예약된 이벤트는 모든 Azure 지역에서 일반 공급됩니다.Scheduled Events is generally available in all Azure Regions. 최신 릴리스 정보는 버전 및 지역 가용성을 참조하세요.See Version and Region Availability for latest release information.

예정된 이벤트 의의Why Scheduled Events?

많은 애플리케이션에서 가상 머신 유지 관리를 준비하는 시간을 활용할 수 있습니다.Many applications can benefit from time to prepare for virtual machine maintenance. 이 시간은 가용성, 안정성 및 서비스 가능성을 향상시키는 다음을 비롯한 특정 애플리케이션 작업을 수행하는 데 사용할 수 있습니다.The time can be used to perform application specific tasks that improve availability, reliability, and serviceability including:

  • 검사점 및 복원Checkpoint and restore
  • 연결 드레이닝Connection draining
  • 주 복제본 장애 조치(failover)Primary replica failover
  • 부하 분산 장치 풀에서 제거Removal from load balancer pool
  • 이벤트 로깅Event logging
  • 정상 종료Graceful shutdown

예약된 이벤트를 사용하면 애플리케이션에서 유지 관리가 발생하는 시간을 검색하고 이로 인한 영향을 제한하는 작업을 트리거할 수 있습니다.Using Scheduled Events your application can discover when maintenance will occur and trigger tasks to limit its impact. 예약된 이벤트를 사용하면 유지 관리 작업을 수행하기 전에 가상 머신에게 최소 시간을 부여할 수 있습니다.Enabling scheduled events gives your virtual machine a minimum amount of time before the maintenance activity is performed. 자세한 내용은 아래 이벤트 예약 섹션을 참조하세요.See the Event Scheduling section below for details.

예약된 이벤트는 다음과 같은 경우에 이벤트를 제공합니다.Scheduled Events provides events in the following use cases:

기본 사항The Basics

Azure 메타데이터 서비스는 VM 내에서 액세스할 수 있는 REST 엔드포인트를 사용하여 Virtual Machines 실행에 대한 정보를 공개합니다.Azure Metadata service exposes information about running Virtual Machines using a REST Endpoint accessible from within the VM. 이 정보는 라우팅할 수 없는 IP를 통해 사용할 수 있으므로 VM 외부에 공개되지 않습니다.The information is available via a non-routable IP so that it is not exposed outside the VM.

엔드포인트 검색Endpoint Discovery

VNET 사용 VM의 경우 메타데이터 서비스를 정적 경로 조정 불가능 IP 169.254.169.254에서 사용할 수 있습니다.For VNET enabled VMs, the metadata service is available from a static non-routable IP, 169.254.169.254. 예약된 이벤트의 최신 버전에 대한 전체 엔드포인트는 다음과 같습니다.The full endpoint for the latest version of Scheduled Events is:

http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01

클라우드 서비스 및 클래식 VM의 기본 사례처럼 Virtual Machine이 Virtual Network에 생성되지 않은 경우 사용할 IP 주소를 검색하려면 추가 논리가 필요합니다.If the Virtual Machine is not created within a Virtual Network, the default cases for cloud services and classic VMs, additional logic is required to discover the IP address to use. 호스트 엔드포인트를 검색하는 방법은 이 샘플을 참조하세요.Refer to this sample to learn how to discover the host endpoint.

버전 및 지역 가용성Version and Region Availability

예약된 이벤트 서비스의 버전이 지정됩니다.The Scheduled Events Service is versioned. 버전은 필수이며 최신 버전은 2017-11-01입니다.Versions are mandatory and the current version is 2017-11-01.

버전Version 릴리스 종류Release Type 영역Regions 릴리스 정보Release Notes
2017-11-012017-11-01 일반 공급General Availability 모두All
  • 우선 순위가 낮은 VM 제거 EventType 'Preempt'에 대 한 지원 추가Added support for Low-priority VM eviction EventType 'Preempt'
  • 2017-08-012017-08-01 일반 공급General Availability 모두All
  • IaaS VM의 리소스 이름에서 앞에 붙은 밑줄이 제거됨Removed prepended underscore from resource names for IaaS VMs
  • 모든 요청에 대해 메타데이터 헤더 요구 사항이 적용됨Metadata Header requirement enforced for all requests
  • 2017-03-012017-03-01 PreviewPreview 모두All
  • 최초 릴리스Initial release
  • 참고

    예약된 이벤트의 이전 미리 보기 릴리스는 api-version으로 {최신 버전}을 지원했습니다.Previous preview releases of scheduled events supported {latest} as the api-version. 이 형식은 더 이상 지원되지 않으며 향후 사용되지 않을 예정입니다.This format is no longer supported and will be deprecated in the future.

    예약된 이벤트 사용 및 사용 안 함Enabling and Disabling Scheduled Events

    예약된 이벤트는 이벤트에 대한 요청을 처음 수행하는 서비스에 대해 사용할 수 있습니다.Scheduled Events is enabled for your service the first time you make a request for events. 최대 2분인 첫 번째 호출에서 지연된 응답을 예상해야 합니다.You should expect a delayed response in your first call of up to two minutes. 향후의 유지 관리 이벤트와, 수행 중인 유지 관리 작업의 상태를 확인하기 위해 주기적으로 엔드포인트를 쿼리해야 합니다.You should query the endpoint periodically to detect upcoming maintenance events as well as the status of maintenance activities that are being performed.

    24시간 동안 요청을 수행하지 않으면 예약된 이벤트를 서비스에 사용할 수 없습니다.Scheduled Events is disabled for your service if it does not make a request for 24 hours.

    사용자 시작 유지 관리User Initiated Maintenance

    사용자가 예정된 이벤트에서 Azure Portal, API, CLI 또는 PowerShell을 통해 가상 머신 유지 관리를 시작했습니다.User initiated virtual machine maintenance via the Azure portal, API, CLI, or PowerShell results in a scheduled event. 그러면 애플리케이션의 유지 관리 준비 논리를 테스트할 수 있으며, 애플리케이션에서 사용자 시작 유지 관리를 준비할 수 있습니다.This allows you to test the maintenance preparation logic in your application and allows your application to prepare for user initiated maintenance.

    가상 머신을 다시 시작하면 Reboot 유형의 이벤트가 예약됩니다.Restarting a virtual machine schedules an event with type Reboot. 가상 머신을 다시 배포하면 Redeploy 유형의 이벤트가 예약됩니다.Redeploying a virtual machine schedules an event with type Redeploy.

    API 사용Using the API

    헤더Headers

    메타데이터 서비스를 쿼리할 때 요청이 실수로 리디렉션되지 않도록 Metadata:true 헤더를 제공해야 합니다.When you query the Metadata Service, you must provide the header Metadata:true to ensure the request was not unintentionally redirected. Metadata:true 헤더는 모든 예약된 이벤트 요청에 필요합니다.The Metadata:true header is required for all scheduled events requests. 헤더를 요청에 포함하지 않으면 메타데이터 서비스에서 잘못된 요청 응답이 발생합니다.Failure to include the header in the request will result in a Bad Request response from the Metadata Service.

    이벤트 쿼리Query for events

    다음과 같이 호출하여 예약된 이벤트를 쿼리할 수 있습니다.You can query for Scheduled Events simply by making the following call:

    PowerShellPowershell

    curl http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01 -H @{"Metadata"="true"}
    

    응답에는 예약된 이벤트의 배열이 포함됩니다.A response contains an array of scheduled events. 빈 배열은 현재 예약된 이벤트가 없음을 의미합니다.An empty array means that there are currently no events scheduled. 예약된 이벤트가 있는 경우 응답에 다음과 같은 이벤트의 배열이 포함됩니다.In the case where there are scheduled events, the response contains an array of events:

    {
        "DocumentIncarnation": {IncarnationID},
        "Events": [
            {
                "EventId": {eventID},
                "EventType": "Reboot" | "Redeploy" | "Freeze" | "Preempt",
                "ResourceType": "VirtualMachine",
                "Resources": [{resourceName}],
                "EventStatus": "Scheduled" | "Started",
                "NotBefore": {timeInUTC},
            }
        ]
    }
    

    DocumentIncarnation은 ETag로, 이벤트 페이로드가 지난 번 쿼리 후 변경되었는지 검사하는 간편한 방법을 제공합니다.The DocumentIncarnation is an ETag and provides an easy way to inspect if the Events payload has changed since the last query.

    이벤트 속성Event Properties

    속성Property DescriptionDescription
    EventIdEventId 이 이벤트의 GUID(Globally Unique Identifier)입니다.Globally unique identifier for this event.

    예제:Example:
    • 602d9444-d2cd-49c7-8624-8643e7171297602d9444-d2cd-49c7-8624-8643e7171297
    EventTypeEventType 이 이벤트로 인해 발생하는 결과입니다.Impact this event causes.

    Values:
    • Freeze: 가상 머신은 몇 초간 일시 중지 되도록 예약 됩니다.Freeze: The Virtual Machine is scheduled to pause for a few seconds. CPU 및 네트워크 연결을 일시 중단할 수 있습니다, 있지만 메모리 나 열린 파일에 영향을 주지 않습니다.CPU and network connectivity may be suspended, but there is no impact on memory or open files.
    • Reboot: Virtual Machine을 다시 부팅하도록 예약합니다(비영구 메모리가 손실됨).Reboot: The Virtual Machine is scheduled for reboot (non-persistent memory is lost).
    • Redeploy: Virtual Machine을 다른 노드로 이동하도록 예약합니다(임시 디스크가 손실됨).Redeploy: The Virtual Machine is scheduled to move to another node (ephemeral disks are lost).
    • Preempt: 우선 순위가 낮은 가상 컴퓨터를 삭제 하는 중 (임시 디스크 손실 됨).Preempt: The Low-priority Virtual Machine is being deleted (ephemeral disks are lost).
    ResourceTypeResourceType 이 이벤트가 영향을 주는 리소스 형식입니다.Type of resource this event impacts.

    Values:
    • VirtualMachine
    리소스Resources 이 이벤트가 영향을 주는 리소스 목록입니다.List of resources this event impacts. 최대 하나의 업데이트 도메인에 있는 컴퓨터를 포함하지만 UD의 모든 컴퓨터를 포함할 수는 없습니다.This is guaranteed to contain machines from at most one Update Domain, but may not contain all machines in the UD.

    예제:Example:
    • ["FrontEnd_IN_0", "BackEnd_IN_0"]["FrontEnd_IN_0", "BackEnd_IN_0"]
    이벤트 상태Event Status 이 이벤트의 상태입니다.Status of this event.

    Values:
    • Scheduled: NotBefore 속성에 지정된 시간 이후 시작하도록 이 이벤트를 예약합니다.Scheduled: This event is scheduled to start after the time specified in the NotBefore property.
    • Started: 이 이벤트가 시작되었습니다.Started: This event has started.
    Completed 또는 유사한 상태가 제공된 적이 없습니다. 이벤트가 완료되면 더 이상 이벤트가 반환되지 않습니다.No Completed or similar status is ever provided; the event will no longer be returned when the event is completed.
    NotBeforeNotBefore 이 시간이 지난 후 이 이벤트가 시작될 수 있습니다.Time after which this event may start.

    예제:Example:
    • 2016년 9월 19일 월요일 18:29:47 GMTMon, 19 Sep 2016 18:29:47 GMT

    이벤트 예약Event Scheduling

    각 이벤트는 이벤트 유형에 따라 향후 최소한의 시간으로 예약됩니다.Each event is scheduled a minimum amount of time in the future based on event type. 이 시간은 이벤트의 NotBefore 속성에 반영됩니다.This time is reflected in an event's NotBefore property.

    EventTypeEventType 최소 공지Minimum Notice
    중지Freeze 15분15 minutes
    RebootReboot 15분15 minutes
    재배포Redeploy 10분10 minutes
    선점Preempt 30초30 seconds

    이벤트 범위Event Scope

    예약된 이벤트는 다음으로 전달됩니다.Scheduled events are delivered to:

    • 독립 실행형 가상 컴퓨터Standalone Virtual Machines
    • 클라우드 서비스의 모든 Virtual MachinesAll Virtual Machines in a Cloud Service
    • 가용성 집합의 모든 Virtual MachinesAll Virtual Machines in an Availability Set
    • 확장 집합 배치 그룹의 모든 Virtual MachinesAll Virtual Machines in a Scale Set Placement Group.

    따라서 이벤트의 Resources 필드를 확인하여 영향을 받을 VM을 식별해야 합니다.As a result, you should check the Resources field in the event to identify which VMs are going to be impacted.

    이벤트 시작Starting an event

    예정된 이벤트에 대해 알게 되고 정상 종료를 위한 논리를 완료하면 EventId로 메타데이터 서비스에 대한 POST 호출을 실행하여 처리 중인 이벤트를 승인할 수 있습니다.Once you have learned of an upcoming event and completed your logic for graceful shutdown, you can approve the outstanding event by making a POST call to the metadata service with the EventId. 이는 Azure에 최소 알림 시간을 단축할 수 있음(가능한 경우)을 나타냅니다.This indicates to Azure that it can shorten the minimum notification time (when possible).

    다음은 POST 요청 본문에 필요한 json입니다.The following is the json expected in the POST request body. 요청에 StartRequests 목록이 포함되어야 합니다.The request should contain a list of StartRequests. StartRequest는 빠르게 처리할 이벤트의 EventId를 포함합니다.Each StartRequest contains the EventId for the event you want to expedite:

    {
        "StartRequests" : [
            {
                "EventId": {EventId}
            }
        ]
    }
    

    PowerShellPowershell

    curl -H @{"Metadata"="true"} -Method POST -Body '{"StartRequests": [{"EventId": "f020ba2e-3bc0-4c40-a10b-86575a9eabd5"}]}' -Uri http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01
    

    참고

    이벤트를 승인하면 해당 이벤트를 승인한 가상 머신뿐만 아니라 이벤트의 모든 Resources에 대해 이벤트가 진행됩니다.Acknowledging an event allows the event to proceed for all Resources in the event, not just the virtual machine that acknowledges the event. 따라서 승인을 조정할 리더를 선택할 수 있으며, 이는 Resources 필드의 첫 번째 컴퓨터처럼 간단할 수 있습니다.You may therefore choose to elect a leader to coordinate the acknowledgement, which may be as simple as the first machine in the Resources field.

    PowerShell 샘플PowerShell sample

    다음 샘플은 예약된 이벤트에 대한 메타데이터 서비스를 쿼리하고 처리 중인 각 이벤트를 승인합니다.The following sample queries the metadata service for scheduled events and approves each outstanding event.

    # How to get scheduled events 
    function Get-ScheduledEvents($uri)
    {
        $scheduledEvents = Invoke-RestMethod -Headers @{"Metadata"="true"} -URI $uri -Method get
        $json = ConvertTo-Json $scheduledEvents
        Write-Host "Received following events: `n" $json
        return $scheduledEvents
    }
    
    # How to approve a scheduled event
    function Approve-ScheduledEvent($eventId, $uri)
    {
        # Create the Scheduled Events Approval Document
        $startRequests = [array]@{"EventId" = $eventId}
        $scheduledEventsApproval = @{"StartRequests" = $startRequests} 
        
        # Convert to JSON string
        $approvalString = ConvertTo-Json $scheduledEventsApproval
    
        Write-Host "Approving with the following: `n" $approvalString
    
        # Post approval string to scheduled events endpoint
        Invoke-RestMethod -Uri $uri -Headers @{"Metadata"="true"} -Method POST -Body $approvalString
    }
    
    function Handle-ScheduledEvents($scheduledEvents)
    {
        # Add logic for handling events here
    }
    
    ######### Sample Scheduled Events Interaction #########
    
    # Set up the scheduled events URI for a VNET-enabled VM
    $localHostIP = "169.254.169.254"
    $scheduledEventURI = 'http://{0}/metadata/scheduledevents?api-version=2017-11-01' -f $localHostIP 
    
    # Get events
    $scheduledEvents = Get-ScheduledEvents $scheduledEventURI
    
    # Handle events however is best for your service
    Handle-ScheduledEvents $scheduledEvents
    
    # Approve events when ready (optional)
    foreach($event in $scheduledEvents.Events)
    {
        Write-Host "Current Event: `n" $event
        $entry = Read-Host "`nApprove event? Y/N"
        if($entry -eq "Y" -or $entry -eq "y")
        {
            Approve-ScheduledEvent $event.EventId $scheduledEventURI 
        }
    }
    

    다음 단계Next steps