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.

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 Anthos Config Management already installed.

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.

Verifying the installation

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

To view the status of the Pod, run the 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

The constraint template library is installed by default. This 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.

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

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.

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.

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

What's next