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

Doc governance-standalone-hub-templating addon

XMLWordPrintable

    • None

      Note: Doc team updates the current version of the documentation and the
      two previous versions (n-2), but we address *only high-priority, or
      customer-reported issues* for -2 releases in support.
      Describe the changes in the doc and link to your dev story:

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

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

      • [ ] We need to update to an existing topic
      • [x] We need to add a new document to an existing section
      • [ ] We need a whole new section; this is a function not
        documented before and doesn't belong in any current section
      • [ ] We need an Operator Advisory review and approval
      • [ ] We need a z-Stream (Errata) Advisory and Release note
        for MCE and/or ACM

      3. - [x] *Mandatory: *Use the following link to open the doc and find where the
      documentation update should go. Note: As the feature and doc is
      understood and developed, this placement decision may change:

      I believe a new subsection under "Advanced template processing in configuration policies" would be a good fit. https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html-single/governance/index#adv-template-processing . In the source: https://github.com/stolostron/rhacm-docs/blob/2.13_stage/governance/adv_template_process.adoc 

      Additionally, the new section should be mentioned under the "Policy deployment with external tools" section https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html-single/governance/index#policy-deploy-ext-tools source: https://github.com/stolostron/rhacm-docs/blob/2.13_stage/governance/pol_deploy_ext_tools.adoc 

      4. - [ ] Mandatory for GA content:

      • [x] Add steps, the diff, known issue, and/or other important
        conceptual information in the following space:

      Design doc for the feature: https://github.com/open-cluster-management-io/enhancements/blob/main/enhancements/sig-policy/134-standalone-hub-templates/README.md 

      In fewer/different words: the new `governance-standalone-hub-templating` ManagedClusterAddOn, which is disabled by default, will allow users to define ConfigurationPolicies directly on their managed clusters (or via another tool like ArgoCD) but still use hub templates to get information from their hub cluster. Previously, hub templates were only resolved by the policy framework, and so required putting the ConfigurationPolicy into a Policy on the hub cluster for distribution via Placement.

      To enable the addon/feature, the user must create a ManagedClusterAddOn resource on the hub cluster, with the name `governance-standalone-hub-templating` inside the managed cluster namespace. For example:

       

      apiVersion: addon.open-cluster-management.io/v1alpha1
      kind: ManagedClusterAddOn
      metadata:
        name: governance-standalone-hub-templating
        namespace: <cluster name>
        labels:
          cluster.open-cluster-management.io/backup: ''
      spec: {}

       

      This must be done for each managed cluster that will use the feature.

      By default, the agent on the managed cluster will only have access to the ManagedCluster resources on the hub. This allows for use of the `.ManagedClusterLabels` template variable in hub cluster templates inside of ConfigurationPolicies deployed directly to the managed cluster. If the hub template needs access to other resources, for example via `lookup` or `fromConfigMap` function calls, those specific permissions will need to be added to the addon's group via the usual RBAC resources like Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings. The addon's group name varies based on the managed cluster name, but takes this form: `system:open-cluster-management:cluster:<cluster name>:addon:governance-standalone-hub-templating`.

      For example, the following commands on the hub cluster would allow access to configmaps in the managed cluster namespace:

      oc create role -n <cluster name> cm-reader --verb=get,list,watch --resource=configmaps
      oc create rolebinding -n <cluster name> cm-reader-binding --role=cm-reader --group=system:open-cluster-management:cluster:<cluster name>:addon:governance-standalone-hub-templating

      Note: after the hub templates are resolved using this feature, the state of the policy is saved in a secret on the managed cluster to prevent interruptions if the hub cluster becomes temporarily unavailable to the managed cluster.

      Note: in order to be backed up and restored properly, any resources on the hub used by this feature (including the roles/rolebindings) need to have the `cluster.open-cluster-management.io/backup` label. See https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html-single/business_continuity/index#resources-that-are-backed-up / https://github.com/stolostron/rhacm-docs/blob/2.13_stage/business_continuity/backup_restore/backup_arch.adoc 

      • [x] *Add Required access level *(example, *Cluster
        Administrator*) for the user to complete the task:

      Cluster Administrator is required

      • [x] Add verification at the end of the task, how does the user
        verify success (a command to run or a result to see?)

      When properly configured, a ConfigurationPolicy deployed directly to the managed cluster using a hub cluster template should be able to be resolved and use information from the hub cluster.

      5. - [ ] Mandatory for bugs: What is the diff? Clearly define what the
      problem is, what the change is, and link to the current documentation. Only
      use this for a documentation bug.

              jberger@redhat.com Jacob Berger
              jkulikau@redhat.com Justin Kulikauskas
              Derek Ho Derek Ho
              ACM GRC & Gatekeeper
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Created:
                Updated:
                Resolved: