Install 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 if you use Google Kubernetes Engine (GKE) Enterprise edition. To learn more, see Google Kubernetes Engine (GKE) Enterprise edition pricing. You can create a report to try Policy Controller before installing it at no cost.

Before you begin

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

  1. Install and initialize the Google Cloud CLI, which provides the gcloud, gsutil, kubectl, and nomos commands used in these instructions. If you previously installed the gcloud CLI, get the latest version by running gcloud components update. If you use Cloud Shell, Google Cloud CLI comes pre-installed.
  2. Ensure open source Open Policy Agent Gatekeeper is not installed on your cluster. If it is, uninstall Gatekeeper before installing Policy Controller.
  3. Enable the GKE Enterprise API.

    Enable GKE Enterprise API

  4. Create, or make sure you have access to, 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.

  5. Grant the required IAM roles to the user registering the cluster.

  6. If you plan to use the Google Cloud CLI to configure Policy Controller, register your cluster to a fleet now. If you plan to use the Google Cloud console, register your clusters when you install Policy Controller.

  7. If you're using GKE attached clusters, ensure that your AKS cluster does not have the Azure Policy add-on and avoid labeling namespaces with the key control-plane.

  8. If you're using GKE on VMware or Google Distributed Cloud Virtual for Bare Metal, ensure that you are installing Policy Controller on a user cluster. Policy Controller can't be installed on an admin cluster.

Install Policy Controller

Starting in version 1.16.0, if you're using the Google Cloud CLI, you can install and manage Policy Controller directly (recommended) or through the ConfigManagement object.

Console

To install Policy Controller in the Google Cloud console, complete the following steps:

  1. In the Google Cloud console, go to the GKE Enterprise Policy page under the Features section.

    Go to Policy

  2. Select Install Policy Controller.

  3. In the Policy Controller Installation pane, select one of the following installation options:

    • To install Policy Controller on all the clusters in a fleet:

      1. Keep Install on your fleet selected.

        If you don't have a fleet in your project, you can create a fleet in the next step.

      2. If you don't already have a fleet, choose a name for your fleet.

      3. Select Activate Policy Controller.

    • To install Policy Controller on individual clusters:

      1. Select Install on individual clusters.

      2. In the Available clusters table, select the clusters that you want to install Policy Controller on.

      3. Select Activate Policy Controller.

You are redirected to the Policy Controller Settings tab. When Policy Controller is installed and configured on your clusters, the status columns show Installed . This can take several minutes.

gcloud Policy Controller

Enable Policy Controller by running the following command:

gcloud alpha container fleet policycontroller enable \
    --memberships=MEMBERSHIP_NAME

You can set additional fields to configure Policy Controller. For example, you might want to tell Policy Controller to exempt some namespaces from enforcement. For a full list of fields you can configure, see the Policy Controller Google Cloud CLI documentation or run gcloud alpha container fleet policycontroller enable --help.

gcloud ConfigManagement

  1. Prepare the configuration by either creating a new apply-spec.yaml manifest or by using an existing manifest. Using an existing manifest lets you configure your cluster with the same settings used by another cluster.

    Create new manifest

    To configure Policy Controller with new settings for your cluster, create a file named apply-spec.yaml and copy the following YAML file into it:

    # 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 enable mutation
        # mutationEnabled: true
        # Uncomment to exempt namespaces
        # exemptableNamespaces: ["namespace-name"]
        # Uncomment to change the monitoring backends
        # monitoring:
        #     backends:
        #     - cloudmonitoring
        #     - prometheus
      # ...other fields...
    

    You must add a spec.policyController field and set the value of enabled to true. You can choose to enable other Policy Controller features. However, support for referential constraints is disabled by default. Before enabling it, be sure that you familiarize yourself with the caveats about eventual consistency.

    Use existing manifest

    To configure your cluster with the same settings used by another cluster, fetch the settings from a registered cluster:

    gcloud alpha container fleet config-management fetch-for-apply \
         --membership=MEMBERSHIP_NAME \
         --project=PROJECT_ID \
         > CONFIG_YAML_PATH
    

    Replace the following:

    • MEMBERSHIP_NAME: the membership name of the registered cluster that has the Policy Controller settings you want to use
    • PROJECT_ID: your project ID
    • CONFIG_YAML_PATH: the path to the apply-spec.yaml file
  2. Apply the apply-spec.yaml file:

    gcloud beta container fleet config-management apply \
        --membership=MEMBERSHIP_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
    

    Replace the following:

    • MEMBERSHIP_NAME: the membership name of the registered cluster that has the Policy Controller settings that you want to use.
    • 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.

Verify the Policy Controller installation

After installing Policy Controller, you can verify that it completed successfully.

Console

Complete the following steps:

  1. In the Google Cloud console, go to the GKE Enterprise Policy page under the Features section.

    Go to Policy

  2. Under the Settings tab, in the cluster table, check the Policy controller status column. A successful installation has a status of Installed .

gcloud Policy Controller

Run the following command:

gcloud alpha container fleet policycontroller describe --memberships=MEMBERSHIP_NAME

A successful installation shows membershipStates: MEMBERSHIP_NAME: policycontroller: state: ACTIVE.

gcloud ConfigManagement

Run the following command:

gcloud beta container fleet 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.

Verify the constraint template library installation

When you install Policy Controller, the constraint template library is installed by default. This installation can take several minutes to complete. You can verify that the template library completed successfully.

Console

Complete the following steps:

  1. In the Google Cloud console, go to the GKE Enterprise Policy page under the Features section.

    Go to Policy

  2. Under the Settings tab, in the cluster table, select the number listed in the Bundles installed column. In the Policy content status pane, a successful installation of the template library has a status of Installed .

gcloud

Run the following command:

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.

Configure fleet-level defaults

If you have enabled Google Kubernetes Engine (GKE) Enterprise edition, you can enable and configure Policy Controller as a fleet-level default for your clusters. This means that every new GKE on Google Cloud cluster registered during cluster creation will have Policy Controller enabled on the cluster with the settings you specify. You can find out more about fleet default configuration in Manage fleet-level features.

To configure fleet-level defaults for Policy Controller, complete the following steps:

Console

  1. In the Google Cloud console, go to the Feature Manager page.

    Go to Feature Manager

  2. In the Policy pane, click Configure.

  3. Review your fleet-level settings. All new clusters you register to the fleet inherit these settings.

  4. Optional: To change the default settings, click Customize fleet settings. In the dialog that appears, do the following:

    1. In the Add/Edit policy bundles section, include or exclude a policy bundle by clicking the relevant toggle.
    2. In the Edit Policy Controller configuration section, do the following:
      1. To enable the mutation webhook, select the Enable mutation webhook checkbox. This feature is not compatible with Autopilot clusters.
      2. In the Audit interval box, enter the period in seconds between two consecutive audits.
      3. In the Exemptible namespaces box, enter a list of namespaces. Policy Controller ignores objects in these namespaces.
      4. To enable referential constraints, select the Enable Constraint Templates that reference to objects other than the object currently being evaluated checkbox.
      5. In the Version list, select the Policy Controller version that you want to use.
    3. Click Save changes.
  5. Click Configure.

  6. In the confirmation dialog, click Confirm. If you haven't previously enabled Policy Controller, clicking Confirm enables the anthospolicycontroller.googleapis.com API.

  7. Optional: Sync existing clusters to the default settings:

    1. In the Clusters in the fleet list, select the clusters that you want to sync.
    2. Click Sync to fleet settings and click Confirm in the confirmation dialog that appears. This operation can take a few minutes to complete.

gcloud

  1. Create a file named fleet-default.yaml that contains the default configurations for Policy Controller. The installSpec field is required to enable fleet-level defaults. This example shows the options you can configure:

    # cat fleet-default.yaml
    
     policyControllerHubConfig:
      installSpec: INSTALL_SPEC_ENABLED 
      # Uncomment to set default deployment-level configurations.
      # deploymentConfigs:
      #   admission:
      #     containerResources:
      #       limits:
      #        cpu: 1000m
      #         memory: 8Gi
      #       requests:
      #         cpu: 500m
      #         memory: 4Gi
      # Uncomment to set policy bundles that you want to install by default.
      # policyContent:
      #   bundles:
      #     cis-k8s-v1.5.1:
      #       exemptedNamespaces:
      #       - "namespace-name"
      # Uncomment to exempt namespaces from admission.
      # exemptableNamespaces:
      # - "namespace-name"
      # 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 enable mutation
      # mutationEnabled: true
      # Uncomment to adjust the value to set the constraint violation limit
      # constraintViolationLimit: 20
      # ... other fields ...
    
  2. Apply the default configuration to your fleet:

    gcloud alpha container fleet policycontroller enable \
      --fleet-default-member-config=fleet-default.yaml
    
  3. To verify that the configuration was applied, run the following command:

    gcloud alpha container hub policycontroller describe
    
  4. To remove the fleet-level default configuration, run the following command:

    gcloud alpha container fleet policycontroller enable \
      --no-fleet-default-member-config
    

Policy Controller interactions with Config Sync

If you're using Policy Controller with Config Sync, you should be aware of the following interactions with resources stored in your source of truth that are synced by Config Sync:

  • 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 source of truth, or match the configuration that Config Sync will install.

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

Manage the constraint template library

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

Exempt namespaces from enforcement

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

Mutate resources

Policy Controller also acts as a mutating webhook. For more information, see Mutate resources.

View 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}"

The Git tag (or hash) used to build Gatekeeper and the ConfigManagement Operator 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 Policy Controller versions alongside their corresponding manifest, installation, and nomos binary versions at the Release version matrix.

Upgrade Policy Controller

Before you upgrade Policy Controller, check the release notes for details on what's changed between versions.

To upgrade Policy Controller, complete the following steps:

Console

  1. In the Google Cloud console, go to the GKE Enterprise Policy page under the Features section.

    Go to Policy

  2. Under the Settings tab, next to the cluster whose version you want to upgrade, select Edit configuration.
  3. Expand the Edit Policy Controller configuration menu.
  4. From the Version drop-down list, select the version that you want to upgrade to.
  5. Click Save changes.

gcloud

Run the following command:

gcloud alpha container fleet policycontroller update \
  --version=VERSION \
  --membership=MEMBERSHIP_NAME

Replace the following:

  • VERSION: the version that you want to upgrade to
  • MEMBERSHIP_NAME: the membership name that you chose when you registered your cluster. You can find the membership name by running gcloud container fleet memberships list.

Uninstall 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. In the Google Cloud console, go to the GKE Enterprise Policy page under the Features section.

    Go to Policy

  2. Under the Settings tab, in the cluster table, select Edit in the Edit configuration column.

  3. In the cluster pane, scroll down and expand the About Policy Controller menu.

  4. Select Uninstall Policy Controller.

  5. Confirm the uninstall by following the instructions in the confirmation dialog and selecting Confirm.

When Policy Controller is uninstalled, the status columns show Not installed .

gcloud Policy Controller

To uninstall Policy Controller, run the following command:

gcloud alpha container fleet policycontroller disable \
  --memberships=MEMBERSHIP_NAME

Replace MEMBERSHIP_NAME with the membership name of the registered cluster to disable Policy Controller on. You can specify multiple memberships separated by a comma.

gcloud ConfigManagement

To uninstall Policy Controller:

  1. Edit the ConfigManagement Operator 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 fleet 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.

Remove the ConfigManagement Operator

If you installed Policy Controller through the ConfigManagement object, you also need to remove the ConfigManagement Operator from your clusters.

To remove the ConfigManagement Operator, run the following commands:

  1. Delete the ConfigManagement object from the cluster:

    kubectl delete configmanagement --all
    

    After you run this command, the following things happen:

    • Any ClusterRoles and ClusterRoleBindings created in the cluster by ConfigManagement Operator are deleted from the cluster.
    • Any admission controller configurations installed by ConfigManagement Operator are deleted.
    • The contents of the config-management-system namespace are deleted, with the exception of the git-creds Secret, and for versions of Policy Controller, Config Sync and Config Controller beginning in 1.9.0, the config-management-operator Deployment, and the config-management-operator Pod. ConfigManagement Operator cannot function without the config-management-system namespace. Any CustomResourceDefinitions (CRDs) created or modified by ConfigManagement Operator controller are removed from the clusters where they were created or modified. The CRD required to run ConfigManagement Operator still exists because from the point of view of Kubernetes, they were added by the user who installed ConfigManagement Operator. Information about removing these components is covered in the next step.
  2. If you need to retain the git-creds Secret, do that now:

    kubectl -n config-management-system get secret git-creds -o yaml
    
  3. Delete the config-management-system namespace:

    kubectl delete ns config-management-system
    
  4. Delete the config-management-monitoring namespace:

    kubectl delete ns config-management-monitoring
    
  5. Delete the ConfigManagement CustomResourceDefinition:

    kubectl delete crd configmanagements.configmanagement.gke.io
    

Policy Controller RBAC and permissions

Policy Controller includes highly privileged workloads. The permissions for these workloads are covered in the Open Policy Agent Gatekeeper operations documentation.

Policy Controller resource requests

The following table lists Kubernetes resource requirements for each supported version. The resource requests for the ConfigManagement Operator only apply if you installed Policy Controller through the ConfigManagement object.

1.16

Component CPU Memory
ConfigManagement Operator 100 m 100 Mi
Policy Controller 100 m 256 Mi

1.15

Component CPU Memory
ConfigManagement Operator 100 m 100 Mi
Policy Controller 100 m 256 Mi

1.14

Component CPU Memory
ConfigManagement Operator 100 m 100 Mi
Policy Controller 100 m 256 Mi

What's next