Auto-Update Agent Rollout Resource Reference

Report an issue with this page

The auto-update agent rollout resource allows cluster administrators to view the current agent rollout for Teleport Agent Managed Updates (v2).

This resource should not be edited by humans.

kind: autoupdate_agent_rollout
metadata:
  # autoupdate_agent_rollout is a singleton resource. There can be only one instance
  # of this resource in the Teleport cluster, and it must be named `autoupdate-agent-rollout`.
  name: autoupdate-agent-rollout
spec:
  # start_version is the version used to install new agents before their
  # group's scheduled update time. Agents never update to the start_version
  # automatically, but may be required to via "teleport-update update --now".
  start_version: v17.2.0

  # target_version is the version that agents update to during their group's
  # scheduled update time. New agents also use this version after their group's
  # scheduled update time.
  target_version: v17.2.1

  # schedule used to roll out updates.
  # The regular schedule is defined in the autoupdate_config resource.
  # The immediate schedule updates all agents to target_version immediately.
  # Possible values: "regular" or "immediate"
  schedule: regular

  # autoupdate_mode allows users to enable, disable, or suspend agent updates at the
  # cluster level. Disable agent automatic updates only if self-managed
  # updates are in place. This value may also be set in autoupdate_config.
  # If set in both places, disabled overrides suspended, which overrides enabled.
  # Possible values: "enabled", "disabled", "suspended"
  autoupdate_mode: enabled

  # strategy used to roll out updates to agents.
  # The halt-on-error strategy ensures that groups earlier in the schedule are
  # given the opportunity to update to the target_version before groups that are
  # later in the schedule. (Currently, the schedule must be stopped manually by
  # setting the mode to "suspended" or "disabled". In the future, errors will be
  # detected automatically).
  # The time-based strategy ensure that each group updates within a defined
  # time window, with no dependence between groups.
  # Possible values: "halt-on-error" or "time-based"
  # Default: "halt-on-error"
  strategy: halt-on-error

  # maintenance_window_duration configures the duration after the start_hour
  # when updates may occur. Only valid for the time-based strategy.
  # maintenance_window_duration: 1h

status:

  # groups contains the status for each group in the currently executing schedule.
  groups:

    # name of each group, configured locally via "teleport-update enable --group"
    - name: staging

      # start_time of the group
      start_time: 0001-01-01T00:00:00Z

      # state of the group
      # Possible values: unstarted, active, done, rolledback
      state: active

      # last_update_time of this group's status
      last_update_time: 0001-01-01T00:00:00Z

      # last_update_reason of this group's status
      last_update_reason: "new version"

      # days that the update may occur on, from autoupdate_config
      # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*"
      config_days: [ "Mon", "Tue", "Wed", "Thu" ]

      # start_hour of the update, in UTC, from autoupdate_config
      config_start_hour: 4

    - name: production

      # ...

      # config_wait_hours is specific number of hours after the previous group that this
      # group may execute after, from autoupdate_config.
      config_wait_hours: 24

      # canary_count is the number of agents selected to update and verify before the rest
      # of the group. Only present for the halt-on-error schedule.
      canary_count: 1

      # canaries describes the status of the selected canaries for this group.
      canaries:

        # updater_id is the unique ID of the updater that is managing the canary.
        - updater_id: 3c6bcc1b-1992-4abc-a6f1-43f8f1b9ff05

          # host_id is the unique host ID of the agent that is being updated.
          host_id: c757ad82-95f2-4416-ae9d-a20ffd9b5a54

          # hostname is the hostname of the agent that is being updated.
          hostname: prod43

          # success is true if the canary was updated successfully.
          success: true


  # start_time of the rollout
  start_time: 0001-01-01T00:00:00Z

  # state of the entire rollout
  # Possible values: unstarted, active, done, rolledback
  state: active

See Teleport Agent Managed Updates for more details.