Events and updates

Events

Cloud-init will fetch and apply cloud and user data configuration upon several event types. The two most common events for cloud-init are when an instance first boots and any subsequent boot thereafter (reboot). In addition to boot events, cloud-init users and vendors are interested in when devices are added. Cloud-init currently supports the following event types:

  • BOOT_NEW_INSTANCE: New instance first boot.

  • BOOT: Any system boot other than BOOT_NEW_INSTANCE.

  • BOOT_LEGACY: Similar to BOOT, but applies networking config twice each boot: once during the Local stage, then again in the Network stage. As this behaviour was previously the default behaviour, this option exists to prevent regressing such behaviour.

  • HOTPLUG: Dynamic add of a system device.

Future work will likely include infrastructure and support for the following events:

  • METADATA_CHANGE: An instance’s metadata has changed.

  • USER_REQUEST: Directed request to update.

Datasource event support

All datasources support the BOOT_NEW_INSTANCE event by default. Each datasource will declare a set of these events that it is capable of handling. Datasources may not support all event types. In some cases a system may be configured to allow a particular event but may be running on a platform whose datasource cannot support the event.

Configuring event updates

Update configuration may be specified via user data, which can be used to enable or disable handling of specific events. This configuration will be honored as long as the events are supported by the datasource. However, configuration will always be applied at first boot, regardless of the user data specified.

Updates

Update policy configuration defines which events are allowed to be handled. This is separate from whether a particular platform or datasource has the capability for such events.

scope: <name of the scope for event policy>

The scope value is a string which defines which domain the event occurs under. Currently, the only known scope is network, though more scopes may be added in the future. Scopes are defined by convention but arbitrary values can be used.

when: <list of events to handle for a particular scope >

Each scope requires a when element to specify which events are to allowed to be handled.

Hotplug

When the hotplug event is supported by the datasource and configured in user data, cloud-init will respond to the addition or removal of network interfaces to the system. In addition to fetching and updating the system metadata, cloud-init will also bring up/down the newly added interface.

Example

Apply network config every boot

On every boot, apply network configuration found in the datasource.

# apply network config on every boot
updates:
  network:
    when: ['boot']