> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/configuration/security/cloud-identities/use-eks-pod-identity-in-aws.md).
# Use EKS Pod Identity in AWS
{% hint style="info" %}
EKS Pod Identity is available for the **orchestrated container deployment** of CARTO on Amazon EKS, with both **Kots** and **Helm**. The AWS-side setup (Pod Identity association, IAM role, and policies) is identical for both; only the final step that tells CARTO to use it differs. The Admin Console has no dedicated fields for Pod Identity, so **Kots** users add the values through the **Custom Configuration** field (the free-form YAML field at the bottom of the configuration screen), while **Helm** users set them in `customizations.yaml` — see the tabs below.
{% endhint %}
## What is EKS Pod Identity?
[Amazon EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) allows Kubernetes pods in EKS clusters to securely assume specific AWS IAM roles, enabling secure, granular access to AWS resources without embedding credentials within the pods.
This approach enhances security by reducing the risk of exposed access keys and supports fine-grained access control by enabling distinct permissions for each workload. With EKS Pod Identity, managing access credentials becomes simpler and safer, allowing developers to control AWS resource permissions at the pod level.
{% hint style="info" %}
Enabling EKS Pod Identity in your Self-Hosted installation is **just available for the orchestrated container deployment** of CARTO.
{% endhint %}
## How does EKS Pod Identity work?
Enabling EKS Pod Identity on a cluster allows assuming an IAM role from the pods deployed. When Amazon EKS starts a new pod that uses a service account with an EKS Pod Identity association it injects some environment variables in the pods that can be used to authenticate against AWS APIs.
In order to enable this feature in your EKS cluster, you can check the following [documentation](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).
## Use EKS Pod Identity to access the metadata database
CARTO Self-Hosted running on an EKS cluster can take advantage of EKS Pod Identity feature to connect to the PostgreSQL metadata database if it's deployed in RDS.
### Configuration
1. Setup EKS Pod Identity following the [documentation](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).
2. Enable IAM Authentication in your PostgreSQL RDS database.
3. Create a user with IAM Authentication enabled in your database:
{% tabs %}
{% tab title="Create user in the metadata database" %}
```sql
CREATE USER {USERNAME};
GRANT rds_iam TO {USERNAME};
```
* `USERNAME`: Username that will be used to connect to your metadata database.
{% endtab %}
{% endtabs %}
**4.** Grant your Pod Identity IAM Role permissions to connect to your metadata database:
{% tabs %}
{% tab title="Configure IAM Role Policy to allow connecting to the RDS database" %}
Assign the following policy to the role configured for EKS Pod Identity:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "rds-db:connect",
"Resource": "arn:aws:rds-db:{REGION}:{AWS_ACCOUNT_ID}:dbuser:{RDS_DATABASE_RESOURCE_ID}/{USERNAME}"
}
]
}
```
* `REGION`: AWS region in which the metadata database is deployed.
* `AWS_ACCOUNT_ID`: ID of the AWS account where the metadata database is deployed.
* `RDS_DATABASE_RESOURCE_ID`: ID of the database in AWS. It should be a string matching the following format: `db-Rxxxxxxxxxxxxxxxx`
* `USERNAME`: Username that will be used to connect to your metadata database. It should be the same that was created previously.
{% endtab %}
{% endtabs %}
**5.** Tell CARTO to use the Pod Identity service account to reach the metadata database:
{% tabs %}
{% tab title="Kots" %} 
1. Enter your external PostgreSQL connection details (host, user, database, port, SSL CA) in the **Metadata Database** section of the Admin Console.
2. Pod Identity has no dedicated fields in the Admin Console, so add the following to the **Custom Configuration** field (the free-form YAML field at the bottom of the configuration screen):
```yaml
commonBackendServiceAccount:
create: false
name: '{EKS_POD_IDENTITY_SERVICE_ACCOUNT}'
externalPostgresql:
awsEksPodIdentityEnabled: true
awsRdsRegion: {REGION}
```
* `EKS_POD_IDENTITY_SERVICE_ACCOUNT`: Name of the service account you created when configuring EKS Pod Identity.
* `REGION`: AWS region in which the metadata database is deployed.
Save and deploy the new version from the Admin Console.
{% endtab %}
{% tab title="Helm" %} 
Provide the following configuration in your customizations.yaml file:
```yaml
commonBackendServiceAccount:
create: false
name: '{EKS_POD_IDENTITY_SERVICE_ACCOUNT}'
externalPostgresql:
host: {HOST}
user: {USERNAME}
database: {DATABASE}
port: {PORT}
awsEksPodIdentityEnabled: true
awsRdsRegion: {REGION}
sslEnabled: true
sslCA: |
{CA_CERT}
```
* `EKS_POD_IDENTITY_SERVICE_ACCOUNT`: Name of the service account you created when configuring EKS Pod Identity.
* `HOST`: Address of the PostgreSQL RDS database.
* `USERNAME`: Username that will be used to connect to your metadata database. It should be the same that was created previously.
* `PORT`: Port used to connect to the PostgreSQL RDS database.
* `REGION`: AWS region in which the metadata database is deployed.
* `CA_CERT`: Content of the CA certificate used to connect to the database using SSL.
{% endtab %}
{% endtabs %}
Once the new version is deployed, your CARTO deployment will use the role you created to connect to the metadata database!
## Use EKS Pod Identity to access the S3 buckets
CARTO Self-Hosted running on an EKS cluster can take advantage of EKS Pod Identity feature to connect to the S3 buckets if it's deployed in RDS.
### Configuration
1. Setup EKS Pod Identity following the [documentation](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).
2. Grant your Pod Identity IAM Role permissions to connect to your S3 buckets. You can find the needed permissions in the [guide to configure your own buckets](/carto-self-hosted/configuration/data-and-storage/configure-your-own-buckets.md).
3. Tell CARTO to use the Pod Identity service account to reach the S3 buckets:
{% tabs %}
{% tab title="Kots" %}
1. Apply the bucket configuration described in [Configure your own buckets](/carto-self-hosted/configuration/data-and-storage/configure-your-own-buckets.md) using the Admin Console bucket fields.
2. Pod Identity has no dedicated fields in the Admin Console, so add the following to the **Custom Configuration** field (the free-form YAML field at the bottom of the configuration screen):
```yaml
commonBackendServiceAccount:
create: false
name: '{EKS_POD_IDENTITY_SERVICE_ACCOUNT}'
appConfigValues:
awsEksPodIdentityBucketsEnabled: true
```
* `EKS_POD_IDENTITY_SERVICE_ACCOUNT`: Name of the service account you created when configuring EKS Pod Identity.
Save and deploy the new version from the Admin Console.
{% endtab %}
{% tab title="Helm" %}
Provide in your customizations.yaml file the changes explained in [Configure your own buckets](/carto-self-hosted/configuration/data-and-storage/configure-your-own-buckets.md) and the following changes:
commonBackendServiceAccount:
create: false
name: '{EKS_POD_IDENTITY_SERVICE_ACCOUNT}'
appConfigValues:
awsEksPodIdentityBucketsEnabled: true
* `EKS_POD_IDENTITY_SERVICE_ACCOUNT`: Name of the service account you created when configuring EKS Pod Identity.
{% endtab %}
{% endtabs %}
Once the new version is deployed, your CARTO deployment will use the role you created to connect to the S3 buckets!
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.carto.com/carto-self-hosted/configuration/security/cloud-identities/use-eks-pod-identity-in-aws.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.