Use csi-secrets-store-provider-alibabacloud to import secrets from KMS - Container Service for Kubernetes

csi-secrets-store-provider-alibabacloud allows you to import or synchronize secrets from Key Management Service (KMS) to Kubernetes Secrets in a Container Service for Kubernetes (ACK) cluster to ensure that applications have secure access to sensitive data in your cluster. In addition, the plug-in allows you to directly mount secrets to applications by using CSI inline volumes. This is suitable for applications that obtain sensitive data by calling file system APIs, such as the API to read files. This component allows you to automatically update secrets to reduce the risk of exposing secrets in Kubernetes Secrets. It also helps you resolve compatibility issues between your applications and the Secrets Manager of KMS.

Security notes

By default, reading secrets from volumes involves a compatibility issue with the Secrets Manager of KMS. The csi-secrets-store-provider-alibabacloud plug-in can resolve this compatibility issue. In addition, you can create a secret as a Kubernetes-native Secret in a cluster when mounting environment variables. Before you use the plug-in, assess the following security risks:

When secrets in your cluster are accessible through the file system, attackers can exploit Common Vulnerabilities and Exposures (CVE) vulnerabilities in applications to traverse the directories in the cluster. As a result, the secrets may be leaked.
Improper configuration of debug breakpoints or excessive log access permissions may expose secrets in your cluster. We recommend that you do not reference secrets through environment variables to avoid potential security risks.
When you enable secret synchronization, strictly follow the least privilege principle to limit access permissions.

If you do not need to persist secrets for your application, we recommend that you refer to Use RRSA to authorize different pods to access different cloud services to grant the least access permissions to pods. Then, obtain the secrets in the application by calling the GetSecretValue operations directly. This reduces the chances of exposing the secrets in the pod file system or Kubernetes Secrets.

Prerequisites

An ACK cluster that meets the following requirements is created. For more information, see Create an ACK managed cluster and Create ACK One registered clusters.
- The Kubernetes version of the cluster is 1.20 or later. You can create an ACK managed cluster, ACK dedicated cluster, or registered cluster. ACK Serverless clusters are not supported.
- The cluster and your KMS secrets must be in the same region.
A kubectl client is connected to the cluster.

Step 1: Configure component authentication information

You must configure authentication information for csi-secrets-store-provider-alibabacloud to ensure that the plug-in has the permissions to obtain secrets from KMS. Otherwise, csi-secrets-store-provider-alibabacloud cannot import or synchronize secrets to the cluster. You can select one of the following authorization methods based on the cluster type.

Grant permissions by using RRSA: This method is applicable to ACK managed clusters that run Kubernetes 1.22 or later.
Grant permissions to the worker Resource Access Management (RAM) role of the cluster: This method applies to ACK managed clusters, ACK dedicated clusters, and registered clusters.
Specify an AccessKey pair to assume a specific RAM role: This method is applicable to all types of ACK clusters.

Use RRSA to grant permissions

This method applies to ACK managed clusters and ACK Serverless clusters that run Kubernetes 1.22 or later. You can use the RRSA feature to implement pod-level permission control. RRSA can also prevent secret leaks because this method does not need AccessKey pairs.

Enable the RRSA feature for the ACK cluster in the ACK console. This allows you to create identity providers (IdPs) for your cluster. For more information, see Enable RRSA.

Create a RAM role for a trusted identity provider (IdP) so that the RAM role can be used by csi-secrets-store-provider-alibabacloud. The following table describes the parameters. For more information, see Create a RAM role for an OIDC IdP.

Parameter	Description
Identity Provider Type	Select OIDC.
Identity Provider	Select ack-rrsa-<cluster_id>. Replace <cluster_id> with the ID of your cluster.
Condition	oidc:iss: Use the default value. oidc:aud: Use the default value. oidc:sub: You must manually add this condition. Key: Select oidc:sub. Operator: Select StringEquals. Value: Enter `system:serviceaccount:<namespace>:<serviceAccountName>`. Replace `<namespace>` with the namespace of your application. Replace `<serviceAccountName>` with the service account used by your application. In this example, enter `system:serviceaccount:kube-system:csi-secrets-store-provider-alibabacloud`. Note We recommend that you install components in the default `kube-system` namespace. If you install csi-secrets-store-provider-alibabacloud in other namespaces, replace `kube-system` with the name of the namespace.

Create a custom policy and grant permissions to the RAM role created in the previous step.
1. Create a policy that is required when you use csi-secrets-store-provider-alibabacloud to import secrets from KMS. The following code block shows the content of the policy. For more information, see Create a custom policy.
```
{
    "Action": [
       "kms:GetSecretValue",
       "kms:Decrypt"
    ],
    "Resource": [
        "*"
    ],
    "Effect": "Allow"
}
```
2. Grant permissions to the RAM role created in the previous step. For more information, see Grant permissions to a RAM role.
Create a Secret named alibaba-credentials in the cluster based on the following configuration template and replace the specified fields.
1. Create a file named secretstore-rrsa.yaml based on the following content and replace the specified fields:
  - {rolearn}: Replace the value with the ARN of the RAM role created in Step 2. The ARN must be a Base64-encoded string.
  - {oidcproviderarn}: Replace the value with the provider ARN generated after RRSA is enabled for the cluster. The ARN must be a Base64-encoded string.
```
apiVersion: v1
data:
  rolearn: {rolearn}
  oidcproviderarn: {oidcproviderarn}
kind: Secret
metadata:
  name: alibaba-credentials
  namespace: kube-system
type: Opaque
	                     
```
2. Run the following command to deploy the Secret:
```
kubectl apply -f secretstore-rrsa.yaml
```

Grant permissions to the worker RAM role of the cluster

This method is applicable to ACK managed clusters, ACK dedicated clusters, and registered clusters.

Create a custom RAM policy based on the following code block. For more information, see Create a custom policy.

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

Attach the custom policy created in the previous step to the worker RAM role. For more information, see Grant permissions to the worker RAM role.

Specify an AccessKey pair used to assume a RAM role

This method is suitable for all types of ACK clusters.

Create a RAM role for a trusted Alibaba Cloud account so that the RAM role can be used by csi-secrets-store-provider-alibabacloud. For more information, see Create a RAM role for a trusted Alibaba Cloud account.
Note
Select Current Account for the Principal Name parameter.
Create a custom RAM policy and attach the policy to the RAM role you created in the previous step.
1. Create a policy that is required to access KMS secrets. The following code block shows the content of the policy. For more information, see Create a custom policy.
```
{
  "Action": [
    "kms:GetSecretValue",
    "kms:Decrypt"
  ],
  "Resource": [
    "*"
  ],
  "Effect": "Allow"
}
```
2. Grant permissions to the RAM role that is created in the previous step. For more information, see Grant permissions to a RAM role.
Create a custom policy for the RAM role created in the previous step and grant permissions to the specified RAM user.
1. Create a custom policy for the RAM role created previously. The following code block shows the content of the policy. For more information, see Create a custom policy.
```
{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "acs:ram:*:<account-id>:role/<role-name>" 
        }
    ],
    "Version": "1"
}
```
  The Resource field in the preceding code block specifies the ARN of the RAM role. Replace <account-id> with the Alibaba Cloud account to which the RAM role you created belongs and <role-name> with the RAM role you created. For more information about how to obtain the ARN of a RAM role, see How do I view the ARN of a RAM role?
2. Attach the policy to the RAM user that you want to use. This way, the RAM user can assume the RAM role. For more information about how to grant permissions to a RAM user, see Grant permissions to RAM users.
Create a Secret named alibaba-credentials in the cluster based on the following configuration template and replace the specified fields.
1. Create a file named alibaba-credentials.yaml based on the following content and replace the specified fields:
  - {rolearn}: Replace the value with the ARN of the RAM role created in Step 1. The ARN must be a Base64-encoded string.
  - {ak}: Replace the value with the AccessKey ID of the RAM user, which must be a Base64-encoded string.
  - {sk}: Replace the value with the AccessKey secret of the RAM user, which must be a Base64-encoded string.
```
apiVersion: v1
data:
  id: {ak}
  secret: {sk}
  rolearn: {rolearn}
kind: Secret
metadata:
  name: alibaba-credentials
  namespace: kube-system
type: Opaque
```
2. Run the following command to deploy the Secret:
```
kubectl apply -f alibaba-credentials.yaml
```

Step 2: Install the csi-secrets-store-provider-alibabacloud component

Log on to the ACK console. In the navigation pane on the left, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left-side navigation pane, choose Applications > Helm.
On the Helm page, click Deploy. In the Chart section, enter csi-secrets-store-provider-alibabacloud. Keep the default settings for other parameters, and then click Next.
In the dialog box that appears, confirm that the component is installed in the default kube-system namespace and the application is released with the component name. If you want to specify a custom application name and namespace, configure the application name and namespace as prompted.
Set the Chart Version parameter to the latest version. In the Parameters section, configure the parameters based on the authentication method that you selected in Step 1 and click OK.
- If you choose to grant permissions by using RRSA, you must set the rrsa.enable parameter to true to enable RRSA.
  The following code block shows other parameters:
```
envVarsFromSecret:
#  ACCESS_KEY_ID:
#    secretKeyRef: alibaba-credentials
#    key: id
#  SECRET_ACCESS_KEY:
#    secretKeyRef: alibaba-credentials
#    key: secret
  ALICLOUD_ROLE_ARN:
    secretKeyRef: alibaba-credentials
    key: rolearn
#  ALICLOUD_ROLE_SESSION_NAME:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionname
#  ALICLOUD_ROLE_SESSION_EXPIRATION:
#    secretKeyRef: alibaba-credentials
#   key: rolesessionexpiration
  ALICLOUD_OIDC_PROVIDER_ARN:
    secretKeyRef: alibaba-credentials
    key: oidcproviderarn
```
- If you choose to grant permissions to the worker RAM role of a cluster, you can use the default parameter settings to directly install csi-secrets-store-provider-alibabacloud.
- If you choose to specify an AccessKey pair to assume a specific RAM role, you must configure the following parameters:
```
envVarsFromSecret:
  ACCESS_KEY_ID:
    secretKeyRef: alibaba-credentials
    key: id
  SECRET_ACCESS_KEY:
    secretKeyRef: alibaba-credentials
    key: secret
  ALICLOUD_ROLE_ARN:
    secretKeyRef: alibaba-credentials
    key: rolearn
#  ALICLOUD_ROLE_SESSION_NAME:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionname
#  ALICLOUD_ROLE_SESSION_EXPIRATION:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionexpiration
#  ALICLOUD_OIDC_PROVIDER_ARN:
#    secretKeyRef: alibaba-credentials
#    key: oidcproviderarn
```
- To enable the scheduled secrets synchronization feature, you must configure the following parameters:
  - secrets-store-csi-driver.enableSecretRotation: Specify whether to enable the automatic rotation feature for secrets. Set the value to true to enable the automatic rotation feature for secrets.
  - secrets-store-csi-driver.rotationPollInterval: Specify the frequency at which the secrets are synchronized. In this example, this parameter is set to 120 seconds, which specifies that the secrets are synchronized every 2 minutes. You can adjust the value as needed.
After the creation, you are redirected to the csi-secrets-store-provider-alibabacloud page of the cluster to check the installation result. If all resources in the following figure are created, the component is installed.

Step 3: Configure data synchronization information

After the authentication information is configured, you must configure KMS secrets by using SecretProviderClass.

Configuration template description

The following code block shows the SecretProviderClass template:

apiVersion: secrets-store.csi.x-k8s.io/v1alpha1
kind: SecretProviderClass
metadata:
  name: <NAME>
spec:
  provider: alibabacloud   # Set the value to alibabacloud. 
  parameters:

The parameters section usually contains the following request parameters for mounting Kubernetes Secrets.

Parameter	Required	Description
objects	Yes	The YAML configuration for mounting Kubernetes Secrets. Example: `parameters: objects: \| - objectName: "MySecret"` The `objects` parameter contains the following subfields: `objectName`: required. This field specifies the name of the secret in the Secrets Manager of KMS. For more information, see SecretName. `objectType`: optional. You can use this field to specify the type of Alibaba Cloud service to be synchronized. Valid values: kms and oos. Default value: kms. You can leave this field empty if you import secrets from KMS. `objectAlias`: optional. You can use this field to specify the name of the file that is mounted to the pod. If you do not specify this field, the value of objectName is used by default. `objectVersion`: optional. This field corresponds to the VersionId parameter in the Secrets Manager of KMS. The VersionId parameter is not supported by ApsaraDB RDS secrets, PolarDB secrets, ApsaraDB for Redis/Tair secrets, RAM secrets, and ECS secrets. `objectVersionLabel`: optional. This field corresponds to the VersionStage parameter in the Secrets Manager of KMS. You can query only secret values whose stage label is ACSPrevious or ACSCurrent for RAM secrets, ApsaraDB RDS secrets, PolarDB secrets, ApsaraDB for Redis secrets, Tair secrets, and Elastic Compute Service (ECS) secrets. `jmesPath`: optional. This field is used to parse the specified key-value pairs in JSON-formatted secrets. For example, the following sample test secret contains a JSON segment: `{ "username": "testuser", "password": "testpassword" }` To mount `username` and `password` as secret files separately, configure the JMESPath field. When you use the JMESPath field, you must specify the following subfields: `path`: required. This field defines the specified configuration items for path retrieval based on JMESPath. `objectAlias`: optional. This field specifies the name of the file that mounts the secret to the pod. `kmsEndpoint`: optional. This field specifies the endpoint address for KMS service requests. When unconfigured, the default endpoint is used. You can configure it as either a shared gateway or dedicated gateway for KMS. The configuration is applied at credential-level, meaning each credential can specify a distinct endpoint address. For more information, see kmsEndpoint description.
region	No	Send requests to the Secrets Manager server in the specified region. If you do not specify this parameter, the region of the current node is selected. This may increase performance overhead if your application runs in large numbers of pods. Therefore, we recommend that you configure this parameter to specify a region.
pathTranslation	No	A substitution path separator to use if the file name of the secret to mount in Secrets Manager contains path separators. For example, `My/Path/Secret` is mounted as My_Path_Secret. If you do not specify this parameter, the path separator for replacement is underscore (_). To disable path separator replacement, set the parameter to `"False"`.

Configuration example

This example shows how to use the SecretProviderClass to import the secret test from KMS to applications in an ACK managed cluster in the same region.

Create a file named secretstore.yaml and add the following content to the file to define the SecretProviderClass:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: test
spec:
  provider: alibabacloud   # Set the value to alibabacloud. 
  parameters:
    objects: | # The objectType parameter can be set to oos or kms. Default value: kms.
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"

Run the following command to deploy the SecretProviderClass:
```
kubectl apply -f secretstore.yaml
```

Create a file named deploy.yaml and add the following content to the file.

An NGINX Deployment is included, which declares the SecretProviderClass created in the preceding example by using a CSI Inline volume. The secrets are mounted in the /mnt/secrets-store directory of the pod. For more information about Deployments, see Deployment examples.

apiVersion: apps/v1  # If the API version is earlier than 1.8.0, use apps/v1beta1. 
kind: Deployment
metadata:
  name: nginx-deployment-basic
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      volumes:
        - name: secrets-store-inline
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: "test-secrets"
      containers:
        - name: nginx
          image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6 # Replace this value with the actual image. 
          ports:
            - containerPort: 80
          resources:
            limits:
              cpu: "500m"
          volumeMounts:
            - name: secrets-store-inline
              mountPath: "/mnt/secrets-store"
              readOnly: true

Run the following command to deploy the Deployment:
```
kubectl apply -f deploy.yaml
```
Verify that the secret is mounted.
Log on to a pod, check whether the secret specified in the SecretProviderClass is created in the mount target /mnt/secrets-store, and then check whether the secret contains the corresponding ciphertext stored in KMS.

kmsEndpoint description

You can obtain a KMS secret through a dedicated gateway or shared gateway. Before you access the gateway, configure a KMS endpoint based on the following table. For more information about the differences between access through dedicated gateways and access through shared gateways, see Differences between shared and dedicated gateways for accessing KMS.

KMS endpoints

Gateway type	Domain type	Endpoint	Description
Dedicated gateway	KMS private domain	{kms-instance-id}.cryptoservice.kms.aliyuncs.com	The KMS secret instance and cluster are in the same region and the same virtual private cloud (VPC). Replace `{kms-instance-id}` with the ID of the KMS secret instance. The version of the KMS secret instance must be 3.0 or later.
Shared gateway	VPC domain	kms-vpc.{region}.aliyuncs.com	The KMS secret and cluster are in the same region. Replace `{region}` with the region where the KMS secret is located. This address can be used with the default configuration without additional setup.
Shared gateway	Public domain	kms.{region}.aliyuncs.com	Replace `{region}` with the region where the KMS secret is located. The cluster can access the public network.

Sample KMS Endpoint configurations

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: test
spec:
  provider: alibabacloud # Set the value to alibabacloud.
  parameters:
    # objects: Example usage of KMS gateways
    # hangzhou-public: Uses a shared gateway public endpoint. Replace {region} with the region where the KMS credential resides. This enables accessing KMS credentials cross-region (outside the cluster's region).
    # hangzhou-vpc: If the kmsEndpoint field is not specified, the default shared gateway VPC endpoint will be used.
    # hangzhou-cryptoservice: Uses a dedicated gateway. Replace {kms-instance-id} with the KMS instance ID owning the credential.
    # london-public: Uses a shared gateway public endpoint. Replace {region} with the region where the KMS credential resides. This enables cross-region credential access.
    objects: |
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-vpc"
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-cryptoservice"
        kmsEndpoint:  "{kms-instance-id}.cryptoservice.kms.aliyuncs.com"
      - objectName: "test-london"
        objectAlias: "london-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"

References

For more information about how to import secrets from KMS to applications in ACK Serverless clusters, see Use ack-secret-manager to import secrets from KMS.
To protect the secrets that are read from KMS and cached in the ACK cluster, you can perform one-click encryption. For more information, see Use KMS to encrypt Kubernetes Secrets.