Install & Compatibility
Where this runs
tested against v4.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.981s · 353.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 21.4s · import 1.273s · 339MB
385MB installed
● package 385MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cluster
✓ from pulumi_eks import Cluster
✗ from pulumi_eks.index import Cluster
While `index` might sometimes work, the public API for components is directly from the package root.
This quickstart deploys a basic EKS cluster with two `t2.medium` worker nodes. It creates the necessary IAM roles and, by default, a new VPC and public subnets. Ensure your AWS credentials are configured and your AWS region is set via `pulumi config set aws:region <region-name>` or environment variables.
import pulumi
import pulumi_aws as aws
import pulumi_eks as eks
import os
# Ensure AWS region is configured.
# For a project, use `pulumi config set aws:region us-west-2`.
# For this quickstart to run, ensure AWS_REGION or AWS_DEFAULT_REGION env var is set,
# or you have a default region configured in your AWS credentials file.
if not pulumi.Config("aws").get("region") and not os.environ.get('AWS_REGION') and not os.environ.get('AWS_DEFAULT_REGION'):
raise Exception("AWS region must be configured via `pulumi config set aws:region <region-name>` or environment variables.")
# Create an IAM role for the EKS Cluster and Node Groups.
# This role grants permissions for EKS to manage resources and for nodes to join the cluster.
eks_cluster_role = aws.iam.Role("eks-cluster-role",
assume_role_policy=aws.iam.get_policy_document(
statements=[aws.iam.GetPolicyDocumentStatementArgs(
actions=["sts:AssumeRole"],
principals=[aws.iam.GetPolicyDocumentStatementPrincipalArgs(
type="Service",
identifiers=["eks.amazonaws.com"],
)],
)]
).json
)
aws.iam.RolePolicyAttachment("eks-cluster-policy",
role=eks_cluster_role.name,
policy_arn="arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
)
aws.iam.RolePolicyAttachment("eks-vpc-cni-policy",
role=eks_cluster_role.name,
policy_arn="arn:aws:iam::aws:policy/AmazonEKSVPCResourceController"
)
# Create the EKS cluster.
# By omitting `vpc_id` and `subnet_ids`, pulumi-eks will create a new VPC and public subnets.
cluster = eks.Cluster("my-eks-cluster",
role_arn=eks_cluster_role.arn,
instance_type="t2.medium", # Default instance type for worker nodes
desired_capacity=2,
min_size=1,
max_size=3,
version="1.28" # Explicitly pin EKS Kubernetes version
)
# Export the cluster's name and kubeconfig
pulumi.export("cluster_name", cluster.name)
pulumi.export("kubeconfig", cluster.kubeconfig)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pulumi_eks'
The `pulumi-eks` Python package is not installed in the current Python environment.
fixInstall the package using pip: `pip install pulumi-eks`
error: configuring AWS: no region was provided
The Pulumi AWS provider requires an AWS region to be configured. This can be done via Pulumi configuration, environment variables, or the AWS credentials file.
fixSet the region using Pulumi config: `pulumi config set aws:region us-west-2` (replace with your desired region), or export an environment variable: `export AWS_REGION=us-west-2`.
pulumi:pulumi:Stack (my-eks-stack): error: AccessDenied: User is not authorized to perform sts:AssumeRole on resource arn:aws:iam::xxxxxxxxxxxx:role/eks-cluster-role
The AWS user or role executing the Pulumi program does not have the necessary `iam:PassRole` or `sts:AssumeRole` permissions to interact with the IAM role specified for the EKS cluster (or other resources).
fixEnsure your AWS credentials have sufficient IAM permissions to create and manage EKS resources. Specifically, the executing role needs `iam:PassRole` permission on the `role_arn` provided to the `eks.Cluster` component, and `sts:AssumeRole` for other service roles.
InvalidParameterException: No default VPC for this user
When `vpc_id` and `subnet_ids` are omitted from `eks.Cluster`, `pulumi-eks` attempts to create a new VPC and subnets. This error indicates that the AWS account or region might have restrictions on creating default networking resources, or there's another underlying issue preventing VPC creation.
fixInstead of relying on implicit VPC creation, explicitly define and pass a `pulumi_aws.ec2.Vpc` and `pulumi_aws.ec2.Subnet` resources to the `eks.Cluster` component, ensuring they are correctly configured and within your AWS account's limits.
Upgrade
Version history
4.2.0latest on PyPI · released Dec 19, 2025
Audit
Dependencies
pulumirequiredCore Pulumi engine for infrastructure as code.
pulumi-awsrequiredManages underlying AWS resources (VPC, IAM, EC2) used by EKS components.