diff --git a/content/en/concepts/clusterclaim.md b/content/en/concepts/clusterclaim.md index c60a251e..153d80ea 100644 --- a/content/en/concepts/clusterclaim.md +++ b/content/en/concepts/clusterclaim.md @@ -1,6 +1,6 @@ --- title: ClusterClaim -weight: 2 +weight: 10 --- diff --git a/content/en/developer-guides/addon.md b/content/en/developer-guides/addon.md index 1ed40322..241bcea8 100644 --- a/content/en/developer-guides/addon.md +++ b/content/en/developer-guides/addon.md @@ -303,7 +303,7 @@ We support 3 kinds of health prober types to monitor the healthiness of add-on a The add-on agent maintains a `Lease` in its installation namespace with its status, the [registration agent](https://open-cluster-management.io/concepts/architecture/#registration) will check this `Lease` to maintain the `AVAILABLE` status of the `ManagedClusterAddOn`. - The addon-framework provides a [leaseUpdater]([https://github.com/open-cluster-management-io/addon-framework/blob/main/pkg/lease/lease_controller.go#L24) interface which can make it easier. + The addon-framework provides a [leaseUpdater](https://github.com/open-cluster-management-io/addon-framework/blob/main/pkg/lease/lease_controller.go#L24) interface which can make it easier. ```go leaseUpdater := lease.NewLeaseUpdater(spokeKubeClient, addonName, installNamespace) diff --git a/content/en/faq/_index.md b/content/en/faq/_index.md new file mode 100644 index 00000000..6488f6fc --- /dev/null +++ b/content/en/faq/_index.md @@ -0,0 +1,7 @@ +--- +title: FAQ +weight: 7 +--- + +---- +TODO \ No newline at end of file diff --git a/content/en/user-guides/_index.md b/content/en/user-guides/_index.md new file mode 100644 index 00000000..5cdab45d --- /dev/null +++ b/content/en/user-guides/_index.md @@ -0,0 +1,6 @@ +--- +title: User Guides +weight: 4 +--- + +{{< toc-tree >}} diff --git a/content/en/user-guides/addon.md b/content/en/user-guides/addon.md new file mode 100644 index 00000000..7d196387 --- /dev/null +++ b/content/en/user-guides/addon.md @@ -0,0 +1,14 @@ +--- +title: Add-ons +weight: 8 +--- + + + +{{< toc >}} + + + +## Add-on enablement +## Add-on lifecycle management +## Add-on configurations \ No newline at end of file diff --git a/content/en/user-guides/administration/_index.md b/content/en/user-guides/administration/_index.md new file mode 100644 index 00000000..cefc01c8 --- /dev/null +++ b/content/en/user-guides/administration/_index.md @@ -0,0 +1,13 @@ +--- +title: Administration +weight: 11 +--- + +A few general guide about operating the open-cluster-management's control plane +and the managed clusters. + + + +{{< toc-tree >}} + + diff --git a/content/en/user-guides/administration/assets/grafana-sample.json b/content/en/user-guides/administration/assets/grafana-sample.json new file mode 100644 index 00000000..c028dfd5 --- /dev/null +++ b/content/en/user-guides/administration/assets/grafana-sample.json @@ -0,0 +1,342 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 0, + "id": 27, + "links": [], + "liveNow": false, + "panels": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 10, + "w": 24, + "x": 0, + "y": 0 + }, + "id": 3, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "editorMode": "code", + "expr": "rate(apiserver_request_total{resource=~\"managedclusters|managedclusteraddons|managedclustersetbindings|managedclustersets|addonplacementscores|placementdecisions|placements|manifestworks|manifestworkreplicasets\"}[1m])", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "API Request Count", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 24, + "x": 0, + "y": 10 + }, + "id": 1, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "editorMode": "code", + "expr": "rate(container_cpu_usage_seconds_total{namespace=~\"open-cluster-management.*\"}[3m])", + "hide": false, + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "CPU Usage", + "transformations": [], + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "bytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 24, + "x": 0, + "y": 18 + }, + "id": 2, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "editorMode": "code", + "expr": "container_memory_working_set_bytes{namespace=~\"open-cluster-management.*\"}", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "Memory Usage", + "transformations": [], + "type": "timeseries" + } + ], + "refresh": "", + "schemaVersion": 38, + "style": "dark", + "tags": [], + "templating": { + "list": [ + { + "current": { + "selected": false, + "text": "prometheus", + "value": "prometheus" + }, + "hide": 0, + "includeAll": false, + "multi": false, + "name": "datasource", + "options": [], + "query": "prometheus", + "queryValue": "", + "refresh": 1, + "regex": "", + "skipUrlSync": false, + "type": "datasource" + } + ] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "OCM", + "uid": "c1c387c4-6ef9-4b14-8435-69f6b0b409e9", + "version": 5, + "weekStart": "" + } \ No newline at end of file diff --git a/content/en/user-guides/administration/monitoring.md b/content/en/user-guides/administration/monitoring.md new file mode 100644 index 00000000..f0f5f6d6 --- /dev/null +++ b/content/en/user-guides/administration/monitoring.md @@ -0,0 +1,71 @@ +--- +title: Monitoring OCM using Prometheus-Operator +weight: 1 +--- + +{{< toc >}} + +In this page, we provide a way to monitor your OCM environment using Prometheus-Operator. + +## Before you get started + +You must have a OCM environment setuped. You can also follow our recommended [quick start guide]({{< ref "/getting-started/quick-start" >}}) to set up a playgroud OCM environment. + +And then please [install the Prometheus-Operator](https://prometheus-operator.dev/docs/prologue/quick-start/) in your hub cluster. You can also run the following commands copied from the official doc: + +```shell +git clone https://github.com/prometheus-operator/kube-prometheus.git +cd kube-prometheus + +# Create the namespace and CRDs, and then wait for them to be availble before creating the remaining resources +kubectl create -f manifests/setup + +# Wait until the "servicemonitors" CRD is created. The message "No resources found" means success in this context. +until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done + +kubectl create -f manifests/ +``` + +## Monitoring the control-plane resource usage. + +You can use `kubectl proxy` to open prometheus UI in your browser on [localhost:9090](http://localhost:9090/): + +```shell +kubectl --namespace monitoring port-forward svc/prometheus-k8s 9090 +``` + +The following queries are to monitor the control-plane pods' cpu usage, memory usage and apirequestcount for critical CRs: + +```shell +rate(container_cpu_usage_seconds_total{namespace=~"open-cluster-management.*"}[3m]) +``` + +```shell +container_memory_working_set_bytes{namespace=~"open-cluster-management.*"} +``` + +```shell +rate(apiserver_request_total{resource=~"managedclusters|managedclusteraddons|managedclustersetbindings|managedclustersets|addonplacementscores|placementdecisions|placements|manifestworks|manifestworkreplicasets"}[1m]) +``` + +## Visualized with Grafana + +We provide a intial grafana dashboard for you to visualize the metrics. But you can also customize your own dashboard. + +First, use the following command to proxy grafana service: + +```shell +kubectl --namespace monitoring port-forward svc/grafana 3000 +``` + +Next, open the grafana UI in your browser on [localhost:3000](http://localhost:3000/login). + +Click the "Import Dashboard" and run the following command to copy a sample dashboard and paste it to the grafana: + +```shell +curl https://raw.githubusercontent.com/open-cluster-management-io/open-cluster-management-io.github.io/main/content/en/getting-started/administration/assets/grafana-sample.json | pbcopy +``` + +Then, you will get a sample grafana dashboard that you can fine-tune further: + +![grafana](/sample-grafana.png) diff --git a/content/en/user-guides/administration/upgrading.md b/content/en/user-guides/administration/upgrading.md new file mode 100644 index 00000000..748e1e56 --- /dev/null +++ b/content/en/user-guides/administration/upgrading.md @@ -0,0 +1,203 @@ +--- +title: Upgrading your OCM environment +weight: 1 +--- + + + +{{< toc >}} + + + +This page provides the suggested steps to upgrade your OCM environment +including both the hub cluster and the managed clusters. Overall the major +steps you should follow are: + +- Read the release notes to confirm the latest OCM release version. _(Note that + some add-ons' version might be different from OCM's overall release version.)_ +- Upgrade your command line tools `clusteradm` + + +## Before you begin + +You must have an existing OCM environment and there's supposed to be +registration-operator running in your clusters. The registration-operators +is supposed to be installed if you're previously following our recommended +[quick start guide]({{< ref "/getting-started/quick-start" >}}) +to set up your OCM. The operator is responsible for helping you upgrade the +other components on ease. + +## Upgrade command-line tool + +In order to retrieve the latest version of OCM's command-line tool `clusteradm`, +run the following one-liner command: + +```shell +$ curl -L https://raw.githubusercontent.com/open-cluster-management-io/clusteradm/main/install.sh | bash +``` + +Then you're supposed to see the following outputs: + +```shell +Getting the latest clusteradm CLI... +Your system is darwin_amd64 + +clusteradm CLI is detected: +Reinstalling clusteradm CLI - /usr/local/bin/clusteradm... + +Installing v0.1.0 OCM clusteradm CLI... +Downloading https://github.com/open-cluster-management-io/clusteradm/releases/download/v0.1.0/clusteradm_darwin_amd64.tar.gz ... +clusteradm installed into /usr/local/bin successfully. + +To get started with clusteradm, please visit https://open-cluster-management.io/getting-started/ +``` + +Also, your can confirm the installed cli version by running: + +```shell +$ clusteradm version +client version :v0.1.0 +server release version : ... +``` + +## Upgrade OCM Components via Command-line tool + +### Hub Cluster + +For example, to upgrade OCM components in the hub cluster, run the following +command: + +```shell +$ clusteradm upgrade clustermanager --bundle-version=0.7.0 +``` + +Then `clusteradm` will make sure everything in the hub cluster is upgraded to +the expected version. To check the latest status after the upgrade, continue to +run the following command: + +```shell +$ cluster get hub-info +``` + +### Managed Clusters + +To upgrade the OCM components in the managed clusters, switch the client context +e.g. overriding `KUBECONFIG` environment variable, then simply run the following +command: + +```shell +$ clusteradm upgrade klusterlet --bundle-version=0.7.0 +``` + +To check the status after the upgrade, continue running this command against the +managed cluster: + +```shell +$ clusteradm get klusterlet-info +``` + +## Upgrade OCM Components via Manual Edit + +### Hub Cluster + +#### Upgrading the registration-operator + +Navigate into the namespace where you installed registration-operator (named +"open-cluster-management" by default) and edit the image version of its +deployment resource: + +```shell +$ kubectl -n open-cluster-management edit deployment cluster-manager +``` + +Then update the image tag version to your target release version, which is +exactly the OCM's overall release version. + +```diff +--- image: quay.io/open-cluster-management/registration-operator: ++++ image: quay.io/open-cluster-management/registration-operator: +``` + +#### Upgrading the core components + +After the upgrading of registration-operator is done, it's about time to surge +the working modules of OCM. Go on and edit the `clustermanager` custom resource +to prescribe the registration-operator to perform the automated upgrading: + +```shell +$ kubectl edit clustermanager cluster-manager +``` + +In the content of `clustermanager` resource, you're supposed to see a few +images listed in its spec: + +```yaml +apiVersion: operator.open-cluster-management.io/v1 +kind: ClusterManager +metadata: ... +spec: + registrationImagePullSpec: quay.io/open-cluster-management/registration: + workImagePullSpec: quay.io/open-cluster-management/work: + # NOTE: Placement release versioning differs from the OCM root version, please refer to the release note. + placementImagePullSpec: quay.io/open-cluster-management/placement: +``` + +Replacing the old release version to the latest and commit the changes will +trigger the process of background upgrading. Note that the status of upgrade +can be actively tracked via the status of `clustermanager`, so if anything goes +wrong during the upgrade it should also be reflected in that status. + + +### Managed Clusters + +#### Upgrading the registration-operator + +Similar to the process of upgrading hub's registration-operator, the only +difference you're supposed to notice when upgrading the managed cluster is +the name of deployment. Note that before running the following command, you +are expected to switch the context to access the managed clusters not the hub. + +```shell +$ kubectl -n open-cluster-management edit deployment klusterlet +``` + +Then repeatedly, update the image tag version to your target release version +and commit the changes will upgrade the registration-operator. + +#### Upgrading the agent components + +After the registration-operator is upgraded, move on and edit the corresponding +`klusterlet` custom resource to trigger the upgrading process in your managed +cluster: + +```shell +$ kubectl edit klusterlet klusterlet +``` + +In the spec of `klusterlet`, what is expected to be updated is also its image +list: + +```yaml +apiVersion: operator.open-cluster-management.io/v1 +kind: Klusterlet +metadata: ... +spec: + ... + registrationImagePullSpec: quay.io/open-cluster-management/registration: + workImagePullSpec: quay.io/open-cluster-management/work: +``` + +After committing the updates, actively checking the status of the `klusterlet` +to confirm whether everything is correctly upgraded. And repeat the above steps +to each of the managed clusters to perform a cluster-wise progressive upgrade. + +#### Confirm the upgrade + +Getting the overall status of the managed cluster will help you to detect the +availability in case any of the managed clusters are running into failure: + +```shell +$ kubectl get managedclusters +``` + +And the upgrading is all set if all the steps above is succeeded. diff --git a/content/en/user-guides/cluster/_index.md b/content/en/user-guides/cluster/_index.md new file mode 100644 index 00000000..746207f9 --- /dev/null +++ b/content/en/user-guides/cluster/_index.md @@ -0,0 +1,6 @@ +--- +title: Clusters +weight: 4 +--- + +{{< toc-tree >}} diff --git a/content/en/user-guides/cluster/managedcluster.md b/content/en/user-guides/cluster/managedcluster.md new file mode 100644 index 00000000..0617d435 --- /dev/null +++ b/content/en/user-guides/cluster/managedcluster.md @@ -0,0 +1,14 @@ +--- +title: ManagedCluster +weight: 1 +--- + + + +{{< toc >}} + + + +## Cluster install + +## Cluster removal \ No newline at end of file diff --git a/content/en/user-guides/cluster/managedclusterset.md b/content/en/user-guides/cluster/managedclusterset.md new file mode 100644 index 00000000..69e353c8 --- /dev/null +++ b/content/en/user-guides/cluster/managedclusterset.md @@ -0,0 +1,18 @@ +--- +title: ManagedClusterSet +weight: 2 +--- + + + +{{< toc >}} + + + +## Operates ManagedClusterSet using clusteradm + +TODO + +## A glance at the "ManagedClusterSet" API + +TODO \ No newline at end of file diff --git a/content/en/user-guides/manifestwork.md b/content/en/user-guides/manifestwork.md new file mode 100644 index 00000000..4f8cf39d --- /dev/null +++ b/content/en/user-guides/manifestwork.md @@ -0,0 +1,17 @@ +--- +title: ManifestWork +weight: 6 +--- + + + +{{< toc >}} + + + +## Status tracking +## Garbage collection +## Resource Race and Adoption +## Permission setting for work agent +## Treating defaulting/immutable fields in API +## Dynamic identity authorization \ No newline at end of file diff --git a/content/en/user-guides/manifestworkreplicaset.md b/content/en/user-guides/manifestworkreplicaset.md new file mode 100644 index 00000000..6288ec8c --- /dev/null +++ b/content/en/user-guides/manifestworkreplicaset.md @@ -0,0 +1,13 @@ +--- +title: ManifestWorkReplicaSet +weight: 7 +--- + + + +{{< toc >}} + + + +## Status tracking +## Release and Enable Feature \ No newline at end of file diff --git a/content/en/concepts/multicluster-controlplane.md b/content/en/user-guides/multicluster-controlplane.md similarity index 100% rename from content/en/concepts/multicluster-controlplane.md rename to content/en/user-guides/multicluster-controlplane.md diff --git a/content/en/user-guides/placement.md b/content/en/user-guides/placement.md new file mode 100644 index 00000000..a2d2ffd0 --- /dev/null +++ b/content/en/user-guides/placement.md @@ -0,0 +1,16 @@ +--- +title: Placement +weight: 5 +--- + + + +{{< toc >}} + + + +## Select clusters in ManagedClusterSet + +## PlacementDecisions + +## Troubleshooting \ No newline at end of file diff --git a/content/en/user-guides/policy.md b/content/en/user-guides/policy.md new file mode 100644 index 00000000..bdbff1b5 --- /dev/null +++ b/content/en/user-guides/policy.md @@ -0,0 +1,312 @@ +--- +title: Policy +weight: 9 +--- + + + +{{< toc >}} + + + +## Overview + +Note: this is also covered in the +[Open Cluster Management - Configuring Your Kubernetes Fleet With the Policy Addon](https://www.youtube.com/watch?v=ZZH654t5YpI) +video. + +[![Open Cluster Management - Configuring Your Kubernetes Fleet With the Policy Addon](https://img.youtube.com/vi/ZZH654t5YpI/0.jpg)](https://www.youtube.com/watch?v=ZZH654t5YpI) + +The policy framework has the following API concepts: + +- [_Policy Templates_](#managed-cluster-policy-controllers) are the policies that perform a desired check or action. For + example, + [ConfigurationPolicy]({{< ref "/getting-started/integration/policy-controllers#install-the-configuration-policy-controller" >}}) + objects are embedded in `Policy` objects under the `policy-templates` array. +- A [`Policy`](#policy) is a grouping mechanism for _Policy Templates_ and is the smallest deployable unit on the hub + cluster. Embedded _Policy Templates_ are distributed to applicable managed clusters and acted upon by the appropriate + [policy controller]({{< ref "/getting-started/integration/policy-controllers" >}}). +- A [`PolicySet`](#policyset) is a grouping mechanism of `Policy` objects. Compliance of all grouped `Policy` objects is + summarized in the `PolicySet`. A `PolicySet` is a deployable unit and its distribution is controlled by a + [Placement]({{< ref "/concepts/placement" >}}). +- A [`PlacementBinding`](#placementbinding) binds a [Placement]({{< ref "/concepts/placement" >}}) to a `Policy` or `PolicySet`. + +The second half of the +[KubeCon NA 2022 - OCM Multicluster App & Config Management](/kubecon-na-2022-ocm-multicluster-app-and-config-management.pdf) +also covers an overview of the Policy addon. + +## Policy + +A `Policy` is a grouping mechanism for _Policy Templates_ and is the smallest deployable unit on the hub cluster. +Embedded _Policy Templates_ are distributed to applicable managed clusters and acted upon by the appropriate +[policy controller]({{< ref "/getting-started/integration/policy-controllers" >}}). The compliance state and status of a `Policy` +represents all embedded _Policy Templates_ in the `Policy`. The distribution of `Policy` objects is controlled by a +[Placement]({{< ref "/concepts/placement" >}}). + +View a simple example of a `Policy` that embeds a `ConfigurationPolicy` policy template to manage a namespace called +"prod". + +```yaml +apiVersion: policy.open-cluster-management.io/v1 +kind: Policy +metadata: + name: policy-namespace + namespace: policies + annotations: + policy.open-cluster-management.io/standards: NIST SP 800-53 + policy.open-cluster-management.io/categories: CM Configuration Management + policy.open-cluster-management.io/controls: CM-2 Baseline Configuration +spec: + remediationAction: enforce + disabled: false + policy-templates: + - objectDefinition: + apiVersion: policy.open-cluster-management.io/v1 + kind: ConfigurationPolicy + metadata: + name: policy-namespace-example + spec: + remediationAction: inform + severity: low + object-templates: + - complianceType: musthave + objectDefinition: + kind: Namespace # must have namespace 'prod' + apiVersion: v1 + metadata: + name: prod +``` + +The `annotations` are standard annotations for informational purposes and can be used by user interfaces, custom report +scripts, or components that integrate with OCM. + +The optional `spec.remediationAction` field dictates whether the policy controller should `inform` or `enforce` when +violations are found and overrides the `remediationAction` field on each policy template. When set to `inform`, the +`Policy` will become noncompliant if the underlying policy templates detect that the desired state is not met. When set +to `enforce`, the policy controller applies the desired state when necessary and feasible. + +The `policy-templates` array contains an array of [_Policy Templates_](#managed-cluster-policy-controllers). Here a +single `ConfigurationPolicy` called `policy-namespace-example` defines a `Namespace` manifest to compare with objects on +the cluster. It has the `remediationAction` set to `inform` but it is overridden by the optional global +`spec.remediationAction`. The `severity` is for informational purposes similar to the `annotations`. + +Inside of the embedded `ConfigurationPolicy`, the `object-templates` section describes the `prod` `Namespace` object +that the `ConfigurationPolicy` applies to. The action that the `ConfigurationPolicy` will take is determined by the +`complianceType`. In this case, it is set to `musthave` which means the `prod` `Namespace` object will be created if it +doesn't exist. Other compliance types include `mustnothave` and `mustonlyhave`. `mustnothave` would delete the `prod` +`Namespace` object. `mustonlyhave` would ensure the `prod` `Namespace` object only exists with the fields defined in the +`ConfigurationPolicy`. See the +[`ConfigurationPolicy` page]({{< ref "/getting-started/integration/policy-controllers/configuration-policy" >}}) for more information +or see the [templating in configuration policies](#templating-in-configuration-policies) topic for advanced templating +use cases with `ConfigurationPolicy`. + +When the `Policy` is bound to a [`Placement`]({{< ref "/concepts/placement" >}}) using a [`PlacementBinding`](#placementbinding), the +`Policy` status will report on each cluster that matches the bound `Placement`: + +```yaml +status: + compliant: Compliant + placement: + - placement: placement-hub-cluster + placementBinding: binding-policy-namespace + status: + - clustername: local-cluster + clusternamespace: local-cluster + compliant: Compliant +``` + +To fully explore the `Policy` API, run the following command: + +```shell +kubectl get crd policies.policy.open-cluster-management.io -o yaml +``` + +To fully explore the `ConfigurationPolicy` API, run the following command: + +```shell +kubectl get crd configurationpolicies.policy.open-cluster-management.io -o yaml +``` + +## PlacementBinding + +A `PlacementBinding` binds a [Placement]({{< ref "/concepts/placement" >}}) to a [`Policy`](#policy) or [`PolicySet`](#policyset). + +Below is an example of a `PlacementBinding` that binds the `policy-namespace` `Policy` to the `placement-hub-cluster` +`Placement`. + +```yaml +apiVersion: policy.open-cluster-management.io/v1 +kind: PlacementBinding +metadata: + name: binding-policy-namespace + namespace: policies +placementRef: + apiGroup: cluster.open-cluster-management.io + kind: Placement + name: placement-hub-cluster +subjects: + - apiGroup: policy.open-cluster-management.io + kind: Policy + name: policy-namespace +``` + +Once the `Policy` is bound, it will be distributed to and acted upon by the managed clusters that match the `Placement`. + +## PolicySet + +A `PolicySet` is a grouping mechanism of [`Policy`](#policy) objects. Compliance of all grouped `Policy` objects is +summarized in the `PolicySet`. A `PolicySet` is a deployable unit and its distribution is controlled by a +[Placement]({{< ref "/concepts/placement" >}}) when bound through a [`PlacementBinding`](#placementbinding). + +This enables a workflow where subject matter experts write `Policy` objects and then an IT administrator creates a +`PolicySet` that groups the previously written `Policy` objects and binds the `PolicySet` to a `Placement` that deploys +the `PolicySet`. + +An example of a `PolicySet` is shown below. + +```yaml +apiVersion: policy.open-cluster-management.io/v1beta1 +kind: PolicySet +metadata: + name: ocm-hardening + namespace: policies +spec: + description: Apply standard best practices for hardening your Open Cluster Management installation. + policies: + - policy-check-backups + - policy-managedclusteraddon-available + - policy-subscriptions +``` + +## Managed cluster policy controllers + +The [`Policy`](#policy) on the hub delivers the policies defined in `spec.policy-templates` to the managed clusters via +the policy framework controllers. Once on the managed cluster, these _Policy Templates_ are acted upon by the associated +controller on the managed cluster. The policy framework supports delivering the _Policy Template_ kinds listed here: + +- Configuration policy + + The `ConfigurationPolicy` is provided by OCM and defines Kubernetes manifests to compare with objects that currently + exist on the cluster. The action that the `ConfigurationPolicy` will take is determined by its `complianceType`. + Compliance types include `musthave`, `mustnothave`, and `mustonlyhave`. `musthave` means the object should have the + listed keys and values as a subset of the larger object. `mustnothave` means an object matching the listed keys and + values should not exist. `mustonlyhave` ensures objects only exist with the keys and values exactly as defined. See + the page on [Configuration Policy]({{< ref "/getting-started/integration/policy-controllers/configuration-policy" >}}) for more + information. + +- Open Policy Agent Gatekeeper + + Gatekeeper is a validating webhook with auditing capabilities that can enforce custom resource definition-based + policies that are run with the Open Policy Agent (OPA). Gatekeeper `ConstraintTemplates` and constraints can be + provided in an OCM `Policy` to sync to managed clusters that have Gatekeeper installed on them. See the page on + [Gatekeeper integration]({{< ref "/getting-started/integration/policy-controllers/gatekeeper" >}}) for more information. + +## Templating in configuration policies + +Configuration policies support the inclusion of Golang text templates in the object definitions. These templates are +resolved at runtime either on the hub cluster or the target managed cluster using configurations related to that +cluster. This gives you the ability to define configuration policies with dynamic content and to inform or enforce +Kubernetes resources that are customized to the target cluster. + +The template syntax must follow the Golang template language specification, and the resource definition generated from +the resolved template must be a valid YAML. (See the +[Golang documentation about package templates](https://golang.org/pkg/text/template/) for more information.) Any errors +in template validation appear as policy violations. When you use a custom template function, the values are replaced at +runtime. + +Template functions, such as resource-specific and generic `lookup` template functions, are available for referencing +Kubernetes resources on the hub cluster (using the `{{hub ... hub}}` delimiters), or managed cluster (using the +`{{ ... }}` delimiters). See the [Hub cluster templates section](#hub-cluster-templates) for more details. The +resource-specific functions are used for convenience and makes content of the resources more accessible. If you use the +generic function, `lookup`, which is more advanced, it is best to be familiar with the YAML structure of the resource +that is being looked up. In addition to these functions, utility functions like `base64encode`, `base64decode`, +`indent`, `autoindent`, `toInt`, and `toBool` are also available. + +To conform templates with YAML syntax, templates must be set in the policy resource as strings using quotes or a block +character (`|` or `>`). This causes the resolved template value to also be a string. To override this, consider using +`toInt` or `toBool` as the final function in the template to initiate further processing that forces the value to be +interpreted as an integer or boolean respectively. + +To bypass template processing you can either: + +- Override a single template by wrapping the template in additional braces. For example, the template + `{{ template content }}` would become `{{ '{{ template content }}' }}`. +- Override all templates in a `ConfigurationPolicy` by adding the + `policy.open-cluster-management.io/disable-templates: "true"` annotation in the `ConfigurationPolicy` section of your + `Policy`. Template processing will be bypassed for that `ConfigurationPolicy`. + +### Hub cluster templating in configuration policies + +Hub cluster templates are used to define configuration policies that are dynamically customized to the target cluster. +This reduces the need to create separate policies for each target cluster or hardcode configuration values in the policy +definitions. + +Hub cluster templates are based on Golang text template specifications, and the `{{hub … hub}}` delimiter indicates a +hub cluster template in a configuration policy. + +A configuration policy definition can contain both hub cluster and managed cluster templates. Hub cluster templates are +processed first on the hub cluster, then the policy definition with resolved hub cluster templates is propagated to the +target clusters. On the managed cluster, the Configuration Policy controller processes any managed cluster templates in +the policy definition and then enforces or verifies the fully resolved object definition. + +In OCM versions 0.9.x and older, policies are processed on the hub cluster only upon creation or after an update. +Therefore, hub cluster templates are only resolved to the data in the referenced resources upon policy creation or +update. Any changes to the referenced resources are not automatically synced to the policies. + +A special annotation, `policy.open-cluster-management.io/trigger-update` can be used to indicate changes to the data +referenced by the templates. Any change to the special annotation value initiates template processing, and the latest +contents of the referenced resource are read and updated in the policy definition that is the propagator for processing +on managed clusters. A typical way to use this annotation is to increment the value by one each time. + +### Templating value encryption + +The encryption algorithm uses AES-CBC with 256-bit keys. Each encryption key is unique per managed cluster and is +automatically rotated every 30 days. This ensures that your decrypted value is never stored in the policy on the managed +cluster. + +To force an immediate encryption key rotation, delete the `policy.open-cluster-management.io/last-rotated` annotation on +the `policy-encryption-key` Secret in the managed cluster namespace on the hub cluster. Policies are then reprocessed to +use the new encryption key. + +### Templating functions + +| Function | Description | Sample | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `fromSecret` | Returns the value of the given data key in the secret. | `PASSWORD: '{{ fromSecret "default" "localsecret" "PASSWORD" }}'` | +| `fromConfigmap` | Returns the value of the given data key in the ConfigMap. | `log-file: '{{ fromConfigMap "default" "logs-config" "log-file" }}'` | +| `fromClusterClaim` | Returns the value of `spec.value` in the `ClusterClaim` resource. | `platform: '{{ fromClusterClaim "platform.open-cluster-management.io" }}'` | +| `lookup` | Returns the Kubernetes resource as a JSON compatible map. Note that if the requested resource does not exist, an empty map is returned. | `metrics-url: \|`
`http://{{ (lookup "v1" "Service" "default" "metrics").spec.clusterIP }}:8080` | +| `base64enc` | Returns a `base64` encoded value of the input string. | `USER_NAME: '{{ fromConfigMap "default" "myconfigmap" "admin-user" \| base64enc }}'` | +| `base64dec` | Returns a `base64` decoded value of the input string. | `app-name: \|`
`"{{ ( lookup "v1" "Secret" "testns" "mytestsecret") .data.appname ) \| base64dec }}"` | +| `indent` | Returns the input string indented by the given number of spaces. | `Ca-cert: \|`
`{{ ( index ( lookup "v1" "Secret" "default" "mycert-tls" ).data "ca.pem" ) \| base64dec \| indent 4 }}` | +| `autoindent` | Acts like the `indent` function but automatically determines the number of leading spaces needed based on the number of spaces before the template. | `Ca-cert: \|`
`{{ ( index ( lookup "v1" "Secret" "default" "mycert-tls" ).data "ca.pem" ) \| base64dec \| autoindent }}` | +| `toInt` | Returns the integer value of the string and ensures that the value is interpreted as an integer in the YAML. | `vlanid: \|`
`{{ (fromConfigMap "site-config" "site1" "vlan") \| toInt }}` | +| `toBool` | Returns the boolean value of the input string and ensures that the value is interpreted as a boolean in the YAML. | `enabled: \|`
`{{ (fromConfigMap "site-config" "site1" "enabled") \| toBool }}` | +| `protect` | Encrypts the input string. It is decrypted when the policy is evaluated. On the replicated policy in the managed cluster namespace, the resulting value resembles the following: `$ocm_encrypted:` | `enabled: \|`
`{{hub "(lookup "route.openshift.io/v1" "Route" "openshift-authentication" "oauth-openshift").spec.host \| protect hub}}` | + +Additionally, OCM supports the following template functions that are included from the `sprig` open source project: + +- `cat` +- `contains` +- `default` +- `empty` +- `fromJson` +- `hasPrefix` +- `hasSuffix` +- `join` +- `list` +- `lower` +- `mustFromJson` +- `quote` +- `replace` +- `semver` +- `semverCompare` +- `split` +- `splitn` +- `ternary` +- `trim` +- `until` +- `untilStep` +- `upper` + +See the [Sprig documentation](https://masterminds.github.io/sprig) for more details. diff --git a/content/zh/blog/addon-rollout/_index.md b/content/zh/blog/addon-rollout/_index.md index 4959c0b9..78e53049 100644 --- a/content/zh/blog/addon-rollout/_index.md +++ b/content/zh/blog/addon-rollout/_index.md @@ -529,4 +529,4 @@ spec: ## 未来计划 -在社区中，我们正在计划实现[RolloutConfig](<(https://github.com/open-cluster-management-io/api/pull/281)>)以提供更细粒度的 rollout 配置，比如 MinSuccessTime, ProgressDeadline, MaxFailures，使得用户可以定义在失败情况下的升级行为，这将为多集群下的升级提供更多的可操作空间。 +在社区中，我们正在计划实现[RolloutConfig](https://github.com/open-cluster-management-io/api/pull/281)以提供更细粒度的 rollout 配置，比如 MinSuccessTime, ProgressDeadline, MaxFailures，使得用户可以定义在失败情况下的升级行为，这将为多集群下的升级提供更多的可操作空间。 diff --git a/content/zh/developer-guides/addon.md b/content/zh/developer-guides/addon.md index 1ed40322..241bcea8 100644 --- a/content/zh/developer-guides/addon.md +++ b/content/zh/developer-guides/addon.md @@ -303,7 +303,7 @@ We support 3 kinds of health prober types to monitor the healthiness of add-on a The add-on agent maintains a `Lease` in its installation namespace with its status, the [registration agent](https://open-cluster-management.io/concepts/architecture/#registration) will check this `Lease` to maintain the `AVAILABLE` status of the `ManagedClusterAddOn`. - The addon-framework provides a [leaseUpdater]([https://github.com/open-cluster-management-io/addon-framework/blob/main/pkg/lease/lease_controller.go#L24) interface which can make it easier. + The addon-framework provides a [leaseUpdater](https://github.com/open-cluster-management-io/addon-framework/blob/main/pkg/lease/lease_controller.go#L24) interface which can make it easier. ```go leaseUpdater := lease.NewLeaseUpdater(spokeKubeClient, addonName, installNamespace) diff --git a/i18n/en.toml b/i18n/en.toml index a2c18caa..d1569441 100644 --- a/i18n/en.toml +++ b/i18n/en.toml @@ -103,9 +103,6 @@ other = "Add-ons" [sidebar_policy] other = "Policy" -[sidebar_multicluster_controlplane] -other = "Multicluster Control Plane" - [sidebar_getting_started] other = "Getting Started" @@ -124,11 +121,38 @@ other = "Register a Cluster" [sidebar_integrations] other = "Add-ons and Integrations" -[sidebar_developer-guides] -other = "Developer Guides" +[sidebar_user_guides] +other = "User Guides" -[sidebar_addon-developer-guide] -other = "Add-on Developer Guide" +[sidebar_cluster_claim_guides] +other = "ClusterClaim" + +[sidebar_cluster_guides] +other = "Clusters" + +[sidebar_managed_cluster_guides] +other = "ManagedCluster" + +[sidebar_managed_cluster_set_guides] +other = "ManagedClusterSet" + +[sidebar_placement_guides] +other = "Placement" + +[sidebar_manifest_work_guides] +other = "ManifestWork" + +[sidebar_manifest_work_replicaset_guides] +other = "ManifestWorkReplicaSet" + +[sidebar_addons_guides] +other = "Add-ons" + +[sidebar_policy_guides] +other = "Policy" + +[sidebar_multicluster_controlplane] +other = "Multicluster Control Plane" [sidebar_administration] other = "Administration" @@ -139,6 +163,11 @@ other = "Upgrading" [sidebar_administration_monitoring] other = "Monitoring" +[sidebar_developer-guides] +other = "Developer Guides" + +[sidebar_addon-developer-guide] +other = "Add-on Developer Guide" [sidebar_apps] other = "Application lifecycle management" @@ -201,3 +230,6 @@ other = "Contribute" [sidebar_blog] other = "Blog" + +[sidebar_faq] +other = "FAQ" diff --git a/themes/ocmTheme/layouts/partials/sidebar.html b/themes/ocmTheme/layouts/partials/sidebar.html index 3cb034d1..82f49c96 100644 --- a/themes/ocmTheme/layouts/partials/sidebar.html +++ b/themes/ocmTheme/layouts/partials/sidebar.html @@ -18,9 +18,6 @@
  • {{ i18n "sidebar_architecture" }}
    • -
  • - {{ i18n "sidebar_cluster_claim" }} -
  • {{ i18n "sidebar_managed_cluster" }}
    • @@ -43,7 +40,7 @@ {{ i18n "sidebar_policy" }}
  • - {{ i18n "sidebar_multicluster_controlplane" }} + {{ i18n "sidebar_cluster_claim" }}
    • @@ -84,14 +81,45 @@ + + +
  • + {{ i18n "sidebar_user_guides" }} +