tencent cloud

Tencent Kubernetes Engine

Pod OIDC Solution

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-23 16:19:18
Traduzido por IA
This document describes the roles of TKE OIDC Provider, ServiceAccount Token, CAM identity provider, and CAM role, as well as their collaboration relationships. It also explains how to configure and run Pods to access Tencent Cloud resources using OIDC identities. Configuration examples for integrating with AWS IAM are provided at the end of this document.

1. Background and Solution Comparison

When a Pod accesses TencentCloud APIs, you must provide identity credentials that the cloud platform can recognize. Common methods include configuring long-term access keys (AK/SK) for the Pod and using TKE Pod OIDC authentication (hereinafter referred to as Pod OIDC) to obtain temporary credentials. Pod OIDC establishes a trust relationship between a Kubernetes ServiceAccount and a cloud role, enabling the cloud platform to authenticate and authorize the Pod based on its namespace and ServiceAccount.

1.1 Long-Term Access Key Solution

The long-term access key approach requires creating AK/SK in advance and providing the credentials to the Pod through Kubernetes Secrets, environment variables, or an external configuration system. Its invocation process is as follows:
Fixed AK/SK
Save to a Secret or an external configuration system.
Inject into the Pod.
The SDK reads the AK/SK.
Access TencentCloud APIs directly.
This approach typically involves a long credential lifecycle, requiring you to handle credential storage, distribution, and rotation on your own. When multiple workloads share the same AK/SK, it is also difficult to precisely map permission scopes and audit records to specific ServiceAccounts. Even if the AK/SK is stored in a Secret or an external configuration system, its long-term credential nature remains unchanged.

1.2 Pod OIDC Solution

The Pod OIDC approach does not provision long-term AK/SK in the Pod. The TKE cluster issues a short-lived OIDC Token for the ServiceAccount, and the application uses this Token to request temporary credentials for the CAM role from STS. Its invocation process is as follows:
The ServiceAccount used by the Pod
TKE issues a short-lived OIDC Token.
STS validates the Token and the role trust relationship.
Return temporary credentials for the CAM role.
The SDK accesses TencentCloud APIs.
The runtime phase includes the following steps:
1. The TKE cluster issues a short-lived OIDC Token for the ServiceAccount used by the Pod.
2. CAM verifies the Token's issuer, signature, validity period, and ServiceAccount identity, and checks whether this identity is allowed to assume the target CAM role.
3. STS returns the temporary credentials for the CAM role (TmpSecretId, TmpSecretKey, and Token).
4. The application uses the temporary credentials to access cloud resources such as COS, CLS, CDB, and SSM.
Both the OIDC Token and CAM temporary credentials have explicit validity periods and are refreshed by kubelet and the cloud SDK respectively. The application only needs to configure the binding between the ServiceAccount and the CAM role, without distributing or rotating long-term AK/SK.

1.3 Key Differences Between the Two Approaches

Comparison Item
Fixed AK/SK
Pod OIDC
Credentials held in the Pod
Long-term AK/SK
Short-lived OIDC tokens and CAM temporary credentials obtained on demand
Identity source
Cloud user or cloud identity associated with the AK/SK
Kubernetes namespace + ServiceAccount
Permission binding
Permissions are bound to the identity associated with the AK/SK.
A ServiceAccount is mapped to a CAM role through an OIDC identity.
Permission isolation
Multiple Pods may share the same set of credentials.
Different roles can be bound by business or ServiceAccount.
Credential storage
Requires storing and distributing AK/SK.
Long-term AK/SK is not stored in the Pod; the Token is mounted through a projected Volume.
Lifecycle
Usually long-term valid and requires proactive rotation.
Tokens and temporary credentials are short-lived and can be automatically refreshed.
Impact of credential leakage
May remain valid until the AK/SK is disabled or rotated.
Restricted by the Token validity period, temporary credential validity period, and role permissions.
Rotation cost
Requires updating storage and notifying users to reload.
The cluster and SDK automatically refresh credentials, and applications do not need to perceive the refresh process.
Audit locating
First locate the identity associated with the AK/SK, and then correlate it with the specific workload.
Workloads can be located by combining role sessions, ServiceAccounts, and namespaces.
The management object of the long-term access key approach is reusable AK/SK, while that of the Pod OIDC approach is the trust relationship between the ServiceAccount and the CAM role. The latter reduces the storage and distribution of long-term credentials within the cluster and refines the authorization scope to the ServiceAccount.

1.4 System Components

Pod OIDC mainly includes the following components:
Component
Main Responsibility
TKE OIDC Provider
Issues OIDC tokens for ServiceAccounts and provides Discovery and JWKS endpoints.
CAM OIDC identity provider and CAM role
Verifies OIDC identities, maps ServiceAccounts to CAM roles, and grants permissions based on role policies.
pod-identity-webhook
Injects projected tokens, role ARNs, and related environment variables into Pods based on ServiceAccount annotations.
pod-identity-webhook does not issue CAM temporary credentials or proxy applications to access cloud resources.

2. TKE Cluster OIDC Provider

2.1 Feature Description

After you enable ServiceAccountIssuerDiscovery, the TKE cluster can serve as an OIDC Provider and provide the following capabilities:
1. Issue ServiceAccount Token: The Kubernetes API Server uses the cluster-managed signing key to issue a short-lived JWT and provides it to the Pod through a projected volume.
2. Provide Token verification information: The external system obtains jwks_uri through the OIDC Discovery endpoint, then obtains the public key from the JWKS endpoint and verifies the JWT signature.
The signing private key is managed by TKE and used only for issuing tokens. The verification public key is provided externally through the Discovery and JWKS endpoints for external systems such as CAM and AWS IAM to verify tokens. The storage and rotation of signing keys are managed by TKE.

2.2 ServiceAccount Identity in Tokens

The Pod specifies the ServiceAccount through serviceAccountName. When the cluster issues a Token, it writes the ServiceAccount identity into the standard claims of the JWT. The following example lists only the primary fields related to authentication:
{
"iss": "<OIDC Issuer URL of the TKE cluster>",
"sub": "system:serviceaccount:prod:cos-reader",
"aud": ["sts.cloud.tencent.com"],
"iat": 1720000000,
"exp": 1720003600
}
Field
Description
Function
iss
Token issuer
Identifies the OIDC Provider corresponding to the TKE cluster.
sub
Token subject
Format: system:serviceaccount:<namespace>:<serviceaccount>
aud
Token audience
Must be consistent with the Audience in the cloud identity provider and role trust policy.
iat / exp
Issued-at and expiration time
Limits the validity period of the Token.
Different ServiceAccounts are distinguished by sub. For example:
system:serviceaccount:prod:cos-reader
system:serviceaccount:prod:log-writer
system:serviceaccount:test:cos-reader
The preceding values represent three independent OIDC identities, which can be bound to different cloud roles respectively.

2.3 Token Verification Process

The external system completes Token verification according to the OIDC standard. The process is as follows:
1. Locate /.well-known/openid-configuration based on the iss in the Token.
2. Read jwks_uri from the Discovery document.
3. Obtain the cluster public key from the JWKS endpoint, and select the corresponding public key based on the kid in the JWT.
4. Verify the signature, validity period, iss, and aud.
TKE rotates the signing private key periodically and retains the corresponding public key for as long as old tokens may still be valid. Verifiers such as CAM can cache the JWKS and refetch it when keys change.
Note:
The OIDC Token is used to prove the Kubernetes identity of a Pod and cannot be used directly to call TencentCloud APIs. Applications must use this Token to request temporary CAM credentials from STS.

3. CAM OIDC Identity and Role Mapping

3.1 Registering a CAM OIDC Identity Provider

When you enable the cluster OIDC feature, if you choose to create a CAM OIDC provider, TKE registers the cluster's Issuer, Discovery/JWKS information, and client ID with CAM. After registration, CAM can verify OIDC Tokens issued by the cluster whose Audience matches the configuration.
The CAM OIDC Provider is used to identify and verify external identity sources. It does not directly grant access permissions to cloud resources such as COS, CLS, or CDB.

3.2 Configuring a Role Trust Policy

A CAM role contains a trust policy and a permissions policy, which serve different purposes:
Policy
Purpose
Typical Content
Role trust policy
Which identities can assume this role
OIDC Provider,oidc:aud,oidc:sub,sts:AssumeRoleWithWebIdentity
Role permission policy
Which operations can this role perform
Cloud service APIs, resource scopes, and access conditions
A role trust policy can map a specified ServiceAccount to a CAM role through oidc:sub. For example:
TKE OIDC Provider
+ aud = sts.cloud.tencent.com
+ sub = system:serviceaccount:prod:cos-reader
└──> CAM role cos-reader-role
└──> Read-only access to the specified COS Bucket
In this configuration, only the cos-reader ServiceAccount in the prod namespace can assume the cos-reader-role. ServiceAccounts with the same name in other namespaces do not meet this condition.

3.3 STS Authentication and Authorization

When an application calls AssumeRoleWithWebIdentity, CAM and STS perform the following checks:
1. Whether the Token's iss corresponds to a registered CAM OIDC Provider.
2. Whether the JWT signature can be verified by the Provider's JWKS public key.
3. Whether the Token is within its validity period and whether aud matches the configuration.
4. Whether the trust policy of the target role allows the Provider, aud, and sub.
5. Whether the session parameters comply with the relevant limits of the role and STS.
After all checks pass, STS returns temporary credentials. The operations that can be performed and the resources that can be accessed with these credentials are determined by the role's permission policy.

4. Responsibilities of the pod-identity-webhook Component

pod-identity-Webhook is a mutating admission Webhook. When a Pod is created, this component reads the annotations of the ServiceAccount used by the Pod and injects the following content:
Project the ServiceAccount Token Volume with a read-only mount.
TKE_ROLE_ARN: The ARN of the target cloud role.
TKE_WEB_IDENTITY_TOKEN_FILE: The path of the projected Token file.
Inject auxiliary environment variables such as TKE_REGION and TKE_PROVIDER_ID based on the configuration.
The responsibilities of each component are as follows:
Action
Actual Executor
Decide whether to inject identity configuration for the Pod.
pod-identity-webhook
Issue ServiceAccount tokens.
Kubernetes API Server
Project the Token to the Pod and refresh it before expiration.
kubelet
Verify the Token and issue CAM temporary credentials.
CAM / STS
Cache and refresh CAM temporary credentials.
Cloud SDK used by the application
This component does not store OIDC signing private keys, does not request CAM temporary credentials, and does not proxy applications to access TencentCloud APIs.

5. End-to-End Process

When a Pod uses cloud resources, the credentials involved and their relationships are as follows:
Credential
How to Obtain
Purpose
OIDC ServiceAccount Token
Issued by the TKE cluster based on the ServiceAccount used by the Pod and mounted into the Pod.
Prove the Kubernetes identity of the Pod to CAM.
CAM temporary credentials
The application or cloud SDK uses the OIDC Token and target role information to request temporary credentials from STS.
Call TencentCloud APIs within the scope of role permissions.
Business credentials (optional)
The application uses CAM temporary credentials to read from services such as SSM.
Connect to services that require independent business credentials, such as databases.
The OIDC ServiceAccount Token cannot be used directly to call TencentCloud APIs. After an application or cloud SDK reads the Token, it requests temporary credentials for the target CAM role from STS. CAM verifies the binding relationship between the ServiceAccount identity and the role, and returns the temporary SecretId, SecretKey, and Token after the verification succeeds. The application then uses these temporary credentials to access the cloud resources authorized for the role.
If the target service also requires independent business credentials, such as a database username and password, the application can first use CAM temporary credentials to access SSM, and then obtain the currently valid database credentials from SSM. In this case, the OIDC Token is used to obtain the cloud identity, the CAM temporary credentials are used to access SSM, and the database credentials are used to connect to the database. For specific practices, see Pod Using CAM for Database Authentication.

6. Tencent Cloud Configuration Process

The configuration process includes the following four steps. For specific console and command-line operations, refer to the corresponding product documentation.

Step 1: Enabling an OIDC Identity Provider for a Cluster (Once per Cluster)

1. Log in to the TKE console and go to the Basic Information > APIServer Information page of the cluster.
2. Edit ServiceAccountIssuerDiscovery and select the following options:
Create a CAM OIDC provider.
Create the pod-identity-webhook component.
Enter the client ID (Audience). The default value is sts.cloud.tencent.com.
Note:
Before enabling this feature for the first time, you need to authorize the service role QcloudAccessForTKERoleInOIDCConfig.


3. Click OK to complete the modification.
Attention:
service-account-issuer and service-account-jwks-uri are managed by TKE and cannot be modified by users.
pod-identity-webhook is installed and maintained by the TKE managed plane. You can view the component status on the Component Management page of the cluster.


Step 2: Creating a CAM Role and Configuring a Trust Policy

1. Go to the CAM console, click Create Role, and select Identity Provider.
2. In Create Custom Role, configure the settings by following the steps below:
2.1 Select the OIDC Provider created in the previous step.

2.2 Configure the role trust policy:
oidc:aud = the client ID from step 1.
It is recommended to configure oidc:sub = system:serviceaccount:<namespace>:<serviceaccount-name> to restrict access to a specific ServiceAccount.

2.3 Attach a role permission policy. It is recommended to create a least-privilege policy based on actual access requirements, and avoid directly binding a broad policy such as *ReadOnlyAccess.
2.4 Record the RoleArn (format example: qcs::cam::uin/xxx:roleName/xxx).
The following trust policy allows only the cos-reader ServiceAccount in the prod namespace to assume this role:
{
"version": "2.0",
"statement": [{
"effect": "allow",
"principal": {
"federated": ["qcs::cam::uin/xxx:oidcProvider/tke-<cluster-id>"]
},
"action": ["sts:AssumeRoleWithWebIdentity"],
"condition": {
"string_equal": {
"oidc:aud": ["sts.cloud.tencent.com"],
"oidc:sub": ["system:serviceaccount:prod:cos-reader"]
}
}
}]
}
The following permission policy allows read-only access to the specified COS Bucket:
{
"version": "2.0",
"statement": [{
"effect": "allow",
"action": ["cos:GetObject", "cos:HeadObject", "cos:ListBucket"],
"resource": ["qcs::cos:ap-guangzhou:uid/xxx:my-bucket-xxx/*"]
}]
}

Step 3: Creating a ServiceAccount and Binding a Role

apiVersion: v1
kind: ServiceAccount
metadata:
name: cos-reader
namespace: prod
annotations:
tke.cloud.tencent.com/role-arn: qcs::cam::uin/xxx:roleName/cos-reader-role
tke.cloud.tencent.com/audience: sts.cloud.tencent.com
tke.cloud.tencent.com/token-expiration: "3600"
Reference this ServiceAccount in the workload via serviceAccountName:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
namespace: prod
spec:
template:
spec:
serviceAccountName: cos-reader
containers:
- name: app
image: my-app:latest

Step 4: Accessing Cloud Resources from the Application Using an SDK

It is recommended to use a Tencent Cloud SDK that supports OIDC credential providers. The SDK can read environment variables and the projected Token, and automatically request and refresh temporary credentials.
If the SDK you are using does not support this credential provider, call STS AssumeRoleWithWebIdentity, and then use the returned temporary credentials to initialize the cloud product client.

7. Tencent Cloud SDK Integration

7.1 Content Automatically Injected by pod-identity-webhook

After a Pod references a ServiceAccount with the tke.cloud.tencent.com/role-arn annotation, the Webhook injects the following content into the Pod:
Type
Key / Path
Description
Environment Variable
TKE_ROLE_ARN
Target CAM role ARN
Environment Variable
TKE_WEB_IDENTITY_TOKEN_FILE
Projected token file path. Default: /var/run/secrets/cloud.tencent.com/serviceaccount/token
Environment Variable
TKE_REGION (if configured)
Default region
Volume
tke-oidc-token
Projected ServiceAccount Token volume
VolumeMount
The Token file path mentioned above
Read-only mount
If the SDK cannot obtain temporary credentials, go to the Pod and run env | grep TKE_, and check the /var/run/secrets/cloud.tencent.com/serviceaccount/ directory to confirm whether the environment variables and Token file have been injected correctly.

7.2 How to Use SDKs for Different Languages

Go: Use common.DefaultTkeOIDCRoleArnProvider() or a custom credential provider.
Python, Java, and Node.js: Use an SDK version that supports TKE OIDC credentials, and confirm that the default credential chain can recognize the relevant environment variables.
SDKs that do not support OIDC: Explicitly call STS AssumeRoleWithWebIdentity, and use the returned temporary credentials to initialize the client.
The default credential chains of SDKs in different languages vary. The following sequence only illustrates the common credential resolution logic. The Go SDK needs to explicitly enable TKE OIDC credentials through DefaultTkeOIDCRoleArnProvider():
Explicitly pass in the SecretId/Key.
Environment variables TENCENTCLOUD_SECRET_ID/KEY
OIDC Web Identity Token (Pod OIDC scenario)
CVM instance role (node role)
Throw an error.
For related APIs, see Go SDK Credential Management, as well as DefaultProviderChain and DefaultTkeOIDCRoleArnProvider in the Go SDK common package.
In production environments, avoid configuring static AK/SK at the same time to prevent the SDK from prioritizing static credentials over OIDC credentials.

7.3 Go Language Example

provider, err := common.DefaultTkeOIDCRoleArnProvider()
if err != nil { /* ... */ }

cred, err := provider.GetCredential()
if err != nil { /* ... */ }

client, _ := cos.NewClient(&cos.BaseURL{...}, &http.Client{
Transport: &cos.AuthorizationTransport{
SecretID: cred.GetSecretId(),
SecretKey: cred.GetSecretKey(),
SessionToken: cred.GetToken(),
},
})

8. ServiceAccount Annotation Reference

Annotation
Required
Default Value
Description
tke.cloud.tencent.com/role-arn
Yes
None
Target CAM role ARN.
tke.cloud.tencent.com/audience
No
sts.cloud.tencent.com
The JWT Audience must match the oidc:aud in the CAM role trust policy. If multiple audiences are configured in the trust policy, you can specify any one of them.
tke.cloud.tencent.com/token-expiration
No
3600
Validity period of the projected Token, in seconds. Value range: 600 to 86400.
To configure a different Token validity period for an individual Pod, you can set an annotation with the same name on the Pod to override the ServiceAccount configuration.

9. Limits and Quotas

Item
Limit
Supported cluster type
TKE managed clusters; for the support status of standalone clusters / Serverless clusters / edge clusters, check the console or submit a ticket for confirmation.
Cluster version requirement
Greater than or equal to v1.20.6-tke.27 or greater than or equal to v1.22.5-tke.1. Later versions are supported by default.
Pod network requirement
Must be able to access the Tencent Cloud STS endpoint. For VPC clusters without internet access, use the private STS endpoint or configure PrivateLink.
Token validity period
600 to 86400 seconds.
Number of roles that can be bound to a single ServiceAccount
1; if multiple roles are needed, create multiple ServiceAccounts.
AssumeRoleWithWebIdentity rate limiting
Follows CAM global quotas. It is recommended that the SDK cache temporary credentials and refresh them when they are close to expiration.
Super nodes / virtual nodes
Supported, and the annotation usage is the same.
Private cluster / no public network egress
Configure the network path from the Pod to the STS private endpoint.

10. Common Issues and Troubleshooting

FAQ 1: SDK Reports Missing Credentials

The troubleshooting steps are as follows:
1. Run kubectl describe pod and check whether environment variables such as TKE_ROLE_ARN exist.
If the environment variables do not exist, check the ServiceAccount annotations, the Pod's serviceAccountName, and the status of the pod-identity-webhook component.
2. Run kubectl exec to enter the Pod, and then run cat $TKE_WEB_IDENTITY_TOKEN_FILE.
If the file does not exist, check whether the projected volume has been injected and mounted, and whether automatic ServiceAccount Token mounting is disabled for the Pod.
3. Confirm that the SDK version supports the TKE OIDC credential provider. If it does not, upgrade the SDK or explicitly call the STS API.

FAQ 2: AssumeRoleWithWebIdentity Returns 401 or Access Denied

The troubleshooting steps are as follows:
Confirm that oidc:aud in the CAM role trust policy matches the Audience in the ServiceAccount annotation.
Confirm that oidc:sub exactly matches the ServiceAccount used by the Pod, in the format system:serviceaccount:<namespace>:<serviceaccount>.
Confirm that the CAM OIDC Provider still exists. If ServiceAccountIssuerDiscovery indicates that the identity provider does not exist, recreate the Provider.

FAQ 3: SDK Does Not Automatically Refresh Temporary Credentials After Expiry

Check whether the SDK version supports automatic refresh of temporary credentials, and upgrade the SDK if necessary.
When using a custom credential provider, refresh the credentials before the remaining validity period drops below 10%.
Do not write temporary credentials to disk, or reuse expired credentials in global variables for an extended period.

FAQ 4: How to Use Clusters Without Outbound Internet Access in a VPC

Ensure that the Pod can access the CAM/STS private network endpoint.
You can establish an access path through the VPC private network, PrivateLink, or NAT egress.
The cluster OIDC Discovery endpoint is hosted by TKE for CAM to obtain the verification public key. Pods still need network access to the STS endpoint.

FAQ 5: ServiceAccountIssuerDiscovery Cannot Be Edited

Confirm that the service role QcloudAccessForTKERoleInOIDCConfig has been authorized.
If authorization is complete but you still cannot edit, submit a ticket for troubleshooting.

FAQ 6: How to Revoke Permissions for a Pod

Remove the role-arn annotation from the ServiceAccount and recreate the Pod so that the new Pod no longer has identity configuration injected.
Issued temporary credentials may remain valid before expiration. To immediately block access, revoke the relevant permissions in the CAM role permission policy.

FAQ 7: Is It Safe for Multiple Pods/Namespaces to Share a Role?

Multiple Pods or namespaces can share the same role, but this expands the trust scope of that role.
It is recommended to configure separate ServiceAccounts and roles by business module, and restrict the identities that can assume the role through oidc:sub.

11. pod-identity-webhook Component Description

11.1 Purpose

For Pods that reference a ServiceAccount with the tke.cloud.tencent.com/role-arn annotation, this component injects the projected ServiceAccount Token, environment variables, and volumes. The component is installed and maintained by the TKE managed plane, and you can view its running status on the Component Management page in the cluster.

11.2 Least Privilege (RBAC)

rules:
- apiGroups: [""]
resources: ["serviceaccounts"]
verbs: ["get", "watch", "list"]
- apiGroups: [""]
resources: ["events"]
verbs: ["patch", "update"]
- apiGroups: ["admissionregistration.k8s.io"]
resources: ["mutatingwebhookconfigurations"]
verbs: ["get"]
For some versions, you need to add the update permission to mutatingwebhookconfigurations to inject self-signed certificates. The actual required permissions depend on the component version.

11.3 Upgrade and Self-Healing

Component versions and upgrade operations are managed centrally by the TKE component management feature. If the component status is abnormal, restart the Webhook Deployment first. If the issue persists, submit a ticket for troubleshooting.

12. Integrating with AWS Services

The ServiceAccount Token issued by TKE is a standard OIDC JWT. In addition to Tencent Cloud CAM, you can also register the TKE OIDC Provider with AWS IAM and use the Web Identity method to request temporary credentials for an AWS IAM Role. The call relationship is as follows:
TKE ServiceAccount
└──> TKE OIDC Token
└──> AWS STS AssumeRoleWithWebIdentity
└──> Temporary credentials for the AWS IAM Role
└──> S3 / DynamoDB / SQS / Other AWS services
TKE can automatically create a CAM OIDC Provider when you enable the cluster OIDC feature, but it does not create an IAM OIDC Provider, IAM Role, or permission policies in your AWS account. You need to configure the identity provider and role trust relationship on the AWS side.

12.1 AWS-Side Objects and Their Purposes

AWS Object
Function
Key Content to Configure
IAM OIDC Provider
Register and validate tokens issued by the TKE cluster.
TKE Issuer URL, Discovery/JWKS, Audience, and certificate fingerprint used when necessary
IAM Role trust policy
Define OIDC identities that are allowed to assume the role.
Provider ARN,sts:AssumeRoleWithWebIdentity,aud,sub
IAM Role permission policy
Define AWS APIs that the role can call.
Action,Resource,Condition
The IAM OIDC Provider is responsible for verifying the identity source, the IAM Role trust policy is responsible for restricting which ServiceAccounts can assume the role, and the IAM Role permission policy is responsible for restricting the role's access permissions.

12.2 Registering a TKE OIDC Provider in AWS IAM

1. Enable ServiceAccountIssuerDiscovery for the TKE cluster and obtain the cluster's OIDC Issuer URL.
2. Confirm that the following endpoints are accessible via public network HTTPS:
<Issuer URL>/.well-known/openid-configuration
The JWKS endpoint pointed to by jwks_uri in the Discovery document
3. In the AWS IAM console, go to Identity providers > Add provider and select OpenID Connect as the provider type.
4. In Provider URL, enter the Issuer URL of the TKE cluster.
5. In Audience, enter sts.amazonaws.com. The aud field of the ServiceAccount projected Token must match this value.
AWS obtains verification information based on the issuer and jwks_uri in the Discovery document. If the root CA used by the OIDC endpoint is not trusted by AWS, or if AWS cannot verify the TLS certificate chain, you also need to configure the certificate fingerprint according to AWS requirements. For specific requirements, see AWS: Creating an IAM OIDC identity provider.
Note:
The IAM OIDC Provider and the IAM Role that trusts it must be in the same AWS account. For cross-account access, you need to establish OIDC trust in the account where the role resides, and then complete subsequent authorization through the role or resource policies.

12.3 Creating an AWS IAM Role and Binding an OIDC Identity

An IAM Role requires both a permission policy and a trust policy. The following permission policy allows only listing and reading the specified S3 Bucket:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::example-bucket"]
},
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": ["arn:aws:s3:::example-bucket/*"]
}
]
}
The following trust policy binds the s3-reader ServiceAccount in the prod namespace to this role:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/<ISSUER_HOST_AND_PATH>"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"<ISSUER_HOST_AND_PATH>:aud": "sts.amazonaws.com",
"<ISSUER_HOST_AND_PATH>:sub": "system:serviceaccount:prod:s3-reader"
}
}
}
]
}
Replace the following placeholders according to your actual environment:
<AWS_ACCOUNT_ID>: The AWS account ID.
<ISSUER_HOST_AND_PATH>: The complete Issuer hostname and path with https:// removed. This value must match the value in the IAM OIDC Provider ARN.
sub: The TKE namespace and ServiceAccount that are allowed to assume the role. In this example, only prod/s3-reader is allowed.
aud: Must match the Audience of the IAM OIDC Provider and the ServiceAccount annotation.
Avoid using unrestricted sub wildcards. Otherwise, other ServiceAccounts in the same cluster may also assume this role. For the trust policy requirements of Web Identity roles, see AWS: Creating a role for OIDC federation.

12.4 Creating a ServiceAccount for AWS

pod-identity-webhook writes the value of the role-arn annotation to TKE_ROLE_ARN. When integrating with AWS, you can specify the AWS IAM Role ARN in this annotation:
apiVersion: v1
kind: ServiceAccount
metadata:
name: s3-reader
namespace: prod
annotations:
tke.cloud.tencent.com/role-arn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/tke-s3-reader
tke.cloud.tencent.com/audience: sts.amazonaws.com
tke.cloud.tencent.com/token-expiration: "3600"
The Pod uses this ServiceAccount through serviceAccountName: s3-reader. The Webhook injects the following environment variables:
TKE_ROLE_ARN=arn:aws:iam::<AWS_ACCOUNT_ID>:role/tke-s3-reader
TKE_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/cloud.tencent.com/serviceaccount/token

12.5 Initializing the AWS SDK Client

The Web Identity default credential chain of the AWS SDK reads:
AWS_ROLE_ARN
AWS_WEB_IDENTITY_TOKEN_FILE
AWS_ROLE_SESSION_NAME (optional)
The variables injected by the TKE Webhook are named TKE_ROLE_ARN and TKE_WEB_IDENTITY_TOKEN_FILE. The AWS SDK default credential chain does not read these variables. You can use the following method for adaptation. The following example explicitly reads the TKE environment variables and initializes an S3 client by using the AWS SDK for Go v2:
package awsauth

import (
"context"
"fmt"
"os"

"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/credentials/stscreds"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/aws-sdk-go-v2/service/sts"
)

func NewS3Client(ctx context.Context, awsRegion string) (*s3.Client, error) {
roleARN := os.Getenv("TKE_ROLE_ARN")
tokenFile := os.Getenv("TKE_WEB_IDENTITY_TOKEN_FILE")
if roleARN == "" || tokenFile == "" {
return nil, fmt.Errorf("missing TKE_ROLE_ARN or TKE_WEB_IDENTITY_TOKEN_FILE")
}

baseCfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(awsRegion))
if err != nil {
return nil, fmt.Errorf("load AWS base config: %w", err)
}

stsClient := sts.NewFromConfig(baseCfg)
roleSessionName := os.Getenv("HOSTNAME")
if roleSessionName == "" {
roleSessionName = "tke-pod"
}

provider := stscreds.NewWebIdentityRoleProvider(
stsClient,
roleARN,
stscreds.IdentityTokenFile(tokenFile),
func(options *stscreds.WebIdentityRoleOptions) {
options.RoleSessionName = roleSessionName
},
)

cfg, err := config.LoadDefaultConfig(
ctx,
config.WithRegion(awsRegion),
config.WithCredentialsProvider(provider),
)
if err != nil {
return nil, fmt.Errorf("load AWS config with web identity: %w", err)
}

return s3.NewFromConfig(cfg), nil
}
For other languages, you can use the same approach: explicitly create a Web Identity Credential Provider and pass TKE_ROLE_ARN and TKE_WEB_IDENTITY_TOKEN_FILE as the role ARN and Token file path, respectively. For AWS standard configuration items, see AWS SDK: Assume role credential provider. For Go v2 Provider usage, see AWS SDK for Go v2: AssumeRoleWithWebIdentity.
Note:
TKE_REGION indicates a Tencent Cloud region and cannot be used as an AWS Region. When initializing the AWS client, you need to configure an AWS Region such as ap-southeast-1 separately.

12.6 Troubleshooting AWS Integration

You can troubleshoot in the following order:
1. InvalidIdentityToken: Confirm that AWS can access the TKE Discovery and JWKS endpoints, and check the Issuer URL and TLS certificate chain.
2. Audience mismatch: Confirm that the IAM OIDC Provider, the role trust policy, and the ServiceAccount annotation all use sts.amazonaws.com.
3. AccessDenied (unable to assume the role): Confirm that the Provider ARN, sub, and target Role ARN match exactly.
4. Temporary credentials obtained but resources cannot be accessed: Check the Action and Resource in the IAM Role permission policy.
5. The SDK reports that no credentials were found: Confirm that the application explicitly reads the TKE_* environment variables, or that they have been mapped to the AWS_* environment variables that the AWS SDK reads by default.

13. Related Documentation

Scenario practice: Pod Using CAM for Database Authentication describes how to configure a Pod to access a MySQL database through CAM and SSM.
To report issues: submit a ticket, or report pod-identity-webhook related issues on the Component Management page of the cluster.

Ajuda e Suporte

Esta página foi útil?

comentários