Container Service for Kubernetes:Import Alibaba Cloud KMS service credentials using ack-secret-manager

Configure permissions in Account A

1. Use Account A to create a RAM role with Account B as the trusted entity. Select Other Account and enter the ID of Account B. For details, see Create a RAM role for a trusted Alibaba Cloud account.

2. Create a custom RAM policy that grants access to KMS secrets. For more information, see Create a custom policy.

   {
       "Version": "1",
       "Statement": [
           {
               "Action": [
                   "kms:GetSecretValue",
                   "kms:Decrypt"
               ],
               "Resource": [
                   "*"
               ],
               "Effect": "Allow"
           }
       ]
   }

3. Attach the policy to the RAM role. For details, see Grant permissions to a RAM role.

Configure permissions in Account B

1. Enable RRSA OIDC for the cluster in the ACK console. See Enable RRSA for your cluster.

   Note

   Set rrsa.enable to true in the ack-secret-manager configuration.

2. Create a RAM role for ack-secret-manager.

   Set Principal Type to Identity Provider and configure the following parameters. For details, see Create a RAM role for an OIDC identity provider.

   Parameter	Description
   Identity Provider Type	Select OIDC.
   Identity Provider	Select ack-rrsa-<CLUSTER_ID>, where <CLUSTER_ID> is your cluster ID.
   Condition	oidc:iss: Keep the default setting. oidc:aud: Keep the default setting. oidc:sub: Manually add this condition. Key: Select oidc:sub. Operator: Select StringEquals. Value: Enter system:serviceaccount:<NAMESPACE>:<SERVICEACCOUNT_NAME>, where <NAMESPACE>is the namespace of ack-secret-manager, and <SERVICEACCOUNT_NAME> is the service account name. In this example, enter system:serviceaccount:kube-system:ack-secret-manager.

3. Create a custom RAM policy in Account B that allows assuming the RAM role in Account A, then attach it to the Account B RAM role.

   1. Create a policy with the following content, where Resource is the ARN of the RAM role created in Account A. For details on finding the ARN, see How do I view the ARN of a RAM role?

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "acs:ram:*:<account-id>:role/<role-name>"
          }
        ],
        "Version": "1"
      }

   2. Attach the policy to the RAM role created in Account B. For details, see Manage permissions for a RAM role.

4. Create a SecretStore for cross-account access.

   1. Create a file named secretstore-ramrole.yaml with the following content. Replace the placeholders as described.

      • <ACK-accountID>: ID of Account B (the account with the ACK cluster).

      • <clusterID>: ID of your ACK cluster.

      • <ACK-roleName>: Name of the RAM role created in Account B.

      • <KMS-accountID>: ID of Account A (the account with the KMS instance).

      • <KMS-roleName>: Name of the RAM role created in Account A.

      • <roleSessionName>: Role session name (any custom string).

        apiVersion: alibabacloud.com/v1alpha1
        kind: SecretStore
        metadata:
          name: scdemo-cross-account
        spec:
          KMS:
            KMSAuth:
              oidcProviderARN: "acs:ram::<ACK-accountID>:oidc-provider/ack-rrsa-<clusterID>"
              ramRoleARN: "acs:ram::<ACK-accountID>:role/<ACK-roleName>"
              remoteRamRoleARN: "acs:ram::<KMS-accountID>:role/<KMS-roleName>"
              remoteRamRoleSessionName: <roleSessionName>

5. Create an ExternalSecret to specify the sync details. For details, see Step 3: Sync KMS secrets to the cluster.

Extract specific fields from a JSON secret

Use jmesPath to extract specific key-value pairs from a KMS secret stored in JSON format.

For example, given the following JSON secret stored in KMS Secrets Manager:

{"name":"tom","friends":[{"name":"lily"},{"name":"mark"}]}

Create an ExternalSecret with jmesPath to extract specific fields:

• path: Required. JMESPath expression to extract the field. See the JMESPath specification.

• objectAlias: Required. Key name in the resulting Kubernetes Secret.

apiVersion: alibabacloud.com/v1alpha1
kind: ExternalSecret
metadata:
  name: es-json-demo
spec:
  provider: kms
  data:
    - key: {KMS secret name}
      versionStage: {KMS secret version stage}
      secretStoreRef:
        name: {secret store name}
        namespace: {secret store namespace}
      jmesPath:
        - path: "name"              # Extracts: "tom"
          objectAlias: "myname"
        - path: "friends[0].name"   # Extracts: "lily"
          objectAlias: "friendname"

Auto-parse a JSON secret

If the JSON structure is unknown or variable, use dataProcess.extract to automatically parse all key-value pairs from a JSON secret. Use dataProcess.replaceRule to rename keys that don't conform to Kubernetes Secret key naming requirements.

For example, given the following JSON secret with non-conforming key names:

{"/name-invalid":"lily","name-invalid/":[{"name":"mark"}]}

Create an ExternalSecret with jmesPath to extract specific fields:

apiVersion: alibabacloud.com/v1alpha1
kind: ExternalSecret
metadata:
  name: extract-secret
spec:
  provider: kms
  dataProcess:
    - extract:
        key: {KMS secret name}
        versionStage: ACSCurrent
        secretStoreRef:
          name: {secret store name}
          namespace: {secret store namespace}
      replaceRule:
        - source: "^/.*d$"   # Keys starting with / and ending with d -> "tom"
          target: "tom"
        - source: "^n.*/$"   # Keys starting with n and ending with / -> "mark"
          target: "mark"

Extract specific fields from a YAML secret

Use jmesPath to extract specific key-value pairs from a KMS secret stored in YAML format.

For example, given the following YAML secret stored in KMS Secrets Manager:

name: tom
friends:
  - name: lily
  - name: mark

Create an ExternalSecret with jmesPath to extract specific fields:

• path: Required. JMESPath expression to extract the field. See the JMESPath specification.

• objectAlias: Required. Key name in the resulting Kubernetes Secret.

apiVersion: alibabacloud.com/v1alpha1
kind: ExternalSecret
metadata:
  name: es-yaml-demo
spec:
  provider: kms
  data:
    - key: {KMS secret name}
      versionStage: {KMS secret version stage}
      secretStoreRef:
        name: {secret store name}
        namespace: {secret store namespace}
      jmesPath:
        - path: "name"              # Extracts: "tom"
          objectAlias: "myname"
        - path: "friends[0].name"   # Extracts: "lily"
          objectAlias: "friendname"

Auto-parse a YAML secret

If the YAML structure is unknown or variable, use dataProcess.extract to auto-parse all key-value pairs. Use dataProcess.replaceRule to handle non-conforming key names.

For example, given the following YAML secret:

/name-invalid: lily
name-invalid/:
  - name: mark

Create an ExternalSecret with jmesPath to extract specific fields:

apiVersion: 'alibabacloud.com/v1alpha1'
kind: ExternalSecret
metadata:
  name: extract-secret
spec:
  provider: kms
  dataProcess:
    - extract:
        key: {KMS secret name}
        versionStage: ACSCurrent
        secretStoreRef:
          name: {secret store name}
          namespace: {secret store namespace}
      replaceRule:
        - source: "^/.*d$"   # Keys starting with / and ending with d -> "tom"
          target: "tom"
        - source: "^n.*/$"   # Keys starting with n and ending with / -> "mark"
          target: "mark"

• SecretStore: Namespace-level resource. Defines authentication configurations (RRSA, AK, etc.).

• ClusterSecretStore: Cluster-level resource. Functions similar to SecretStore but can be referenced by ExternalSecret resources across all namespaces. Supports access control through spec.conditions.

• ExternalSecret: Namespace-level resource. Defines which KMS secret to sync and references a SecretStore.

• ClusterExternalSecret: Cluster-level resource. Automatically provisions ExternalSecret resources into multiple namespaces based on spec.namespaceSelectors.

Cluster-level resources

apiVersion: "alibabacloud.com/v1alpha1"
kind: ClusterExternalSecret
metadata:
  name: cluster-kms
spec:
  externalSecretSpec:
    provider: kms
    data:
      - key: test
        name: test
        versionId: v1
        secretStoreRef:
          name: alibaba-credentials
          kind: ClusterSecretStore
  externalSecretName: kms
  externalSecretMetadata:
    labels:
      app: "my-app"
      team: "backend"
    annotations:
      annotation-key1: "annotation-value1"
      annotation-key2: "annotation-value2"
  namespaceSelectors:
  - matchLabels:
      kubernetes.io/metadata.name: default
  - matchExpressions: 
    - key: kubernetes.io/metadata.name
      operator: In
      values:
      - test
  rotationInterval: 10s

apiVersion: alibabacloud.com/v1alpha1
kind: ClusterSecretStore
metadata:
  name: alibaba-credentials
spec:
  conditions: 
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: test
  KMS:
    KMSAuth:
      oidcProviderARN: acs:ram::<role-name>:oidc-provider/ack-rrsa-<cluster-id>
      serviceAccountRef:
        name: test-serviceaccount-auth
        namespace: test

Cross-namespace access control

Enhance security by restricting cross-namespace references.

Recommended approach for cross-namespace access

For cross-namespace access, the following combinations are recommended:

• ClusterSecretStore + ExternalSecret: Use when multiple namespaces need to share the same authentication configuration.

• ClusterSecretStore + ClusterExternalSecret: Use when you need to automatically create ExternalSecrets with the same configuration across multiple namespaces.

Security best practices

• Principle of least privilege: If cross-namespace access is not required, disable enableCrossNamespaceSecretStore and enableCrossNamespaceAuthRef. Always prioritize namespace-level resources (SecretStore) over cluster-level ones.

• Restrict ClusterSecretStore: Never create a ClusterSecretStore without configuring spec.conditions.

• Avoid AccessKey exposure: Prioritize RRSA or ServiceAccount-based authentication over statically storing AccessKey pairs in Kubernetes Secrets.

• Limit ClusterExternalSecret: Use ClusterExternalSecret only when absolutely necessary, and strictly define namespaceSelectors to prevent unintended secret proliferation.