Skip to content

Commit 4cf31cc

Browse files
sethmanheimsethmanheim
committed
Add Edge Essentials workload identity article
1 parent 892a2e4 commit 4cf31cc

File tree

2 files changed

+267
-0
lines changed

2 files changed

+267
-0
lines changed

‎AKS-Hybrid/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,8 @@
206206
href: aks-edge-howto-more-configs.md
207207
- name: Use GPU acceleration
208208
href: aks-edge-gpu.md
209+
- name: Deploy and configure Workload Identity for AKS Edge Essentials clusters
210+
href: aks-edge-workload-identity.md
209211
- name: Update AKS Edge Essentials
210212
items:
211213
- name: Update online

‎AKS-Hybrid/aks-edge-workload-identity.md

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
title: Deploy and configure Workload Identity on an AKS Edge Essentials cluster (preview)
3+
description: Learn how to deploy and configure an AKS Edge Essentials cluster with workload identity.
4+
author: sethmanheim
5+
ms.author: sethm
6+
ms.topic: how-to
7+
ms.date: 11/12/2024
8+
9+
---
10+
11+
# Deploy and configure Workload Identity on an AKS Edge Essentials cluster (preview)
12+
13+
[!INCLUDE [hci-applies-to-23h2](includes/hci-applies-to-23h2.md)]
14+
15+
Azure Kubernetes Service (AKS) Edge Essentials is an on-premises Kubernetes implementation of Azure Kubernetes Service (AKS) that automates running containerized applications at scale. This article describes how to perform the following tasks:
16+
17+
- Create a Kubernetes service account and bind it to the Azure Managed Identity.
18+
- Create a federated credential on the managed identity to trust the OIDC issuer.
19+
- Optional: Grant a pod in the cluster access to secrets in an Azure key vault.
20+
- Deploy your application.
21+
22+
For a conceptual overview of using Workload Identity federation with Azure Arc-enabled Kubernetes clusters, see [Deploy and configure Workload Identity on an AKS enabled by Azure Arc cluster (preview)](workload-identity.md).
23+
24+
> [!IMPORTANT]
25+
> These 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 Service Edge Essentials previews are partially covered by customer support on a best-effort basis.
26+
27+
> [!NOTE]
28+
> In this public preview, AKS Edge Essentials allows you to enable workload identity during the initial deployment of the Azure IoT Operations quickstart script. This feature is not available for other AKS Edge Essentials scenarios.
29+
30+
## Prerequisites
31+
32+
Before using workload identity federation for an AKS Edge Essentials cluster, you must deploy the Azure IoT Operation quickstart script as described in [Create and configure an AKS Edge Essentials cluster that can run Azure IoT Operations](aks-edge-howto-deploy-azure-iot.md). The script automatically enables the workload identity federation feature on the AKS Edge Essentials cluster.
33+
34+
After you deploy the AKS Edge Essentials cluster, you can use the following command to check the status of the workload identity extension:
35+
36+
```azurecli
37+
az connectedk8s show -n $aks_cluster_name -g $resource_group_name
38+
```
39+
40+
```output
41+
# agentState = "Succeeded"
42+
"agentPublicKeyCertificate": "",
43+
"agentVersion": "1.21.10",
44+
"arcAgentProfile": {
45+
"agentAutoUpgrade": "Enabled",
46+
"agentErrors": [],
47+
"agentState": "Succeeded",
48+
"desiredAgentVersion": "",
49+
"systemComponents": null
50+
51+
# oidcIssuerProfile "enabled": true and "issuerUrl" present
52+
"oidcIssuerProfile": {
53+
"enabled": true,
54+
"issuerUrl": "https://oidcdiscovery-{location}-endpoint-1111111111111111.000.azurefd.net/00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111/",
55+
56+
# workloadIdentity "enabled": true
57+
"securityProfile": {
58+
"workloadIdentity": {
59+
"enabled": true
60+
```
61+
62+
In the Azure portal, you can view the `wiextension` extension under the **Properties** section of your Kubernetes cluster.
63+
64+
### Export environment variables
65+
66+
To help simplify the steps to configure the required identities, the following steps define environment variables that are referenced in the examples in this article. Remember to replace the values shown with your own values:
67+
68+
```azurecli
69+
$AZSubscriptionID = "00000000-0000-0000-0000-000000000000"
70+
$Location = "westeurope"
71+
$resource_group_name = "myResourceGroup"
72+
73+
$aks_cluster_name = "myAKSCluster"
74+
75+
$SERVICE_ACCOUNT_NAMESPACE = "default"
76+
$SERVICE_ACCOUNT_NAME = "workload-identity-sa"
77+
78+
$FedIdCredentialName = "myFedIdentity"
79+
$MSIName = "myIdentity"
80+
81+
# Include these variables to access key vault secrets from a pod in the cluster.
82+
$KVName = "KV-workload-id"
83+
$KVSecretName= "KV-secret"
84+
```
85+
86+
### Save the OIDC issuer URL to an environment variable
87+
88+
To get the OIDC issuer URL and save it to an environment variable, run the following command:
89+
90+
```azurecli
91+
$SERVICE_ACCOUNT_ISSUER =$(az connectedk8s show --n $aks_cluster_name --resource-group $resource_group_name --query "oidcIssuerProfile.issuerUrl" --output tsv)
92+
```
93+
94+
## Step 1: Create a Kubernetes service account and bind it to the Azure Managed Identity
95+
96+
First, call the [az identity create](/cli/azure/identity#az-identity-create) command to create a managed identity:
97+
98+
```azurecli
99+
az identity create --name $MSIName --resource-group $resource_group_name --location $Location --subscription $AZSubscriptionID
100+
```
101+
102+
Next, create variables for the managed identity's client ID:
103+
104+
```azurecli
105+
$MSIId=$(az identity show --resource-group $resource_group_name --name $MSIName --query 'clientId' --output tsv) 
106+
$MSIPrincipalId=$(az identity show --resource-group $resource_group_name --name $MSIName --query 'principalId' --output tsv)
107+
```
108+
109+
### Create a Kubernetes service account
110+
111+
Create a Kubernetes service account and annotate it with the client ID of the managed identity you created in the previous step. Copy and paste the following Azure CLI commands:
112+
113+
```azurecli
114+
$yaml = @"
115+
apiVersion: v1
116+
kind: ServiceAccount
117+
metadata:
118+
annotations:
119+
azure.workload.identity/client-id: $MSIId
120+
name: $SERVICE_ACCOUNT_NAME
121+
namespace: $SERVICE_ACCOUNT_NAMESPACE
122+
"@
123+
124+
# Replace variables within the YAML content
125+
$yaml = $yaml -replace '\$MSIId', $MSIId `
126+
-replace '\$SERVICE_ACCOUNT_NAME', $SERVICE_ACCOUNT_NAME `
127+
-replace '\$SERVICE_ACCOUNT_NAMESPACE', $SERVICE_ACCOUNT_NAMESPACE
128+
129+
# Apply the YAML content to Kubernetes
130+
$yaml | kubectl apply -f -
131+
```
132+
133+
The following output shows the workload identity created successfully:
134+
135+
```output
136+
serviceaccount/workload-identity-sa created
137+
```
138+
139+
## Step 2: Create a federated credential on the managed identity to trust the OIDC issuer
140+
141+
To create the federated identity credential between the managed identity, the service account issuer, and the subject, call the [az identity federated-credential create](/cli/azure/identity/federated-credential#az-identity-federated-credential-create) command. For more information about federated identity credentials in Microsoft Entra, see [Overview of federated identity credentials in Microsoft Entra ID](/cli/azure/identity/federated-credential#az-identity-federated-credential-create).
142+
143+
```azurecli
144+
# Create a federated credential
145+
az identity federated-credential create --name $FedIdCredentialName --identity-name $MSIName --resource-group $resource_group_name --issuer $SERVICE_ACCOUNT_ISSUER --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"
146+
147+
# Show the federated credential
148+
az identity federated-credential show --name $FedIdCredentialName --resource-group $resource_group_name --identity-name $MSIName
149+
```
150+
151+
> [!NOTE]
152+
> After you add a federated identity credential, it takes a few seconds to propagate. Token requests made immediately afterward might fail until the cache refreshes. To prevent this issue, consider adding a brief delay after creating the federated identity credential.
153+
154+
## Optional: Grant permissions to access Azure Key Vault
155+
156+
The instructions in this step describe how to access secrets, keys, or certificates in an Azure key vault from the pod. The examples in this section configure access to secrets in the key vault for the workload identity, but you can perform similar steps to configure access to keys or certificates.
157+
158+
The following example shows how to use the Azure role-based access control (Azure RBAC) permission model to grant the pod access to the key vault. For more information about the Azure RBAC permission model for Azure Key Vault, see [Grant permission to applications to access an Azure key vault using Azure RBAC](/azure/key-vault/general/rbac-guide).
159+
160+
1. Create a key vault with purge protection and RBAC authorization enabled. You can also use an existing key vault if it is configured for both purge protection and RBAC authorization:
161+
162+
```azurecli
163+
az keyvault create --name $KVName --resource-group $resource_group_name --location $Location --enable-purge-protection --enable-rbac-authorization
164+
165+
# retrieve the key vault ID for role assignment
166+
$KVId=$(az keyvault show --resource-group $resource_group_name --name $KVName --query id --output tsv)
167+
```
168+
169+
1. Assign the RBAC [Key Vault Secrets Officer](/azure/role-based-access-control/built-in-roles/security#key-vault-secrets-officer) role to yourself so that you can create a secret in the new key vault. New role assignments can take up to five minutes to propagate and be updated by the authorization server.
170+
171+
```azurecli
172+
az role assignment create --assignee-object-id $MSIPrincipalId --role "Key Vault Secrets Officer" --scope $KVId --assignee-principal-type ServicePrincipal
173+
```
174+
175+
1. Create a secret in the key vault:
176+
177+
```azurecli
178+
az keyvault secret set --vault-name $KVName --name $KVSecretName --value "Hello!"
179+
```
180+
181+
1. Assign the [Key Vault Secrets User](/azure/role-based-access-control/built-in-roles/security#key-vault-secrets-user) role to the user-assigned managed identity that you created previously. This step gives the managed identity permission to read secrets from the key vault:
182+
183+
```azurecli
184+
az role assignment create --assignee-object-id $MSIPrincipalId --role "Key Vault Secrets User" --scope $KVId --assignee-principal-type ServicePrincipal
185+
```
186+
187+
1. Create an environment variable for the key vault URL:
188+
189+
```azurecli
190+
$KVUrl=$(az keyvault show --resource-group $resource_group_name --name $KVName --query properties.vaultUri --output tsv)
191+
```
192+
193+
1. Deploy a pod that references the service account and key vault URL:
194+
195+
```azurecli
196+
$yaml = @"
197+
apiVersion: v1
198+
kind: Pod
199+
metadata:
200+
name: sample-quick-start
201+
namespace: $SERVICE_ACCOUNT_NAMESPACE
202+
labels:
203+
azure.workload.identity/use: "true"
204+
spec:
205+
serviceAccountName: $SERVICE_ACCOUNT_NAME
206+
containers:
207+
- image: ghcr.io/azure/azure-workload-identity/msal-go
208+
name: oidc
209+
env:
210+
- name: KEYVAULT_URL
211+
value: $KVUrl
212+
- name: SECRET_NAME
213+
value: $KVSecretName
214+
nodeSelector:
215+
kubernetes.io/os: linux
216+
"@
217+
218+
# Replace variables within the YAML content
219+
$yaml = $yaml -replace '\$SERVICE_ACCOUNT_NAMESPACE', $SERVICE_ACCOUNT_NAMESPACE `
220+
-replace '\$SERVICE_ACCOUNT_NAME', $SERVICE_ACCOUNT_NAME `
221+
-replace '\$KVUrl', $KVUrl `
222+
-replace '\$KVSecretName', $KVSecretName
223+
224+
# Apply the YAML configuration
225+
$yaml | kubectl --kubeconfig $aks_cluster_name apply -f -
226+
```
227+
228+
## Step 3: Deploy your application
229+
230+
When you deploy your application pods, the manifest should reference the service account created in the **Create Kubernetes service account** step. The following manifest shows how to reference the account, specifically the `metadata\namespace` and `spec\serviceAccountName` properties. Make sure to specify an image for `image` and a container name
231+
for `containerName`:
232+
233+
```azurecli
234+
$image = "<image>" # Replace <image> with the actual image name
235+
$containerName = "<containerName>" # Replace <containerName> with the actual container name
236+
237+
$yaml = @"
238+
apiVersion: v1
239+
kind: Pod
240+
metadata:
241+
name: sample-quick-start
242+
namespace: $SERVICE_ACCOUNT_NAMESPACE
243+
labels:
244+
azure.workload.identity/use: "true" # Required. Only pods with this label can use workload identity.
245+
spec:
246+
serviceAccountName: $SERVICE_ACCOUNT_NAME
247+
containers:
248+
- image: $image
249+
name: $containerName
250+
"@
251+
252+
# Replace variables within the YAML content
253+
$yaml = $yaml -replace '\$SERVICE_ACCOUNT_NAMESPACE', $SERVICE_ACCOUNT_NAMESPACE `
254+
-replace '\$SERVICE_ACCOUNT_NAME', $SERVICE_ACCOUNT_NAME
255+
256+
# Apply the YAML configuration
257+
$yaml | kubectl apply -f -
258+
```
259+
260+
> [!IMPORTANT]
261+
> Ensure that the application pods using workload identity include the label `azure.workload.identity/use: "true"` in the pod spec. Otherwise the pods fail after they restart.
262+
263+
## Next steps
264+
265+
In this article, you deployed a Kubernetes cluster and configured it to use a workload identity in preparation for application workloads to authenticate with that credential. Now you're ready to deploy your application and configure it to use the workload identity with the latest version of the [Azure Identity client library](/azure/active-directory/develop/reference-v2-libraries).

0 commit comments

Comments
 (0)