incorporating feedback

Author: schaffererin

articles/aks/image-integrity.md

@@ -5,14 +5,14 @@ author: schaffererin
 ms.author: schaffererin
 ms.service: azure-kubernetes-service
 ms.topic: article
-ms.date: 09/20/2023
+ms.date: 09/26/2023
 ---
 
 # Use Image Integrity to validate signed images before deploying them to your Azure Kubernetes Service (AKS) clusters (Preview)
 
 Azure Kubernetes Service (AKS) and its underlying container model provide increased scalability and manageability for cloud native applications. With AKS, you can launch flexible software applications according to the runtime needs of your system. However, this flexibility can introduce new challenges.
 
-In these application environments, using signed container images helps verify that your deployments are built from a trusted entity and that images haven't been tampered with since their creation. Image Integrity is a service that allows you to add an AKS built-in policy to verify and enforce that only signed images are deployed to your AKS clusters.
+In these application environments, using signed container images helps verify that your deployments are built from a trusted entity and that images haven't been tampered with since their creation. Image Integrity is a service that allows you to add an Azure Policy built-in definition to verify that only signed images are deployed to your AKS clusters.
 
 > [!NOTE]
 > Image Integrity is a feature based on [Ratify][ratify]. On an AKS cluster, the feature name and property name is `ImageIntegrity`, while the relevant Image Integrity pods' names contain `Ratify`.
@@ -24,7 +24,7 @@ In these application environments, using signed container images helps verify th
 * An Azure subscription. If you don't have an Azure subscription, you can create a [free account](https://azure.microsoft.com/free).
 * [Azure CLI][azure-cli-install] or [Azure PowerShell][azure-powershell-install].
 * `aks-preview` CLI extension version 0.5.96 or later.
-* The Azure Policy add-on for AKS. If you don't have this add-on installed, see [Install Azure Policy add-on for AKS](../governance/policy/concepts/policy-for-kubernetes.md#install-azure-policy-add-on-for-aks).
+* Ensure that the Azure Policy add-on for AKS is enabled on your cluster. If you don't have this add-on installed, see [Install Azure Policy add-on for AKS](../governance/policy/concepts/policy-for-kubernetes.md#install-azure-policy-add-on-for-aks).
 * An AKS cluster enabled with OIDC Issuer. To create a new cluster or update an existing cluster, see [Configure an AKS cluster with OIDC Issuer](./use-oidc-issuer.md).
 * The `EnableImageIntegrityPreview` and `AKS-AzurePolicyExternalData` feature flags registered on your Azure subscription. Register the feature flags using the following commands:
 
@@ -71,14 +71,14 @@ In these application environments, using signed container images helps verify th
 Image Integrity uses Ratify, Azure Policy, and Gatekeeper to validate signed images before deploying them to your AKS clusters. Enabling Image Integrity on your cluster deploys a `Ratify` pod. This `Ratify` pod performs the following tasks:
 
 1. Reconciles certificates from Azure Key Vault per the configuration you set up through `Ratify` CRDs.
-2. Accesses images stored in ACR when validation requests come from [Azure Policy](../governance/policy/concepts/policy-for-kubernetes.md), an admission controller webhook that extends [Gatekeeper](https://open-policy-agent.github.io/gatekeeper).
+2. Accesses images stored in ACR when validation requests come from [Azure Policy](../governance/policy/concepts/policy-for-kubernetes.md). To enable this experience, Azure Policy extends Gatekeeper, an admission controller webhook for [Open Policy Agent (OPA)](https://www.openpolicyagent.org/).
 3. Determines whether the target image is signed with a trusted cert and therefore considered as *trusted*.
 4. `AzurePolicy` and `Gatekeeper` consume the validation results as the compliance state to decide whether to allow the deployment request.
 
 ## Enable Image Integrity on your AKS cluster
 
 > [!NOTE]
-> Image signature verification is a governance-oriented scenario and works closely with [Azure Policy](../governance/policy/concepts/policy-for-kubernetes.md). We recommend using AKS built-in policy to enable Image Integrity. For more information, see the [Image Integrity policy][image-integrity-policy].
+> Image signature verification is a governance-oriented scenario and leverages [Azure Policy](../governance/policy/concepts/policy-for-kubernetes.md) to verify image signatures on AKS clusters at-scale. We recommend using AKS's Image Integrity built-in Azure Policy initiative, which is available in [Azure Policy's built-in definition library](../governance/policy/samples/built-in-policies.md#kubernetes).
 
 ### [Azure CLI](#tab/azure-cli)
 
@@ -116,7 +116,7 @@ Image Integrity uses Ratify, Azure Policy, and Gatekeeper to validate signed ima
 
 For Image Integrity to properly verify the target signed image, you need to set up `Ratify` configurations through K8s [CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) using `kubectl`.
 
-In this article, we use a self-signed CA cert from the official Ratify documentation to set up verification configurations. For more examples, see [Ratify CRDs](https://github.com/deislabs/ratify/blob/main/docs/reference/ratify-configuration.md).
+In this article, we use a self-signed CA cert from the official Ratify documentation to set up verification configurations. For more examples, see [Ratify CRDs](https://ratify.dev/docs/1.0/ratify-configuration).
 
 1. Create a `VerifyConfig` file named `verify-config.yaml` and copy in the following YAML:
 
@@ -190,19 +190,7 @@ In this article, we use a self-signed CA cert from the official Ratify documenta
 
 ## Deploy sample images to your AKS cluster
 
-1. Deploy an unsigned image using the `kubectl run demo` command.
-
-    ```azurecli-interactive
-    kubectl run demo-unsigned --image=ghcr.io/deislabs/ratify/notary-image:unsigned 
-    ```
-
-    The following example output shows that Image Integrity denies the deployment since the image hasn't been signed and doesn't meet the deployment criteria:
-
-    ```output
-    Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [ratify-constraint] Subject failed verification: ghcr.io/deislabs/ratify/notary-image:unsigned
-    ```
-
-2. Deploy a signed image using the `kubectl run demo` command.
+* Deploy a signed image using the `kubectl run demo` command.
 
     ```azurecli-interactive
     kubectl run demo-signed --image=ghcr.io/deislabs/ratify/notary-image:signed