Edit

Define reusable update strategies using Azure Kubernetes Fleet Manager

Applies to: ✔️ Fleet Manager ✔️ Fleet Manager with hub cluster

Administrators can control the sequence of updates to Fleet-managed clusters by defining a series of stages and groups. They can configure when approvals and pauses should occur within those stages and groups. The entire configuration can be saved as an update strategy which can be managed independently of update runs or auto-upgrades, allowing strategies to be reused as required.

This article covers how to define update strategies using groups and stages.

A diagram showing an example update strategy containing two update stages. Each update stage contains two update groups. Each update group contains two member clusters.

Prerequisites

  • Read the conceptual overview of Fleet updates, which provides an explanation of update runs, stages, groups, and strategies referenced in this guide.

  • You must have a Fleet resource with one or more member clusters. If not, follow the quickstart to create a Fleet resource and join Azure Kubernetes Service (AKS) clusters as members.

  • Set the following environment variables:

    export GROUP=<resource-group>
export FLEET=<fleet-name>
export CLUSTERID=<aks-cluster-resource-id>
export STRATEGY=<strategy-name>

  • If you're following the Azure CLI instructions in this article, install the latest version of the Azure CLI. To install or upgrade, see Install the Azure CLI.

  • You also need the fleet Azure CLI extension. To install it, run the following command:

    az extension add --name fleet

    Run the az extension update command to update to the latest version of the extension released:

    az extension update --name fleet

Select clusters for your strategy

There are two ways to select which clusters are included in each stage and group of your update strategy to control update sequence:

  • Member labels (recommended): Assign labels to each fleet member and use memberSelector to select members by those labels. Each member can have multiple labels.
  • Update groups: Assign an update group to each fleet member, then define groups in your strategy that match those group names. Each member can only belong to one group.

Create an update strategy using member selectors (preview)

Member labels are the recommended approach for selecting clusters in your update strategies because they provide more flexibility. For conceptual details, see Group clusters using member labels.

Important

Azure Kubernetes Fleet Manager preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. Azure Kubernetes Fleet Manager previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use.

Apply labels on member clusters

Apply labels when adding member cluster to the fleet

Apply labels on your fleet members using the az fleet member create command. The following example applies two labels to the member cluster: env=staging and tier=frontend:

az fleet member create \
    --resource-group $GROUP \
    --fleet-name $FLEET \
    --name member1 \
    --member-cluster-id $CLUSTERID \
    --labels "env=staging tier=frontend"

Apply labels to an existing fleet member

Apply labels on your fleet members using the az fleet member update command

az fleet member update \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name member1 \
 --labels "env=staging tier=frontend"

Create an update strategy

An update strategy consists of one or more stages, where a stage can contain one or more update groups.

Note

An Azure portal experience will be available prior to general availability of this capability.

  1. Create a JSON file to define the stages and groups for the update run. Stages run sequentially in the order they appear in the JSON file. Groups run in parallel within each stage. The following example file (example-labels-strategy.json) defines a strategy with two stages using memberSelector to select clusters by their labels and includes optional maxConcurrency settings:

    • The staging stage uses a stage-level memberSelector to select all clusters with the label env=staging and create one implicit group.
    • The production stage uses a stage-level memberSelector to prefilter all clusters with the label env=production, then defines two groups, each with its own memberSelector to select clusters by the tier label.

    When memberSelector is set on a group, the group's name field is used only as a display identifier for status reporting and logging and no longer used for update group based selection of fleet members.

    {
    "stages": [
        {
            "name": "staging",
            "memberSelector": { "byLabel": "env=staging" },
            "maxConcurrency": "1",
            "afterStageWaitInSeconds": 600
        },
        {
            "name": "production",
            "memberSelector": { "byLabel": "env=production" },
            "maxConcurrency": "4",
            "groups": [
                {
                    "name": "frontend",
                    "memberSelector": { "byLabel": "tier=frontend" },
                    "maxConcurrency": "3"
                },
                {
                    "name": "backend",
                    "memberSelector": { "byLabel": "tier=backend" },
                    "maxConcurrency": "3"
                }
            ]
        }
    ]
}

Note

The maxConcurrency field is optional and controls how many clusters can upgrade concurrently at the stage or group level. Use a larger value to upgrade clusters faster across your fleet, or a smaller value for a more controlled rollout that limits the blast radius if issues arise.

When a stage uses memberSelector without groups (like staging), all matching members form a single implicit group and the stage's maxConcurrency controls concurrency directly. When groups are defined (like production), the stage-level maxConcurrency acts as an overall ceiling across all groups.

In this example, the staging stage sets maxConcurrency to "1", so staging clusters upgrade one at a time. The production stage allows up to "4" clusters concurrently, with the frontend and backend groups each limited to "3".

Values can be a fixed integer (for example, "3") or a percentage (for example, "50%"). If omitted, the system applies default values. For details on how these values are resolved and their upper limits, see Maximum concurrency (preview).

  1. Create a new update strategy using the az fleet updatestrategy create command with the --stages flag set to the name of your JSON file.

    az fleet updatestrategy create \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name $STRATEGY \
 --stages example-labels-strategy.json

Create an update strategy using update groups

Clusters can also be selected in update strategies by assigning them to a single update group. You can define an update strategy that assigns these update groups to stages. Within an update stage, updates are applied to each update group in parallel. Within an update group, member clusters update sequentially.

Note

A fleet member can only be a part of one update group, but an update group can have multiple fleet members assigned to it. An update group itself isn't a separate resource type. Update groups are only strings representing references from the fleet members. So, if all fleet members with references to a common update group are deleted, that specific update group ceases to exist as well.

Assign clusters to update groups

Assign to group when adding member cluster to the fleet

  1. In the Azure portal, navigate to your Azure Kubernetes Fleet Manager resource.

  2. From the service menu, under Settings, select Member clusters > Add.

    Screenshot of the Azure portal page for Azure Kubernetes Fleet Manager for adding member clusters.

  3. Select the cluster that you want to add, and then select Next: Review + add.

  4. Enter the name of the update group that you want to assign the cluster to, and then select Add.

    Screenshot of the Azure portal page for Azure Kubernetes Fleet Manager review and add step for member clusters.

Assign a member cluster to an update group when adding the member cluster to the fleet using the az fleet member create command with the --update-group parameter set to the name of the update group.

az fleet member create \
    --resource-group $GROUP \
    --fleet-name $FLEET \
    --name member1 \
    --member-cluster-id $CLUSTERID \
    --update-group group-1a

Assign an existing fleet member to an update group

  1. In the Azure portal, navigate to your Azure Kubernetes Fleet Manager resource.

  2. From the service menu, under Settings, select Member clusters.

  3. Select the clusters that you want to assign to an update group, and then select Assign update group

    Screenshot of the Azure portal page for assigning existing member clusters to a group.

  4. Enter the name of the update group that you want to assign the cluster to, and then select Assign.

    Screenshot of the Azure portal page for member clusters that shows the form for updating a member cluster's group.

Assign an existing fleet member to an update group using the az fleet member update command with the --update-group flag set to the name of the update group.

az fleet member update \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name member1 \
 --update-group group-1

Create an update strategy

An update strategy consists of one or more stages, where a stage can contain one or more update groups.

  1. In the Azure portal, navigate to your Azure Kubernetes Fleet Manager resource.

  2. From the service menu, under Settings, select Multi-cluster update > Strategies, then Create.

  3. Enter a name for the strategy.

  4. The first time you view the page, an update strategy explanation diagram is displayed which can help visualize how strategies function.

    A screenshot of the Azure portal showing creation of update strategy.

  5. Select Create Stage and enter:

    • Stage name - name the stage - it must be unique across all stage names in the strategy.
    • (Optional) Stage approvals - select this option if you would like to wait for an approval before this stage starts or after it completes. For more information, see Add approvals to update groups and stages.
    • (Optional) Pause after stage - select this option if you would like to define a pause before moving to the next stage.
    • (Optional) Pause duration - select a predefined duration, or enter a custom value in seconds.

    A screenshot of the Azure portal showing creation of Azure Kubernetes Fleet Manager update strategy stage.

  6. Assign one or more Update Groups to the stage, and then select Create.

    Note

    The maximum number of Update Groups in each Update Stage is 50.

    A screenshot of the Azure portal showing creation of Azure Kubernetes Fleet Manager update strategy stage, selecting update groups to include.

For this scenario, we create stages and groups to match the details used for the Azure portal process.

  1. Create a JSON file to define the stages and groups for the update run. Stages run sequentially in the order they appear in the JSON file. Groups run in parallel within each stage, so ordering isn't important. The following example file (example-stages.json) defines a strategy with two stages and includes optional maxConcurrency and maxAllowedFailures settings:

    {
    "stages": [
        {
            "name": "stage-1",
            "maxConcurrency": "7",
            "maxAllowedFailures": "2",
            "groups": [
                {
                    "name": "group-1",
                    "maxConcurrency": "3",
                    "maxAllowedFailures": "1"
                },
                {
                    "name": "group-2",
                    "maxConcurrency": "50%",
                    "maxAllowedFailures": "25%"
                }
            ],
            "afterStageWaitInSeconds": 300
        },
        {
            "name": "stage-2",
            "maxConcurrency": "100%",
            "maxAllowedFailures": "0",
            "groups": [
                {
                    "name": "group-3",
                    "maxConcurrency": "2",
                    "maxAllowedFailures": "0"
                }
            ]
        }
    ]
}

    maxConcurrency

    The maxConcurrency field is optional and controls how many clusters can upgrade concurrently at the stage or group level. Use a larger value to upgrade clusters faster across your fleet, or a smaller value for a more controlled rollout that limits the blast radius if problems arise.

    In this example, stage-1 sets maxConcurrency to "7", which allows up to "7" clusters in this stage to upgrade concurrently. Within stage-1, group-1 limits concurrency to "3" clusters, which means up to "3" in this group can upgrade concurrently. group-2 allows up to "50%" of its clusters to upgrade concurrently (for example, if the group contains 4 clusters, up to 2 can upgrade at the same time).

    Values can be a fixed integer (for example, "3") or a percentage (for example, "100%"). If omitted, the system applies default values. For details on how these values are resolved and their upper limits, see Maximum concurrency (preview).

    maxAllowedFailures

    The maxAllowedFailures field is optional and controls how many member cluster upgrade failures are tolerated before the group or stage is marked as failed. By default (when unset or "0"), a single failure stops the entire update run.

    This setting evaluates failure count only. It doesn't enforce a minimum success rate. A group or stage can therefore end in Completed even if some or all members failed, as long as the failure threshold wasn't exceeded when Fleet made its scheduling decisions.

    In this example, stage-1 sets maxAllowedFailures to "2", tolerating up to two member failures across the stage. Within stage-1, group-1 tolerates "1" failure and group-2 tolerates "25%" of its members failing (for example, if the group contains 4 clusters, up to 1 failure is tolerated). stage-2 sets maxAllowedFailures to "0", which means any failure immediately stops the run and is often useful for production stages.

    For most rollouts, prefer percentage-based values because they scale better across different group sizes. Avoid setting the value equal to the total member count unless you intentionally want effectively "never fail" behavior for that segment.

    Values can be a fixed integer (for example, "3") or a percentage (for example, "25%"). For details on how these values are resolved, see Maximum allowed failures (preview).

  2. Create a new update strategy using the az fleet updatestrategy create command with the --stages flag set to the name of your JSON file.

    az fleet updatestrategy create \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name $STRATEGY \
 --stages example-stages.json

Next steps

You can use an update strategy as part of a manual update run or an auto-upgrade profile. See:

  • Last updated on