Shared Secrets Workload ID
This is a Business Critical Plan feature. For more information, see our pricing plans or contact our sales team.
Workload-identity authentication lets you use access policies to grant your self-hosted Space cluster access to your cloud providers. Workload identity authentication grants temporary AWS credentials to your Kubernetes pod based on a service account. Assigning IAM roles and service accounts allows the pod to assume the IAM role dynamically and much more securely than static credentials.
This guide walks you through creating an IAM trust role policy and applying it to your EKS cluster for secret sharing with Kubernetes.
Prerequisites
To set up a workload-identity, you'll need:
- A self-hosted Space cluster
- Administrator access in your cloud provider
- Helm and
kubectl
About the Shared Secrets component
The External Secrets Operator (ESO) runs in each control plane's host namespace as external-secrets-controller
. It needs to access
your external secrets management service like AWS Secrets Manager.
To configure your shared secrets workflow controller, you must:
- Annotate the Kubernetes service account to associate it with a cloud-side principal (such as an IAM role, service account, or enterprise application). The workload must then use this service account.
- Label the workload (pod) to allow the injection of a temporary credential set, enabling authentication.
Configuration
Upbound supports workload-identity configurations in AWS with IAM Roles for Service Accounts or EKS pod identity association.
IAM Roles for Service Accounts (IRSA)
With IRSA, you can associate a Kubernetes service account in an EKS cluster with
an AWS IAM role. Upbound authenticates workloads with that service account as
the IAM role using temporary credentials instead of static role credentials.
IRSA relies on AWS AssumeRoleWithWebIdentity
STS
to exchange OIDC ID tokens with
the IAM role's temporary credentials. IRSA uses the eks.amazon.aws/role-arn
annotation to link the service account and the IAM role.
Create an IAM role and trust policy
First, create an IAM role with appropriate permissions to access AWS Secrets Manager:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"ssm:GetParameter"
],
"Resource": [
"arn:aws:secretsmanager:${YOUR_REGION}:${YOUR_AWS_ACCOUNT_ID}:secret:${YOUR_SECRET_PREFIX}*",
"arn:aws:ssm:${YOUR_REGION}:${YOUR_AWS_ACCOUNT_ID}:parameter/${YOUR_PARAMETER_PREFIX}*"
]
}
]
}
You must configure the IAM role trust policy with the exact match for each provisioned control plane. An example of a trust policy for a single control plane is below:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::${YOUR_AWS_ACCOUNT_ID}:oidc-provider/${YOUR_OIDC_PROVIDER}"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"<OIDC_PROVIDER>:aud": "sts.amazonaws.com"
},
"StringLike": {
"<OIDC_PROVIDER>:sub": "system:serviceaccount:*:external-secrets-controller"
}
}
}
]
}
Configure the EKS OIDC provider
Next, ensure your EKS cluster has an OIDC identity provider:
eksctl utils associate-iam-oidc-provider --cluster ${YOUR_CLUSTER_NAME} --approve
Apply the IAM role
In your control plane, pass the --set
flag with the Spaces Helm chart
parameters for the shared secrets component:
--set controlPlanes.sharedSecrets.serviceAccount.customAnnotations."eks\.amazonaws\.com/role-arn"="arn:aws:iam::${YOUR_AWS_ACCOUNT_ID}:role/${YOUR_ESO_ROLE_NAME}"
This command allows the shared secrets component to authenticate with your dedicated IAM role in your EKS cluster environment.
EKS pod identities
Upbound also supports EKS Pod Identity configuration. EKS Pod Identities allow you to create a pod identity association with your Kubernetes namespace, a service account, and an IAM role, which allows the EKS control plane to automatically handle the credential exchange.
Create an IAM role
First, create an IAM role with appropriate permissions to access AWS Secrets Manager:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"ssm:GetParameter"
],
"Resource": [
"arn:aws:secretsmanager:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:secret:${YOUR_SECRET_PREFIX}*",
"arn:aws:ssm:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:parameter/${YOUR_PARAMETER_PREFIX}*"
]
}
]
}
Configure your Space with Helm
When you install or upgrade your Space with Helm, add the shared secrets value:
helm upgrade spaces spaces-helm-chart \
--set "sharedSecrets.enabled=true"
Create a Pod Identity Association
After Upbound provisions your control plane, create a Pod Identity Association
with the aws
CLI:
aws eks create-pod-identity-association \
--cluster-name ${YOUR_CLUSTER_NAME} \
--namespace ${YOUR_CONTROL_PLANE_NAMESPACE} \
--service-account external-secrets-controller \
--role-arn arn:aws:iam::${YOUR_AWS_ACCOUNT_ID}:role/${YOUR_ROLE_NAME}
Verify your configuration
After you apply the configuration use kubectl
to verify the service account
has the correct annotation:
kubectl get serviceaccount external-secrets-controller -n ${YOUR_CONTROL_PLANE_NAMESPACE} -o yaml
Verify the external-secrets
pod is running correctly:
kubectl get pods -n ${YOUR_CONTROL_PLANE_NAMESPACE} | grep external-secrets
Restart workload
You must manually restart a workload's pod when you add the
eks.amazonaws.com/role-arn key
annotation to the running pod's service
account.
This restart enables the EKS pod identity webhook to inject the necessary environment for using IRSA.
kubectl rollout restart deployment external-secrets
Use cases
Shared secrets with workload identity eliminates the need for static credentials in your cluster. These benefits are particularly helpful in:
- Secure application credentials management
- Database connection string storage
- API token management
- Compliance with secret rotation security standards
- Multi-environment configuration with centralized secret management
Next steps
Now that you have workload identity configured for the shared secrets component, visit the Shared Secrets guide for more information.
Other workload identity guides are: