Installing Policy Controller

This page shows you how to install Policy Controller, a Kubernetes admission controller that checks, audits, and enforces your clusters' compliance with policies related to security, regulations, or business rules.

Note: The Policy Controller webhook fails open when Policy Controller is not running. This is to avoid interfering with cluster operations while the controller is down (for example, during upgrades). When the controller becomes available, audit logs resources that do not comply with constraints.

Before you begin

Before you start, make sure you have performed the following tasks:

• Install and initialize the Cloud SDK, which provides the gcloud, gsutil, kubectl, and nomos commands used in these instructions. If you use Cloud Shell, Cloud SDK comes pre-installed.

• You must have an Anthos entitlement to install Policy Controller using Anthos Config Management. For more information, see Setting up Anthos.

• Have a cluster running a Kubernetes version of 1.14.x or later with Config Sync already installed. Policy Controller might appear to run on versions of Kubernetes earlier than 1.14.x, but the product does not behave correctly.

Installing Policy Controller

Follow these steps to configure Anthos Config Management to install the Policy Controller dynamic admission controller into the cluster.

Console

To configure Policy Controller on the Cloud Console, complete the following steps:

1. Visit the Anthos Config Management menu in Google Cloud Console.

   Visit the Anthos Config Management menu

2. Select the clusters you want to enable Policy Controller on and click Configure.

3. Click the ACM settings for your clusters heading.

4. Under the Policy Controller heading, select the Enable Policy Controller checkbox.

   1. Leave the Install default template library checkbox selected to install a library of constraint templates for common policy types.
   2. In the Audit interval field select the period in seconds between consecutive syncs. The default is 60 seconds and if you set the audit interval to 0, auditing is disabled.
   3. In the Exempt namespaces field, provide a list of valid namespaces. Objects in these namespaces are ignored by all policies. The namespaces do not need to currently exist.
   4. Select the Enables the ability to use Constraint Templates that reference objects other than the object currently being evaluated checkbox to enable referential constraints. To learn more about referential constraints, see Enabling referential constraints.

5. Click Done. You are taken back to the Anthos Config Management menu.

gcloud

Follow these steps to configure Anthos Config Management to install the Policy Controller dynamic admission controller into the cluster.

By default, Policy Controller installs a library of constraint templates for common policy types. To skip installing the constraint templates, uncomment the line that starts with templateLibraryInstalled in the manifest.

1. Set the value of enabled within the spec.policyController object to true in the configuration file for Anthos Config Management:

   # config-management.yaml
   
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # Set to true to install and enable Policy Controller
     policyController:
       enabled: true
       # Uncomment to prevent the template library from being installed
       # templateLibraryInstalled: false
       # Uncomment to enable support for referential constraints
       # referentialRulesEnabled: true
       # Uncomment to disable audit, adjust value to set audit interval
       # auditIntervalSeconds: 0
       # Uncomment to log all denies and dryrun failures
       # logDeniesEnabled: true
       # Uncomment to exempt namespaces
       # exemptableNamespaces: ["namespace-name"]
     # ...other fields...
   

   Support for referential constraints is disabled by default. Before enabling it, be sure that you understand the caveats about eventual consistency.

2. Apply the config-management.yaml file:

    gcloud alpha container hub config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Replace the following:

   • CLUSTER_NAME: add the registered cluster that you want to apply this configuration to.
   • CONFIG_YAML: add the path to your config-management.yaml file.
   • PROJECT_ID: add your project ID.

The Pod is created and Policy Controller starts checking for and enforcing constraints.

kubectl

By default, Policy Controller installs a library of constraint templates for common policy types. To skip installing the constraint templates, uncomment the line that starts with templateLibraryInstalled in the manifest.

1. Set the value of enabled within the spec.policyController object to true in the configuration file for Anthos Config Management:

   # config-management.yaml
   
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # Set to true to install and enable Policy Controller
     policyController:
       enabled: true
       # Uncomment to prevent the template library from being installed
       # templateLibraryInstalled: false
       # Uncomment to enable support for referential constraints
       # referentialRulesEnabled: true
       # Uncomment to disable audit, adjust value to set audit interval
       # auditIntervalSeconds: 0
       # Uncomment to log all denies and dryrun failures
       # logDeniesEnabled: true
       # Uncomment to exempt namespaces
       # exemptableNamespaces: ["namespace-name"]
     # ...other fields...
   

   Support for referential constraints is disabled by default. Before enabling it, be sure you understand the caveats about eventual consistency.

2. Apply the configuration using kubectl apply.

   kubectl apply -f config-management.yaml
   

The Pod is created and Policy Controller starts checking for and enforcing constraints.

Installing Policy Controller on a private cluster

If you are installing Policy Controller on a private cluster in Google Kubernetes Engine (GKE), you need to take additional steps to complete your installation. In private clusters, the firewall blocks the control plane from reaching the nodes on port 8443, which is where the control plane tries to connect to Policy Controller. You can create a firewall rule so that the control plane can reach the port 8443 (or any other custom port). You can also make your Pod run on privileged port 443. For more information, see Running on private GKE Cluster nodes in the Gatekeeper documentation.

Verifying the installation

After you have installed Policy Controller, you can verify that the installation completed successfully.

Console

Complete the following steps:

1. In the Cloud Console, go to the Anthos Config Management page.

   Go to Anthos Config Management

2. In the cluster table, view the Policy controller status column. A successful installation has a status of Installed.

gcloud

Run the following command:

gcloud alpha container hub config-management status \
    --project=PROJECT_ID

Replace PROJECT_ID with your project's ID.

You should see output similar to the following example:

Name          Status  Last_Synced_Token  Sync_Branch  Last_Synced_Time      Policy_Controller
CLUSTER_NAME  SYNCED  a687c2c            1.0.0        2021-02-17T00:15:55Z  INSTALLED

A successful installation has a status of INSTALLED in the Policy Controller column.

kubectl

If Policy Controller is installed correctly, its Pod will be running. The Pod might restart several times before it's available.

Since the Policy Controller Pod runs in the gatekeeper-system namespace, you can view its status by running following command:

kubectl get pods -n gatekeeper-system

You should see output similar to the following example:

NAME                              READY   STATUS    RESTARTS   AGE
gatekeeper-controller-manager-0   1/1     Running   1          53s

Verifying the constraint template library installation

When you install Policy Controller, the constraint template library is installed by default and this installation can take several minutes to complete.

To verify that the template library is installed, list all ConstraintTemplate objects:

kubectl get constrainttemplates

You should see output similar to the following example:

NAME                                      AGE
k8sallowedrepos                           84s
k8scontainerlimits                        84s
k8spspallowprivilegeescalationcontainer   84s
...[OUTPUT TRUNCATED]...

When an individual constraint template is installed correctly, its status.created field is true.

Policy Controller interactions with Anthos Config Management

Anthos Config Management manages the resources essential for running Policy Controller. To avoid contention between Anthos Config Management and Policy Controller, be aware of what gets put into the Anthos Config Management repository.

When using Policy Controller, consider the following points:

• You cannot sync a constraint template that is also part of the template library unless the constraint template library is disabled.

  Caution: Disabling the template library might remove some of your constraint's dependencies. For more information, see Creating constraints.

• If you want to sync the config resource stored in the gatekeeper-system namespace, the namespace must either be undefined in the repository, or match the configuration Anthos Config Management wants to install.

• If the gatekeeper-system namespace is removed from the source-of-truth repository, Anthos Config Management might not be able to recover. To recover, delete the validating webhook configuration for Policy Controller.

Managing the constraint template library

For information on uninstalling or reinstalling constraint templates, their associated constraints, or the constraint template library, see Creating constraints.

Exempting namespaces from enforcement

You can configure Policy Controller to ignore objects within a namespace. For more information, see Excluding namespaces from Policy Controller.

Viewing the Policy Controller version

To view which version of Gatekeeper Policy Controller is using, view the image tag by running the following command:

kubectl get deployments -n gatekeeper-system gatekeeper-controller-manager \
  -o="jsonpath={.spec.template.spec.containers[0].image}"

From Anthos Config Management version 1.3.2 and later, the Git tag (or hash) used to build Gatekeeper and the Anthos Config Management version number are included in the image tag as follows:

.../gatekeeper:version-number-git-tag.gbuild-number

For example, for the following image:

gcr.io/config-management-release/gatekeeper:anthos1.3.2-480baac.g0

• anthos1.3.2 is the version number.
• 480baac is the Git tag.
• 0 is the build number.

You can also view a list of all Anthos Config Management versions alongside their corresponding manifest, installation, and nomos binary versions at the Release version matrix.

Upgrading Policy Controller

Policy Controller is upgraded whenever you upgrade Anthos Config Management.

To upgrade Anthos Config Management, you can use the Google Cloud Console or kubectl. Before upgrading, check the release notes for any specific instructions.

Console

1. In the Cloud Console, go to the Anthos Config Management page.

   Go to Anthos Config Management

2. Select the clusters that you want to upgrade.

3. Click Configure.

4. Click ACM settings for your clusters.

5. From the Version dropdown, select the version that you want to upgrade to.

6. Click Done.

kubectl

Run these commands for each enrolled cluster:

1. Download the Anthos Config Management manifest and nomos commands for the new version.

2. Apply the Anthos Config Management manifest:

   kubectl apply -f config-management-operator.yaml
   

   This command updates the Anthos Config Management image. Kubernetes retrieves the new version and restarts the Anthos Config Management Pod using the new version. When Anthos Config Management starts, it runs a reconcile loop that applies the set of manifests bundled in the new image. This updates and restarts each component Pod.

3. Replace the nomos or nomos.exe command on all clients with the new version. This change ensures that the nomos command can always get the status of all enrolled clusters and can validate configs for them.

Uninstalling Policy Controller

Follow these steps to uninstall Policy Controller from your clusters.

Console

To disable Policy Controller on your clusters, complete the following tasks:

1. Visit the Anthos Config Management menu in Google Cloud Console.

   Visit the Anthos Config Management menu

2. Select the clusters that you want to disable Policy Controller on.

3. Click Configure.

4. Click the ACM settings for your clusters heading.

5. In the Policy Controller section, clear the Policy Controller checkbox.

6. Click Done.

gcloud

To uninstall the Policy Controller:

1. Edit the Anthos Config Management configuration in your config-management.yaml file and set policyController.enabled to false.

2. Apply the changes in the config-management.yaml file:

    gcloud alpha container hub config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Replace the following:

   • CLUSTER_NAME: add the registered cluster that you want to apply this configuration to.
   • CONFIG_YAML: add the path to your config-management.yaml file.
   • PROJECT_ID: add your project ID.

After Anthos Config Management removes the policycontroller.configmanagement.gke.io finalizer, uninstallation is complete.

Note: Uninstalling the Policy Controller removes all constraints and templates stored in your cluster.

kubectl

To uninstall Policy Controller, edit the Anthos Config Management configuration in your config-management.yaml file and set policyController.enabled to false. After Anthos Config Management removes the policycontroller.configmanagement.gke.io finalizer, uninstallation is complete.

Note: Uninstalling the Policy Controller removes all constraints and templates stored in your cluster.

If you want to fully uninstall Anthos Config Management, see Uninstalling Config Sync from a cluster.

What's next

• Learn more about Policy Controller.
• Learn how to create a constraint.
• Use the constraint template library provided by Google.
• Learn how to use constraints instead of PodSecurityPolicies.