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.

This page is for IT administrators and Operators who want to ensure that all resources running within the cloud platform meet organizational compliance requirements by providing and maintaining automation to audit or enforce. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE Enterprise user roles and tasks.

Policy Controller is available if you use Google Kubernetes Engine (GKE) Enterprise edition. To learn more, see Google Kubernetes Engine (GKE) Enterprise edition pricing.

Note: The Policy Controller webhook fails to 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, the audit logs record the resources that don't comply with constraints.

Caution: Don't use these steps for Config Controller-created clusters, as Policy Controller is already included. See the Config Controller overview for more information.

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, 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. Enable the Policy Controller API.

   Enable Policy Controller API

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

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

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

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

9. If you're using Google Distributed Cloud on VMware or 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

Note: When you install Config Sync using the Google Cloud console or the Google Cloud CLI, you cannot later use kubectl commands to modify your configuration.

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

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 Posture Management section.

   Go to Policy

2. Select Configure 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 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 container fleet policycontroller enable --help.

gcloud ConfigManagement

Caution: Configuring Policy Controller through the ConfigManagement object is no longer recommended. Use gcloud Policy Controller instead.

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

   Note: If you are exempting namespaces, you must also label those namespaces with "admission.gatekeeper.sh/ignore=true". For instructions on how to apply the label, see Exclude namespaces.

   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.

   Note: you cannot enable mutation on Autopilot clusters.

   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 Posture Management 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 container fleet policycontroller describe --memberships=MEMBERSHIP_NAME

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

gcloud ConfigManagement

Caution: Configuring Policy Controller through the ConfigManagement object is no longer recommended. Use gcloud Policy Controller instead.

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 Posture Management 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.
      Warning: After you choose a method to apply policy bundles (manual, gcloud CLI, or Google Cloud console), using a different method to install policy bundles can cause errors in your environment.
   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 container fleet policycontroller enable \
     --fleet-default-member-config=fleet-default.yaml
   

3. To verify that the configuration was applied, run the following command:

   gcloud container fleet policycontroller describe
   

4. To remove the fleet-level default configuration, run the following command:

   gcloud 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, like a Git repository, 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.

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

• If you want to sync the Config resource stored in the gatekeeper-system namespace, then you must only define the Config resource in the source of truth. The gatekeeper-system Namespace must not be defined with it.

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.

Upgrade Policy Controller

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

Note: If you use Config Controller to install and manage Policy Controller, you don't need to manually upgrade. Config Controller is a managed service, so Google upgrades it automatically. For details on Config Controller changes, see the Config Controller release notes.

To upgrade Policy Controller, complete the following steps:

Console

1. In the Google Cloud console, go to the GKE Enterprise Policy page under the Posture Management 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 container fleet policycontroller update \
  --version=VERSION \
  --memberships=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 Posture Management 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 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

Caution: Configuring Policy Controller through the ConfigManagement object is no longer recommended. Use the gcloud Policy Controller commands instead.

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.

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

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 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 of Policy Controller. The resource requests for the ConfigManagement Operator only apply if you installed Policy Controller through the ConfigManagement object.

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

What's next

• Learn more about Policy Controller.
• Lean more about Policy Controller bundles.
• Learn how to create a constraint.
• Troubleshoot Policy Controller.