|
| 1 | +--- |
| 2 | +title: Create Kubernetes clusters using REST APIs |
| 3 | +description: Learn how to create Kubernetes clusters in Azure Local using REST API for the Hybrid Container Service. |
| 4 | +ms.topic: how-to |
| 5 | +author: rcheeran |
| 6 | +ms.date: 06/19/2025 |
| 7 | +ms.author: rcheeran |
| 8 | +ms.lastreviewed: 06/19/2025 |
| 9 | +ms.reviewer: rjaini |
| 10 | +--- |
| 11 | + |
| 12 | +# Create Kubernetes clusters using the REST API |
| 13 | + |
| 14 | +[!INCLUDE [hci-applies-to-23h2](includes/hci-applies-to-23h2.md)] |
| 15 | + |
| 16 | +This article describes how to create Kubernetes clusters on Azure Local using the REST API. The Azure resource type for [AKS Arc provisioned clusters](/azure/templates/microsoft.hybridcontainerservice/provisionedclusterinstances?pivots=deployment-language-arm-template) is **"Microsoft.HybridContainerService/provisionedClusterInstances"**. This resource is an extension of the [connected clusters](/azure/templates/microsoft.kubernetes/connectedclusters?pivots=deployment-language-arm-template) resource type, **"Microsoft.Kubernetes/connectedClusters"**. Due to this dependency, you must first create a connected cluster resource before creating an AKS Arc resource. |
| 17 | + |
| 18 | +## Before you begin |
| 19 | + |
| 20 | +Before you begin, make sure you have the following details from your on-premises infrastructure administrator: |
| 21 | + |
| 22 | +- **Azure subscription ID**: The Azure subscription ID that Azure Local uses for deployment and registration. |
| 23 | +- **Custom Location ID**: The Azure Resource Manager ID of the custom location. The custom location is configured during the Azure Local cluster deployment. Your infrastructure admin should give you the Resource Manager ID of the custom location. This parameter is required in order to create Kubernetes clusters. If the infrastructure admin provides a custom location name and resource group name, you can also get the Resource Manager ID using the following command: |
| 24 | + |
| 25 | + ```azurecli |
| 26 | + az customlocation show --name "<custom location name>" --resource-group <azure resource group> --query "id" -o tsv |
| 27 | + ``` |
| 28 | + |
| 29 | +- **Network ID**: The Azure Resource Manager ID of the Azure Local logical network you created [following these steps](aks-networks.md). Your admin should give you the ID of the logical network. This parameter is required in order to create Kubernetes clusters. If you know the resource group in which the logical network was created, you can also get the Azure Resource Manager ID using the following command: |
| 30 | + |
| 31 | + ```azurecli |
| 32 | + az stack-hci-vm network lnet show --name "<lnet name>" --resource-group <azure resource group> --query "id" -o tsv |
| 33 | + ``` |
| 34 | + |
| 35 | +- **Create an SSH key pair**: Create an SSH key pair in Azure and store the private key file for troubleshooting and log collection purposes. For detailed instructions, see [Create and store SSH keys with the Azure CLI](/azure/virtual-machines/ssh-keys-azure-cli), or with the [Azure portal](/azure/virtual-machines/ssh-keys-portal). |
| 36 | +- To connect to the Kubernetes cluster from anywhere, create a Microsoft Entra group and add members to it. All the members in the Microsoft Entra group have cluster administrator access to the cluster. Make sure to add yourself as a member to the Microsoft Entra group. If you don't add yourself, you can't access the Kubernetes cluster using **kubectl**. For more information about creating Microsoft Entra groups and adding users, see [Manage Microsoft Entra groups and group membership](/entra/fundamentals/how-to-manage-groups). |
| 37 | + |
| 38 | +## Step 1: Create a connected cluster resource |
| 39 | + |
| 40 | +See the API definition for [connected clusters](/rest/api/hybridkubernetes/connected-cluster/create) and create a **PUT** request with the `kind` property set to `ProvisionedCluster`. The following example is a sample **PUT** request to create a connected cluster resource using the REST API: |
| 41 | + |
| 42 | +```http |
| 43 | +PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Kubernetes/connectedClusters/{connectedClusterName}?api-version=2024-01-01 |
| 44 | +Content-Type: application/json |
| 45 | +Authorization: Bearer <access_token> |
| 46 | +
|
| 47 | +{ |
| 48 | + "location": "<region>", |
| 49 | + "identity": { |
| 50 | + "type": "SystemAssigned" |
| 51 | + }, |
| 52 | + "kind": "ProvisionedCluster", |
| 53 | + "properties": { |
| 54 | + "agentPublicKeyCertificate": "", |
| 55 | + "azureHybridBenefit": "NotApplicable", |
| 56 | + "distribution": "AKS", |
| 57 | + "distributionVersion": "1.0", |
| 58 | + "aadProfile": { |
| 59 | + "enableAzureRBAC": true, |
| 60 | + "adminGroupObjectIDs": [ |
| 61 | + "<entra-group-id>" |
| 62 | + ], |
| 63 | + "tenantID": "<tenant-id>" |
| 64 | + }, |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +Replace all placeholder values with your actual details. For more information, see the [connected clusters API documentation](/rest/api/hybridkubernetes/connected-cluster/create). |
| 70 | + |
| 71 | +## Step 2: Create a provisioned cluster resource |
| 72 | + |
| 73 | +See the API definition for [provisioned clusters](/rest/api/hybridcontainer/provisioned-cluster-instances/create-or-update). In this **PUT** call, pass the Azure Resource Manager identifier created in the previous step as the URI parameter. The following code is an example HTTP **PUT** request to create a provisioned cluster resource with only the required parameters: |
| 74 | + |
| 75 | +```http |
| 76 | +PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HybridContainerService/provisionedClusterInstances/{clusterName}?api-version=2024-01-01-preview |
| 77 | +Content-Type: application/json |
| 78 | +Authorization: Bearer <access_token> |
| 79 | +
|
| 80 | +{ |
| 81 | + "extendedLocation": { |
| 82 | + "type": "CustomLocation", |
| 83 | + "name": "<ARM ID of Custom Location>" |
| 84 | + }, |
| 85 | + "properties": { |
| 86 | + "controlPlane": { |
| 87 | + "count": 1, |
| 88 | + "vmSize": "Standard_A4_v2" |
| 89 | + }, |
| 90 | + "agentPoolProfiles": [ |
| 91 | + { |
| 92 | + "name": "default-nodepool-1", |
| 93 | + "count": 1, |
| 94 | + "vmSize": "Standard_A4_v2", |
| 95 | + "osType": "Linux", |
| 96 | + } |
| 97 | + ], |
| 98 | + "linuxProfile": { |
| 99 | + "ssh": { |
| 100 | + "publicKeys": [ |
| 101 | + { |
| 102 | + "keyData": "<SSH public key>" |
| 103 | + } |
| 104 | + ] |
| 105 | + } |
| 106 | + }, |
| 107 | + "cloudProviderProfile": { |
| 108 | + "infraNetworkProfile": { |
| 109 | + "vnetSubnetIds": [ |
| 110 | + "<ARM ID of logical network>" |
| 111 | + ] |
| 112 | + } |
| 113 | + }, |
| 114 | + } |
| 115 | +} |
| 116 | +
|
| 117 | +``` |
| 118 | + |
| 119 | +Replace the placeholder values with your actual details. For more information, see the [provisioned clusters API documentation](/rest/api/hybridcontainer/provisioned-cluster-instances/create-or-update). |
| 120 | + |
| 121 | +## Connect to the Kubernetes cluster |
| 122 | + |
| 123 | +Now you can connect to your Kubernetes cluster by running the `az connectedk8s proxy` command from your development machine. Make sure you sign in to Azure before running this command. If you have multiple Azure subscriptions, select the appropriate subscription ID using the [az account set](/cli/azure/account#az-account-set) command. |
| 124 | + |
| 125 | +This command downloads the **kubeconfig** of your Kubernetes cluster to your development machine and opens a proxy connection channel to your on-premises Kubernetes cluster. The channel is open for as long as the command runs. Let this command run for as long as you want to access your cluster. If it times out, close the CLI window, open a fresh one, and then run the command again. |
| 126 | + |
| 127 | +You must have Contributor permissions on the resource group that hosts the Kubernetes cluster in order to successfully run the following command: |
| 128 | + |
| 129 | +```azurecli |
| 130 | +az connectedk8s proxy --name $aksclustername --resource-group $resource_group --file .\aks-arc-kube-config |
| 131 | +``` |
| 132 | + |
| 133 | +Expected output: |
| 134 | + |
| 135 | +```output |
| 136 | +Proxy is listening on port 47011 |
| 137 | +Merged "aks-workload" as current context in .\\aks-arc-kube-config |
| 138 | +Start sending kubectl requests on 'aks-workload' context using |
| 139 | +kubeconfig at .\\aks-arc-kube-config |
| 140 | +Press Ctrl+C to close proxy. |
| 141 | +``` |
| 142 | + |
| 143 | +Keep this session running and connect to your Kubernetes cluster from a different terminal or command prompt. Verify that you can connect to your Kubernetes cluster by running the `kubectl get` command. This command returns a list of the cluster nodes: |
| 144 | + |
| 145 | +```azurecli |
| 146 | +kubectl get node -A --kubeconfig .\aks-arc-kube-config |
| 147 | +``` |
| 148 | + |
| 149 | +The following example output shows the node you created in the previous steps. Make sure the node status is **Ready**: |
| 150 | + |
| 151 | +```output |
| 152 | +NAME STATUS ROLES AGE VERSION |
| 153 | +moc-l0ttdmaioew Ready control-plane,master 34m v1.24.11 |
| 154 | +moc-ls38tngowsl Ready <none> 32m v1.24.11 |
| 155 | +``` |
| 156 | + |
| 157 | +## Next steps |
| 158 | + |
| 159 | +[AKS Arc overview](overview.md) |
0 commit comments