Use AWS IAM Roles with Qovery

​

Prerequisites

• A Qovery cluster running on AWS EKS
• Basic knowledge of AWS IAM and Kubernetes
• Access to AWS Console and Qovery 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
2. Locate QOVERY_KUBERNETES_NAMESPACE_NAME
3. This value represents the namespace where the container runs

​

Step 2: Configure OIDC Provider

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

​

Step 3: Configure AWS IAM Roles

​

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

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

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

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

​

Step 4: Create a Service Account

​

Service Account Manifest

apiVersion: v1
kind: ServiceAccount
metadata:
 name: $SERVICE_ACCOUNT_NAME
 namespace: $QOVERY_KUBERNETES_NAMESPACE_NAME
 annotations:
   eks.amazonaws.com/role-arn: $AWS_ROLE_ARN

​

Deploy with Helm

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

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

1. serviceAccount.name: Your service account name
2. awsRoleArn: Your role ARN

​

Step 5: Set Application Service Account

​

Configure Service Account

1. Access your application Advanced settings
2. Set Service account 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
• Cluster-Wide Availability: Service accounts accessible by all applications in the same namespace

​

Conclusion

​

Related Documentation

AWS EKS Integration

Learn about EKS cluster management

Advanced Settings

Configure service advanced settings

Environment Variables

Manage environment variables and secrets

Helm Services

Deploy applications with Helm