Use EKS Pod Identity in AWS

For CARTO Self-Hosted orchestrated (Kubernetes) deployments — Kots and Helm

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.

What is EKS Pod Identity?

Amazon EKS Pod Identity 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.

Enabling EKS Pod Identity in your Self-Hosted installation is just available for the orchestrated container deployment of CARTO.

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.

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.

2. Enable IAM Authentication in your PostgreSQL RDS database.

3. Create a user with IAM Authentication enabled in your database:

Create user in the metadata database

CREATE USER {USERNAME};
GRANT rds_iam TO {USERNAME};

• USERNAME: Username that will be used to connect to your metadata database.

4. Grant your Pod Identity IAM Role permissions to connect to your metadata database:

Configure IAM Role Policy to allow connecting to the RDS database

Assign the following policy to the role configured for EKS Pod Identity:

{
    "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.

5. Tell CARTO to use the Pod Identity service account to reach the metadata database:

Kots

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):

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.

Helm

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.

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.

3. Tell CARTO to use the Pod Identity service account to reach the S3 buckets:

Kots

Kots

1. Apply the bucket configuration described in Configure your own buckets 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):

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.

Helm

Once the new version is deployed, your CARTO deployment will use the role you created to connect to the S3 buckets!