Skip to content

Commit a6c9a13

Browse files
sethmanheimsethmanheim
committed
AKS EE: new article for Key Manager extension
1 parent 31c9e55 commit a6c9a13

File tree

2 files changed

+120
-0
lines changed

2 files changed

+120
-0
lines changed

‎AKS-Arc/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,8 @@
226226
href: aks-edge-howto-access-tpm.md
227227
- name: Enable secret encryption with the KMS plugin
228228
href: aks-edge-howto-secret-encryption.md
229+
- name: Use the Key Manager for Kubernetes extension
230+
href: aks-edge-howto-key-manager.md
229231
- name: Update AKS Edge Essentials
230232
items:
231233
- name: Update online

‎AKS-Arc/aks-edge-howto-key-manager.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Use Key Manager for Kubernetes clusters on AKS Edge Essentials (preview)
3+
description: Learn how to use the Key Manager for Kubernetes extension to rotate service account keys in Azure Kubernetes Service (AKS) Edge Essentials clusters.
4+
ms.topic: how-to
5+
author: sethmanheim
6+
ms.author: sethm
7+
ms.date: 02/24/2025
8+
ms.reviewer: leslielin
9+
---
10+
11+
# How-to: use Key Manager for Kubernetes on an AKS Edge Essentials cluster (preview)
12+
13+
The [Kubernetes service account](https://kubernetes.io/docs/concepts/security/service-accounts/) is a a non-human account that provides a unique identity within a Kubernetes cluster. Service account tokens serve important security and authentication functions in Kubernetes.
14+
15+
In AKS Edge Essentials, *service account tokens* enable workload pods to authenticate and access Azure resources through [*workload identity federation*](aks-edge-workload-identity.md). Key Manager for Kubernetes is an Azure Arc extension that automates the rotation of the signing key used to issue these service account tokens. The rotation reduces the risk of token misuse and improves the overall security posture of the cluster.
16+
17+
The following table compares the default behavior with and without using the Key Manager for Kubernetes extension:
18+
19+
| Behavior | By default, without the Key Manager extension | With the Key Manager extension |
20+
|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
21+
| Automated service account key rotation | By default, Kubernetes doesn't automatically rotate service account signing keys. Instead, it uses the same key indefinitely to sign tokens. | Once enabled, the service account signing key is rotated automatically every 45 days. |
22+
| Service account signing key validity | Unlimited | 90 days |
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+
> During the preview, the Key Manager for Kubernetes is only available for AKS Edge Essentials K3s version 1.30.6 or later single control plane node deployments with Arc connectivity. It's not compatible with other Arc-enabled Kubernetes distributions.
29+
30+
## Before you begin
31+
32+
Before you begin, ensure you have the following prerequisites:
33+
34+
- An AKS Edge Essentials K3s cluster with Arc connectivity. If you plan to use Azure IoT Operations with AKS Edge Essentials, follow this [Quickstart guide](aks-edge-howto-deploy-azure-iot.md#create-an-arc-enabled-cluster) to create your cluster.
35+
- To enable TLS for intracluster log communication, the `cert-manager` and `trust-manager` tools are required.
36+
- If you plan to [use Azure IoT Operations](/azure/iot-operations/get-started-end-to-end-sample/quickstart-deploy#deploy-azure-iot-operations), deploy it before installing the Key Manager for Kubernetes extension, since Azure IoT Operations installs its own copy of these applications by default.
37+
- To verify if `cert-manager` and `trust-manager` are installed, run the following command::
38+
39+
```bash
40+
kubectl get pods -n cert-manager
41+
```
42+
43+
If they are installed, you can see their pods in a running state.
44+
45+
- If `cert-manager` and `trust-manager` are not present, follow the documentation to:
46+
47+
1. Install [cert-manager](https://cert-manager.io/docs/installation/).
48+
1. Install [trust-manager](https://cert-manager.io/docs/trust/trust-manager/installation/). While installing trust manager, set the `trust namespace` to `cert-manager`. For example:
49+
50+
```bash
51+
helm upgrade trust-manager jetstack/trust-manager --install --namespace cert-manager --set app.trust.namespace=cert-manager --wait
52+
```
53+
54+
`trust-manager` is used to distribute a trust bundle to components.
55+
56+
- The key manager extension only works with [bounded service account tokens](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/#manual-secret-management-for-serviceaccounts). It doesn't support legacy tokens with infinite lifetimes. If your workflow relies on legacy tokens, do not install this extension.
57+
- Bounded service account tokens have a default lifetime of one year. To rotate these tokens, this lifetime should be reduced to one day, which ensures that tokens are rapidly reissued and signed with newly rotated keys. To implement these changes, you must modify the `api-server` configuration as follows.
58+
59+
Run the following commands:
60+
61+
```powershell
62+
$url = "https://raw.githubusercontent.com/Azure/AKS-Edge/refs/heads/main/tools/scripts/AksEdgeKeyManagerExtension/UpdateK3sConfigForKeyManager.ps1"
63+
Invoke-WebRequest -Uri $url -OutFile .\UpdateK3sConfigForKeyManager.ps1
64+
Unblock-File .\UpdateK3sConfigForKeyManager.ps1
65+
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
66+
67+
.\UpdateK3sConfigForKeyManager.ps1
68+
```
69+
70+
## Install the Key Manager for Kubernetes extension for service account key rotation
71+
72+
> [!IMPORTANT]
73+
> After you install the key manager, the `api-server` is updated with the new service account token during token rotation. This process briefly makes the API server inaccessible as it restarts.
74+
75+
Now run the following commands. Replace the variables with your specific resource group name and AKS cluster name:
76+
77+
# [Azure PowerShell](#tab/powershell)
78+
79+
```powershell
80+
New-AzKubernetesExtension -SubscriptionId $yoursubscriptionID -ResourceGroupName $resource_group_name -ClusterName $aks_cluster_name -ClusterType connectedClusters -Name "MySAkeymanager" -ExtensionType microsoft.arc.kuberneteskeymanager
81+
```
82+
83+
# [Azure CLI](#tab/azurecli)
84+
85+
```azurecli
86+
az k8s-extension create -g $resource_group_name -c $aks_cluster_name -t connectedClusters -n "MySAkeymanager" --extension-type microsoft.arc.kuberneteskeymanager
87+
```
88+
89+
---
90+
91+
After you install the extension, you can view the **MySAkeymanager** extension in the Azure portal under the **Settings/Extensions** section of your Kubernetes cluster.
92+
93+
## Remove key manager for Kubernetes extension
94+
95+
You can uninstall the Key Manager extension using the [az k8s-extension delete](/cli/azure/k8s-extension#az-k8s-extension-delete) command:
96+
97+
# [Azure PowerShell](#tab/powershell)
98+
99+
```powershell
100+
Remove-AzKubernetesExtension -ResourceGroupName $resource_group_name -ClusterName $aks_cluster_name -ClusterType connectedClusters -Name "MySAkeymanager"
101+
```
102+
103+
# [Azure CLI](#tab/azurecli)
104+
105+
```azurecli
106+
az k8s-extension delete -g $resource_group_name -c $aks_cluster_name -t connectedClusters -n "MySAkeymanager"
107+
```
108+
109+
---
110+
111+
## Working with Azure IoT Operations
112+
113+
If you installed the Key Manager for Kubernetes extension before you deployed Azure IoT Operations, you must follow the [Bring your own issuer](/azure/iot-operations/secure-iot-ops/concept-default-root-ca#bring-your-own-issuer) instructions, as Azure IoT Operations installs `cert-manager` and `trust-manager` by default.
114+
115+
## Next steps
116+
117+
- [Deploy and configure workload identity on an AKS cluster](/azure/aks/workload-identity-deploy-cluster)
118+
- [Configure Workload Identity on an AKS Edge Essentials cluster](aks-edge-workload-identity.md)

0 commit comments

Comments
 (0)