Pulumi EKS Components

4.2.0 · active · verified Fri Apr 17

Pulumi EKS (Elastic Kubernetes Service) is a component package for provisioning and managing Amazon EKS clusters and their associated resources (VPC, IAM, Node Groups, Fargate profiles, etc.) using Python, TypeScript, Go, or C#. It simplifies EKS cluster deployment by encapsulating common patterns and best practices. The current version is 4.2.0, with frequent updates that often reflect changes in the underlying Pulumi AWS provider.

Common errors

```
ModuleNotFoundError: No module named 'pulumi_eks'
```
cause The `pulumi-eks` Python package is not installed in the current Python environment.

fix Install the package using pip: `pip install pulumi-eks`
```
error: configuring AWS: no region was provided
```
cause 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.

fix Set 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
```
cause 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).

fix Ensure 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
```
cause 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.

fix Instead 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.

Warnings

breaking Pulumi EKS versions, even minor ones (e.g., v3.7.0, v3.9.0, v4.0.0), frequently introduce breaking changes due to underlying `pulumi-aws` provider upgrades. These can involve changes in resource input/output types (e.g., from `v6.x.x` to `v7.x.x` of `pulumi-aws`) or removal of properties (e.g., `defaultAddonsToRemove` in v4.0.0).
Fix: Always review the changelog and release notes when upgrading `pulumi-eks`. Test upgrades in a staging environment. Be prepared to update your code to reflect changes in resource properties or types.
gotcha Omitting the `version` property in `eks.Cluster` can lead to automatic Kubernetes version upgrades with minor `pulumi-eks` updates, which might break existing Kubernetes applications or require manual intervention.
Fix: Explicitly pin your Kubernetes version, e.g., `version="1.28"`, to control when your EKS cluster undergoes version upgrades. This allows you to plan and test for compatibility.
gotcha Correct AWS IAM permissions are crucial for both the EKS control plane (passed via `role_arn` to `eks.Cluster`) and worker nodes (managed by the `eks.Cluster` component internally or explicitly via `instanceRole`). Misconfigured policies (e.g., `AmazonEKSClusterPolicy`, `AmazonEKSWorkerNodePolicy`, `AmazonEC2ContainerRegistryReadOnly`) are a frequent cause of cluster creation failures or node group issues.
Fix: Carefully review and apply the recommended IAM policies for EKS. Ensure the Pulumi execution role has `iam:PassRole` permissions for the roles used by EKS. Leverage `pulumi-eks` components' default role creation or explicitly define and attach standard EKS policies.
breaking As of `v4.0.0`, the `defaultAddonsToRemove` input for `eks.Cluster` was removed. If you were using this to manage default add-ons, your program will no longer compile or function as expected.
Fix: Remove the `defaultAddonsToRemove` property from your `eks.Cluster` configuration. Adapt your configuration to explicitly manage EKS add-ons using the `aws.eks.Addon` resource if you need to customize or remove specific add-ons.

Install

pip install pulumi-eks Install pulumi-eks

Imports

Cluster
wrong:
```
from pulumi_eks.index import Cluster
```
correct:
```
from pulumi_eks import Cluster
```
While `index` might sometimes work, the public API for components is directly from the package root.

Quickstart

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)

view raw JSON →