> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Use AWS IAM Roles with Qovery
> Grant AWS IAM permissions to applications without managing credentials
This tutorial demonstrates how to grant AWS IAM permissions to applications, containers, or jobs deployed through Qovery. This approach eliminates credential management by automatically rotating tokens through AWS's identity service.
## 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
First, deploy a simple Debian container that will need S3 access:
* 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: Configure OIDC Provider
\###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
***
## 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
Update the trust policy from:
```json theme={null}
"oidc.eks.eu-west-3.amazonaws.com/id/xxxxxxx:aud": "sts.amazonaws.com"
```
To:
```json theme={null}
"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-s3-role`)
For On-demand/Clone features, use `StringLike` with wildcard:
```json theme={null}
"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 later use.
***
## Step 4: Create a Service Account
### Service Account Manifest
```yaml theme={null}
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
We'll use a Helm chart to deploy the service account:
**Chart Configuration:**
* Helm source: Helm repository
* Chart name: `qovery-sa-helper`
* Version: `0.1.0`
**Repository Details:**
1. Repository name: `Qovery Service Account Helper`
2. Kind: `HTTPS`
3. URL: `https://qovery.github.io/create_service_account/`
**Override Arguments:**
1. `serviceAccount.name`: Your service account name
2. `awsRoleArn`: Your role ARN
Deploy the Helm service and verify it completes successfully:
***
## 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
Using Qovery CLI:
```bash theme={null}
$ qovery shell
```
Check AWS environment variables:
```bash theme={null}
$ 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
```
Validate S3 access:
```bash theme={null}
$ 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
Initial setup requires multiple configuration steps across AWS and Kubernetes. Once configured, applying roles to applications becomes straightforward, enabling secure access to AWS services without credential management overhead.
***
## Related Documentation
Learn about EKS cluster management
Configure service advanced settings
Manage environment variables and secrets
Deploy applications with Helm