|
| 1 | +--- |
| 2 | +title: Enable secret encryption on an AKS Edge Essentials cluster (preview) |
| 3 | +description: Learn how to enable the KMS plugin for AKS Edge Essentials clusters to encrypt secrets. |
| 4 | +author: sethmanheim |
| 5 | +ms.author: sethm |
| 6 | +ms.topic: how-to |
| 7 | +ms.date: 02/13/2025 |
| 8 | +ms.custom: template-how-to |
| 9 | +ms.reviewer: leslielin |
| 10 | +--- |
| 11 | + |
| 12 | +# Enable secret encryption on an AKS Edge Essentials cluster (preview) |
| 13 | + |
| 14 | +Following Kubernetes security best practices, it's recommended that you encrypt the Kubernetes secret store on AKS Edge Essentials clusters. You can perform this encryption by activating the *Key Management Service (KMS) plugin for AKS Edge Essentials*, which enables [encryption at rest for secrets](https://kubernetes.io/docs/concepts/configuration/secret/) stored in the etcd key-value store. It enables this encryption by generating a Key Encryption Key (KEK) and automatically rotating it every 30 days. The KEK is protected with administrator credentials and is accessible only to administrators. |
| 15 | + |
| 16 | +For more detailed information about using KMS, see the official [KMS provider documentation](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/). |
| 17 | + |
| 18 | +This article demonstrates how to activate the KMS plugin for AKS Edge Essentials clusters. |
| 19 | + |
| 20 | +> [!IMPORTANT] |
| 21 | +> The KMS plugin for AKS Edge Essentials is currently in PREVIEW. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability. |
| 22 | +
|
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +The KMS plugin is supported for all AKS Edge Essentials clusters, version 1.10.xxx.0 and later. |
| 26 | + |
| 27 | +> [!NOTE] |
| 28 | +> The KMS plugin can only be used for single node clusters. The plugin can't be used with [experimental features such as multi-node and Windows node](aks-edge-system-requirements.md#experimental-or-prerelease-features). |
| 29 | +
|
| 30 | +## Enable the KMS plugin |
| 31 | + |
| 32 | +In your [**aksedge-config.json** file](aks-edge-deployment-config-json.md), in the `Init` section, set `Init.KmsPlugin.Enable` to `true`: |
| 33 | + |
| 34 | +```json |
| 35 | +"Init": { |
| 36 | + "KmsPlugin": { |
| 37 | + "Enable": true |
| 38 | + } |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +The following output is displayed during deployment, showing that the KMS plugin is enabled: |
| 43 | + |
| 44 | +```output |
| 45 | +Preparing to install kms-plugin as encryption provider... |
| 46 | +``` |
| 47 | + |
| 48 | +For deployment instructions, see [Single machine deployment](aks-edge-howto-single-node-deployment.md). |
| 49 | + |
| 50 | +> [!NOTE] |
| 51 | +> You can only enable or disable the KMS plugin when you create a new deployment. Once you set the flag, it can't be changed. |
| 52 | +
|
| 53 | +To create secrets in AKS Edge Essentials clusters, see [Managing Secrets using kubectl](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/#use-raw-data) in the Kubernetes documentation. |
| 54 | + |
| 55 | +If you encounter errors, see the [Troubleshooting](#troubleshooting) section. |
| 56 | + |
| 57 | +## Troubleshooting |
| 58 | + |
| 59 | +If there are errors with the KMS plugin, follow this procedure: |
| 60 | + |
| 61 | +1. Check that the AKS version is **1.10.xxx.0** or later. Use the following command to check the current version of AKS Edge Essentials: |
| 62 | + |
| 63 | + ```powershell |
| 64 | + Get-Command -Module AKSEdge | Format-Table Name, Version |
| 65 | + ``` |
| 66 | + |
| 67 | + If the version is older, upgrade to the latest version. For more information, see [Upgrade an AKS cluster](aks-edge-howto-update.md). |
| 68 | + |
| 69 | +1. View the `readyz` API. If the problem persists, validate that the installation succeeded. To check the health of the KMS plugin, run the following command and ensure that the health status of **kms-providers** is **OK**: |
| 70 | + |
| 71 | + ```powershell |
| 72 | + kubectl get --raw='/readyz?verbose' |
| 73 | + ``` |
| 74 | + |
| 75 | + ```output |
| 76 | + [+]ping ok |
| 77 | + [+]Log ok |
| 78 | + [+]etcd ok |
| 79 | + [+]kms-providers ok |
| 80 | + [+]poststarthook/start-encryption-provider-config-automatic-reload ok |
| 81 | + ``` |
| 82 | + |
| 83 | + If you receive "**[-]**" before the `kms-providers` field, collect diagnostic logs for debugging. For more information, see [Get kubelet logs from cluster nodes](aks-get-kubelet-logs.md). |
| 84 | + |
| 85 | +1. Repair KMS. If there are still errors, the machine running the AKS Edge Essentials cluster might be paused or turned off for an extended period of time (over 30 days). To get KMS back into a healthy state, you can use the `Repair-Kms` command to restore any necessary tokens: |
| 86 | + |
| 87 | + ```powershell |
| 88 | + Repair-AksEdgeKms |
| 89 | + ``` |
| 90 | + |
| 91 | +1. If you still encounter errors, contact [Microsoft Customer Support](aks-edge-troubleshoot-overview.md) and [collect logs](aks-get-kubelet-logs.md). |
| 92 | + |
| 93 | +## Next steps |
| 94 | + |
| 95 | +- [Overview](aks-edge-overview.md) |
| 96 | +- [Uninstall AKS cluster](aks-edge-howto-uninstall.md) |
0 commit comments