Policy framework

The policy framework provides governance capabilities to OCM managed Kubernetes clusters. Policies provide visibility and drive remediation for various security and configuration aspects to help IT administrators meet their requirements.

API Concepts

View the Policy API page for additional details about the Policy API managed by the Policy Framework components, including:

Architecture

Policy framework architecture

The governance policy framework distributes policies to managed clusters and collects results to send back to the hub cluster.

Note that in OCM versions newer than 0.8.x, the following controllers were consolidated into the policy framework addon.

Prerequisite

You must meet the following prerequisites to install the policy framework:

  • Ensure kubectl and kustomize are installed.

  • Ensure Golang is installed, if you are planning to install from the source.

  • Ensure the open-cluster-management cluster manager is installed. See Start the control plane for more information.

  • Ensure the open-cluster-management klusterlet is installed. See Register a cluster for more information.

  • If you are using PlacementRules with your policies, ensure the open-cluster-management application is installed . See Application management for more information. If you are using the default Placement API, you can skip the Application management installation, but you do need to install the PlacementRule CRD with this command:

    kubectl apply -f https://raw.githubusercontent.com/open-cluster-management-io/multicloud-operators-subscription/main/deploy/hub-common/apps.open-cluster-management.io_placementrules_crd.yaml
    

Install the governance-policy-framework hub components

Install via Clusteradm CLI

Ensure clusteradm CLI is installed and is at least v0.3.0. Download and extract the clusteradm binary. For more details see the clusteradm GitHub page.

  1. Deploy the policy framework controllers to the hub cluster:

    # The context name of the clusters in your kubeconfig
    # If the clusters are created by KinD, then the context name will the follow the pattern "kind-<cluster name>".
    export CTX_HUB_CLUSTER=<your hub cluster context>           # export CTX_HUB_CLUSTER=kind-hub
    export CTX_MANAGED_CLUSTER=<your managed cluster context>   # export CTX_MANAGED_CLUSTER=kind-cluster1
    
    # Set the deployment namespace
    export HUB_NAMESPACE="open-cluster-management"
    
    # Deploy the policy framework hub controllers
    clusteradm install hub-addon --names governance-policy-framework --context ${CTX_HUB_CLUSTER}
    
  2. Ensure the pods are running on the hub with the following command:

    $ kubectl get pods -n ${HUB_NAMESPACE}
    NAME                                                       READY   STATUS    RESTARTS   AGE
    governance-policy-addon-controller-bc78cbcb4-529c2         1/1     Running   0          94s
    governance-policy-propagator-8c77f7f5f-kthvh               1/1     Running   0          94s
    

Install from source

  1. Deploy the policy Custom Resource Definitions (CRD) and policy propagator component to the open-cluster-management namespace on the hub cluster with the following commands:

    # Configure kubectl to point to the hub cluster
    kubectl config use-context ${CTX_HUB_CLUSTER}
    
    # Create the namespace
    export HUB_NAMESPACE="open-cluster-management"
    kubectl create ns ${HUB_NAMESPACE}
    
    # Set the hub cluster name
    export HUB_CLUSTER_NAME="hub"
    
    # Set the hub kubeconfig file
    export HUB_KUBECONFIG="hub-kubeconfig"
    
    # Apply the CRDs
    export GIT_PATH="https://raw.githubusercontent.com/open-cluster-management-io/governance-policy-propagator/v0.12.0/deploy"
    kubectl apply -f ${GIT_PATH}/crds/policy.open-cluster-management.io_policies.yaml
    kubectl apply -f ${GIT_PATH}/crds/policy.open-cluster-management.io_placementbindings.yaml
    kubectl apply -f ${GIT_PATH}/crds/policy.open-cluster-management.io_policyautomations.yaml
    kubectl apply -f ${GIT_PATH}/crds/policy.open-cluster-management.io_policysets.yaml
    
    # Deploy the policy-propagator
    kubectl apply -f ${GIT_PATH}/operator.yaml -n ${HUB_NAMESPACE}
    
  2. The policy propagator manages a webhook that requires a certificate. You can either disable the webhook or deploy cert-manager alongside the webhook resources to ensure the policy propagator runs properly:

    • Optional 1: Enable the webhook

      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml
      kubectl apply -f ${GIT_PATH}/webhook.yaml -n ${HUB_NAMESPACE}
      
    • Optional 2: Disable the webhook with the --enable-webhooks=false argument

      kubectl patch deployment governance-policy-propagator --type='json' -p='[
           {"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--enable-webhooks=false"}
         ]' -n ${HUB_NAMESPACE}
      kubectl patch deployment governance-policy-propagator --type='json' -p='[
           {"op": "remove", "path": "/spec/template/spec/containers/0/volumeMounts/0"},
           {"op": "remove", "path": "/spec/template/spec/volumes/0"}
         ]' -n ${HUB_NAMESPACE}
      
  3. Ensure the pods are running on the hub with the following command:

    $ kubectl get pods -n ${HUB_NAMESPACE}
    NAME                                                       READY   STATUS    RESTARTS   AGE
    governance-policy-propagator-8c77f7f5f-kthvh               1/1     Running   0          94s
    

Deploy the synchronization components to the managed cluster(s)

Deploy via Clusteradm CLI

  1. To deploy the synchronization components to a self-managed hub cluster:

    clusteradm addon enable --names governance-policy-framework --clusters <managed_hub_cluster_name> --annotate addon.open-cluster-management.io/on-multicluster-hub=true --context ${CTX_HUB_CLUSTER}
    

    To deploy the synchronization components to a managed cluster:

    clusteradm addon enable --names governance-policy-framework --clusters <cluster_name> --context ${CTX_HUB_CLUSTER}
    
  2. Verify that the governance-policy-framework-addon controller pod is running on the managed cluster with the following command:

    $ kubectl get pods -n open-cluster-management-agent-addon
    NAME                                                     READY   STATUS    RESTARTS   AGE
    governance-policy-framework-addon-57579b7c-652zj         1/1     Running   0          87s
    

    NOTE: If you are using clusteradm v0.3.x or older, the pod will be called governance-policy-framework and have a container per synchronization component (2 on a self-managed Hub, or 3 on a managed cluster).

Deploy from source

  1. Export the hub cluster kubeconfig with the following command:

    For kind cluster:

    kind get kubeconfig --name ${HUB_CLUSTER_NAME} --internal > ${HUB_KUBECONFIG}
    

    For non-kind clusters:

    kubectl config view --context=${CTX_HUB_CLUSTER} --minify --flatten > ${HUB_KUBECONFIG}
    
  2. Deploy the policy synchronization component to each managed cluster. Run the following commands:

    NOTE: The --disable-spec-sync flag should be set to true in the governance-policy-framework-addon container arguments when deploying the synchronization component to a hub that is managing itself.

    # Set whether or not this is being deployed on the Hub
    export DEPLOY_ON_HUB=false
    
    # Configure kubectl to point to the managed cluster
    kubectl config use-context ${CTX_MANAGED_CLUSTER}
    
    # Create the namespace for the synchronization components
    export MANAGED_NAMESPACE="open-cluster-management-agent-addon"
    kubectl create ns ${MANAGED_NAMESPACE}
    
    # Create the secret to authenticate with the hub
    kubectl -n ${MANAGED_NAMESPACE} create secret generic hub-kubeconfig --from-file=kubeconfig=${HUB_KUBECONFIG}
    
    # Apply the policy CRD
    export GIT_PATH="https://raw.githubusercontent.com/open-cluster-management-io"
    kubectl apply -f ${GIT_PATH}/governance-policy-propagator/v0.12.0/deploy/crds/policy.open-cluster-management.io_policies.yaml
    
    # Set the managed cluster name and create the namespace
    export MANAGED_CLUSTER_NAME=<your managed cluster name>  # export MANAGED_CLUSTER_NAME=cluster1
    kubectl create ns ${MANAGED_CLUSTER_NAME}
    
    # Deploy the synchronization component
    export COMPONENT="governance-policy-framework-addon"
    kubectl apply -f ${GIT_PATH}/${COMPONENT}/v0.12.0/deploy/operator.yaml -n ${MANAGED_NAMESPACE}
    kubectl patch deployment governance-policy-framework-addon -n ${MANAGED_NAMESPACE} \
      -p "{\"spec\":{\"template\":{\"spec\":{\"containers\":[{\"name\":\"governance-policy-framework-addon\",\"args\":[\"--hub-cluster-configfile=/var/run/klusterlet/kubeconfig\", \"--cluster-namespace=${MANAGED_CLUSTER_NAME}\", \"--enable-lease=true\", \"--log-level=2\", \"--disable-spec-sync=${DEPLOY_ON_HUB}\"]}]}}}}"
    
  3. Verify that the pods are running on the managed cluster with the following command:

    $ kubectl get pods -n ${MANAGED_NAMESPACE}
    NAME                                                READY   STATUS    RESTARTS   AGE
    governance-policy-framework-addon-6474b6d898-tmkw6  1/1     Running   0          2m14s
    

What is next

Install the policy controllers to the managed clusters.

Last modified September 20, 2024: Refactor using docsy. (#429) (3f36d75)