Managed Updates Resource Reference

Report an issue with this page

This document provides detailed reference information about the Managed Updates v2 resources. See also:

• the Managed Updates Architecture describing the agent update architecture and security invariants.
• the Managed Updates Guide for more details on how to set up Managed updates.

Managed Updates v2 resources

User facing

Managed Updates are configured via two user-facing resources:

autoupdate_config

This describes how and when updates are applied. Configuration changes take effect during the next rollout.

kind: autoupdate_config
metadata:
  # autoupdate_config is a singleton resource. There can be only one instance
  # of this resource in the Teleport cluster, and it must be named `autoupdate-config`.
  name: autoupdate-config
spec:
  agents:
    # 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_version.
    # If set in both places, disabled overrides suspended, which overrides enabled.
    # Possible values: "enabled", "disabled", "suspended"
    # Default: "disabled" (unless specified in autoupdate_version)
    mode: enabled

    # strategy used to roll out updates to agents. Applies to every group.
    # 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

    # schedules define groups of agents with different update times.
    # Currently, only the regular schedule is configurable.
    schedules:
      regular:

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

          # start_hour of the update, in UTC
          start_hour: 4

          # days that the update may occur on
          # Days are not configurable for most Enterprise cloud-hosted users.
          # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*"
          # Default: [ "Mon", "Tue", "Wed", "Thu" ]
          days: [ "Mon", "Tue", "Wed", "Thu" ]

        - name: production
          start_hour: 5

          # wait_hours ensures that the group executes at least a specific number of hours
          # after the previous group. Only valid for the halt-on-error schedule.
          # Default: 0
          wait_hours: 24

  tools:
    # mode allows users to enable or disable client tool updates at the
    # cluster level. Disable client tool automatic updates only if self-managed
    # updates are in place.
    # Possible values: "enabled" or "disabled"
    # Default: "disabled"
    mode: enabled

autoupdate_version

This specifies which version agents should update to. Changing the start or target version creates a new rollout.

note

This resource is not editable for cloud-managed Teleport Enterprise to ensure that all of your clients receive security patches and remain compatible with your cluster.

kind: autoupdate_version
metadata:
  # autoupdate_version is a singleton resource. There can be only one instance
  # of this resource in the Teleport cluster, and it must be named `autoupdate-version`.
  name: autoupdate-version
spec:
  agents:
    # 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"
    # Default: "regular"
    schedule: regular

    # 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"
    # Default: "disabled" (unless specified in autoupdate_config)
    mode: enabled

  tools:
    # target_version is the semver version of client tools the cluster will advertise.
    # Client tools such as tsh and tctl will update to this version at login if the
    # mode set in autoupdate_config is set to enabled.
    # Default: cluster version
    target_version: v17.2.1

System resources

Those resources are generated automatically by Teleport. Users should not edit them, reading them can be helpful to track the autoupdate state and understand Teleport's update decisions.

autoupdate_agent_rollout

autoupdate_agent_rollout describes the rollout of the version across agent groups. A single rollout is active at a time. Each Auth Service updates the rollout every minute.

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

  # 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

autoupdate_agent_report

Reports how many agents are connected to each auth, and which version they are running. This is used to track update progress and automatically progress the rollout.

kind: autoupdate_agent_report
version: v1
metadata:
  # Instance ID of the auth that generated the report.
  name: auth1
spec:
  # When the report was generated.
  timestamp: 2025-05-28T11:22:41.924956-04:00
  # Map of the agent groups seen by the auth.
  groups:
    dev:
      # Map of the agent versions seen for this group by the auth.
      versions:
        "1.2.3":
          # Number of registered agents with this version.
          count: 15
        "1.2.4":
          count: 2
        "1.2.5":
          count: 34
    stage:
      versions:
        "1.2.3":
          count: 15
        "1.2.4":
          count: 125
    prod:
      versions:
        "1.2.5":
          count: 1543
  # List of agents omitted from the report.
  omitted:
    - count: 120
      reason: "version is pinned"
    - count: 12
      reason: "managed update v1 updater does not support agent reports"
    - count: 42
      reason: "updater version predates agent report"

Reports can be individually seen using tctl get autoupdate_agent_reports. To aggregate every report into a single one, run tctl autoupdate agents report.

Agent Update Overview

Here's a schema describing the interactions between the different Managed Updates v2 components when updating agents:

Update Strategies

The autoupdate_config resource supports two different strategies for managing how updates propagate across your agent groups:

halt-on-error Strategy

The halt-on-error strategy provides predictable, sequential updates across environments. It's ideal for traditional development pipelines where you want to ensure that development environments are successfully updated before proceeding to staging and production.

Key characteristics:

• Updates proceed sequentially through groups in the order they are defined
• If an earlier group fails to update, later groups will not be updated
• Provides a controlled, predictable update path
• Groups with a wait_hours parameter will wait the specified duration after the previous group's successful update

Example configuration:

kind: autoupdate_config
metadata:
  name: autoupdate-config
spec:
  agents:
    mode: enabled
    strategy: halt-on-error
    schedules:
      regular:
        - name: dev
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 16
        - name: stage
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 18
        - name: prod
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 20
          wait_hours: 24

In this example, the dev group updates first, followed by stage, and finally prod. The prod group will only update if both dev and stage have updated successfully, and will wait 24 hours after stage has completed.

time-based Strategy

The time-based strategy is designed for environments where update groups are independent of each other, such as geographical regions or different teams. It allows updates to occur whenever the specified maintenance window is active for a group, regardless of the status of other groups.

Key characteristics:

• Groups update independently during their configured maintenance windows
• No dependency between groups - if prod's window occurs before dev's, prod will update first
• Maintenance windows are strictly enforced - updates only occur during the specified window duration
• Does not support the wait_hours parameter

Example configuration:

kind: autoupdate_config
metadata:
  name: autoupdate-config
spec:
  agents:
    mode: enabled
    strategy: time-based
    maintenance_window_duration: 2h
    schedules:
      regular:
        - name: us-east
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 4
        - name: us-west
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 6
        - name: europe
          days: ["Mon", "Tue", "Wed", "Thu"]
          start_hour: 12

In this example, each region will update during its own 2-hour maintenance window, regardless of the status of other regions. If a new version becomes available when Europe's window is active but before US East's window, Europe will update first.

Version Behavior During Rollout

Depending on which strategy is selected, the system behaves differently regarding which versions are installed at different points in the rollout. Consider a scenario where start_version is A and target_version is B:

halt-on-error Strategy Version Behavior

This table summarizes which version an agent will install based on its group's maintenance window:

Timing	New Agent Installations	Existing Agent Updates
Before maintenance window	Install version A	No updates occur
During maintenance window	Install version B	Update to version B
After maintenance window	Install version B	Update to version B

In halt-on-error strategy, if the previous group is not done updating, the next one will not start. For example, if you have 2 groups:

• dev updating everyday at 13:00
• prod updating on weekdays at 15:00

If dev finishes updating Friday at 16:30, prod will not start updating immediately as update windows are 1-hour-long and prod's update window is over. prod update will start on Monday at 15:00.

time-based Strategy Version Behavior

This table summarizes which version an agent will install based on its group's maintenance window:

Timing	New Agent Installations	Existing Agent Updates
Before maintenance window	Install version A	No updates occur
During maintenance window	Install version B	Update to version B
After maintenance window	Install version B	No updates occur until next window

The key difference is what happens after the maintenance window closes:

• With halt-on-error, agents update even if they missed the window to run the same version as the other agents in their group.
• With time-based, updates are strictly limited to the maintenance window duration.

In time-based strategy, the group will start updating as soon as it enters its maintenance window, even if the previous group is not done updating yet.

Mode Precedence

The mode field can be set in both autoupdate_config and autoupdate_version resources. The most restrictive mode takes precedence:

1. disabled (most restrictive)
2. suspended
3. enabled (least restrictive)

This allows different teams to manage the configuration and version resources independently while maintaining safety controls.

Cloud-specific Constraints

For cloud-hosted Teleport Enterprise:

• The autoupdate_version resource is managed automatically and cannot be edited
• The days field in schedules is often not configurable
• The start_hour defaults to your selected maintenance window
• A maximum of 5 update groups is allowed by default
• A full update schedule cannot be longer than 4 days

These constraints ensure that all agents are updated weekly and remain compatible with the Teleport cluster's version.