Uploaded image for project: 'Red Hat Advanced Cluster Management'
  1. Red Hat Advanced Cluster Management
  2. ACM-4766

Document native Gatekeeper constraint support in policies

XMLWordPrintable

    • False
    • None
    • False
    • ACM-2707 - ACM Gatekeeper Enhancements
    • No

      Create an informative issue (See each section, incomplete templates/issues won't be triaged)

      Using the current documentation as a model, please complete the issue template. 

      Note: Doc team updates the current version and the two previous versions (n-2). For earlier versions, we will address only high-priority, customer-reported issues for releases in support.

      Prerequisite: Start with what we have

      Always look at the current documentation to describe the change that is needed. Use the source or portal link for Step 4:

       - Use the Customer Portal: https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes

       - Use the GitHub link to find the staged docs in the repository: https://github.com/stolostron/rhacm-docs 

      Describe the changes in the doc and link to your dev story

      Provide info for the following steps:

      1. - [x] Mandatory Add the required version to the Fix version/s field.

      2. - [x] Mandatory Choose the type of documentation change.

            - [x] New topic in an existing section or new section
            - [ ] Update to an existing topic

      3. - [x] Mandatory for GA content:
                  
             - [ ] Add steps and/or other important conceptual information here: 

      Red Hat Advanced Cluster Management now provides integration with Gatekeeper, which is a supported Kubernetes admission controller available with a RHACM subscription. This integration allows multicluster distribution and Gatekeeper audit results aggregation on the ACM Hub using RHACM policies. This is done by directly including a Gatekeeper constraint and optionally the associated ConstraintTemplate in a policy's `policy-templates` array. Note that Gatekeeper installation is a prerequisite on the managed cluster before using this feature.

      An example below shows a policy that defines a Gatekeeper ConstraintTemplate and constraint (K8sRequiredLabels) to ensure the "gatekeeper" label is set on all namespaces. Because the policy's `remediationAction` is set to `inform`, the Gatekeeper constraint's "enforcementAction" field will be overridden to `warn`. In this context, this means that Gatekeeper would not prevent the user from creating or updating a namespace without the "gatekeeper" label, but would be warned.  If the policy's `remediationAction` is set to `enforce`, the Gatekeeper constraint's "enforcementAction" field will be overridden to `deny`, which in this context, would prevent any user from creating or updating a namespace without the "gatekeeper" label. If the policy's `remediationAction` was not set, the Gatekeeper constraint's "enforcementAction" field would be honored.

      With this policy, any namespaces that do not have the "gatekeeper" label would be detected by Gatekeeper's audit functionality, which runs every minute by default. These audit results are sent back to the RHACM Hub cluster to be viewed in the policy status of the managed cluster. These status messages are in the format of `<enforcementAction> - <message> (on <kind> <namespace/name or name>)`. With this policy, you might see a message like `warn - you must provide labels: {"gatekeeper"} (on Namespace default); warn - you must provide labels: {"gatekeeper"} (on Namespace gatekeeper-system)`.

      Once a policy containing Gatekeeper constraints or ConstraintTemplates is deleted, the constraints and ConstraintTemplates in the policy are also deleted from the managed cluster.

      apiVersion: policy.open-cluster-management.io/v1
      kind: Policy
      metadata:
        name: require-gatekeeper-labels-on-ns
      spec:
        remediationAction: inform
        disabled: false
        policy-templates:
          - objectDefinition:
              apiVersion: templates.gatekeeper.sh/v1beta1
              kind: ConstraintTemplate
              metadata:
                name: k8srequiredlabels
              spec:
                crd:
                  spec:
                    names:
                      kind: K8sRequiredLabels
                    validation:
                      openAPIV3Schema:
                        properties:
                          labels:
                            type: array
                            items: string
                targets:
                  - target: admission.k8s.gatekeeper.sh
                    rego: |
                      package k8srequiredlabels                violation[{"msg": msg, "details": {"missing_labels": missing}}] {
                        provided := {label | input.review.object.metadata.labels[label]}
                        required := {label | label := input.parameters.labels[_]}
                        missing := required - provided
                        count(missing) > 0
                        msg := sprintf("you must provide labels: %v", [missing])
                      }
          - objectDefinition:
              apiVersion: constraints.gatekeeper.sh/v1beta1
              kind: K8sRequiredLabels
              metadata:
                name: ns-must-have-gk
              spec:
                enforcementAction: dryrun
                match:
                  kinds:
                    - apiGroups: [""]
                      kinds: ["Namespace"]
                parameters:
                  labels: ["gatekeeper"] 

                  
             - [ ] Add Required access level for the user to complete the task here:

       

             - [ ] Add verification at the end of the task, how does the user verify success (a command to run or a result to see?)
           
           
             - [x] Add link to dev story here:
      https://issues.redhat.com/browse/ACM-3322

      4. - [ ] Mandatory for bugs: What is the diff? Clearly define what the problem is, what the change is, and link to the current documentation:

            mdockery@redhat.com Mikela Jackson
            mprahl Matthew Prahl
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: