Enhance concurrency control with entity tags (eTags) in Azure Kubernetes Service

To prevent conflicting requests in Azure Kubernetes Service (AKS), eTags (Entity Tags) serve as unique identifiers that enable concurrency control. When a request to the cluster is made, the system checks whether the provided eTag matches the latest version stored in the database. If there is a mismatch, the request fails early, ensuring that no unintended overwrites occur.

There are two options for applying eTags through headers:

–-if-match Header: Ensures that the operation is performed only if the existing eTag matches the value provided in this header.

–-if-none-match Header: Ensures that the operation is performed only if none of the eTags matches the value provided in this header. This header type can only be empty or a *.

You can do either a LIST or a GET call to your cluster or node pool to see the existing ETag. An ETag looks something like the following example:

"agentPoolProfiles": [
    {"eTag": "5e5ffdce-356b-431b-b050-81b45eef2a12"}
]

ETags can exist at both the cluster and agent pool levels. Depending on the scope of the operations you are performing, you can pass in the corresponding eTag. When you perform a cluster-level operation, both the cluster-level eTag and agent pool eTag are updated. When you perform an agent pool operation, only the agent pool eTag is updated.

Headers are optional to use. The following examples show how to use –-if-match and -–if-none-match headers.

Example 1: The CLI command below s an existing cluster MyManagedCluster if the eTag matches with yvjvt

az aks delete -g MyResourceGroup -n MyManagedCluster --if-match "yvjvt"

Example 2: The CLI command below creates a new cluster called MyManagedCluster. If * is provided in the –if-none-match header, that means to validate the resource does not exist.

az aks create -g MyResourceGroup -n MyManagedCluster --if-none-match "*"

The table below outlines the expected behavior of HTTP operations (PUT, PATCH, and DELETE) based on different eTag configurations and resource existence. They show how the presence of --if-match or --if-none-match headers affects the response status codes, ensuring concurrency control and preventing unintended modifications.

This fails the prevalidation checks. The --if-none-match header can only be empty or take a value of *.

This fails the prevalidation checks. Both headers cannot be used at the same time.

The request is rejected if a * (wildcard of any) value is passed into --if-none-match header and the resource already exists.

The request is rejected if the header provided does not match with the eTag value. A new GET operation is needed to get the latest eTag on the resource and update the header value in the request.