diff --git a/content/en/docs/concepts/override.md b/content/en/docs/concepts/override.md index d1451aa..1df3816 100644 --- a/content/en/docs/concepts/override.md +++ b/content/en/docs/concepts/override.md @@ -98,9 +98,14 @@ Each override rule contains the following fields: There is a list of reserved variables that will be replaced by the actual values used in the `value` of the JSON patch override rule: -- `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. +- `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. +- `${MEMBER-CLUSTER-LABEL-KEY-}`: this will be replaced by the value of the label with the key `` on the `memberCluster`. For example, `${MEMBER-CLUSTER-LABEL-KEY-region}` will be replaced by the value of the `region` label on the target member cluster. If the label does not exist on the cluster, the override will fail with an error. -For example, to add a label to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`, +These variables are supported in both `ClusterResourceOverride` and `ResourceOverride`. + +#### Example: Using `${MEMBER-CLUSTER-NAME}` in a `ClusterResourceOverride` + +To add a label to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`, you can use the following configuration: ```yaml @@ -132,6 +137,84 @@ spec: The `ClusterResourceOverride` object above will add a label `cluster-name` with the value of the `memberCluster` name to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`. +#### Example: Using `${MEMBER-CLUSTER-LABEL-KEY-...}` in a `ClusterResourceOverride` + +Suppose you have member clusters with a `region` label (e.g., `region: us-west`, `region: eu-central`) and you want +to add a label reflecting the cluster's region to a `ClusterRole`: + +```yaml +apiVersion: placement.kubernetes-fleet.io/v1alpha1 +kind: ClusterResourceOverride +metadata: + name: cro-region-label +spec: + placement: + name: crp-example + clusterResourceSelectors: + - group: rbac.authorization.k8s.io + kind: ClusterRole + version: v1 + name: secret-reader + policy: + overrideRules: + - clusterSelector: + clusterSelectorTerms: [] + jsonPatchOverrides: + - op: add + path: /metadata/labels/cluster-region + value: "${MEMBER-CLUSTER-LABEL-KEY-region}" +``` + +When applied to a cluster with the label `region: us-west`, the `ClusterRole` will receive the label +`cluster-region: us-west`. When applied to a cluster with `region: eu-central`, the label will be +`cluster-region: eu-central`. + +#### Example: Using `${MEMBER-CLUSTER-LABEL-KEY-...}` in a `ResourceOverride` + +You can also use cluster label variables in a `ResourceOverride` to customize namespace-scoped resources. +For example, suppose you have a `Deployment` named `my-app` in the namespace `app-ns`, and your member clusters +have `region` and `env` labels. You can inject those values as annotations: + +```yaml +apiVersion: placement.kubernetes-fleet.io/v1alpha1 +kind: ResourceOverride +metadata: + name: ro-label-vars + namespace: app-ns +spec: + placement: + name: crp-example + resourceSelectors: + - group: apps + kind: Deployment + version: v1 + name: my-app + policy: + overrideRules: + - clusterSelector: + clusterSelectorTerms: [] + jsonPatchOverrides: + - op: add + path: /metadata/annotations + value: + {"target-region":"${MEMBER-CLUSTER-LABEL-KEY-region}", "target-env":"${MEMBER-CLUSTER-LABEL-KEY-env}"} +``` + +When applied to a cluster with labels `region: us-west` and `env: production`, the deployment will receive the +annotations `target-region: us-west` and `target-env: production`. + +You can also combine multiple variables in a single value. For example: + +```yaml + jsonPatchOverrides: + - op: replace + path: /spec/template/spec/containers/0/image + value: "myregistry-${MEMBER-CLUSTER-LABEL-KEY-region}.example.com/my-app:${MEMBER-CLUSTER-LABEL-KEY-env}" +``` + +On a cluster with `region: us-west` and `env: staging`, this would resolve to +`myregistry-us-west.example.com/my-app:staging`. + ## When To Trigger Rollout It will take the snapshot of each override change as a result of `ClusterResourceOverrideSnapshot` and diff --git a/content/en/docs/how-tos/cluster-resource-override.md b/content/en/docs/how-tos/cluster-resource-override.md index 4e1aae7..9a92ca5 100644 --- a/content/en/docs/how-tos/cluster-resource-override.md +++ b/content/en/docs/how-tos/cluster-resource-override.md @@ -133,7 +133,8 @@ The jsonPatchOverrides field supports the following fields: - `value`: The value to be set. - If the `op` is `remove`, the value cannot be set. - There is a list of reserved variables that will be replaced by the actual values: - - `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. + - `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. + - `${MEMBER-CLUSTER-LABEL-KEY-}`: this will be replaced by the value of the label with the key `` on the `memberCluster`. For example, `${MEMBER-CLUSTER-LABEL-KEY-region}` will be replaced by the value of the `region` label on the target member cluster. If the label does not exist on the cluster, the override will fail with an error. ##### Example: Override Labels @@ -177,6 +178,49 @@ spec: The `ClusterResourceOverride` object above will add a label `cluster-name` with the value of the `memberCluster` name to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`. +##### Example: Override Using Cluster Label Variables + +To dynamically set a label based on a member cluster's `region` label, you can use the `${MEMBER-CLUSTER-LABEL-KEY-}` variable. +For instance, if your member clusters have a label `region` with values like `us-west` or `eu-central`: + +```yaml +apiVersion: placement.kubernetes-fleet.io/v1alpha1 +kind: ClusterResourceOverride +metadata: + name: cro-region +spec: + placement: + name: crp-example + clusterResourceSelectors: + - group: rbac.authorization.k8s.io + kind: ClusterRole + version: v1 + name: secret-reader + policy: + overrideRules: + - clusterSelector: + clusterSelectorTerms: [] + jsonPatchOverrides: + - op: add + path: /metadata/labels/cluster-region + value: "${MEMBER-CLUSTER-LABEL-KEY-region}" +``` + +When applied to a cluster with the label `region: us-west`, the `ClusterRole` will receive the label `cluster-region: us-west`. + +You can also use multiple label variables together. For example, to add annotations sourced from cluster labels: + +```yaml + jsonPatchOverrides: + - op: add + path: /metadata/annotations + value: + {"target-region":"${MEMBER-CLUSTER-LABEL-KEY-region}", "target-env":"${MEMBER-CLUSTER-LABEL-KEY-env}"} +``` + +On a cluster with labels `region: us-west` and `env: production`, the annotations will be set to +`target-region: us-west` and `target-env: production`. + ##### Example: Remove Verbs To remove the verb "list" in the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`, diff --git a/content/en/docs/how-tos/resource-override.md b/content/en/docs/how-tos/resource-override.md index d93e2a3..0918f32 100644 --- a/content/en/docs/how-tos/resource-override.md +++ b/content/en/docs/how-tos/resource-override.md @@ -171,7 +171,8 @@ The `jsonPatchOverrides` field supports the following fields: - `value`: The value to be set. - If the `op` is `remove`, the value cannot be set. - There is a list of reserved variables that will be replaced by the actual values: - - `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. + - `${MEMBER-CLUSTER-NAME}`: this will be replaced by the name of the `memberCluster` that represents this cluster. + - `${MEMBER-CLUSTER-LABEL-KEY-}`: this will be replaced by the value of the label with the key `` on the `memberCluster`. For example, `${MEMBER-CLUSTER-LABEL-KEY-region}` will be replaced by the value of the `region` label on the target member cluster. If the label does not exist on the cluster, the override will fail with an error. ##### Example: Override Labels @@ -216,6 +217,53 @@ spec: The `ResourceOverride` object above will add a label `cluster-name` with the value of the `memberCluster` name to the `Deployment` named `example-ro` on clusters with the label `env: prod`. +##### Example: Override Using Cluster Label Variables + +To dynamically customize resources based on member cluster labels, you can use the `${MEMBER-CLUSTER-LABEL-KEY-}` variable. +For instance, if your member clusters have labels such as `region: us-west` and `env: production`, you can inject +those values into a deployment's annotations: + +```yaml +apiVersion: placement.kubernetes-fleet.io/v1alpha1 +kind: ResourceOverride +metadata: + name: ro-label-vars + namespace: test-namespace +spec: + placement: + name: crp-example + resourceSelectors: + - group: apps + kind: Deployment + version: v1 + name: my-deployment + policy: + overrideRules: + - clusterSelector: + clusterSelectorTerms: [] + jsonPatchOverrides: + - op: add + path: /metadata/annotations + value: + {"target-region":"${MEMBER-CLUSTER-LABEL-KEY-region}", "target-env":"${MEMBER-CLUSTER-LABEL-KEY-env}"} +``` + +When applied to a cluster with labels `region: us-west` and `env: production`, the deployment will receive the +annotations `target-region: us-west` and `target-env: production`. + +You can also combine multiple variables in a single value. For example, to construct a container image path +from cluster labels: + +```yaml + jsonPatchOverrides: + - op: replace + path: /spec/template/spec/containers/0/image + value: "myregistry-${MEMBER-CLUSTER-LABEL-KEY-region}.example.com/my-app:${MEMBER-CLUSTER-LABEL-KEY-env}" +``` + +On a cluster with `region: us-west` and `env: staging`, this would resolve to +`myregistry-us-west.example.com/my-app:staging`. + ##### Example: Override Image To override the image of the container in the `Deployment` named `my-deployment` on all clusters with the label `env: prod`: