Get Started

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.

Policy Controller is available if you use KOSMOS.

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 .

Before you begin

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

  1. Ensure open source Open Policy Agent Gatekeeper is not installed on your cluster. If it is, uninstall Gatekeeper before installing Policy Controller.
  2. 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.
  3. If you’re using GKE clusters, ensure that your GKE cluster does not have the GKE Policy Controller add-on.
  4. 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 .

Install Policy Controller

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

  1. In the KOSMOS console, go to the Policy tab under the Fleet section.

  2. Click Install Policy Controller.

  3. Optional: To change the default fleet settings, click Edit Policy Controller. 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.
      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. In the Version list, select the Policy Controller version that you want to use.

    3. In the Select target clusters section, include or exclude a cluster which Policy Controller will be deployed.

    4. Click Save.

[!TIP] Exempt system namespaces to avoid errors in your environment. You can find the instructions to exempt namespaces and a list of common namespaces created by KOSMOS on the Exclude namespaces page .

  1. Click Save.
  2. Optional: Sync existing clusters to the default settings:
    1. In the Settings tab, click Sync to fleet settings.
    2. In the Clusters in the fleet list, select the clusters that you want to sync and then click Sync to fleet settings. This operation can take a few minutes to complete.

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.

Verify the Policy Controller installation

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

Complete the following steps:

  1. In the KOSMOS console, go to the Policy page under the Fleet section.
  2. Under the Settings tab, in the cluster table, check the Policy controller status column. A successful installation has a status of Installed.

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.

Complete the following steps:

  1. In the KOSMOS console, go to the Policy page under the Fleet section.
  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.

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

Upgrade Policy Controller

To upgrade Policy Controller, complete the following steps:

  1. In the KOSMOS console, go to the Policy page under the Fleet section.
  2. Under the Settings tab, next to the cluster whose version you want to upgrade, select edit 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.

Uninstall Policy Controller

Follow these steps to uninstall Policy Controller from your clusters.

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

  1. In the KOSMOS console, go to the Policy page under the Fleet section.
  2. Under the Settings tab, in the cluster table, select Edit in the Edit configuration column.
  3. In the cluster pane, expand the Deployment status menu.
  4. Select Uninstall Policy Controller.
  5. Confirm the uninstall by following the instructions in the confirmation dialog and selecting Uninstall.

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

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.

Custom RBAC permissions for Policy Controller

Policy functionality is recommended to be restricted to fleet administrators only. When creating custom roles, fleet administrators must include the following verbs for the specified resources.

Policy management permissions:

To manage policies, include these permissions:

  • fleetpolicyset: get, patch, update
  • clusterpolicyset: get, list, patch, update
  • policyconfig, policyreport: get

Policy viewing permissions:

To view policy results and status, include these permissions:

  • fleetpolicyset, policyconfig, policyreport: get
  • clusterpolicyset: get, list

What’s next

Edit this page on GitHub

← Discover
Kosmos building blocks →