Use API Key credentials stored in a Kubernetes Secret by configuring a CredentialProvider

Feature introduction

In AI Agent scenarios, Agents often need to call APIs of third-party services that require API Keys, such as LLM services like OpenAI and Tongyi Qianwen. Embedding a real API Key directly in application code, images, or environment variables poses risks of credential leakage and difficulty in rotation.

CredentialProvider is a credential source custom resource (CRD) provided by ack-agent-identity. When the type is APIKey and the source is Kubernetes, it reads a single field from a Kubernetes Secret in the cluster as the API Key and provides the following capabilities:

• The real API Key is stored only in a Kubernetes Secret on the cluster side, and is centrally managed and rotated by the platform.

• The AgentRole / AgentRoleBinding authorization mechanism precisely controls which CredentialProviders each Agent identity can obtain credentials from.

• secretRef.name supports template variables, allowing different Secrets to be referenced dynamically based on context such as the Agent identity. This achieves "one configuration, different credentials per identity".

In addition to APIKey, CredentialProvider also supports types such as RAM, and supports sources such as KMS and RRSA. This topic only covers type: APIKey with a Kubernetes Secret source. For other types and sources, see the corresponding documentation.

Resource objects involved

Setting up API Key credential delivery typically involves the following CRs, which are created in sequence in the steps below:

Applicability

• The cluster Kubernetes version is >= 1.28.

• On the Component Management page of the cluster, make sure that the version of the ack-agent-identity add-on is >= 0.2.0.

Configure an API Key credential

The following operations are performed with kubectl. Before you proceed, make sure that you have configured a kubeconfig that can access the target ACS cluster. For more information, see Use ACS with kubectl.

The following resources must be created in the same namespace: the Secret referenced by the CredentialProvider must reside in the same namespace as the CredentialProvider. Cross-namespace references are currently not supported.

1. Save the following content as llm-api-key-secret.yaml and run the kubectl apply -f llm-api-key-secret.yaml command to create the Kubernetes Secret that stores the API Key.

   apiVersion: v1
   kind: Secret
   metadata:
     name: llm-api-key
     namespace: <YOUR_NAMESPACE>
   type: Opaque
   stringData:
     apiKey: "sk-xxxxxxxxxxxxxxxx"   # Replace with the real API Key

2. Save the following content as agent-identity.yaml and run the kubectl apply -f agent-identity.yaml command to create an AgentIdentity that defines the Agent identity.

   apiVersion: agentidentity.alibabacloud.com/v1alpha1
   kind: AgentIdentity
   metadata:
     name: my-agent          # The Agent identity name, referenced in later authorization
     namespace: <YOUR_NAMESPACE>
   spec:
     description: "Sample AI Agent identity"

3. Save the following content as credential-provider-apikey.yaml and run the kubectl apply -f credential-provider-apikey.yaml command to create a CredentialProvider that references the preceding Secret.

   apiVersion: agentidentity.alibabacloud.com/v1alpha1
   kind: CredentialProvider
   metadata:
     name: llm-api-key
     namespace: <YOUR_NAMESPACE>
   spec:
     type: APIKey
     apiKey:
       source:
         provider: Kubernetes
         kubernetes:
           secretRef:
             name: llm-api-key       # The name of the Secret created in Step 1
           keyName: apiKey           # The field name in the Secret that contains the API Key

   secretRef.name supports template variables that dynamically reference different Secrets based on context. For more information, see Template variables in secretRef.name.

4. Save the following content as agent-role-apikey.yaml and run the kubectl apply -f agent-role-apikey.yaml command to create an AgentRole and an AgentRoleBinding that authorize the Agent identity to obtain credentials from this CredentialProvider.

   apiVersion: agentidentity.alibabacloud.com/v1alpha1
   kind: AgentRole
   metadata:
     name: get-llm-key
     namespace: <YOUR_NAMESPACE>
   spec:
     rules:
     - effect: Allow
       action: "GetResourceCredential"
       resource: "CredentialProvider/llm-api-key"   # The name of the CredentialProvider created in the previous step
   ---
   apiVersion: agentidentity.alibabacloud.com/v1alpha1
   kind: AgentRoleBinding
   metadata:
     name: my-agent-get-llm-key
     namespace: <YOUR_NAMESPACE>
   spec:
     agentRoleRef:
       apiGroup: agentidentity.alibabacloud.com
       kind: AgentRole
       name: get-llm-key
     subjects:
     - authorizationType: "Agent"
       agentAuthorizationConfiguration:
         agentName: my-agent                        # Must match the AgentIdentity name

5. Confirm that the CredentialProvider is ready (the Available column shows True).

   kubectl get credentialprovider llm-api-key -n <YOUR_NAMESPACE>

   Expected output:

   NAME          AVAILABLE   AGE
   llm-api-key   True        30s

   If Available is not True, use kubectl describe to check the cause in Conditions. For troubleshooting methods, see Status and troubleshooting.

Consume credentials

A created and authorized API Key credential is typically consumed through credential injection for Agent Sandbox egress traffic: reference this CredentialProvider in a tokenTransformation rule of a SecurityProfile. The Sandbox application initiates requests with a placeholder token, and the egress gateway automatically replaces it with the real API Key when forwarding. For the complete end-to-end configuration (SecurityProfile, SandboxSet, SandboxClaim, and verification), see Configure credential injection for Agent Sandbox.

Template variables in secretRef.name

In addition to a fixed Secret name, secretRef.name can also embed ${ack:agent-identity/...} template variables. When obtaining credentials, the system renders the actual Secret name based on the identity context of the current request, thereby delivering different credentials per identity. For example, llm-api-key-${ack:agent-identity/agent-name} resolves to llm-api-key-my-agent based on the Agent name.

The following template variables are supported:

If a template variable cannot be resolved in the current request context (for example, the referenced metadata key does not exist), the credential retrieval request fails with an explicit error message instead of silently returning an empty value.

The following example demonstrates how to dynamically reference different Secrets per tenant: the API Keys of different tenants are stored in Secrets named llm-api-key-<tenant identifier>, and the CredentialProvider resolves the corresponding Secret name through ${ack:agent-identity/metadata/tenant-id} when obtaining credentials.

The metadata values come from the custom metadata written when the identity token was issued. In Agent Sandbox scenarios, they can be passed in through the security.agents.kruise.io/<key> annotation of a SandboxClaim (the part after removing the prefix is the metadata key):

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: my-claim
  namespace: <YOUR_NAMESPACE>
spec:
  templateName: my-sandbox-set
  replicas: 1
  annotations:
    # After removing the prefix, the following annotation can be referenced in templates via ${ack:agent-identity/metadata/tenant-id}
    security.agents.kruise.io/tenant-id: acme
  labels:
    security.agents.kruise.io/agent-name: my-agent

The corresponding CredentialProvider:

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: llm-api-key
  namespace: <YOUR_NAMESPACE>
spec:
  type: APIKey
  apiKey:
    source:
      provider: Kubernetes
      kubernetes:
        secretRef:
          name: 'llm-api-key-${ack:agent-identity/metadata/tenant-id}'   # Resolves to llm-api-key-acme
        keyName: apiKey

With the preceding configuration, when the tenant-id in the identity metadata of the request is acme, secretRef.name resolves to llm-api-key-acme, reading the Secret dedicated to that tenant.

Field descriptions

The spec structure for type: APIKey with a Kubernetes source is as follows:

spec:
  type: APIKey                     # Required. Credential type. Cannot be changed after creation
  apiKey:
    source:
      provider: Kubernetes         # Required. Credential source
      kubernetes:
        secretRef:
          name: <secret-name>      # Required. Name of the Secret in the same namespace. Supports template variables
        keyName: <key>             # Required. Field name in the Secret data

Key field descriptions:

Status and troubleshooting

The running status of a CredentialProvider is recorded in status.conditions. To view it, run kubectl describe credentialprovider <name> -n <YOUR_NAMESPACE>. Common Conditions and Reasons are as follows:

When secretRef.name uses a template variable, the actual Secret name can only be determined when credentials are obtained. Therefore, the reconciliation phase skips the Secret existence check and marks the CredentialProvider Available directly. Errors in such configurations (for example, the rendered Secret does not exist) surface when credentials are actually obtained, and are not reflected in the CredentialProvider status.

Limits

FAQ

Related documentation

• Configure credential injection for Agent Sandbox