Quick access from ACK

Step 1: Create a namespace and a service account (optional)

A namespace partitions your ACK cluster into logically isolated virtual spaces for different environments such as development, testing, and production. Applications in different namespaces cannot access each other's resources by default. If you already have a namespace and service account for your business application, skip this step.

1. Create a namespace.

   1. Create a namespace by using a YAML file. The following example uses app1-namespace.yaml to create a namespace named app1-dev:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: app1-dev

   2. Run the following command to create the namespace:

      kubectl apply -f app1-namespace.yaml

   3. Verify that the namespace is created. If the output includes app1-dev, the namespace is created.

      kubectl get namespaces

2. Create a service account.

   1. Create a service account by using a YAML file. The following example uses app1-serviceaccount.yaml to create a service account named app1-service in the app1-dev namespace that you created in the previous step:

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: app1-service
        namespace: app1-dev

   2. Run the following command to create the service account:

      kubectl apply -f app1-serviceaccount.yaml

   3. Verify that the service account is created. If the output includes app1-service, the service account is created.

      kubectl get serviceaccount -n app1-dev

Step 2: Configure permissions

KMS cloud-native access supports the following two authentication methods.

Step 3: Install ack-kms-agent-webhook-injector

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster to go to the details page.

3. In the left-side navigation pane of the details page, choose Applications > Helm.

4. On the Helm page, click Deploy. Configure the Basic Information section, and then click Next.

   Parameter	Description
   Application Name	Use the default application name ack-kms-agent-webhook-injector.
   Namespace	Use the default chart namespace kube-system. Install to one namespace per ACK cluster; no need to install multiple times.
   Source	Default: Marketplace. This parameter cannot be modified.
   Chart	Search for and select ack-kms-agent-webhook-injector.

5. When the confirmation dialog appears, verify the information and click Yes.

6. On the Parameters page, configure the parameters based on the authentication method you selected in Step 2.

   • OIDC (ACK): Keep the default configuration.

   • RAM role: Leave agent.auth.roleArn empty, and set agent.auth.roleArnMapping to <Namespace>:<ServiceAccountName>:<RAM Role ARN>. The following example uses the data created in Step 2:

     Note

     The Namespace and ServiceAccountName correspond to the namespace and service account of the pod running the workload. The RAM Role ARN can be viewed on the RAM role details page.

     agent:
       auth:
         roleArn:
         roleArnMapping:
           app1-dev:app1-service: acs:ram::190325303126****:role/app1-rrsa

7. After the configuration is complete, click OK. You are redirected to the application details page.

Step 4: Inject the Agent Sidecar

1. Add a pod annotation: Set the annotation key to kms-agent-webhook-injector/inject and the value to true.

   1. In the left-side navigation pane of the cluster details page, choose Workloads > Deployments.

   2. Switch to the namespace in which your workload runs, and add the pod annotation to the Deployment.

      Important

      For the RAM role authentication method, modify the Deployment YAML configuration and set the ServiceAccountName parameter to the service account name of the pod running the workload (for example, app1-service). For the OIDC (ACK) authentication method, no modification is required.

      • Create a new Deployment

        Create from Image

        1. Click Create from Image above the Deployment list and configure the parameters.

        2. When configuring Advanced, go to the Labels and Annotations section and add the pod annotation: enter kms-agent-webhook-injector/inject in the Name column and true in the Value column.

        3. Click Create to complete.

        Create from YAML

        1. Click Create from YAML above the Deployment list.

        2. Edit the YAML file and add kms-agent-webhook-injector/inject: "true" under spec.template.metadata.annotations (create this section if it does not exist).

        3. Click Create to complete.

      • Modify an existing Deployment

        1. Find the target workload and click Actions > Details.

        2. On the details page, click Edit YAML in the upper-right corner.

        3. Add kms-agent-webhook-injector/inject: "true" under spec.template.metadata.annotations (create this section if it does not exist).

        4. Click Update and wait for the workload to be ready.

2. Verify the injection

   1. Go back to Workloads > Deployments and click the name of the target Deployment to go to the details page.

   2. On the Pods tab, check the Image column. The KMS Agent appears injected into the pod as a Sidecar.

      Note

      A pod may be injected with the KMS Agent twice. This happens because an init container is used for initialization. The init container terminates (Terminated) after initialization completes, and does not negatively impact the application or continuously consume compute resources.

Using curl

# Read the token from a file
curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

# Or write the token directly
curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Go code example

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    // You can specify versionStage or versionId to retrieve a specific credential version.
    // The following example retrieves a credential by versionId:
    // url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
    url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

    // Note: In the ACK scenario, the token path is /var/run/kmstoken/token
    token, err := os.ReadFile("/var/run/kmstoken/token")
    if err != nil {
        fmt.Printf("error reading token file: %v\n", err)
        return
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("error creating request: %v\n", err)
        return
    }

    req.Header.Add("X-KMS-Token", string(token))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("error sending request: %v \n", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}

Expected response

A successful request returns an HTTP status code 200 and a JSON body containing the credential value. The following is an example response:

{
    "RequestId": "4e5b3c7a-****-****-****-1a2b3c4d5e6f",
    "SecretName": "agent-test",
    "SecretData": {
        "username": "admin",
        "password": "Ex@mpleP@ssw0rd"
    },
    "VersionId": "v1",
    "VersionStage": "ACSCurrent"
}