Azure Metadata Service: Linux VM の Scheduled EventsAzure Metadata Service: Scheduled Events for Linux VMs

スケジュールされたイベントとは、仮想マシン (VM) のメンテナンスに備えるための時間をアプリケーションに与える Azure Metadata Service です。Scheduled Events is an Azure Metadata Service that gives your application time to prepare for virtual machine (VM) maintenance. 今後のメンテナンス イベント (再起動など) に関する情報を提供することで、アプリケーションがイベントの準備を行い、中断を制限できるようにします。It provides information about upcoming maintenance events (for example, reboot) so that your application can prepare for them and limit disruption. このサービスは、Windows および Linux の、PaaS と IaaS を含むすべての Azure Virtual Machine の種類で利用できます。It's available for all Azure Virtual Machines types, including PaaS and IaaS on both Windows and Linux.

Windows のスケジュールされたイベントの詳細については、Windows VM のスケジュールされたイベントに関する記事をご覧ください。For information about Scheduled Events on Windows, see Scheduled Events for Windows VMs.

注意

スケジュールされたイベントは、すべての Azure リージョンで一般公開されています。Scheduled Events is generally available in all Azure Regions. 最新リリースについては、「利用可能なバージョンとリージョン」をご覧ください。See Version and Region Availability for latest release information.

スケジュールされたイベントを使用する理由Why use Scheduled Events?

多くのアプリケーションに、VM のメンテナンスに備える時間が得られるメリットがあります。Many applications can benefit from time to prepare for VM maintenance. この時間を使用して、可用性、信頼性、およびサービスを向上させる、次のようなアプリケーション固有のタスクを実行できます。The time can be used to perform application-specific tasks that improve availability, reliability, and serviceability, including:

  • チェックポイントと復元Checkpoint and restore.
  • 接続のドレインConnection draining.
  • プライマリ レプリカのフェールオーバーPrimary replica failover.
  • ロード バランサー プールからの削除Removal from a load balancer pool.
  • イベント ログEvent logging.
  • グレースフル シャットダウンGraceful shutdown.

スケジュールされたイベントを使用すると、アプリケーションはメンテナンスが行われる時期を検出し、その影響を制限するタスクをトリガーできます。With Scheduled Events, your application can discover when maintenance will occur and trigger tasks to limit its impact.

スケジュールされたイベントは、次のユース ケースでイベントを提供します。Scheduled Events provides events in the following use cases:

基本操作The Basics

Metadata Service では、VM 内部からアクセスできる REST エンドポイントを使用した VM の実行に関する情報が公開されます。Metadata Service exposes information about running VMs by using a REST endpoint that's accessible from within the VM. 情報は、VM の外部に公開されないように、ルーティング不可能な IP 経由で提供されます。The information is available via a nonroutable IP so that it's not exposed outside the VM.

ScopeScope

スケジュールされたイベントの配信先は次のとおりです。Scheduled events are delivered to:

  • スタンドアロンの仮想マシン。Standalone Virtual Machines.
  • クラウド サービス内のすべての VM。All the VMs in a cloud service.
  • 可用性セット内のすべての VM。All the VMs in an availability set.
  • 可用性ゾーン内のすべての VM。All the VMs in an availability zone.
  • スケール セットの配置グループすべての VM。All the VMs in a scale set placement group.

注意

可用性ゾーンの VM に固有ですが、スケジュール化されたイベントはゾーン内のシングル VM に進みます。Specific to VMs in an availability zone, the scheduled events go to single VMs in a zone. たとえば、ある可用性セット内に 100 の VM があるとき、そのうちの 1 つが更新されるなら、スケジュール化されたイベントは 100 すべてに進みます。一方で、あるゾーン内に 100 のシングル VM がある場合、イベントは、影響を受ける VM にのみ進みます。For example, if you have 100 VMs in a availability set and there is an update to one of them, the scheduled event will go to all 100, whereas if there are 100 single VMs in a zone, then event will only go to the VM which is getting impacted.

そのため、イベント内の Resources フィールドをチェックして、影響を受ける VM を特定する必要があります。As a result, check the Resources field in the event to identify which VMs are affected.

エンドポイントの検出Endpoint Discovery

VNET が有効な VM の場合は、静的でルーティング不可能な IP アドレス 169.254.169.254 から Metadata Service を利用できます。For VNET enabled VMs, Metadata Service is available from a static nonroutable 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=2019-08-01

VM が仮想ネットワーク内で作成されていない場合 (クラウド サービスと従来の VM の既定のケース)、使用する IP アドレスを検出する追加のロジックが必要となります。If the VM 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. ホスト エンドポイントの検出方法の詳細については、このサンプルを参照してください。To learn how to discover the host endpoint, see this sample.

利用可能なバージョンとリージョンVersion and Region Availability

スケジュールされたイベントのサービスは、バージョンによって管理されています。The Scheduled Events service is versioned. バージョンは必須で、現在のバージョンは 2019-01-01 です。Versions are mandatory; the current version is 2019-01-01.

VersionVersion リリースの種類Release Type リージョンRegions リリース ノートRelease Notes
2019-08-012019-08-01 一般公開General Availability AllAll
  • EventSource のサポートを追加しましたAdded support for EventSource
  • 2019-04-012019-04-01 一般公開General Availability AllAll
  • イベントの説明のサポートを追加しましたAdded support for Event Description
  • 2019-01-012019-01-01 一般公開General Availability AllAll
  • 仮想マシン スケール セットの EventType "Terminate" のサポートが追加されましたAdded support for virtual machine scale sets EventType 'Terminate'
  • 2017-11-012017-11-01 一般公開General Availability AllAll
  • スポット VM 削除の EventType 「Preempt」のサポートを追加するAdded support for Spot VM eviction EventType 'Preempt'
  • 2017-08-012017-08-01 一般公開General Availability AllAll
  • IaaS VM のリソース名から先頭のアンダースコアを削除Removed prepended underscore from resource names for IaaS VMs
  • すべての要求にメタデータ ヘッダー要件を適用Metadata header requirement enforced for all requests
  • 2017-03-012017-03-01 プレビューPreview AllAll
  • 最初のリリースInitial release
  • 注意

    スケジュールされたイベントの前のプレビュー リリースでは、api-version として {latest} がサポートされていました。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.

    スケジュールされたイベントは、サービスが 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 を使用して開始した VM のメンテナンスによって、スケジュールされたイベントが発生します。User-initiated VM maintenance via the Azure portal, API, CLI, or PowerShell results in a scheduled event. これによって、アプリケーションでメンテナンス準備ロジックをテストすることができ、アプリケーションでは、ユーザーが開始したメンテナンスの準備をすることができます。You then can test the maintenance preparation logic in your application, and your application can prepare for user-initiated maintenance.

    VM を再起動すると、型 Reboot のイベントがスケジュールされます。If you restart a VM, an event with the type Reboot is scheduled. VM を再デプロイすると、型 Redeploy のイベントがスケジュールされています。If you redeploy a VM, an event with the type Redeploy is scheduled.

    API の使用Use the API

    ヘッダーHeaders

    メタデータ サービスのクエリを実行するときには、要求が意図せずリダイレクトされないように、ヘッダー Metadata:true を指定する必要があります。When you query Metadata Service, you must provide the header Metadata:true to ensure the request wasn't unintentionally redirected. Metadata:true ヘッダーは、スケジュールされたイベントのすべての要求で必要です。The Metadata:true header is required for all scheduled events requests. 要求にヘッダーを含めないと、メタデータ サービスから Bad Request (無効な要求) という応答があります。Failure to include the header in the request results in a "Bad Request" response from Metadata Service.

    イベントのクエリQuery for events

    次の呼び出しを行うと、スケジュールされたイベントのクエリを実行できます。You can query for scheduled events by making the following call:

    BashBash

    curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2019-08-01
    

    応答には、スケジュールされたイベントの配列が含まれています。A response contains an array of scheduled events. 空の配列は、現在スケジュールされているイベントがないことを意味します。An empty array means that currently no events are 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" | "Terminate",
                "ResourceType": "VirtualMachine",
                "Resources": [{resourceName}],
                "EventStatus": "Scheduled" | "Started",
                "NotBefore": {timeInUTC},       
                "Description": {eventDescription},
                "EventSource" : "Platform" | "User",
            }
        ]
    }
    

    イベントのプロパティEvent Properties

    プロパティProperty 説明Description
    EventIdEventId このイベントのグローバル一意識別子。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 Spot Virtual Machine is being deleted (ephemeral disks are lost).
    • Terminate:仮想マシンは削除がスケジュールされています。Terminate: The virtual machine is scheduled to be deleted.
    ResourceTypeResourceType このイベントが影響を与えるリソースの種類。Type of resource this event affects.

    値:Values:
    • VirtualMachine
    リソースResources このイベントが影響を与えるリソースの一覧。List of resources this event affects. これには最大 1 つの更新ドメインのマシンが含まれることが保証されますが、更新ドメインの一部のマシンは含まれない場合があります。The list is guaranteed to contain machines from at most one update domain, but it might not contain all machines in the UD.

    例:Example:
    • ["FrontEnd_IN_0", "BackEnd_IN_0"]["FrontEnd_IN_0", "BackEnd_IN_0"]
    EventStatusEventStatus このイベントの状態。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 is no longer returned when the event is finished.
    NotBeforeNotBefore このイベントが開始される時間。Time after which this event can start.

    例:Example:
    • Mon, 19 Sep 2016 18:29:47 GMTMon, 19 Sep 2016 18:29:47 GMT
    説明Description このイベントの説明。Description of this event.

    例:Example:
    • ホスト サーバーのメンテナンス中です。Host server is undergoing maintenance.
    EventSourceEventSource イベントのイニシエーター。Initiator of the event.

    例:Example:
    • Platform:このイベントは、プラットフォームによって開始されています。Platform: This event is initiated by platform.
    • User:このイベントは、ユーザーによって開始されています。User: This event is initiated by user.

    イベントのスケジューリングEvent Scheduling

    各イベントは、スケジュールされているイベントの種類に基づいて、将来の最小値の時間でスケジュールされます。Each event is scheduled a minimum amount of time in the future based on the event type. この時間は、イベントの NotBefore プロパティに反映されます。This time is reflected in an event's NotBefore property.

    EventTypeEventType 最小値の通知Minimum notice
    FreezeFreeze 約 15 分15 minutes
    再起動Reboot 約 15 分15 minutes
    RedeployRedeploy 10 分10 minutes
    PreemptPreempt 30 秒30 seconds
    TerminateTerminate ユーザーが構成可能:5 から 15 分User Configurable: 5 to 15 minutes

    注意

    Azure では、劣化したハードウェアに起因するホストの故障を予測が可能になり、移行をスケジュールすることでサービスの中断を軽減しようとすることがあります。In some cases, Azure is able to predict host failure due to degraded hardware and will attempt to mitigate disruption to your service by scheduling a migration. 影響を受ける仮想マシンには、スケジュールされているイベントと NotBefore が届きます。これは通常、2、3 日先になります。Affected virtual machines will receive a scheduled event with a NotBefore that is typically a few days in the future. 実際の時間は、予測された故障のリスク評価によって異なります。The actual time varies depending on the predicted failure risk assessment. Azure では、可能であれば、7 日前に通知を行いますが、実際の時間はさまざまであり、ハードウェアが今にも故障する可能性が高い場合、7 日より短くなることがあります。Azure tries to give 7 days' advance notice when possible, but the actual time varies and might be smaller if the prediction is that there is a high chance of the hardware failing imminently. システムによって開始される移行の前にハードウェアで障害が発生した場合に備えて、サービスのリスクを最小限に抑えるために、できるだけ早く仮想マシンをご自身で再デプロイすることをお勧めします。To minimize risk to your service in case the hardware fails before the system-initiated migration, we recommend that you self-redeploy your virtual machine as soon as possible.

    イベントの開始Start an event

    今後予定されているイベントを確認し、グレースフル シャットダウンのロジックを完了すると、EventId を使用してメタデータ サービスに POST 呼び出しを行うことにより、未処理のイベントを承認できます。After you learn of an upcoming event and finish your logic for graceful shutdown, you can approve the outstanding event by making a POST call to Metadata Service with EventId. この呼び出しは、通知の最小時間を短縮できる (可能な場合) ことが Azure に示されます。This call indicates to Azure that it can shorten the minimum notification time (when possible).

    次に示すのは、POST 要求本文で求められている JSON のサンプルです。The following JSON sample is expected in the POST request body. 要求には、StartRequests の一覧を含める必要があります。The request should contain a list of StartRequests. StartRequest には、迅速に進める必要があるイベントの EventId が含まれます。Each StartRequest contains EventId for the event you want to expedite:

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

    Bash のサンプルBash sample

    curl -H Metadata:true -X POST -d '{"StartRequests": [{"EventId": "f020ba2e-3bc0-4c40-a10b-86575a9eabd5"}]}' http://169.254.169.254/metadata/scheduledevents?api-version=2019-01-01
    

    注意

    イベントの受信確認により、イベントを受信確認した VM だけでなく、イベント内のすべての Resources でイベントが続行されます。Acknowledging an event allows the event to proceed for all Resources in the event, not just the VM that acknowledges the event. そのため、受信確認を調整するリーダーを選択できます。これは、Resources フィールド内の最初のマシンと同様に簡単です。Therefore, you can choose to elect a leader to coordinate the acknowledgement, which might be as simple as the first machine in the Resources field.

    Python のサンプルPython sample

    次のサンプルでは、スケジュールされたイベントのメタデータ サービスにクエリを実行し、未処理の各イベントを承認しています。The following sample queries Metadata Service for scheduled events and approves each outstanding event:

    #!/usr/bin/python
    
    import json
    import socket
    import urllib2
    
    metadata_url = "http://169.254.169.254/metadata/scheduledevents?api-version=2019-08-01"
    this_host = socket.gethostname()
    
    
    def get_scheduled_events():
        req = urllib2.Request(metadata_url)
        req.add_header('Metadata', 'true')
        resp = urllib2.urlopen(req)
        data = json.loads(resp.read())
        return data
    
    
    def handle_scheduled_events(data):
        for evt in data['Events']:
            eventid = evt['EventId']
            status = evt['EventStatus']
            resources = evt['Resources']
            eventtype = evt['EventType']
            resourcetype = evt['ResourceType']
            notbefore = evt['NotBefore'].replace(" ", "_")
        description = evt['Description']
        eventSource = evt['EventSource']
            if this_host in resources:
                print("+ Scheduled Event. This host " + this_host +
                    " is scheduled for " + eventtype + 
            " by " + eventSource + 
            " with description " + description +
            " not before " + notbefore)
                # Add logic for handling events here
    
    
    def main():
        data = get_scheduled_events()
        handle_scheduled_events(data)
    
    
    if __name__ == '__main__':
        main()
    

    次のステップNext steps