Skip to main content
Version: 3.4

How to use workload identity for AWS cloud operations in Portworx

Portworx supports using AWS IAM Roles for Service Accounts (IRSA) to access cloud resources such as Amazon S3 for CloudSnap backups and Amazon EBS for CloudDrive provisioning. This removes the need to manage static AWS credentials or assign IAM permissions at the node level.

The workload identity feature in Portworx Operator enables Portworx pods to securely access AWS services without hardcoding cloud credentials. Instead, Portworx leverages AWS IAM Roles for Service Accounts (IRSA), injecting short-lived credentials that are automatically rotated into pods. This improves security posture and operational simplicity for cloud-native storage workflows such as CloudSnap and CloudDrive.

By configuring workload identity, Portworx can securely perform cloud operations using short-lived tokens that are automatically rotated and injected into its pods via Portworx service account and projected tokens.

This approach enhances security, simplifies credential management, and meets the compliance needs of enterprises operating on AWS-based Kubernetes clusters.

How it works​

When this feature is configured:

  • Portworx service account is annotated with an AWS IAM role.
  • The Portworx Operator ensures pods are injected with:
    • A projected service account token.
    • Environment variables like AWS_ROLE_ARN, AWS_REGION, AWS_DEFAULT_REGION, and AWS_WEB_IDENTITY_TOKEN_FILE.
  • The AWS SDK within Portworx uses these to inherit the IAM role at runtime.

On Amazon Elastic Kubernetes Service (EKS), this is handled automatically by the eks-pod-identity-webhook. On non-EKS environments, users must deploy it manually.

Why use workload identity​

Traditional AWS credential mechanisms involve manually provisioning access keys and rotating them securely—an operational and security risk. Workload identity offers the following benefits:

  • Eliminates static AWS access keys and secrets.
  • Avoids granting IAM permissions to entire Kubernetes node.
  • Automatically injects short-lived credentials into the appropriate pods.

Supported platforms​

This feature is supported on the following AWS-based Kubernetes distributions:

  • Amazon Elastic Kubernetes Service (EKS)
  • Red Hat OpenShift Service on AWS (ROSA)
  • Google Anthos on AWS

Prerequisites​

Before configuring workload identity, ensure that the following prerequisites are met:

  • A Kubernetes cluster on the AWS platform
  • Portworx Enterprise version 3.4.0 or later
  • Portworx Operator version 25.3.1 or later
  • An OIDC provider linked to your Kubernetes cluster. For more information, refer to Create an OpenID Connect (OIDC) identity provider in IAM.
  • The Pod Identity Webhook is deployed and running:
    • Included by default in EKS and ROSA clusters.
    • For other clusters running on EC2 instances, you need to manually deploy the webhook. For more information, refer to Amazon EKS Pod Identity Webhook.
      important

      After cloning the repository, edit the deployment-base.yaml file to include --aws-default-region <aws-region> flag in the spec.template.spec.containers.command field before deploying the webhook.

Create an IAM role​

  1. Define an IAM role with the required permissions for AWS services used by CloudSnap or CloudDrive.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "EBSVolumeManagement",
                "Effect": "Allow",
                "Action": [
                    "ec2:CreateVolume",
                    "ec2:DeleteVolume",
                    "ec2:AttachVolume",
                    "ec2:DetachVolume",
                    "ec2:DescribeVolumes",
                    "ec2:ModifyVolume",
                    "ec2:DescribeVolumeStatus",
                    "ec2:CreateSnapshot",
                    "ec2:DeleteSnapshot",
                    "ec2:DescribeSnapshots",
                    "ec2:CreateTags",
                    "ec2:DeleteTags",
                    "ec2:DescribeTags",
                    "ec2:DescribeVolumeAttribute",
                    "ec2:DescribeVolumesModifications",
                    "autoscaling:DescribeAutoScalingGroups"
                ],
                "Resource": "*"
            },
            {
                "Sid": "InstanceDescription",
                "Effect": "Allow",
                "Action": [
                    "ec2:DescribeInstances"
                ],
                "Resource": "*"
            },
            {
                "Sid": "S3BucketManagement",
                "Effect": "Allow",
                "Action": [
                    "s3:CreateBucket",
                    "s3:ListAllMyBuckets",
                    "s3:GetBucketLocation",
                    "s3:ListBucket",
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:DeleteObject"
                ],
                "Resource": [
                    "*"
                ]
            }
        ]
    }

  2. Attach a trust policy to the role.

    Choose the appropriate trust policy based on your Kubernetes distribution:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Federated": "arn:aws:iam::<account-id>:oidc-provider/<oidc-provider-url>"
                },
                "Action": "sts:AssumeRoleWithWebIdentity",
                "Condition": {
                    "StringEquals": {
                        "<oidc-provider-url>:aud": "sts.amazonaws.com"
                    },
                    "StringLike": {
                        "<oidc-provider-url>:sub": "system:serviceaccount:<namespace>:portworx"
                    }
                }
            }
        ]
    }

    Refer to Create a role for OpenID Connect federation (console) for more details.

Configure workload identity​

To configure the workload identity feature, edit the StorageCluster custom resource to add the following section:

spec:
  workloadIdentity:
    credentials:
    - cloudProvider: "aws"
      key: "eks.amazonaws.com/role-arn"
      value: "arn:aws:iam::<account-id>:role/<role-name>"

Configure workload identity​

To configure the workload identity feature for an existing cluster, edit the StorageCluster custom resource to include the following section:

spec:
  workloadIdentity:
    credentials:
    - cloudProvider: "aws"
      key: "eks.amazonaws.com/role-arn"
      value: "arn:aws:iam::<account-id>:role/<role-name>"

Verify token injection​

Once the configuration is applied, the Portworx Operator will restart pods as needed. Following the restart, Portworx pods should include the following:

Token volume​

volumes:
- name: aws-iam-token
  projected:
    defaultMode: 420
    sources:
    - serviceAccountToken:
        audience: sts.amazonaws.com
        expirationSeconds: 86400
        path: token

Volume mount​

volumeMounts:
- mountPath: /var/run/secrets/eks.amazonaws.com/serviceaccount
  name: aws-iam-token
  readOnly: true

Environment variables​

spec:
  containers:
  - env:
    - name: AWS_WEB_IDENTITY_TOKEN_FILE
      value: /var/run/secrets/eks.amazonaws.com/serviceaccount/token
    - name: AWS_ROLE_ARN
      value: arn:aws:iam::<account-id>:role/<role-name>
    - name: AWS_REGION
      value: us-west-2
    - name: AWS_DEFAULT_REGION
      value: us-west-2

These are used by the AWS SDK to authenticate and make API calls.

Create credentials using workload identity​

To create CloudSnap credentials using workload identity, run the following Portworx CLI command:

pxctl credentials create px-cloud-cred \
  --provider s3 \
  --use-workload-identity

This credential can be used to create cloud snapshots. For more information, see Create and use cloud snapshots.

note

The --s3-disable-ssl flag is not supported with workload identity for AWS endpoints as it enforces SSL..