Introduction
This blog covers the usage of Microsoft.ContainerService REST APIs to demonstrate upgrade options on an AKS cluster. It also goes through the authentication setup to call these APIs using POSTMAN and we also look at options using CURL.
Prerequisites
Setup an AKS cluster within a Subscription assigned to an Azure AD tenant. Cluster will reside in resource group within the subscription. Make a note of the Subscription and Tenant IDs, in addition to Resource Group and AKS Resource names for later use.
Source associated with this article can be found in this GitHub link.
Steps Involved
1. The Stable ContainerService API release can be found by clicking this link. For this exercise, API version 2022-06-01, found in its respective folder, has been used for testing.
2. Download the managedClusters.json file as raw format and import it into POSTMAN. The file contains the API schema in Swagger format and can be customized with changes described below before import.
3. From Azure Portal’s Active Directory site go to App Registration and register an application as seen below. Make a note of the Client and Tenant ID.
4. From Secrets, create a client secret and save the Secret value to use later.
5. From API Permissions, add delegated user_impersonation permission for ‘Azure Service Management’ as seen below
6. From Subscription, add IAM ‘Contributor’ role to the application created above. Also make a note of the Subscription ID, from the Subscription’s overview page.
7. In POSTMAN, create an ‘AKS’ Environment with below variables. Insert the Subscription ID from above. Using an existing AKS cluster environment, insert its Resource Group name and AKS Resource (cluster) name in the value fields below, in addition to the baseUrl and api-version fields. These variables will be used by the API.
8. In POSTMAN’s Variables section for the imported API, create the following variables. Insert the values of clientId, clientSecret, tenantId and subscriptionId from the application created above. The value of bearerToken will be filled dynamically, so leave it empty for now.
9. In POSTMAN’s Authorization section for the imported API, use type=Bearer Token with the bearerToken variable assigned to the Token
10. In POSTMAN’s Pre-request Script section for the imported API, enter the code below.
- Line 1 will add query parameter ‘api-version’ to every request.
- Lines 3-23 will be used for Token generation. Variables set earlier will be obtained here.
- Line 22 will insert the generated token into the bearerToken variable.
The code as seen above, can be copied from below for use in your setup.
pm.request.addQueryParams({ key: 'api-version', value: pm.environment.get("api-version") });
let resource = (typeof pm.collectionVariables.get("resource") !== "undefined" ? pm.collectionVariables.get("resource") : "https://management.azure.com/");
let tenantId = pm.collectionVariables.get("tenantId");
console.log('tenantId =' + tenantId);
pm.sendRequest({
url: "https://login.microsoftonline.com/" + tenantId + "/oauth2/token",
method: 'POST',
header: 'Content-Type: application/x-www-form-urlencoded',
body: {
mode: 'urlencoded',
urlencoded: [
{key: "grant_type", value: "client_credentials", disable: false},
{key: "client_id", value: pm.collectionVariables.get("clientId"), disable: false},
{key: "client_secret", value: pm.collectionVariables.get("clientSecret"), disable: false},
{key: "resource", value: resource, disable: false}
]
}
}, function(err, res) {
pm.collectionVariables.set("bearerToken", res.json().access_token);
});
11. For the API ‘GET a Managed Cluster’, fill in the Path variables values with the Environment variables. On hitting Send, a status of 200 OK confirms valid Token generation and results confirm cluster is in Running state.
Upgrading Node Image version of Node Pool
This section investigates upgrading node images in an AKS cluster node pool. The API below supports upgrading node so that its image is up to date with the newest OS and runtime updates. This is done without upgrading the version of Kubernetes on the cluster.
Values of SubID, Resource Group Name, Cluster (Resource) name and the Agent Pool Name (that needs to be upgraded), will need to be added as shown below.
The end result is this triggers node image upgrade on the user node pool, as seen in the Response body and confirmed in the Azure portal screen shot.
Auto Upgrades using Scheduled Maintenance Window
To perform auto-upgrade on an AKS cluster, we go through two steps which involve setting the weekly schedule, followed by setting the upgrade channel. This will be described in detail in the following steps.
1. Set Cluster Maintenance Window
Planned Maintenance allows scheduling weekly maintenance windows, which once set causes all upgrade actions to happen during that time. Property setting in the body allows scheduling one or more weekly windows, which in this case falls on a Monday @1a UTC. API also exists to Get and Delete existing Scheduled Maintenance.
Aside from setting SubID, Resource Group and AKS Cluster (Resource) names, we also need a configName to label the maintenance window.
2. Upgrade Cluster with Auto-Upgrade setting
To automatically upgrade an AKS cluster, an auto-upgrade-channel parameter needs to be set in the ‘Create or Update of Manage Cluster’ API call. Channel values are explained in this link.
Setting the Auto-Upgrade Channel using values of patch/stable/rapid, also enables auto-upgrade of the entire AKS cluster. Upgrade of the AKS cluster also automatically performs the AKS node-image upgrade. By default, auto-upgrade is disabled or by manually setting the channel value to ‘none’.
Parameters SubID, Resource Group and AKS Cluster (Resource) names should be inserted, of which Cluster Name is required. In the example below, when channel = ‘rapid’ is applied, cluster gets upgraded to latest patch on latest supported minor version.
Use the API ‘Get a Managed Cluster’ to confirm upgradeChannel setting, as seen below.
When Planned Maintenance is enabled in Step 1, along with Auto-Upgrade Channel in Step 2, then the AKS cluster gets scheduled for auto-upgrade during the Planned Maintenance window.
Using Curl to get AKS upgrade options
Curl is the easiest way to issue HTTP requests to the AKS REST API. In the example below we list the Orchestrator versions and the upgrades offered in a certain region for a given subscription.
First obtain a token and store it in a $token variable and then use the token to invoke REST call as seen below. From below, if the control plane is on 1.22.11, the possible upgrade options go up to 1.23.8.
export TOKEN=$(az account get-access-token --query 'accessToken' -o tsv)
curl -H "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/<subscriber_id>/providers/Microsoft.ContainerService/locations/eastus/orchestrators?api-version=2022-06-01&resource-type=managedClusters"
type=managedClusters"
{ "id":"/subscriptions/<subscriber_id>/providers/Microsoft.ContainerService/locations/eastus/orchestrators",
"name": "default",
"type": "Microsoft.ContainerService/locations/orchestrators",
"properties": {
"orchestrators": [
. . .
{
"orchestratorType": "Kubernetes",
"orchestratorVersion": "1.22.11",
"default": true,
"upgrades": [
{
"orchestratorType": "Kubernetes",
"orchestratorVersion": "1.23.5"
},
{
"orchestratorType": "Kubernetes",
"orchestratorVersion": "1.23.8"
}
]
}
}
Conclusion
In the sections above we’ve covered the usage of AKS REST APIs to not only upgrade node images, but also show how easy it is to enable auto-upgrades with planned maintenance. Thank you for taking the time to read this blog.
Disclaimer
The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without a warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.