Merge pull request #108623 from DCtheGeek/dmc-policy-akschanges

Changes for OPA and AKS Engine

Author: ShannonLeavitt

articles/governance/policy/concepts/effects.md

@@ -1,7 +1,7 @@
 ---
 title: Understand how effects work
 description: Azure Policy definitions have various effects that determine how compliance is managed and reported.
-ms.date: 11/04/2019
+ms.date: 03/23/2020
 ms.topic: conceptual
 ---
 # Understand Azure Policy effects
@@ -532,17 +532,16 @@ not, then a deployment to enable is executed.
 This effect is used with a policy definition *mode* of `Microsoft.Kubernetes.Data`. It's used to
 pass Gatekeeper v3 admission control rules defined with
 [OPA Constraint Framework](https://github.com/open-policy-agent/frameworks/tree/master/constraint#opa-constraint-framework)
-to [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) to self-managed Kubernetes clusters
-on Azure.
+to [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) to Kubernetes clusters on Azure.
 
 > [!NOTE]
-> [Azure Policy for AKS Engine](aks-engine.md) is in Public Preview and only supports built-in
-> policy definitions.
+> [Azure Policy for Kubernetes](aks-engine.md) is in Preview and only supports built-in policy
+> definitions.
 
 ### EnforceOPAConstraint evaluation
 
 The Open Policy Agent admission controller evaluates any new request on the cluster in real time.
-Every 5 minutes, a full scan of the cluster is completed and the results reported to Azure Policy.
+Every 15 minutes, a full scan of the cluster is completed and the results reported to Azure Policy.
 
 ### EnforceOPAConstraint properties
 
@@ -561,10 +560,10 @@ Gatekeeper v3 admission control rule.
   - Defines any parameters and values to pass to the Constraint. Each value must exist in the
     Constraint template CRD.
 
-### EnforceRegoPolicy example
+### EnforceOPAConstraint example
 
-Example: Gatekeeper v3 admission control rule to set container CPU and memory resource limits in AKS
-Engine.
+Example: Gatekeeper v3 admission control rule to set container CPU and memory resource limits in
+Kubernetes.
 
 ```json
 "if": {
@@ -603,9 +602,11 @@ to pass Gatekeeper v2 admission control rules defined with
 [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) on
 [Azure Kubernetes Service](../../../aks/intro-kubernetes.md).
 
-> [!NOTE]
-> [Azure Policy for AKS](rego-for-aks.md) is in Limited Preview and only supports built-in policy
-> definitions
+> [!IMPORTANT]
+> [Azure Policy for Kubernetes](rego-for-aks.md) is in Preview and only supports built-in policy
+> definitions. Built-in policies are in the **Kubernetes** category. The **EnforceRegoPolicy**
+> effect and related **Kubernetes Service** category policies are being _deprecated_. Instead, use
+> the updated [EnforceOPAConstraint](#enforceopaconstraint) effect.
 
 ### EnforceRegoPolicy evaluation
 

articles/governance/policy/concepts/rego-for-aks.md

@@ -1,21 +1,23 @@
 ---
 title: Learn Azure Policy for Azure Kubernetes Service
-description: Learn how Azure Policy uses Rego and Open Policy Agent to manage clusters on Azure Kubernetes Service. 
-ms.date: 03/18/2020
+description: Learn how Azure Policy uses Rego and Open Policy Agent to manage clusters on Azure Kubernetes Service.
+ms.date: 03/23/2020
 ms.topic: conceptual
 ---
 # Understand Azure Policy for Azure Kubernetes Service
 
 Azure Policy integrates with the [Azure Kubernetes Service](../../../aks/intro-kubernetes.md) (AKS)
 to apply at-scale enforcements and safeguards on your clusters in a centralized, consistent manner.
-By extending use of
-[Gatekeeper](https://github.com/open-policy-agent/gatekeeper/tree/master/deprecated) v2, an
-_admission controller webhook_ for [Open Policy Agent](https://www.openpolicyagent.org/) (OPA),
-Azure Policy makes it possible to manage and report on the compliance state of your Azure resources
-and AKS clusters from one place.
+By extending use of [Gatekeeper](https://github.com/open-policy-agent/gatekeeper) v3, an _admission
+controller webhook_ for [Open Policy Agent](https://www.openpolicyagent.org/) (OPA), Azure Policy
+makes it possible to manage and report on the compliance state of your Azure resources and AKS
+clusters from one place.
 
-> [!NOTE]
-> Azure Policy for AKS is in Limited Preview and only supports built-in policy definitions.
+> [!IMPORTANT]
+> [Azure Policy for AKS](rego-for-aks.md) is in Preview and only supports built-in policy
+> definitions. Built-in policies are in the **Kubernetes** category. The **EnforceRegoPolicy**
+> effect and related **Kubernetes Service** category policies are being _deprecated_. Instead, use
+> the updated [EnforceOPAConstraint](./effects.md#enforceopaconstraint) effect.
 
 ## Overview
 
@@ -28,9 +30,9 @@ To enable and use Azure Policy for AKS with your AKS cluster, take the following
 
 ## Opt-in for preview
 
-Before installing the Azure Policy Add-on or enabling any of the service features, your subscription
-must enable the **Microsoft.ContainerService** resource provider and the
-**Microsoft.PolicyInsights** resource provider, then be approved to join the preview. To join the
+Before you install the Azure Policy Add-on or enabling any of the service features, your
+subscription must enable the **Microsoft.ContainerService** resource provider and the
+**Microsoft.PolicyInsights** resource provider, then get approved to join the preview. To join the
 preview, follow these steps in either the Azure portal or with Azure CLI:
 
 - Azure portal:
@@ -57,7 +59,7 @@ preview, follow these steps in either the Azure portal or with Azure CLI:
   ```azurecli-interactive
   # Log in first with az login if you're not using Cloud Shell
 
-  # Provider register: Register the Azure Kubernetes Services provider
+  # Provider register: Register the Azure Kubernetes Service provider
   az provider register --namespace Microsoft.ContainerService
 
   # Provider register: Register the Azure Policy provider
@@ -72,27 +74,19 @@ preview, follow these steps in either the Azure portal or with Azure CLI:
   # Once the above shows 'Registered' run the following to propagate the update
   az provider register -n Microsoft.ContainerService
   
-  # Feature register: enables the add-on to call the Azure Policy resource provider
-  az feature register --namespace Microsoft.PolicyInsights --name AKS-DataPlaneAutoApprove
-  
-  # Use the following to confirm the feature has registered
-  az feature list -o table --query "[?contains(name, 'Microsoft.PolicyInsights/AKS-DataPlaneAutoApprove')].{Name:name,State:properties.state}"
-  
-  # Once the above shows 'Registered' run the following to propagate the update
-  az provider register -n Microsoft.PolicyInsights
-  
   ```
 
 ## Azure Policy Add-on
 
 The _Azure Policy Add-on_ for Kubernetes connects the Azure Policy service to the Gatekeeper
-admission controller. The add-on, which is installed into the _azure-policy_ namespace, enacts the
+admission controller. The add-on, which is installed into the _kube-system_ namespace, enacts the
 following functions:
 
-- Checks with Azure Policy for assignments to the AKS cluster
-- Downloads and caches policy details, including the _rego_ policy definition, as **configmaps**
-- Runs a full scan compliance check on the AKS cluster
-- Reports auditing and compliance details back to Azure Policy
+- Checks with Azure Policy service for assignments to the cluster.
+- Deploys policies in the cluster as
+  [constraint template](https://github.com/open-policy-agent/gatekeeper#constraint-templates) and
+  [constraint](https://github.com/open-policy-agent/gatekeeper#constraints) custom resources.
+- Reports auditing and compliance details back to Azure Policy service.
 
 ### Installing the add-on
 
@@ -101,10 +95,13 @@ following functions:
 Before you install the add-on in your AKS cluster, the preview extension must be installed. This
 step is done with Azure CLI:
 
+1. If Gatekeeper v2 policies were installed, remove the add-on with the **Disable** button on your
+   AKS cluster under the **Policies (preview)** page.
+
 1. You need the Azure CLI version 2.0.62 or later installed and configured. Run `az --version` to
    find the version. If you need to install or upgrade, see [Install the Azure CLI](/cli/azure/install-azure-cli).
 
-1. The AKS cluster must be version _1.10_ or higher. Use the following script to validate your AKS
+1. The AKS cluster must be version _1.14_ or higher. Use the following script to validate your AKS
    cluster version:
 
    ```azurecli-interactive
@@ -152,7 +149,8 @@ manage.
 
      > [!NOTE]
      > If the **Enable add-on** button is grayed out, the subscription has not yet been added to the
-     > preview. See [Opt-in for preview](#opt-in-for-preview) for the required steps.
+     > preview. See [Opt-in for preview](#opt-in-for-preview) for the required steps. If a
+     > **Disable** button is available, Gatekeeper v2 is still installed and must be removed.
 
 - Azure CLI
 
@@ -164,81 +162,98 @@ manage.
 
 ### Validation and reporting frequency
 
-The add-on checks in with Azure Policy for changes in policy assignments every 5 minutes. During
-this refresh cycle, the add-on removes all _configmaps_ in the _azure-policy_ namespace then
-recreates the _configmaps_ for Gatekeeper use.
+The add-on checks in with Azure Policy service for changes in policy assignments every 15 minutes.
+During this refresh cycle, the add-on checks for changes. These changes trigger creates, updates, or
+deletes of the constraint templates and constraints.
 
 > [!NOTE]
-> While a _cluster admin_ may have permission to the _azure-policy_ namespace, it's not recommended
-> or supported to make changes to the namespace. Any manual changes made are lost during the
-> refresh cycle.
+> While a cluster admin may have permission to create and update constraint templates and
+> constraints resources, these are not supported scenarios as manual updates will be overwritten.
 
-Every 5 minutes, the add-on calls for a full scan of the cluster. After gathering details of the
+Every 15 minutes, the add-on calls for a full scan of the cluster. After gathering details of the
 full scan and any real-time evaluations by Gatekeeper of attempted changes to the cluster, the
-add-on reports the results back to Azure Policy for inclusion in
-[compliance details](../how-to/get-compliance-data.md) like any Azure Policy assignment. Only
-results for active policy assignments are returned during the audit cycle.
+add-on reports the results back to Azure Policy service for inclusion in
+[compliance details](../how-to/get-compliance-data.md#portal) like any Azure Policy assignment. Only
+results for active policy assignments are returned during the audit cycle. Audit results can also be
+seen as [violations](https://github.com/open-policy-agent/gatekeeper#audit) listed in the status
+field of the failed constraint.
 
 ## Policy language
 
-The Azure Policy language structure for managing AKS follows that of existing policies. The effect
-_EnforceRegoPolicy_ is used to manage your AKS clusters and takes _details_ properties specific to
-working with OPA and Gatekeeper v2. For details and examples, see the
-[EnforceRegoPolicy](effects.md#enforceregopolicy) effect.
-
-As part of the _details.policy_ property in the policy definition, Azure Policy passes the URI of a
-rego policy to the add-on. Rego is the language that OPA and Gatekeeper support to validate or
-mutate a request to the Kubernetes cluster. By supporting an existing standard for Kubernetes
-management, Azure Policy makes it possible to reuse existing rules and pair them with Azure Policy
-for a unified cloud compliance reporting experience. For more information, see
+The Azure Policy language structure for managing Kubernetes follows that of existing policies. The
+effect _EnforceOPAConstraint_ is used to manage your Kubernetes clusters and takes details
+properties specific to working with
+[OPA Constraint Framework](https://github.com/open-policy-agent/frameworks/tree/master/constraint)
+and Gatekeeper v3. For details and examples, see the  
+[EnforceOPAConstraint](./effects.md#enforceopaconstraint) effect.
+  
+As part of the _details.constraintTemplate_ and _details.constraint_ properties in the policy
+definition, Azure Policy passes the URIs of these
+[CustomResourceDefinitions](https://github.com/open-policy-agent/gatekeeper#constraint-templates)
+(CRD) to the add-on. Rego is the language that OPA and Gatekeeper support to validate a request to
+the Kubernetes cluster. By supporting an existing standard for Kubernetes management, Azure Policy
+makes it possible to reuse existing rules and pair them with Azure Policy for a unified cloud
+compliance reporting experience. For more information, see
 [What is Rego?](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego).
 
 ## Built-in policies
 
-To find the built-in policies for managing AKS using the Azure portal, follow these steps:
+To find the built-in policies for managing your cluster using the Azure portal, follow these steps:
 
-1. Start the Azure Policy service in the Azure portal. Select **All services** in the left pane and
-   then search for and select **Policy**.
+1. Start the Azure Policy service in the Azure portal. Select All services in the left pane and then
+   search for and select **Policy**.
 
 1. In the left pane of the Azure Policy page, select **Definitions**.
 
-1. From the Category drop-down list box, use **Select all** to clear the filter and then select
-   **Kubernetes service**.
+1. From the Category drop-down list box, use Select all to clear the filter and then select
+   **Kubernetes**.
 
 1. Select the policy definition, then select the **Assign** button.
 
-> [!NOTE]
-> When assigning the Azure Policy for AKS definition, the **Scope** must include the AKS cluster
-> resource.
+1. Set the **Scope** to the management group, subscription, or resource group of the Kubernetes
+   cluster where the policy assignment will apply.
+
+   > [!NOTE]
+   > When assigning the Azure Policy for AKS definition, the **Scope** must include the AKS cluster
+   > resource.
+
+1. Give the policy assignment a **Name** and **Description** that you can use to identify it easily.
+
+1. Set the [Policy enforcement](./assignment-structure.md#enforcement-mode) to one of the values
+   below.
+
+   - **Enabled** - Enforce the policy on the cluster. Kubernetes admission requests with violations
+     are denied.
+   
+   - **Disabled** - Don't enforce the policy on the cluster. Kubernetes admission requests with
+     violations aren't denied. Compliance assessment results are still available. When rolling out
+     new policies to running clusters, _Disabled_ option is helpful for testing the policies as
+     admission requests with violations aren't denied.
+
+1. Select **Next**.
+
+1. Set **parameter values**
+   
+   - To exclude Kubernetes namespaces from policy evaluation, specify the list of namespaces in
+     parameter **Namespace exclusions**. It's recommended to exclude: _kube-system_
+
+1. Select **Review + create**.
 
 Alternately, use the [Assign a policy - Portal](../assign-policy-portal.md) quickstart to find and
 assign an AKS policy. Search for a Kubernetes policy definition instead of the sample 'audit vms'.
 
 > [!IMPORTANT]
-> Built-in policies in category **Kubernetes service** are only for use with AKS.
+> Built-in policies in category **Kubernetes** are only for use with AKS. For a list of built-in
+> policies, see [../samples/built-in-policies.md#kubernetes]
 
 ## Logging
 
 ### Azure Policy Add-on logs
 
-As a Kubernetes controller/container, the Azure Policy Add-on keeps logs in the AKS cluster. The
-logs are exposed in the **Insights** page of the AKS cluster. For more information, see
+As a Kubernetes controller/container, both Azure Policy Add-on and Gatekeeper keep logs in the AKS
+cluster. The logs are exposed in the **Insights** page of the AKS cluster. For more information, see
 [Understand AKS cluster performance with Azure Monitor for containers](../../../azure-monitor/insights/container-insights-analyze.md).
 
-### Gatekeeper logs
-
-To enable Gatekeeper logs for new resource requests, follow the steps in [Enable and review Kubernetes master node logs in AKS](../../../aks/view-master-logs.md).
-Here is an example query to view denied events on new resource requests:
-
-```kusto
-| where Category == "kube-audit"
-| where log_s contains "admission webhook"
-| limit 100
-```
-
-To view logs from Gatekeeper containers, follow the steps in [Enable and review Kubernetes master node logs in AKS](../../../aks/view-master-logs.md)
-and check the _kube-apiserver_ option in the **Diagnostic settings** pane.
-
 ## Remove the add-on
 
 To remove the Azure Policy Add-on from your AKS cluster, use either the Azure portal or Azure CLI:

articles/governance/policy/toc.yml

@@ -81,7 +81,7 @@
   - name: Azure Policy for Kubernetes
     items:
     - name: Policy for AKS
-      displayName: aks, rego, k8s, opa, open policy agent, gatekeeper, v2
+      displayName: aks, rego, k8s, opa, open policy agent, gatekeeper, v3, crd, constraints
       href: ./concepts/rego-for-aks.md
     - name: Policy for AKS Engine
       displayName: aks, k8s, opa, open policy agent, gatekeeper, v3, crd, constraints