Skip to content

Commit 7073bc1

Browse files
rcheeranrcheeran
committed
Add steps on using API
1 parent e0d7a10 commit 7073bc1

File tree

2 files changed

+151
-0
lines changed

2 files changed

+151
-0
lines changed

‎AKS-Arc/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@
6262
href: create-clusters-terraform.md
6363
- name: Azure Resource Manager template
6464
href: resource-manager-quickstart.md
65+
- name: REST API
66+
href: aks-create-clusters-api.md
6567
- name: Networking
6668
items:
6769
- name: Create logical networks

‎AKS-Arc/aks-create-clusters-api.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
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 a 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 is an extension of the [Connected cluster](/azure/templates/microsoft.kubernetes/connectedclusters?pivots=deployment-language-arm-template) resource type **"Microsoft.Kubernetes/connectedClusters"**. Due to this dependency, you would need to 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 where Azure Local is used for deployment and registration.
23+
- **Custom Location ID** - 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. You can also get the Resource Manager ID using `az customlocation show --name "<custom location name>" --resource-group <azure resource group> --query "id" -o tsv`, if the infrastructure admin provides a custom location name and resource group name.
24+
- **Network ID** - Azure Resource Manager ID of the Azure Local logical network 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. You can also get the Azure Resource Manager ID using `az stack-hci-vm network lnet show --name "<lnet name>" --resource-group <azure resource group> --query "id" -o tsv` if you know the resource group in which the logical network was created.
25+
- **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 in the [Azure portal](/azure/virtual-machines/ssh-keys-portal).
26+
- 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 cannot 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).
27+
28+
## Step 1: Create a Connected cluster resource
29+
30+
Refer to the API definition for [Connected clusters](/rest/api/hybridkubernetes/connected-cluster/create) and create PUT request with the **`kind`** property set as 'ProvisionedCluster'. Here is a sample PUT request to create a Connected cluster resource using the REST API:
31+
32+
```http
33+
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Kubernetes/connectedClusters/{connectedClusterName}?api-version=2024-01-01
34+
Content-Type: application/json
35+
Authorization: Bearer <access_token>
36+
37+
{
38+
"location": "<region>",
39+
"identity": {
40+
"type": "SystemAssigned"
41+
},
42+
"kind": "ProvisionedCluster",
43+
"properties": {
44+
"agentPublicKeyCertificate": "",
45+
"azureHybridBenefit": "NotApplicable",
46+
"distribution": "AKS",
47+
"distributionVersion": "1.0",
48+
"aadProfile": {
49+
"enableAzureRBAC": true,
50+
"adminGroupObjectIDs": [
51+
"<entra-group-id>"
52+
],
53+
"tenantID": "<tenant-id>"
54+
},
55+
}
56+
}
57+
```
58+
59+
Replace all placeholder values with your actual details. For more information, see the [Connected cluster API documentation](/rest/api/hybridkubernetes/connected-cluster/create).
60+
61+
## Step 2: Create a Provisioned cluster resource
62+
63+
Refer to 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. Here is a sample HTTP PUT request to create a Provisioned cluster resource with only the required parameters:
64+
65+
```http
66+
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HybridContainerService/provisionedClusterInstances/{clusterName}?api-version=2024-01-01-preview
67+
Content-Type: application/json
68+
Authorization: Bearer <access_token>
69+
70+
{
71+
"extendedLocation": {
72+
"type": "CustomLocation",
73+
"name": "<ARM ID of Custom Location>"
74+
},
75+
"properties": {
76+
"controlPlane": {
77+
"count": 1,
78+
"vmSize": "Standard_A4_v2"
79+
},
80+
"agentPoolProfiles": [
81+
{
82+
"name": "default-nodepool-1",
83+
"count": 1,
84+
"vmSize": "Standard_A4_v2",
85+
"osType": "Linux",
86+
}
87+
],
88+
"linuxProfile": {
89+
"ssh": {
90+
"publicKeys": [
91+
{
92+
"keyData": "<SSH public key>"
93+
}
94+
]
95+
}
96+
},
97+
"cloudProviderProfile": {
98+
"infraNetworkProfile": {
99+
"vnetSubnetIds": [
100+
"<ARM ID of logical network>"
101+
]
102+
}
103+
},
104+
}
105+
}
106+
107+
```
108+
109+
Replace the placeholder values with your actual details. For more information, see the [Provisioned cluster API documentation](/rest/api/hybridcontainer/provisioned-cluster-instances/create-or-update).
110+
111+
## Connect to the Kubernetes cluster
112+
113+
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.
114+
115+
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, then run the command again.
116+
117+
You must have Contributor permissions on the resource group that hosts the Kubernetes cluster in order to run the following command successfully:
118+
119+
```azurecli
120+
az connectedk8s proxy --name $aksclustername --resource-group $resource_group --file .\aks-arc-kube-config
121+
```
122+
123+
Expected output:
124+
125+
```output
126+
Proxy is listening on port 47011
127+
Merged "aks-workload" as current context in .\\aks-arc-kube-config
128+
Start sending kubectl requests on 'aks-workload' context using
129+
kubeconfig at .\\aks-arc-kube-config
130+
Press Ctrl+C to close proxy.
131+
```
132+
133+
Keep this session running and connect to your Kubernetes cluster from a different terminal/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:
134+
135+
```azurecli
136+
kubectl get node -A --kubeconfig .\aks-arc-kube-config
137+
```
138+
139+
The following output example shows the node created in the previous steps. Make sure the node status is **Ready**:
140+
141+
```output
142+
NAME STATUS ROLES AGE VERSION
143+
moc-l0ttdmaioew Ready control-plane,master 34m v1.24.11
144+
moc-ls38tngowsl Ready <none> 32m v1.24.11
145+
```
146+
147+
## Next steps
148+
149+
-[AKS Arc overview](overview.md)

0 commit comments

Comments
 (0)