ack-secret-manager

ACK Secret Manager

English | 中文简体

ack-secret-manager enables you to securely import credentials stored in Alibaba Cloud KMS Secrets Manager or Alibaba Cloud OOS Encryption Parameter into your Kubernetes cluster as native Secret objects. This ensures automatic synchronization of encrypted data while allowing applications to safely consume secrets by mounting them in Pod configurations. It helps mitigate sensitive data exposure risks in the development and deployment stages of the supply chain, ensuring compliance with security best practices.

📚 Documentation

Install

1. Make sure that the credentials used by the ack-secret-manager has sufficient permissions to access the Alibaba Cloud product service. You can use the following two configuration methods, and we recommend you to use the second RRSA method to achieve authorization in the Pod level.

   • Implement pod-level authorization using RRSA method

     • Enable RRSA
     • Use RRSA: Create a corresponding RAM role for the specified ServiceAccount, configure a trust policy for the RAM role, and grant necessary permissions to the RAM role.
     • By configuring ramRoleARN and oidcProviderARN in SecretStore, you can bind KMS secret retrieval permissions to the specific ServiceAccount used by the ack-secret-manager component without using AccessKey (AK).
     • In multi-tenant scenarios, using the serviceAccountRef authentication method in the tenant namespace’s SecretStore enables fine-grained, ServiceAccount-level control over KMS secret retrieval permissions. For details on SecretStore configuration, see Authentication using serviceAccountRef.

   • Add permissions to the Worker RAM role associated with the cluster

     • Log in to the Container Service for Kubernetes (ACK) console.

     • Select your target cluster to open its Cluster Details page.

     • Go to the Cluster Resources section. Locate and click the Worker RAM role named KubernetesWorkerRole-xxxxxxxxxxxxxxx. This will redirect you to the corresponding RAM role page in the RAM console.

     • Click Add Permissions to create a custom policy with the following content (only grant the permissions required for the secret manager, adhering to the principle of least privilege):

     Note: Only grant the minimal permissions required for KMS Secret Manager, adhering to the principle of least privilege.

     {
         "Action": [
           // Permission required to access Alibaba Cloud KMS Secrets Manager
           "kms:GetSecretValue",
           "kms:Decrypt", 
     
           // Permission required to access Alibaba Cloud OOS Encryption Parameter
           "oos:GetSecretParameter",
           "kms:GetSecretValue"
         ],
         "Resource": [
             "*"
         ],
         "Effect": "Allow"
     }
     

     • Attach the created custom policy to the cluster's WorkerRole.

   • For all supported authentication configuration methods in ack-secret-manager, please refer to the official documentation.

   💡 Detailed Authentication Guide: For 5 authentication methods, configuration steps, priority, and Namespace rules, please refer to Authentication Guide

2. Log in to the Container Service console

   • Select Marketplace -> Marketplace in the left navigation bar, enter ack-secret-manager in the search bar, and select to enter the application page;
   • Select the target cluster, namespace, and release name to be installed;
   • Configure custom parameters on the parameter configuration page, including rrsa.enable in values.yaml and related parameters in envVarsFromSecret. For parameter descriptions, see the configuration instructions below;
   • Click the OK button to complete the installation.

Upgrade

1. Log in to the Container Service console;
2. Select the target cluster and click to enter the cluster details page;
3. Select Applications -> Helm in the navigation bar on the left, find the Update button corresponding to ack-secret-manager, modify the configuration and click the OK button to complete the installation.

Uninstall

1. Log in to the Container Service console;
2. Select the target cluster and click to enter the cluster details page;
3. Select Applications -> Helm in the navigation bar on the left, find the Delete button corresponding to ack-secret-manager, and click the Delete button in the operation bar to delete it.

Configuration instructions

Usage Instructions

This section adds a test credential in KMS Secrets Manager for synchronization and shows extended capabilities.

Tip: The ciphertext synchronization method for other Alibaba Cloud service mirrors that of KMS Secrets Manager. Follow these steps:

1. Add the ciphertext for your desired product by referencing the process in Step 1.
2. Update the configuration fields in the SecretStore and ExternalSecret examples below to match the corresponding values in the table provided.

1. Create ciphertexts

Currently supports synchronization of KMS credentials and OOS encryption parameters. The following are references to how to create two ciphertexts.

• Add the following credential in the KMS Secrets Manager. For detailed procedures, please refer to Manage Common Credentials

  SecretName: test1
  SecretData: {"name":"tom","age":"14","friends":[{"name":"lili"},{"name":"edf"}]} 
  VersionId: v1
  

• Add the following parameter to the OOS Encryption Parameters. Please refer to the detailed processCreateSecretParameter

  Name: test2
  Value: {"name":"tom","age":"14","friends":[{"name":"lili"},{"name":"edf"}]} 
  

2. Create SecretStore & ExternalSecret

Prerequisite: Enable RRSA for the cluster and properly configure the relevant RAM Role permissions

This example includes descriptions of some configuration fields in the template, which will not be repeated in the following example.

• Create a test instance named scdemo of SecretStore, and saved as a file hello-service-secret-store.yml. The sample template is as follows, with some fields need to be replaced.

  apiVersion: 'alibabacloud.com/v1alpha1'
  kind: SecretStore
  metadata:
    name: scdemo
  spec:
    KMS: # When synchronizing KMS Secret Manager credentials, specify as KMS, and OOS when synchronizing OOS encryption parameters
      KMSAuth: # KMSAuth or OOSAuth
        oidcProviderARN: "acs:ram::{accountID}:oidc-provider/ack-rrsa-{clusterID}"
        ramRoleARN: "acs:ram::{accountID}:role/{roleName}"
  

• Create a test instance named esdemo of ExternalSecret, and saved as a file hello-service-external-secret.yml. The test template is as follows:

  apiVersion: 'alibabacloud.com/v1alpha1'
  kind: ExternalSecret
  metadata:
    name: esdemo
  spec:
    provider: kms  # Currently supports kms and oos, the default value is kms when this field is not specified
    data:
      - key: test1 # Key name to be synchronized, currently supports kms credentials and oos encryption parameters, this example is kms credential name
        name: test1 # the secret name in target Kubernetes cluster
        versionId: v1 # kms credential version, this field does not need to be configured when the provider is not kms
        kmsEndpoint: kms.cn-hangzhou.aliyuncs.com # KMS service endpoint, field should only be configured when kms is the selected provider. For configuration details, see Part 6 of the usage instructions
        secretStoreRef: # no need to be specified when using worker node RAM Role authentication
          name: scdemo
          namespace: default
  

• Execute the command to create an secretstore test instance(This instance does not need to be created when using Worker Role authentication):

  kubectl apply -f hello-service-secret-store.yml
  

• Execute the command to create an externalsecret test instance:

  kubectl apply -f hello-service-external-secret.yml
  

• Check whether the target secret is created successfully:

  kubectl get secret esdemo -oyaml
  

• If the creation is successful, view the secret content as follows:

  apiVersion: v1
  data:
    test1: eyJuYW1lIjoidG9tIiwiYWdlIjoiMTQiLCJmcmllbmRzIjpbeyJuYW1lIjoibGlsaSJ9LHsibmFtZSI6ImVkZiJ9XX0=
  kind: Secret
  metadata:
    name: esdemo
    namespace: default
  type: Opaque
  

• Without turning off the automatic synchronization configuration, you can modify the key content in the KMS Secrets Manager and wait for a while to check whether the target secret has been synchronized.

3. Authentication Configuration

ack-secret-manager supports multiple authentication methods, including ServiceAccount RRSA, environment variable RRSA/OIDC, AK+AssumeRole, pure AccessKey, and ECS WorkerRole.

• For detailed authentication methods (including priority, configuration examples, and cross-account authentication): Authentication Guide

4. Advanced Features

ack-secret-manager provides various advanced features. For detailed usage, please refer to the corresponding documentation:

5. Template Processing

ack-secret-manager supports advanced template processing capabilities, allowing you to transform and customize secret data before creating Kubernetes Secrets. For Go template syntax, 70+ Sprig functions, templateFrom, mergePolicy, metadata templates, and custom functions, please refer to: Template Processing Guide

6. CRD Resource Details

ack-secret-manager involves four CRD resources. For CRD overview, cross-namespace control mechanisms, security best practices, configuration examples, and field descriptions, please refer to: CRD Resources Guide

Security

Please report vulnerabilities by email to kubernetes-security@service.aliyun.com. Also see our SECURITY.md file for details.

Release Note