Use AWS IAM Roles with Qovery

1. A Terraform service creates the IAM role (and the OIDC identity provider if needed)
2. A Helm service creates the Kubernetes ServiceAccount annotated with the role ARN
3. Your application picks up the ServiceAccount through the Service account advanced setting

​

Prerequisites

• A Qovery cluster running on AWS EKS
• Basic knowledge of AWS IAM and Kubernetes
• AWS credentials allowed to manage IAM (for the Terraform service or the Console)

​

Step 1: Create an Application Requiring S3 Permissions

• Deploy a Debian container with 1 instance and 128MB memory
• You can also use existing applications, containers, or jobs

​

Get Kubernetes Namespace Name

1. Access your container variables and locate QOVERY_KUBERNETES_NAMESPACE_NAME
2. This value represents the namespace where the container runs

​

Step 2: Create the OIDC Provider and IAM Role

• Terraform service (recommended)
• Manually (AWS Console)

Add a Terraform service to the same environment:

• Source: Git repository https://github.com/Qovery/create_service_account
• Root path: terraform/

Set these variables on the service:

Variable	Value
TF_VAR_cluster_name	Alias of the built-in QOVERY_KUBERNETES_CLUSTER_NAME
TF_VAR_role_name	Name for the IAM role, e.g. my-s3-role
TF_VAR_service_account_name	ServiceAccount name, e.g. my-app-sa
TF_VAR_policy_arns	e.g. ["arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"]
TF_VAR_namespace	Alias of QOVERY_KUBERNETES_NAMESPACE_NAME to scope the role to this environment, or empty for a cluster-scoped role (required for Preview/Clone)
TF_VAR_create_oidc_provider	true the first time, if the cluster’s OIDC provider is not registered in IAM yet
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION	Credentials allowed to manage IAM (mark the secret as such)

Deploy the service. The module creates the trust policy for you (namespace-scoped StringEquals, or cluster-scoped StringLike on system:serviceaccount:z*:<service_account_name> when TF_VAR_namespace is empty).The module outputs role_arn. Qovery exposes it to the environment as a variable named QOVERY_OUTPUT_TERRAFORM_<service short id>_ROLE_ARN; check the exact name in your environment variables after the first deployment. You will reference it in step 3.

​

Get Cluster OIDC Provider URL

1. Navigate to your AWS EKS cluster Overview section
2. Copy the OpenID Connect provider URL

​

Create Identity Provider

1. In AWS IAM, access the Identity providers section
2. Select OpenID Connect provider type
3. Paste the provider URL
4. Click Get thumbprint
5. Add sts.amazonaws.com as Audience
6. Create the provider

​

Create a Role

1. In IAM Roles section, select Create role
2. Choose Web identity as Trusted entity type
3. Set Identity provider and Audience to sts.amazonaws.com

​

Add Role Permissions

1. Select the desired policy (example uses AmazonS3ReadOnlyAccess)
2. Set role name and description
3. Proceed to creation

​

Configure Trusted Entities

For a role scoped to one environment, update the trust policy from:

"oidc.eks.eu-west-3.amazonaws.com/id/xxxxxxx:aud": "sts.amazonaws.com"

To:

"oidc.eks.eu-west-3.amazonaws.com/id/xxxxxxx:sub":
"system:serviceaccount:kubernetes_namespace:service_account_name"

Replace placeholders:

• kubernetes_namespace: Your Qovery environment namespace
• service_account_name: Define a service account name (e.g., my-app-sa)

For a cluster-scoped role (required by On-demand/Clone features), use StringLike with a wildcard:

"Condition": {
    "StringLike": {
        "oidc.eks.eu-west-3.amazonaws.com/id/xxxxxxx:sub":
        "system:serviceaccount:z*:service_account_name"
    }
}

This allows the service account to be used across all namespaces starting with z.

Save the role ARN for step 3.

​

Step 3: Create the Service Account

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <service_account_name>
  annotations:
    eks.amazonaws.com/role-arn: <role_arn>

1. Repository name: Qovery Service Account Helper
2. Kind: HTTPS
3. URL: https://qovery.github.io/create_service_account/

• Helm source: Helm repository
• Chart name: qovery-sa-helper
• Version: 0.2.0

serviceAccount:
  name: my-app-sa   # same as TF_VAR_service_account_name
awsRoleArn: qovery.env.QOVERY_OUTPUT_TERRAFORM_<SHORT_ID>_ROLE_ARN

serviceAccount:
  name: my-app-sa
awsRoleArn: arn:aws:iam::xxxxxx:role/my-s3-role

​

Step 4: Set Application Service Account

​

Configure Service Account

1. Access your application Advanced settings
2. Set Service account (security.service_account_name) to the created service account name
3. Deploy using the Deploy now button

​

Validate Access

$ qovery shell

$ env | grep AWS
AWS_DEFAULT_REGION=us-east-2
AWS_REGION=us-east-2
AWS_ROLE_ARN=arn:aws:iam::xxxxxx:role/my-s3-role
AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
AWS_STS_REGIONAL_ENDPOINTS=regional

$ apt-get update && apt-get -y install awscli
$ aws s3 ls

​

Key Concepts

• OIDC Integration: Enables Kubernetes service accounts to assume AWS roles
• Token Rotation: Automatic credential rotation without manual management
• Namespace Scoping: Restricts role access to specific Kubernetes namespaces
• Everything as Qovery services: The IAM role and the ServiceAccount are regular services in your environment, so they are versioned, visible in the Console, replicated with Clone/Preview, and cleaned up with the environment

​

Conclusion

​

Related Documentation

Terraform Services

Deploy Terraform manifests with Qovery

Advanced Settings

Configure service advanced settings

Environment Variables

Manage environment variables and secrets

Helm Services

Deploy applications with Helm