Installing Policy Controller

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

Policy Controller is available for Anthos and Google Kubernetes Engine (GKE) users. For GKE users, Policy Controller is a paid feature. To learn more, see Pricing.

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.

  • If you are using Anthos Config Management for the first time, enable Anthos Config Management.

  • Register your clusters to a fleet. Your project's fleet provides a unified way to view and manage your clusters and their workloads as part of Anthos, including clusters outside Google Cloud. Anthos charges apply only to your registered clusters.

  • Have a cluster running a Kubernetes version of 1.14.x or later. 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 - Anthos

Make sure you've registered your clusters to a fleet before continuing.

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

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

    Go to Anthos Config Management

  2. Select the registered clusters that 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. Optional: Leave the Install default template library checkbox selected to install a library of constraint templates for common policy types.
    2. Optional: 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. Optional: 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. Optional: 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.

Console - GKE

Registering your clusters

To use Config Management with GKE, you must first register the clusters. Registering your clusters lets them share a common set of configurations and policies.

To register your clusters, complete the following tasks:

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

    Go to Config Management

    This page shows you which clusters are currently registered and configured and lets you begin registering new clusters.

  2. To begin the registration process, click Set up Config Management.

  3. To enable the Config Management API, click Next.

  4. In the Select registered clusters for Config Management page, locate the Unregistered clusters from this project table, and find the cluster that you want to register.

  5. Click Register next to the cluster that you want to register.

    Once the cluster is successfully registered, it appears in the Select registered clusters for Config Management table.

Installing Policy Controller

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

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

    Go to Config Management

  2. Click New setup.

  3. Select the registered clusters that you want to enable Policy Controller on, and select Next.

  4. In the Version drop-down list, select the Anthos Config Management version that you want to use. The default is the current version.

  5. If you don't want to install Config Sync, clear the Enable Config Sync checkbox and click Next.

  6. In the Policy Controller page, leave the Enable Policy Controller checkbox selected.

  7. Optional: To install a library of constraint templates for common policy types, leave the Install default template library checkbox selected.

  8. Optional: 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.

  9. Optional: In the Exempt namespaces field, provide a list of namespaces. Objects in these namespaces are ignored by all policies. The namespaces do not need to currently exist.

  10. Optional: To enable referential constraints, select the Enable the ability to use Constraint Templates that reference objects other than the object currently being evaluated checkbox.

  11. Click Complete. You are taken back to the Config Management page.

    After a few minutes, you should see Installed in the Policy Controller status column next to the clusters that you configured.

gcloud

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

Make sure you've registered your clusters to a fleet before continuing.

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 gcloud configuration file:

    # apply-spec.yaml
    
    applySpecVersion: 1
    spec:
      policyController:
        # Set to true to install and enable Policy Controller
        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"]
        # Uncomment to enable mutation (preview feature)
        # mutation:
        #   # enabled: true
      # ...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 apply-spec.yaml file:

     gcloud beta 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 apply-spec.yaml file.
    • PROJECT_ID: add your project ID.

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

Installing Policy Controller on a private cluster

If you are using a version of earlier than 1.8.0 and 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 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 - Anthos

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.

Console - GKE

Complete the following steps:

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

    Go to 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 beta 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.

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 Config Sync 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.

  • 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.

Mutating resources

Policy Controller also acts as a mutating webhook (preview feature). For more information, see our documentation on mutation.

Viewing the Policy Controller version

To discover 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:VERIOSN_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.

Console - Anthos

  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 drop-down list, select the version that you want to upgrade to.

  6. Click Done.

Console - GKE

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

    Go to Config Management

  2. Next to the cluster you want to upgrade, click Edit.

  3. From the Version drop-down list, select the version that you want to upgrade to.

  4. Click Done.

gcloud

Run the following command:

gcloud beta container hub config-management upgrade \
    --project=PROJECT_ID \
    --membership=CLUSTER_NAME

Replace the following:

  • CLUSTER_NAME: the name of the registered cluster that you want to upgrade
  • PROJECT_ID: your project ID

Uninstalling Policy Controller

Follow these steps to uninstall Policy Controller from your clusters.

Console - Anthos

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

  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 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.

Console - GKE

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

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

    Go to Config Management

  2. Next to the cluster the clusters that you want to disable Policy Controller on, click Edit.

  3. To go to the Policy Controller configuration page, click Next.

  4. Clear the Enable Policy Controller checkbox.

  5. Click Complete.

gcloud

To uninstall the Policy Controller:

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

  2. Apply the changes in the apply-spec.yaml file:

     gcloud beta 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 apply-spec.yaml file.
    • PROJECT_ID: add your project ID.

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

If you want to fully uninstall Anthos Config Management, see uninstalling Anthos Config Management.

What's next