Edit

Define reusable update strategies using Azure Kubernetes Fleet Manager

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, you need Azure CLI version 2.70.0 or later installed. To install or upgrade, see Install the Azure CLI.

  • You also need the fleet Azure CLI extension version 1.6.0 or later, which you can install by running 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.

  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 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.

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.

Next steps

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

  • Last updated on