Merge pull request #7337 from stolostron/2.12_stage

2.12 refresh Dec 12 2024

apis/clusterinstance.json.adoc

@@ -362,9 +362,24 @@ The default value is `None`.|string
 |*diskEncryption* +
 __optional__|Enable or disable disk encryption for the cluster.|object
 |*extraAnnotations* +
-__optional__|Specify additional cluster-level annotations to be applied to the rendered templates.|object
+__optional__|Specify additional cluster-level annotations to be applied to the rendered templates by using the following format: +
+[source,yaml]
+----
+extraAnnotations:
+  ClusterDeployment:
+    myClusterAnnotation: success
+----
+|object
 |*extraLabels* +
-__optional__|Specify additional cluster-level labels to be applied to the rendered templates.|object
+__optional__|Specify additional cluster-level labels to be applied to the rendered templates by using the following format: +
+[source,yaml]
+----
+extraLabels:
+  ManagedCluster:
+    common: "true"
+    label-a : "value-a"
+----
+|object
 |*extraManifestsRefs* +
 __optional__|Specify the list of the `ConfigMap` object references that contain additional manifests to be applied to the cluster.|array
 |*holdInstallation* +
@@ -438,9 +453,24 @@ The following values are supported:
 * `UEFISecureBoot`
 * `legacy`|string
 |*extraAnnotations* +
-__optional__|Specify additional node-level annotations to be applied to the rendered templates.|object
+__optional__|Specify additional node-level annotations to be applied to the rendered templates by using the following format: +
+[source,yaml]
+----
+extraAnnotations:
+  BareMetalHost:
+    myNodeAnnotation: success
+----
+|object
 |*extraLabels* +
-__optional__|Specify additional node-level labels to be applied to the rendered templates.|object
+__optional__|Specify additional node-level labels to be applied to the rendered templates. +
+[source,yaml]
+----
+extraLabels:
+  ManagedCluster:
+    common: "true"
+    label-a : "value-a"
+----
+|object
 |*hostName* +
 __required__|Define the host name.|string
 |*installerArgs* +

governance/policy_ctrl_adv_config.adoc

@@ -164,7 +164,7 @@ Logging the diff:
 [#gov-metric]
 == Governance metric
 
-The policy framework exposes metrics that show policy distribution and compliance. Use the `policy_governance_info` metric on the hub cluster to view trends and analyze any policy failures. See the following topics for an overview of metrics:
+The policy framework exposes metrics that show policy distribution and status. Use the `policy_governance_info` metric on the hub cluster to view trends and analyze any policy failures. See the following topics for an overview of metrics:
 
 [#metric-policy-governance-info]
 === Metric: policy_governance_info

governance/policy_deployment.adoc

@@ -36,9 +36,9 @@ See the following comparison table to learn which option supports specific featu
 | Yes, you can have a combination of statuses and deployments through `Policy` and `PolicySet` resources.
 | You cannot use policy grouping directly on your policies when deployed from external tools, but Argo CD `Application` objects for each grouping gives a high-level status.
 
-| Compliance history
+| Policy event history
 | You can view the last 10 events per cluster per policy stored on the hub cluster.
-| No, but you can scrape the compliance history from the controller logs on each managed cluster.
+| No, but you can scrape the policy event history from the controller logs on each managed cluster.
 
 | Policy dependencies
 | Yes
@@ -54,19 +54,19 @@ You must complete extra configuration for Argo CD versions earlier than 2.13.
 | Yes
 | Yes
 
-| Policy compliance history API (Technology Preview) 
+| Policy compliance history API (Technology Preview) (Deprecated)
 | Yes
 | No
 
 | {gitops-short} applying native Kubernetes manifests and {acm-short} policy on the managed cluster
 | No, you must deploy a policy on your {acm-short} hub cluster.
 | Yes
 
-| Policy compliance metric on the hub cluster for alerts
+| Policy status metric on the hub cluster for alerts
 | Yes
 | No
 
-| Running Ansible jobs on policy noncompliance
+| Running Ansible jobs on violated policies
 | Yes, use the `PolicyAutomation` resource.
 | No
 |===

mce_acm_integration/siteconfig/siteconfig_install_clusters.adoc

@@ -67,7 +67,7 @@ data:
   .dockerconfigjson: <encoded_docker_configuration> <2>
 type: kubernetes.io/dockerconfigjson
 ----
-<1> The `namespace` value must match the target namespace.
+<1> Ensure that the `namespace` value matches the target namespace.
 <2> Specify the base64-encoded configuration file as the value. 
 
 . Apply the file to create the resource. Run the following command on the hub cluster:
@@ -98,7 +98,7 @@ metadata:
   namespace: "example-sno" <1>
 type: Opaque
 ----
-<1> The `namespace` value must match the target namespace.
+<1> Ensure that the `namespace` value matches the target namespace.
 
 . Apply the file to create the resource. Run the following command on the hub cluster:
 
@@ -148,7 +148,7 @@ data:
       containerRuntimeConfig:
         defaultRuntime: crun
 ----
-<1> The `namespace` value must match the target namespace.
+<1> Ensure that the `namespace` value matches the target namespace.
 
 . Create the resource by running the following command on the hub cluster:
 
@@ -198,13 +198,13 @@ spec:
           namespace: rhacm
       [...]
 ----
-<1> The `namespace` in the `ClusterInstance` custom resource must match the target namespace that you defined.
+<1> Ensure that the `namespace` in the `ClusterInstance` custom resource matches the target namespace that you defined.
 <2> Reference the `name` of one or more extra manifests `ConfigMap` objects.
 <3> Reference the `name` of your pull secret.
-<4> The value of the `clusterName` field in the `ClusterInstance` custom resource must match the value of the `namespace` field.
-<5> Reference the `name` of the cluster-level templates under the `spec.templateRefs` field. If you are using a default installation template, the `namespace` must match the namespace where the Operator is installed.
+<4> Ensure that the value of the `clusterName` field in the `ClusterInstance` custom resource matches the value of the `namespace` field.
+<5> Reference the `name` of the cluster-level templates in the `spec.templateRefs` field. If you are using a default installation template, the `namespace` must match the namespace where the Operator is installed.
 <6> Reference the `name` of the BMC secret.
-<7> Reference the `name` of the node-level templates under the `spec.nodes.templateRefs` field. If you are using a default installation template, the `namespace` must match the namespace where the Operator is installed.
+<7> Reference the `name` of the node-level templates in the `spec.nodes.templateRefs` field. If you are using a default installation template, the `namespace` must match the namespace where the Operator is installed.
 
 . Apply the file and create the resource by running the following command:
 

mce_acm_integration/siteconfig/siteconfig_installation_templates.adoc

@@ -14,6 +14,7 @@ For more information about installation templates, see the following documentati
 * <<default-templates,Default set of templates>>
 * <<special-template-variables,Special template variables>>
 * <<custom-manifest-order,Customization of the manifests order>>
+* <<extra-annotations-labels,Configuration of additional annotations and labels>>
 
 [#template-functions]
 == Template functions
@@ -70,6 +71,8 @@ The {sco} provides the following default, validated, and immutable set of templa
 `NetworkSecret`
 |===
 
+For more information about the `ClusterInstance` API, see link:../../apis/clusterinstance.json.adoc#clusterinstance-api[ClusterInstance API].
+
 [#special-template-variables]
 == Special template variables
 
@@ -136,4 +139,91 @@ metadata:
   namespace: example-namespace
 ----
 
-If the {sco} deletes the resources, `KlusterletAddonConfig` and `ManagedCluster` custom resources are the first to be deleted, while the `AgentClusterInstall` and `ClusterDeployment` custom resources are the last.
+If the {sco} deletes the resources, `KlusterletAddonConfig` and `ManagedCluster` custom resources are the first to be deleted, while the `AgentClusterInstall` and `ClusterDeployment` custom resources are the last.
+
+[#extra-annotations-labels]
+== Configuration of additional annotations and labels
+
+You can configure additional annotations and labels to both cluster-level and node-level installation manifests by using the `extraAnnotations` and `extraLabels` fields in the `ClusterInstance` API.
+The {sco} applies your additional annotations and labels to the manifests that you specify in the `ClusterInstance` resource.
+
+When creating your additional annotations and labels, you must specify a manifest type to allow the {sco} to apply them to all the matching manifests.
+However, the annotations and labels are arbitrary and you can set any key and value pairs that are meaningful to your applications.
+
+*Note:* The additional annotations and labels are only applied to the resources that were rendered through the referenced templates.
+
+View the following example application of `extraAnnotations` and `extraLabels`:
+
+.Example application of `extraAnnotations` and `extraLabels`
+[source,yaml]
+----
+apiVersion: siteconfig.open-cluster-management.io/v1alpha1
+kind: ClusterInstance
+metadata:
+  name: "example-sno"
+  namespace: "example-sno"
+spec:
+  [...]
+  clusterName: "example-sno"
+  extraAnnotations: <1>
+    ClusterDeployment:
+      myClusterAnnotation: success
+  extraLabels: <1>
+    ManagedCluster:
+      common: "true"
+      group-du: ""
+  nodes:
+    - hostName: "example-sno.example.redhat.com"
+      role: "master"
+      extraAnnotations: <2>
+        BareMetalHost:
+          myNodeAnnotation: success
+      extraLabels: <2>
+        BareMetalHost:
+          "testExtraLabel": "success"
+----
+<1> This field supports cluster-level annotations and labels that the {sco} applies to the the `ManagedCluster` and `ClusterDeployment` manifests.
+<2> This field supports node-level annotations and labels that the {sco} applies to the `BareMetalHost` manifest.
+
+* You can verify that your additional labels are applied by running the following command:
+
++
+--
+[source,terminal]
+----
+oc get managedclusters example-sno -ojsonpath='{.metadata.labels}' | jq
+----
+
+View the following example of applied labels:
+
+.Example applied labels
+[source,json]
+----
+{
+  "common": "true",
+  "group-du": "",
+  ...
+}
+----
+--
+
+* You can verify that your additional annotations are applied by running the following command:
+
++
+--
+[source,terminal]
+----
+oc get bmh example-sno.example.redhat.com -n example-sno -ojsonpath='{.metadata.annotations}' | jq
+----
+
+View the following example of applied annotations:
+
+.Example applied annotation
+[source,json]
+----
+{
+  "myNodeAnnotation": "success",
+  ...
+}
+----
+--

release_notes/acm_whats_new.adoc

@@ -44,12 +44,14 @@ Learn about what is new in the {acm-short} integrated console.
 
 * Command line interface (CLI) downloads are now available in the console, which are available from the `acm-cli` container image and are specified with the operating system and architecture. See link:../console/console.adoc#command-line-tools[Command line tools] to access command line interface (CLI) downloads, such as the `PolicyGenerator` and `policytools`.
 
-* View more information about your cluster when you enable the _Fleet view_ switch. Many summary cards are redesigned, such as _Cluster_ and _Application types_ cards. Additionally, many new summary cards are available, such as _Cluster recommendations_, _Nodes_. See the numerous changes to summary cards in the product console.
+* View more information about your cluster when you enable the _Fleet view_ switch. Many summary cards are redesigned, such as _Cluster_, _Application types_, _Policies_, and _Nodes_ cards. Additionally, there are two new summary cards available, such as _Cluster version_ and _Worker core count_. See the numerous changes to summary cards in the product console.
 
 * You can now export data in a CSV file by using selecting the *Export* button. See link:../console/console_access.adoc#accessing-your-console[Accessing your console].
 
 * You can now view virtual machine resources from the console and your search results. Configure actions for the virtual machine resources. See link:../console/enable_vm_actions.adoc#enable-vm-actions[Enabling virtual machine actions (Technology Preview)].
 
+See link:../console/search_console.adoc#search-console-intro[Search in the console] for more information.
+
 [#cluster-whats-new]
 == Clusters
 

troubleshooting/acm_thanos_compactor.adoc

@@ -1,22 +1,58 @@
 [#troubleshooting-thanos-compactor]
-= Troubleshooting a block error for Thanos compactor
+= Troubleshooting Thanos compactor halts
 
-You might receive a block error message that indicates that the block for Thanos compactor is corrupted.
+You might receive an error message that the compactor is halted. This can occur when there are corrupted blocks or when there is insufficient space on the Thanos compactor persistent volume claim (PVC).
 
 [#symptom-thanos-compactor]
-== Symptom: Block error for Thanos compactor
+== Symptom: Thanos compactor halts
 
-After you upgrade {acm} and check the logs for the Thanos compactor by using the `oc logs observability-thanos-compact-0` command, the logs display the following error message:
+The Thanos compactor halts because there is no space left on your persistent volume claim (PVC). You receive the following message:
 
+[source,terminal]
 ----
-ts=2024-01-24T15:34:51.948653839Z caller=compact.go:491 level=error msg="critical error detected; halting" err="compaction: group 0@15699422364132557315: compact blocks [/var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZQK7TD06J2XWGR5EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZYEZ2DVDQXF1STVEXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HM05APAHXBQSNC0N5EXAMPLE]: populate block: chunk iter: cannot populate chunk 8 from block 01HKZYEZ2DVDQXF1STVEXAMPLE: segment index 0 out of range"
+ts=2024-01-24T15:34:51.948653839Z caller=compact.go:491 level=error msg="critical error detected; halting" err="compaction: group 0@5827190780573537664: compact blocks [ /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE]: 2 errors: populate block: add series: write series data: write /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE.tmp-for-creation/index: no space left on device; write /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE.tmp-for-creation/index: no space left on device"
 ----
 
 [#resolving-thanos-compactor]
-== Resolving the problem: Add the _thanos bucket verify_ command
+== Resolving the problem: Thanos compactor halts
+
+To resolve the problem, increase the storage space of the Thanos compactor PVC. Complete the following steps:
+
+
+. Increase the storage space for the `data-observability-thanos-compact-0` PVC. See link:../observability/customize_observability.adoc#increase-decrease-pv-pvc[Increasing and decreasing persistent volumes and persistent volume claims] for more information.
+
+
+. Restart the `observability-thanos-compact` pod by deleting the pod. The new pod is automatically created and started.
+
++
+[source,bash]
+----
+oc delete pod observability-thanos-compact-0 -n open-cluster-management-observability
+----
+
+. After you restart the `observability-thanos-compact` pod, check the `acm_thanos_compact_todo_compactions` metric. As the Thanos compactor works through the backlog, the metric value decreases. 
+
+. Confirm that the metric changes in a consistent cycle and check the disk usage. Then you can reattempt to decrease the PVC again.
+
++
+*Note:* This might take several weeks. 
+
+[#symptom-thanos-compactor-two]
+== Symptom: Thanos compactor halts
+
+The Thanos compactor halts because you have corrupted blocks. You might receive the following output where the `01HKZYEZ2DVDQXF1STVEXAMPLE` block is corrupted:
+
+[source,terminal]
+----
+ts=2024-01-24T15:34:51.948653839Z caller=compact.go:491 level=error msg="critical error detected; halting" err="compaction: group 0@15699422364132557315: compact blocks [/var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZQK7TD06J2XWGR5EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZYEZ2DVDQXF1STVEXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HM05APAHXBQSNC0N5EXAMPLE]: populate block: chunk iter: cannot populate chunk 8 from block 01HKZYEZ2DVDQXF1STVEXAMPLE: segment index 0 out of range"
+----
+
+[#resolving-thanos-compactor-two]
+== Resolving the problem: Thanos compactor halts
 
 Add the `thanos bucket verify` command to the object storage configuration. Complete the following steps:
 
+
 . Resolve the block error by adding the `thanos bucket verify` command to the object storage configuration. Set the configuration in the `observability-thanos-compact` pod by using the following commands:
 
 +
@@ -35,10 +71,10 @@ thanos tools bucket verify -r --objstore.config="$OBJSTORE_CONFIG" --objstore-ba
 thanos tools bucket mark --id "01HKZYEZ2DVDQXF1STVEXAMPLE" --objstore.config="$OBJSTORE_CONFIG" --marker=deletion-mark.json --details=DELETE 
 ----
 
-. If you blocked for deletion, clean up the marked blocks by running the following command:
+. If you are blocked for deletion, clean up the marked blocks by running the following command:
 
 +
 [source,bash]
 ----
 thanos tools bucket cleanup --objstore.config="$OBJSTORE_CONFIG"
-----
+----