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
, andnomos
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:
Visit the Anthos Config Management menu in Google Cloud Console.
Select the clusters you want to enable Policy Controller on and click Configure.
Click the ACM settings for your clusters heading.
Under the Policy Controller heading, select the Enable Policy Controller checkbox.
- Leave the Install default template library checkbox selected to install a library of constraint templates for common policy types.
- 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.
- 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.
- 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.
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.
Set the value of
enabled
within thespec.policyController
object totrue
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.
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.
Set the value of
enabled
within thespec.policyController
object totrue
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.
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:
In the Cloud Console, go to the Anthos Config Management page.
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.
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
In the Cloud Console, go to the Anthos Config Management page.
Select the clusters that you want to upgrade.
Click Configure.
Click ACM settings for your clusters.
From the Version dropdown, select the version that you want to upgrade to.
Click Done.
kubectl
Run these commands for each enrolled cluster:
Download the Anthos Config Management manifest and
nomos
commands for the new version.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.
Replace the
nomos
ornomos.exe
command on all clients with the new version. This change ensures that thenomos
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:
Visit the Anthos Config Management menu in Google Cloud Console.
Select the clusters that you want to disable Policy Controller on.
Click Configure.
Click the ACM settings for your clusters heading.
In the Policy Controller section, clear the Policy Controller checkbox.
Click Done.
gcloud
To uninstall the Policy Controller:
Edit the Anthos Config Management configuration in your
config-management.yaml
file and setpolicyController.enabled
tofalse
.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 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.