Chapter 3. Policy controllers overview

Additional resources

• Create configuration policies
• Hub cluster policy framework
• NIST Special Publication 800-53 (Rev. 4)
• CM-Configuration-Management folder
• Dry-run
• Supported policies
• Policy controllers overview
• Policy controller advanced configuration
• Cleaning up resources that are created by policies
• Policy Generator configuration
• Governance dashboard
• Template processing in policies

• Find the description of a field on your managed cluster.

  Run the following command and replace <field-path> with the path to the field that you need:

  oc explain --api-version=policy.open-cluster-management.io/v1 ConfigurationPolicy.<field-path>

• Configuration policy YAML file structure:

  apiVersion: policy.open-cluster-management.io/v1
  kind: ConfigurationPolicy
  metadata:
    name: policy-config
  spec:
    namespaceSelector:
      include: ["default"]
      exclude: []
      matchExpressions: []
      matchLabels: {}
    remediationAction: inform
    customMessage:
      compliant: {}
      noncompliant: {}
    severity: low
    evaluationInterval:
      compliant: ""
      noncompliant: ""
    object-templates-raw: ""
    object-templates:
     - complianceType: musthave
       metadataComplianceType:
       recordDiff: ""
       recreateOption: ""
       objectSelector:
         matchLabels: {}
         matchExpressions: []
       objectDefinition:
         apiVersion: v1
         kind: Pod
         metadata:
           name: pod
         spec:
           containers:
            - image: pod-image
              name: pod-name
              ports:
               - containerPort: 80
     - complianceType: mustonlyhave
       objectDefinition:
         apiVersion: v1
         kind: ConfigMap
         metadata:
           name: myconfig
           namespace: default
           data:
             testData: hello

• When the remediationAction for the configuration policy is set to enforce, the controller applies the specified configuration to the target managed cluster. However, configuration policies that specify an object without a name can only be set to inform, unless the objectSelector is also configured.
• A Kubernetes object is defined in the object-templates array in the configuration policy, where fields of the configuration policy controller is compared with objects on the managed cluster. You can also use templated values within configuration policies. For more advanced use cases, specify a string in object-templates-raw to create the object-templates that you want. For more information, see Template processing.
• Configuration policy YAML table

Additional resources

• Kubernetes labels and selectors

• Configuration policy objectSelector:

  To iterate over multiple objects filtered by a label within a ConfigurationPolicy resource, use the objectSelector parameter and specify the object kind in the objectDefinition parameter. The objectSelector parameter operates similarly to namespaceSelector but does not support name filtering. To filter by name, use the skipObject Go template function. Referencing {{ skipObject }} excludes that specific object from the selection.

  • Object selection configuration example

  ...
  object-templates:
    - objectSelector:
        matchExpressions:
        - key: foo
          operator: In
          values:
          - bar
      objectDefinition:
        apiVersion: v1
        kind: ConfigMap
        data:
          key: '{{ if (hasSuffix "-prod" .ObjectName) }}{{ skipObject }}{{ end }}{{ hasNodesWithExactRoles "infra" }}'

• Raw template processing

  The optional object-templates-raw parameter supports advanced templating use cases, such as the if conditional function and the range loop function. The object-templates-raw parameter accepts a string containing Go templates that must resolve to an object-templates array.

  Note: You must set exactly one of either spec.object-templates or spec.object-templates-raw.

  • Raw template configuration example with conditional labels

    object-templates-raw: |
      {{- range (lookup "v1" "ConfigMap" "default" "").items }}
      {{- if eq .data.name "Sea Otter" }}
      - complianceType: musthave
        objectDefinition:
          kind: ConfigMap
          apiVersion: v1
          metadata:
            name: {{ .metadata.name }}
            namespace: {{ .metadata.namespace }}
            labels:
              species-category: mammal
      {{- end }}
      {{- end }}

  • Policy configuration example creating infrastructure MachineSet objects

  apiVersion: policy.open-cluster-management.io/v1
  kind: ConfigurationPolicy
  metadata:
    name: create-infra-machineset
  spec:
    remediationAction: enforce
    severity: low
    object-templates-raw: |
      {{- /* Specify the parameters needed to create the MachineSet  */ -}}
      {{- $machineset_role := "infra" }}
      {{- $region := "ap-southeast-1" }}
      {{- $zones := list "ap-southeast-1a" "ap-southeast-1b" "ap-southeast-1c" }}
      {{- $infrastructure_id := (lookup "config.openshift.io/v1" "Infrastructure" "" "cluster").status.infrastructureName }}
      {{- $worker_ms := (index (lookup "machine.openshift.io/v1beta1" "MachineSet" "openshift-machine-api" "").items 0) }}
      {{- /* Generate the MachineSet for each zone as specified  */ -}}
      {{- range $zone := $zones }}
      - complianceType: musthave
        objectDefinition:
          apiVersion: machine.openshift.io/v1beta1
          kind: MachineSet
          metadata:
            labels:
              machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
            name: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
            namespace: openshift-machine-api
          spec:
            replicas: 1
            selector:
              matchLabels:
                machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
                machine.openshift.io/cluster-api-machineset: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
            template:
              metadata:
                labels:
                  machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
                  machine.openshift.io/cluster-api-machine-role: {{ $machineset_role }}
                  machine.openshift.io/cluster-api-machine-type: {{ $machineset_role }}
                  machine.openshift.io/cluster-api-machineset: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
              spec:
                metadata:
                  labels:
                    node-role.kubernetes.io/{{ $machineset_role }}: ""
                taints:
                  - key: node-role.kubernetes.io/{{ $machineset_role }}
                    effect: NoSchedule
                providerSpec:
                  value:
                    ami:
                      id: {{ $worker_ms.spec.template.spec.providerSpec.value.ami.id }}
                    apiVersion: awsproviderconfig.openshift.io/v1beta1
                    blockDevices:
                      - ebs:
                          encrypted: true
                          iops: 2000
                          kmsKey:
                            arn: ''
                          volumeSize: 500
                          volumeType: io1
                    credentialsSecret:
                      name: aws-cloud-credentials
                    deviceIndex: 0
                    instanceType: {{ $worker_ms.spec.template.spec.providerSpec.value.instanceType }}
                    iamInstanceProfile:
                      id: {{ $infrastructure_id }}-worker-profile
                    kind: AWSMachineProviderConfig
                    placement:
                      availabilityZone: {{ $zone }}
                      region: {{ $region }}
                    securityGroups:
                      - filters:
                          - name: tag:Name
                            values:
                              - {{ $infrastructure_id }}-worker-sg
                    subnet:
                      filters:
                        - name: tag:Name
                          values:
                            - {{ $infrastructure_id }}-private-{{ $zone }}
                    tags:
                      - name: kubernetes.io/cluster/{{ $infrastructure_id }}
                        value: owned
                    userDataSecret:
                      name: worker-user-data
      {{- end }}

Additional resources

• Template functions
• Configuration policy controller

• Non-compliant scernarios

  A policy status changes to non-compliant when either of these situations occurs:

• When a certificate expires in less than the minimum duration of time or exceeds the maximum time.
• When DNS names fail to match the specified pattern.

• Certificate policy controller does not support the enforce feature.
• The certificate policy controller automatically looks for a certificate in a secret in only the tls.crt key. If you store a secret in a different key, define the certificate_key_name parameter. For example, if you have a secret that contains a sensor-cert.pem certificate, add the following label to the secret: certificate_key_name: sensor-cert.pem.

Additional resources

• Hub cluster policy framework
• Certificate policy controller schema and parameters
• Creating security policies
• Policy controllers introduction
• Certificates

• Certificate policy YAML file structure

  apiVersion: policy.open-cluster-management.io/v1
  kind: CertificatePolicy
  metadata:
    name: certificate-policy-example
  spec:
    namespaceSelector:
      include: ["default"]
      exclude: []
      matchExpressions: []
      matchLabels: {}
    labelSelector:
      myLabelKey: myLabelValue
    remediationAction:
    severity:
    minimumDuration:
    minimumCADuration:
    maximumDuration:
    maximumCADuration:
    allowedSANPattern:
    disallowedSANPattern:

• Certificate policy controller YAML file table

Additional resources

• Kubernetes labels and selectors
• Golang Parse Duration
• Golang Regular Expression syntax

• The Red Hat Advanced Cluster Management sample policy set uses cluster placement. If you use cluster placement, bind the namespace containing the policy to the managed cluster set. See Deploying policies to your cluster for more details on using cluster placement.
• To use a Placement resource, bind a ManagedClusterSet resource to the namespace of the Placement resource with a ManagedClusterSetBinding resource. See Creating a ManagedClusterSetBinding resource for additional details.

• Policy set YAML structure

  Your policy set might resemble the following YAML file:

• Policy set table

  View the following parameter table for descriptions:

• Policy set sample

  apiVersion: policy.open-cluster-management.io/v1beta1
  kind: PolicySet
  metadata:
    name: pci
    namespace: default
  spec:
    description: Policies for PCI compliance
    policies:
    - policy-pod
    - policy-namespace
  status:
    compliant: NonCompliant
    placement:
    - placementBinding: binding1
      placement: placement1
      policySet: policyset-ps

Additional resources

• Deploying policies to your cluster
• Creating a ManagedClusterSetBinding resource
• Red Hat OpenShift Platform Plus policy set
• Create policy sets from the command line

• Operator Lifecycle Manager must be available on your managed cluster. This is enabled by default on Red Hat OpenShift Container Platform.
• Required access: Cluster administrator

• Operator policy YAML table

  Field	Optional or required	Description
  apiVersion	Required	Set the value to policy.open-cluster-management.io/v1beta1.
  kind	Required	Set the value to OperatorPolicy to indicate the type of policy.
  metadata.name	Required	The name for identifying the policy resource.
  spec.remediationAction	Required	If the remediationAction for the operator policy is set to enforce, the controller creates resources on the target managed cluster to communicate to OLM to install the operator and approve updates based on the versions specified in the policy. + If the remediationAction set to inform, the controller only reports the status of the operator, including if any upgrades are available.
  spec.operatorGroup	Optional	By default, if the operatorGroup field is not specified, the controller generates an AllNamespaces type OperatorGroup resource in the same namespace as the subscription, if supported. The operator policy controller produces this resource. View the following parameter descriptions: name: The name of the OperatorGroup resource. namespace: The namespace of the OperatorGroup resource. This parameter must match the namespace where you install the operator. targetNamespaces: A list of namespaces that the operator is configured to watch and operate.
  spec.complianceType	Required	Specifies the desired state of the operator on the cluster. If set to musthave, the policy is compliant when the operator is found. If set to mustnothave, the policy is compliant when the operator is not found.
  spec.removalBehavior	Optional	Determines which resource types need to be kept or removed when you enforce an OperatorPolicy resource with complianceType: mustnothave defined. There is no effect when complianceType is set to musthave. View the following parameter descriptions: operatorGroups can be set to Keep or DeleteIfUnused. The default value is DeleteIfUnusued which only removes the OperatorGroup resource if it is not used by any other operators. subscriptions can be set to Keep or Delete. The default value is Delete. clusterServiceVersions can be set to Keep or Delete. The default value is Delete. customResourceDefinitions can be set to Keep or Delete. The default value is Keep. If you set this to Delete, the CustomResourceDefintion resources on the managed cluster are removed and can cause data loss.
  spec.subscription	Required	Define the configurations to create an operator subscription. Add information in the following fields to create an operator subscription. View the following parameter descriptions: channel: If not specified, the default channel is selected from the operator catalog. The default can be different on different OpenShift Container Platform versions. name: Specify the package name of the operator. namespace: If not specified, the default namespaced that is used for OpenShift Container Platform managed clusters is openshift-operators. source: If not specified, the catalog that contains the operator is chosen. sourceNamespace: If not specified, the namespace of the catalog that contains the operator is chosen. config: Optional. Specify extra configuration details for the operator subscription. The name field is the only required field. The other fields are populated based on the catalog information within the managed cluster. Note: If you define a value for the installPlanApproval field in this parameter section, the policy becomes non-compliant. Use spec.upgradeApproval in the OperatorPolicy resource.
  spec.complianceConfig	Optional	Use this parameter to define the compliance behavior for specific scenarios that are associated with operators. You can set each of the following options individually, where the supported values are Compliant and NonCompliant: catalogSourceUnhealthy: Define the compliance when the catalog source for the operator is unhealthy. The default value is Compliant because this only affects possible upgrades. deploymentsUnavailable: Define the compliance when at least one deployment of the operator is not fully available. The default value is NonCompliant because this reflects the availability of the service that the operator provides. upgradesAvailable: Define the compliance when there is an upgrade available for the operator. The default value is Compliant because the existing operator installation might be running correctly. deprecationsPresent: Specifies that the compliance of the policy is affected by the deprecations. For example, the default value is Compliant, but if the deprecationsPresent=NonCompliant configuration detects the deprecations, then the policy compliance status is set to NonCompliant. minorChannelUpgradeAvailable: Detects if a minor version upgrade is available for the operator on different channels. The default value is Compliant.
  spec.upgradeApproval	Required	If the upgradeApproval field is set to Automatic, version upgrades on the cluster are approved by the policy when the policy is set to enforce. If you set the field to None, version upgrades to the specific operator are not approved when the policy is set to enforce.
  spec.versions	Optional	Declare which versions of the operator are compliant. The versions parameter is a list of templatable strings that specifies which installed ClusterServiceVersion names are compliant when in inform mode, and which InstallPlans are approved when in enforce mode. To give different versions in one entry, separate the versions with commas. If the field is empty, the strings are ignored and all ClusterServiceVersion names are approved. The default value is empty.

Additional resources

• Template processing in policies
• Create an operator policy to install an operator
• Deploy operators using policies
• Subscription
• Operator Lifecycle Manager (OLM)
• Adding Operators to a cluster