namespace, injection configuration-阿里云帮助中心

The ASMReconcileNSLabels CRD, available in ASM 1.28 and later, lets you configure the synchronization policy for namespace labels. This reference provides YAML examples and field descriptions.

Use cases

In a multi-cluster ASM instance, namespaces in the control plane (the ASM instance) and the data plane (Kubernetes clusters) are managed independently. When you apply Istio-related labels to a namespace on the control plane, such as enabling Sidecar automatic injection or Ambient mode, these labels are synchronized to the data plane clusters by default. You can use the ASMReconcileNSLabels CRD to modify this behavior.

Limitations

Your ASM instance must be version 1.28 or later. For upgrade instructions, see Upgrade an ASM instance.
ASMReconcileNSLabels is a cluster-scoped resource. You can create only one resource named default in an ASM instance.
Only the following Istio-related labels are synchronized. Custom labels are not affected:
- istio.io/dataplane-mode: Enables Ambient mode for the namespace.
- istio-injection: Enables or disables Sidecar automatic injection for the namespace.
- istio.io/rev: Assigns the namespace to a specific Istio revision.

YAML examples

Example 1: enable namespace label synchronization globally

Synchronize namespace labels from the control plane to all data plane clusters.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default  # Must be default
spec:
  syncPolicy:
    enabled: true

Example 2: disable namespace label synchronization globally

Stop synchronizing all namespace labels to data plane clusters.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default
spec:
  syncPolicy:
    enabled: false

Example 3: synchronize to specific clusters (allowlist)

Synchronize namespace labels to only the specified data plane clusters. When enabled is true, the clusters list (cluster IDs) acts as an allowlist.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default
spec:
  syncPolicy:
    enabled: true
    clusters:
    - c-xxxx1  # Data plane cluster ID
    - c-xxxx2

Example 4: exclude specific clusters (denylist)

Synchronize namespace labels to all data plane clusters except the specified ones. When enabled is false, the clusters list (cluster IDs) acts as a denylist.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default
spec:
  syncPolicy:
    enabled: false
    clusters:
    - c-xxxx3  # Data plane cluster ID

Example 5: specify a source cluster

Use the cardinal field to specify the ID of the source cluster.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default
spec:
  syncPolicy:
    enabled: true
    cardinal: c-xxxx4  # The ID of the source cluster for synchronization

Example 6: combine allowlist and source cluster

Read namespace labels from a specified source cluster and synchronize them to only the clusters in the allowlist.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMReconcileNSLabels
metadata:
  name: default
spec:
  syncPolicy:
    enabled: true
    cardinal: c-xxxx4  # The ID of the source cluster for synchronization
    clusters:
    - c-xxxx1
    - c-xxxx2

Fields

Spec

Field	Type	Required	Description
syncPolicy	SyncPolicy	No	Configures the global policy for synchronizing namespace labels to data plane clusters. By default, if this field is omitted, labels are synchronized to all data plane clusters.

SyncPolicy

The SyncPolicy object defines the synchronization behavior for namespace labels. The enabled and clusters fields work together to determine the synchronization scope based on the following rules:

enabled	clusters	Synchronization behavior
`true` (default)	Empty	Synchronize to all data plane clusters.
`true`	`[A, B]`	Synchronize to only clusters A and B (allowlist).
`false`	Empty	Synchronize to no clusters.
`false`	`[A, B]`	Synchronize to all clusters except clusters A and B (denylist).

Field	Type	Required	Description
enabled	bool	No	Controls the enabled state of the synchronization policy. The default value is `true`. This parameter works with the `clusters` field to determine the allowlist or denylist behavior. When set to `true`, the `clusters` list acts as an allowlist. When set to `false`, the `clusters` list acts as a denylist.
cardinal	string	No	Specifies the ID of the source cluster for label synchronization. If not specified, labels are synchronized from the control plane cluster by default. If the specified cluster does not exist, the system falls back to using the control plane cluster.
clusters	string[]	No	A list of data plane cluster IDs. This parameter is used with the enabled field. The list acts as an allowlist when `enabled` is `true`, and acts as a denylist when `enabled` is `false`. If the list is empty, this setting applies to all clusters.