Share via


Update Runs - Get

Get a UpdateRun

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/fleets/{fleetName}/updateRuns/{updateRunName}?api-version=2025-03-01

URI Parameters

Name In Required Type Description
fleetName
path True

string

minLength: 1
maxLength: 63
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

The name of the Fleet resource.

resourceGroupName
path True

string

minLength: 1
maxLength: 90

The name of the resource group. The name is case insensitive.

subscriptionId
path True

string (uuid)

The ID of the target subscription. The value must be an UUID.

updateRunName
path True

string

minLength: 1
maxLength: 50
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

The name of the UpdateRun resource.

api-version
query True

string

minLength: 1

The API version to use for this operation.

Responses

Name Type Description
200 OK

UpdateRun

Azure operation completed successfully.

Other Status Codes

ErrorResponse

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Gets an UpdateRun resource.
Gets an UpdateRun resource. - generated by [MaximumSet] rule

Gets an UpdateRun resource.

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ContainerService/fleets/fleet1/updateRuns/run1?api-version=2025-03-01

Sample response

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ContainerService/fleets/myFleet/updateRuns/run1",
  "name": "run1",
  "type": "Microsoft.ContainerService/fleets/updateRuns",
  "systemData": {
    "createdBy": "@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-03-01T01:10:08.395Z",
    "lastModifiedBy": "@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-03-01T01:10:08.395Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "strategy": {
      "stages": [
        {
          "name": "stage1",
          "groups": [
            {
              "name": "group-a"
            }
          ],
          "afterStageWaitInSeconds": 3600
        }
      ]
    },
    "managedClusterUpdate": {
      "upgrade": {
        "type": "Full",
        "kubernetesVersion": "1.26.1"
      },
      "nodeImageSelection": {
        "type": "Latest"
      }
    },
    "status": {
      "status": {
        "state": "NotStarted"
      },
      "stages": [
        {
          "status": {
            "state": "NotStarted"
          },
          "name": "stage1",
          "groups": [
            {
              "status": {
                "state": "NotStarted"
              },
              "name": "group-a",
              "members": [
                {
                  "status": {
                    "state": "NotStarted"
                  },
                  "name": "member-one",
                  "clusterResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myClusters/providers/Microsoft.ContainerService/managedClusters/myCluster"
                }
              ]
            }
          ],
          "afterStageWaitStatus": {
            "status": {
              "state": "NotStarted"
            },
            "waitDurationInSeconds": 3600
          }
        }
      ]
    }
  },
  "eTag": "\"EtagValue\""
}

Gets an UpdateRun resource. - generated by [MaximumSet] rule

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgfleets/providers/Microsoft.ContainerService/fleets/fleet1/updateRuns/fleet1?api-version=2025-03-01

Sample response

{
  "properties": {
    "updateStrategyId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ContainerService/fleets/myFleet/updateStrategies/strategy1",
    "strategy": {
      "stages": [
        {
          "name": "stage1",
          "groups": [
            {
              "name": "group-a"
            }
          ],
          "afterStageWaitInSeconds": 3600
        }
      ]
    },
    "managedClusterUpdate": {
      "upgrade": {
        "type": "Full",
        "kubernetesVersion": "1.26.1"
      },
      "nodeImageSelection": {
        "type": "Latest",
        "customNodeImageVersions": [
          {
            "version": "wkcmcqhecdbsoskkny"
          }
        ]
      }
    },
    "provisioningState": "Succeeded",
    "status": {
      "status": {
        "startTime": "2025-02-14T23:29:32.768Z",
        "completedTime": "2025-02-14T23:29:32.768Z",
        "state": "NotStarted",
        "error": {
          "code": "ezwocfahsfmbddlqgloysjkthkn",
          "message": "udtnrxlgadzqlogclb",
          "target": "l",
          "details": [],
          "additionalInfo": [
            {
              "type": "fzgprz",
              "info": {}
            }
          ]
        }
      },
      "stages": [
        {
          "status": {
            "state": "NotStarted",
            "startTime": "2025-02-14T23:29:32.767Z",
            "completedTime": "2025-02-14T23:29:32.767Z",
            "error": {
              "code": "ezwocfahsfmbddlqgloysjkthkn",
              "message": "udtnrxlgadzqlogclb",
              "target": "l",
              "details": [],
              "additionalInfo": [
                {
                  "type": "fzgprz",
                  "info": {}
                }
              ]
            }
          },
          "name": "stage1",
          "groups": [
            {
              "status": {
                "state": "NotStarted",
                "startTime": "2025-02-14T23:29:32.767Z",
                "completedTime": "2025-02-14T23:29:32.767Z",
                "error": {
                  "code": "ezwocfahsfmbddlqgloysjkthkn",
                  "message": "udtnrxlgadzqlogclb",
                  "target": "l",
                  "details": [],
                  "additionalInfo": [
                    {
                      "type": "fzgprz",
                      "info": {}
                    }
                  ]
                }
              },
              "name": "group-a",
              "members": [
                {
                  "status": {
                    "state": "NotStarted",
                    "startTime": "2025-02-14T23:29:32.767Z",
                    "completedTime": "2025-02-14T23:29:32.767Z",
                    "error": {
                      "code": "ezwocfahsfmbddlqgloysjkthkn",
                      "message": "udtnrxlgadzqlogclb",
                      "target": "l",
                      "details": [],
                      "additionalInfo": [
                        {
                          "type": "fzgprz",
                          "info": {}
                        }
                      ]
                    }
                  },
                  "name": "member-one",
                  "clusterResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myClusters/providers/Microsoft.ContainerService/managedClusters/myCluster",
                  "operationId": "islvvdetacuskjzmkcxc",
                  "message": "xrvhotarzemcgeen"
                }
              ]
            }
          ],
          "afterStageWaitStatus": {
            "status": {
              "state": "NotStarted",
              "startTime": "2025-02-14T23:29:32.767Z",
              "completedTime": "2025-02-14T23:29:32.767Z",
              "error": {
                "code": "ezwocfahsfmbddlqgloysjkthkn",
                "message": "udtnrxlgadzqlogclb",
                "target": "l",
                "details": [],
                "additionalInfo": [
                  {
                    "type": "fzgprz",
                    "info": {}
                  }
                ]
              }
            },
            "waitDurationInSeconds": 3600
          }
        }
      ],
      "nodeImageSelection": {
        "selectedNodeImageVersions": [
          {
            "version": "wkcmcqhecdbsoskkny"
          }
        ]
      }
    },
    "autoUpgradeProfileId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgfleets/providers/Microsoft.ContainerService/fleets/fleet1/autoUpgradeProfiles/aup1"
  },
  "eTag": "\"EtagValue\"",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ContainerService/fleets/myFleet/updateRuns/run1",
  "name": "run1",
  "type": "Microsoft.ContainerService/fleets/updateRuns",
  "systemData": {
    "createdBy": "someUser",
    "createdByType": "User",
    "createdAt": "2022-03-23T05:40:40.657Z",
    "lastModifiedBy": "someOtherUser",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2022-03-23T05:40:40.657Z"
  }
}

Definitions

Name Description
createdByType

The type of identity that created the resource.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

ManagedClusterUpdate

The update to be applied to the ManagedClusters.

ManagedClusterUpgradeSpec

The upgrade to apply to a ManagedCluster.

ManagedClusterUpgradeType

The type of upgrade to perform when targeting ManagedClusters.

MemberUpdateStatus

The status of a member update operation.

NodeImageSelection

The node image upgrade to be applied to the target nodes in update run.

NodeImageSelectionStatus

The node image upgrade specs for the update run.

NodeImageSelectionType

The node image upgrade type.

NodeImageVersion

The node upgrade image version.

systemData

Metadata pertaining to creation and last modification of the resource.

UpdateGroup

A group to be updated.

UpdateGroupStatus

The status of a UpdateGroup.

UpdateRun

A multi-stage process to perform update operations across members of a Fleet.

UpdateRunProvisioningState

The provisioning state of the UpdateRun resource.

UpdateRunStatus

The status of a UpdateRun.

UpdateRunStrategy

Defines the update sequence of the clusters via stages and groups.

Stages within a run are executed sequentially one after another. Groups within a stage are executed in parallel. Member clusters within a group are updated sequentially one after another.

A valid strategy contains no duplicate groups within or across stages.

UpdateStage

Defines a stage which contains the groups to update and the steps to take (e.g., wait for a time period) before starting the next stage.

UpdateStageStatus

The status of a UpdateStage.

UpdateState

The state of the UpdateRun, UpdateStage, UpdateGroup, or MemberUpdate.

UpdateStatus

The status for an operation or group of operations.

WaitStatus

The status of the wait duration.

createdByType

The type of identity that created the resource.

Value Description
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

ManagedClusterUpdate

The update to be applied to the ManagedClusters.

Name Type Description
nodeImageSelection

NodeImageSelection

The node image upgrade to be applied to the target nodes in update run.

upgrade

ManagedClusterUpgradeSpec

The upgrade to apply to the ManagedClusters.

ManagedClusterUpgradeSpec

The upgrade to apply to a ManagedCluster.

Name Type Description
kubernetesVersion

string

The Kubernetes version to upgrade the member clusters to.

type

ManagedClusterUpgradeType

ManagedClusterUpgradeType is the type of upgrade to be applied.

ManagedClusterUpgradeType

The type of upgrade to perform when targeting ManagedClusters.

Value Description
Full

Full upgrades the control plane and all agent pools of the target ManagedClusters. Requires the ManagedClusterUpgradeSpec.KubernetesVersion property to be set.

NodeImageOnly

NodeImageOnly upgrades only the node images of the target ManagedClusters. Requires the ManagedClusterUpgradeSpec.KubernetesVersion property to NOT be set.

ControlPlaneOnly

ControlPlaneOnly upgrades only targets the KubernetesVersion of the ManagedClusters and will not be applied to the AgentPool. Requires the ManagedClusterUpgradeSpec.KubernetesVersion property to be set.

MemberUpdateStatus

The status of a member update operation.

Name Type Description
clusterResourceId

string

The Azure resource id of the target Kubernetes cluster.

message

string

The status message after processing the member update operation.

name

string

The name of the FleetMember.

operationId

string

The operation resource id of the latest attempt to perform the operation.

status

UpdateStatus

The status of the MemberUpdate operation.

NodeImageSelection

The node image upgrade to be applied to the target nodes in update run.

Name Type Description
customNodeImageVersions

NodeImageVersion[]

Custom node image versions to upgrade the nodes to. This field is required if node image selection type is Custom. Otherwise, it must be empty. For each node image family (e.g., 'AKSUbuntu-1804gen2containerd'), this field can contain at most one version (e.g., only one of 'AKSUbuntu-1804gen2containerd-2023.01.12' or 'AKSUbuntu-1804gen2containerd-2023.02.12', not both). If the nodes belong to a family without a matching image version in this field, they are not upgraded.

type

NodeImageSelectionType

The node image upgrade type.

NodeImageSelectionStatus

The node image upgrade specs for the update run.

Name Type Description
selectedNodeImageVersions

NodeImageVersion[]

The image versions to upgrade the nodes to.

NodeImageSelectionType

The node image upgrade type.

Value Description
Latest

Use the latest image version when upgrading nodes. Clusters may use different image versions (e.g., 'AKSUbuntu-1804gen2containerd-2021.10.12' and 'AKSUbuntu-1804gen2containerd-2021.10.19') because, for example, the latest available version is different in different regions.

Consistent

The image versions to upgrade nodes to are selected as described below: for each node pool in managed clusters affected by the update run, the system selects the latest image version such that it is available across all other node pools (in all other clusters) of the same image type. As a result, all node pools of the same image type will be upgraded to the same image version. For example, if the latest image version for image type 'AKSUbuntu-1804gen2containerd' is 'AKSUbuntu-1804gen2containerd-2021.10.12' for a node pool in cluster A in region X, and is 'AKSUbuntu-1804gen2containerd-2021.10.17' for a node pool in cluster B in region Y, the system will upgrade both node pools to image version 'AKSUbuntu-1804gen2containerd-2021.10.12'.

Custom

Upgrade the nodes to the custom image versions. When set, update run will use node image versions provided in customNodeImageVersions to upgrade the nodes. If set, customNodeImageVersions must not be empty.

NodeImageVersion

The node upgrade image version.

Name Type Description
version

string

The image version to upgrade the nodes to (e.g., 'AKSUbuntu-1804gen2containerd-2022.12.13').

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string (date-time)

The timestamp of resource creation (UTC).

createdBy

string

The identity that created the resource.

createdByType

createdByType

The type of identity that created the resource.

lastModifiedAt

string (date-time)

The timestamp of resource last modification (UTC)

lastModifiedBy

string

The identity that last modified the resource.

lastModifiedByType

createdByType

The type of identity that last modified the resource.

UpdateGroup

A group to be updated.

Name Type Description
name

string

minLength: 1
maxLength: 50
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

Name of the group. It must match a group name of an existing fleet member.

UpdateGroupStatus

The status of a UpdateGroup.

Name Type Description
members

MemberUpdateStatus[]

The list of member this UpdateGroup updates.

name

string

The name of the UpdateGroup.

status

UpdateStatus

The status of the UpdateGroup.

UpdateRun

A multi-stage process to perform update operations across members of a Fleet.

Name Type Description
eTag

string

If eTag is provided in the response body, it may also be provided as a header per the normal etag convention. Entity tags are used for comparing two or more entities from the same requested resource. HTTP/1.1 uses entity tags in the etag (section 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and If-Range (section 14.27) header fields.

id

string (arm-id)

Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"

name

string

The name of the resource

properties.autoUpgradeProfileId

string (arm-id)

AutoUpgradeProfileId is the id of an auto upgrade profile resource.

properties.managedClusterUpdate

ManagedClusterUpdate

The update to be applied to all clusters in the UpdateRun. The managedClusterUpdate can be modified until the run is started.

properties.provisioningState

UpdateRunProvisioningState

The provisioning state of the UpdateRun resource.

properties.status

UpdateRunStatus

The status of the UpdateRun.

properties.strategy

UpdateRunStrategy

The strategy defines the order in which the clusters will be updated. If not set, all members will be updated sequentially. The UpdateRun status will show a single UpdateStage and a single UpdateGroup targeting all members. The strategy of the UpdateRun can be modified until the run is started.

properties.updateStrategyId

string (arm-id)

The resource id of the FleetUpdateStrategy resource to reference.

When creating a new run, there are three ways to define a strategy for the run:

  1. Define a new strategy in place: Set the "strategy" field.
  2. Use an existing strategy: Set the "updateStrategyId" field. (since 2023-08-15-preview)
  3. Use the default strategy to update all the members one by one: Leave both "updateStrategyId" and "strategy" unset. (since 2023-08-15-preview)

Setting both "updateStrategyId" and "strategy" is invalid.

UpdateRuns created by "updateStrategyId" snapshot the referenced UpdateStrategy at the time of creation and store it in the "strategy" field. Subsequent changes to the referenced FleetUpdateStrategy resource do not propagate. UpdateRunStrategy changes can be made directly on the "strategy" field before launching the UpdateRun.

systemData

systemData

Azure Resource Manager metadata containing createdBy and modifiedBy information.

type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

UpdateRunProvisioningState

The provisioning state of the UpdateRun resource.

Value Description
Succeeded

Resource has been created.

Failed

Resource creation failed.

Canceled

Resource creation was canceled.

UpdateRunStatus

The status of a UpdateRun.

Name Type Description
nodeImageSelection

NodeImageSelectionStatus

The node image upgrade specs for the update run. It is only set in update run when NodeImageSelection.type is Consistent.

stages

UpdateStageStatus[]

The stages composing an update run. Stages are run sequentially withing an UpdateRun.

status

UpdateStatus

The status of the UpdateRun.

UpdateRunStrategy

Defines the update sequence of the clusters via stages and groups.

Stages within a run are executed sequentially one after another. Groups within a stage are executed in parallel. Member clusters within a group are updated sequentially one after another.

A valid strategy contains no duplicate groups within or across stages.

Name Type Description
stages

UpdateStage[]

The list of stages that compose this update run. Min size: 1.

UpdateStage

Defines a stage which contains the groups to update and the steps to take (e.g., wait for a time period) before starting the next stage.

Name Type Description
afterStageWaitInSeconds

integer (int32)

The time in seconds to wait at the end of this stage before starting the next one. Defaults to 0 seconds if unspecified.

groups

UpdateGroup[]

Defines the groups to be executed in parallel in this stage. Duplicate groups are not allowed. Min size: 1.

name

string

minLength: 1
maxLength: 50
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

The name of the stage. Must be unique within the UpdateRun.

UpdateStageStatus

The status of a UpdateStage.

Name Type Description
afterStageWaitStatus

WaitStatus

The status of the wait period configured on the UpdateStage.

groups

UpdateGroupStatus[]

The list of groups to be updated as part of this UpdateStage.

name

string

The name of the UpdateStage.

status

UpdateStatus

The status of the UpdateStage.

UpdateState

The state of the UpdateRun, UpdateStage, UpdateGroup, or MemberUpdate.

Value Description
NotStarted

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that has not been started.

Running

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that is running.

Stopping

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that is being stopped.

Stopped

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that has stopped.

Skipped

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that has been skipped.

Failed

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that has failed.

Pending

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that is pending.

Completed

The state of an UpdateRun/UpdateStage/UpdateGroup/MemberUpdate that has completed.

UpdateStatus

The status for an operation or group of operations.

Name Type Description
completedTime

string (date-time)

The time the operation or group was completed.

error

ErrorDetail

The error details when a failure is encountered.

startTime

string (date-time)

The time the operation or group was started.

state

UpdateState

The State of the operation or group.

WaitStatus

The status of the wait duration.

Name Type Description
status

UpdateStatus

The status of the wait duration.

waitDurationInSeconds

integer (int32)

The wait duration configured in seconds.