Freshness pass

schaffererin · schaffererin · commit bdfaaa426ae0 · 2023-04-24T16:03:59.000-07:00
diff --git a/articles/aks/custom-certificate-authority.md b/articles/aks/custom-certificate-authority.md
@@ -5,82 +5,71 @@ author: rayoef
 ms.author: rayoflores
 ms.topic: article
 ms.custom: devx-track-azurecli
-ms.date: 4/12/2022
+ms.date: 4/24/2022
 ---
 
 # Custom certificate authority (CA) in Azure Kubernetes Service (AKS) (preview)
 
-Custom certificate authorities (CAs) allow you to establish trust between your Azure Kubernetes Service (AKS) cluster and your workloads, such as private registries, proxies, and firewalls. A Kubernetes secret is used to store the certificate authority's information, then it's passed to all nodes in the cluster.
+Custom certificate authorities (CAs) allow you to establish trust between your Azure Kubernetes Service (AKS) clusters and workloads, such as private registries, proxies, and firewalls. A Kubernetes secret stores the certificate authority's information, and then it's passed to all nodes in the cluster.
 
-This feature is applied per nodepool, so new and existing node pools must be configured to enable this feature.
+This feature is applied per node pool, so new and existing node pools must be configured to enable this feature.
 
 ## Prerequisites
 
-* An Azure subscription. If you don't have an Azure subscription, you can create a [free account](https://azure.microsoft.com/free).
+* An Azure subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free).
 * [Azure CLI installed][azure-cli-install] (version 2.43.0 or greater).
 * A base64 encoded certificate string or a text file with certificate.
 
 ## Limitations
 
-This feature isn't currently supported for Windows node pools.
+* This feature currently isn't supported for Windows node pools.
 
-## Install the aks-preview Azure CLI extension
+## Install the `aks-preview` Azure CLI extension
 
 [!INCLUDE [preview features callout](includes/preview/preview-callout.md)]
 
-To install the aks-preview extension, run the following command:
+Install the aks-preview extension using the [`az extension add`][az-extension-add] command.
 
 ```azurecli
 az extension add --name aks-preview
 ```
 
-Run the following command to update to the latest version of the extension released:
+Update to the latest version of the extension using the [`az extension update`][az-extension-update] command.
 
 ```azurecli
 az extension update --name aks-preview
 ```
 
 ## Register the 'CustomCATrustPreview' feature flag
 
-Register the `CustomCATrustPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:
+Register the `CustomCATrustPreview` feature flag using the [`az feature register`][az-feature-register] command. It takes a few minutes for the status to show *Registered*.
 
 ```azurecli
 az feature register --namespace "Microsoft.ContainerService" --name "CustomCATrustPreview"
 ```
 
-It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature show][az-feature-show] command:
+Verify the registration status using the [`az feature show`][az-feature-show] command.
 
-```azurecli-interactive
+```azurecli
 az feature show --namespace "Microsoft.ContainerService" --name "CustomCATrustPreview"
 ```
 
-When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:
+When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider using the [`az provider register`][az-provider-register] command.
 
-```azurecli-interactive
+```azurecli
 az provider register --namespace Microsoft.ContainerService
 ```
 
-## Two ways for custom CA installation on AKS node pools
+## Custom CA installation on AKS node pools
 
-Two ways of installing custom CAs on your AKS cluster are available. They're intended for different use cases, which are outlined below.
+### Install CAs during node pool creation
 
-### Install CAs during node pool boot up
-If your environment requires your custom CAs to be added to node trust store for correct provisioning,
-text file containing up to 10 blank line separated certificates needs to be passed during
-[az aks create][az-aks-create] or [az aks update][az-aks-update] operations.
+If your environment requires your custom CAs to be added to node trust store for correct provisioning, you need to pass a text file containing up to 10 blank line separated certificates during
+[`az aks create`][az-aks-create] or [`az aks update`][az-aks-update] operations.
 
-Example command:
-```azurecli
-az aks create \
-    --resource-group myResourceGroup \
-    --name myAKSCluster \
-    --node-count 2 \
-    --enable-custom-ca-trust \
-    --custom-ca-trust-certificates pathToFileWithCAs
-```
+Example text file:
 
-Example file:
-```
+```txt
 -----BEGIN CERTIFICATE-----
 cert1
 -----END CERTIFICATE-----
@@ -90,10 +79,19 @@ cert2
 -----END CERTIFICATE-----
 ```
 
-CAs will be added to node's trust store during node boot up process, allowing the node to, for example access a private registry.
+```azurecli
+az aks create \
+    --resource-group myResourceGroup \
+    --name myAKSCluster \
+    --node-count 2 \
+    --enable-custom-ca-trust \
+    --custom-ca-trust-certificates pathToFileWithCAs
+```
 
 #### CA rotation for availability during node pool boot up
-To update CAs passed to cluster during boot up [az aks update][az-aks-update] operation has to be used.
+
+You can update CAs passed to your cluster during boot up using the [`az aks update`][az-aks-update] command and specifying your text file.
+
 ```azurecli
 az aks update \
     --resource-group myResourceGroup \
@@ -102,19 +100,13 @@ az aks update \
 ```
 
 > [!NOTE]
-> Running this operation will trigger a model update, to ensure that new nodes added during for example scale up operation have the newest CAs required for correct provisioning.
-> This means that AKS will create additional nodes, drain currently existing ones, delete them and then replace them with nodes that have the new set of CAs installed.
-
+> This operation triggers a model update, ensuring new nodes have the newest CAs required for correct provisioning. AKS creates additional nodes, drains existing ones, deletes them, and replaces them with nodes that have the new set of CAs installed.
 
 ### Install CAs once node pool is up and running
-If your environment can be successfully provisioned without your custom CAs, you can provide the CAs using a secret deployed in the kube-system namespace.
-This approach allows for certificate rotation without the need for node recreation.
 
-Create a [Kubernetes secret][kubernetes-secrets] YAML manifest with your base64 encoded certificate string in the `data` field. Data from this secret is used to update CAs on all nodes.
+If your environment can be successfully provisioned without your custom CAs, you can provide the CAs by deploying a secret in the `kube-system` namespace. This approach allows for certificate rotation without the need for node recreation.
 
-You must ensure that:
-* The secret is named `custom-ca-trust-secret`.
-* The secret is created in the `kube-system` namespace.
+Create a [Kubernetes secret][kubernetes-secrets] YAML manifest with your base64 encoded certificate string in the `data` field. Data from this secret is used to update CAs on all nodes. Make sure the secret is named `custom-ca-trust-secret` and is created in the `kube-system` namespace. Installing CAs using the secret in the `kube-system` namespace allows for CA rotation without the need for node recreation.
 
 ```yaml
 apiVersion: v1
@@ -130,18 +122,16 @@ data:
       {anotherBase64EncodedCertStringHere}
 ```
 
-To update or remove a CA, edit and apply the secret's YAML manifest. The cluster will poll for changes and update the nodes accordingly. This process may take a couple of minutes before changes are applied.
-
-Sometimes containerd restart on the node might be required for the CAs to be picked up properly. If it appears like CAs aren't added correctly to your node's trust store, you can trigger such restart using the following command from node's shell:
-
-```systemctl restart containerd```
+To update or remove a CA, you can edit and apply the YAML manifest. The cluster polls for changes and updates the nodes accordingly. It may take a couple minutes before changes are applied.
 
 > [!NOTE]
-> Installing CAs using the secret in the kube-system namespace will allow for CA rotation without need for node recreation.
+> Sometimes, containerd restart on the node might be required for the CAs to be picked up properly. If it appears like CAs aren't correctly added to your node's trust store, you can trigger a restart using the following command from node's shell:
+>
+> ```systemctl restart containerd```
 
 ## Configure a new AKS cluster to use a custom CA
 
-To configure a new AKS cluster to use a custom CA, run the [az aks create][az-aks-create] command with the `--enable-custom-ca-trust` parameter.
+Configure a new AKS cluster to use a custom CA using the [`az aks create`][az-aks-create] command with the `--enable-custom-ca-trust` parameter.
 
 ```azurecli
 az aks create \
@@ -151,7 +141,7 @@ az aks create \
     --enable-custom-ca-trust
 ```
 
-To configure a new AKS cluster to use custom CA with CAs installed before node boots up,  run the [az aks create][az-aks-create] command with the `--enable-custom-ca-trust` and `--custom-ca-trust-certificates` parameters.
+You can also configure a new AKS cluster to use custom CA with CAs installed before the node boots up using the [`az aks create`][az-aks-create] command with the `--enable-custom-ca-trust` and `--custom-ca-trust-certificates` parameters.
 
 ```azurecli
 az aks create \
@@ -164,7 +154,7 @@ az aks create \
 
 ## Configure an existing AKS cluster to have custom CAs installed before node boots up
 
-To configure an existing AKS cluster to have your custom CAs added to node's trust store before it boots up, run  [az aks update][az-aks-update] command with the `--custom-ca-trust-certificates` parameter.
+Configure an existing AKS cluster to have your custom CAs added to node's trust store before it boots up using the [`az aks update`][az-aks-update] command with the `--custom-ca-trust-certificates` parameter.
 
 ```azurecli
 az aks update \
@@ -175,7 +165,7 @@ az aks update \
 
 ## Configure a new node pool to use a custom CA
 
-To configure a new node pool to use a custom CA, run the [az aks nodepool add][az-aks-nodepool-add] command with the `--enable-custom-ca-trust` parameter.
+Configure a new node pool to use a custom CA using the [`az aks nodepool add`][az-aks-nodepool-add] command with the `--enable-custom-ca-trust` parameter.
 
 ```azurecli
 az aks nodepool add \
@@ -186,22 +176,17 @@ az aks nodepool add \
     --os-type Linux
 ```
 
-If there are currently no other node pools with the feature enabled, cluster will have to reconcile its settings for
-the changes to take effect. Before that happens, daemonset and pods, which install CAs won't appear on the cluster.
-This operation will happen automatically as a part of AKS's reconcile loop.
-You can trigger reconcile operation immediately by running the [az aks update][az-aks-update] command:
+If no other node pools with the feature enabled exist, the cluster has to reconcile its settings for the changes to take effect. This operation happens automatically as a part of AKS's reconcile loop. Before the operation, the daemonset and pods won't appear on the cluster. You can trigger an immediate reconcile operation using the [`az aks update`][az-aks-update] command. The daemonset and pods will appear after the update completes.
 
 ```azurecli
 az aks update \
  --resource-group myResourceGroup \
  --name cluster-name
 ```
 
-Once completed, the daemonset and pods will appear in the cluster.
-
 ## Configure an existing node pool to use a custom CA
 
-To configure an existing node pool to use a custom CA, run the [az aks nodepool update][az-aks-nodepool-update] command with the `--enable-custom-trust-ca` parameter.
+Configure an existing node pool to use a custom CA using the [`az aks nodepool update`][az-aks-nodepool-update] command with the `--enable-custom-trust-ca` parameter.
 
 ```azurecli
 az aks nodepool update \
@@ -211,25 +196,24 @@ az aks nodepool update \
     --enable-custom-ca-trust
 ```
 
-If there are currently no other node pools with the feature enabled, cluster will have to reconcile its settings for
-the changes to take effect. Before that happens, daemon set and pods, which install CAs won't appear on the cluster.
-This operation will happen automatically as a part of AKS's reconcile loop.
-You can trigger reconcile operation by running the following command:
+If no other node pools with the feature enabled exist, the cluster has to reconcile its settings for the changes to take effect. This operation happens automatically as a part of AKS's reconcile loop. Before the operation, the daemonset and pods won't appear on the cluster. You can trigger an immediate reconcile operation using the [`az aks update`][az-aks-update] command. The daemonset and pods will appear after the update completes.
 
 ```azurecli
 az aks update -g myResourceGroup --name cluster-name
 ```
 
-Once complete, the daemonset and pods will appear in the cluster.
-
 ## Troubleshooting
 
 ### Feature is enabled and secret with CAs is added, but operations are failing with X.509 Certificate Signed by Unknown Authority error
+
 #### Incorrectly formatted certs passed in the secret
+
 AKS requires certs passed in the user-created secret to be properly formatted and base64 encoded. Make sure the CAs you passed are properly base64 encoded and that files with CAs don't have CRLF line breaks.
-Certificates passed to ```--custom-ca-trust-certificates``` option shouldn't be base64 encoded.
-#### Containerd hasn't picked up new certs
-From node's shell, run ```systemctl restart containerd```, once containerd is restarted, new certs will be properly picked up by the container runtime.
+Certificates passed to ```--custom-ca-trust-certificates``` shouldn't be base64 encoded.
+
+#### containerd hasn't picked up new certs
+
+From the node's shell, run ```systemctl restart containerd```. Once containerd is restarts, the new certs will be properly picked up by the container runtime.
 
 ## Next steps
 
