{"id":10070,"library":"pulumi-eks","title":"Pulumi EKS Components","description":"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.","status":"active","version":"4.2.0","language":"en","source_language":"en","source_url":"https://github.com/pulumi/pulumi-eks","tags":["pulumi","aws","eks","kubernetes","iac","cloud"],"install":[{"cmd":"pip install pulumi-eks","lang":"bash","label":"Install pulumi-eks"}],"dependencies":[{"reason":"Core Pulumi engine for infrastructure as code.","package":"pulumi","optional":false},{"reason":"Manages underlying AWS resources (VPC, IAM, EC2) used by EKS components.","package":"pulumi-aws","optional":false}],"imports":[{"note":"While `index` might sometimes work, the public API for components is directly from the package root.","wrong":"from pulumi_eks.index import Cluster","symbol":"Cluster","correct":"from pulumi_eks import Cluster"}],"quickstart":{"code":"import pulumi\nimport pulumi_aws as aws\nimport pulumi_eks as eks\nimport os\n\n# Ensure AWS region is configured.\n# For a project, use `pulumi config set aws:region us-west-2`.\n# For this quickstart to run, ensure AWS_REGION or AWS_DEFAULT_REGION env var is set,\n# or you have a default region configured in your AWS credentials file.\nif not pulumi.Config(\"aws\").get(\"region\") and not os.environ.get('AWS_REGION') and not os.environ.get('AWS_DEFAULT_REGION'):\n    raise Exception(\"AWS region must be configured via `pulumi config set aws:region <region-name>` or environment variables.\")\n\n# Create an IAM role for the EKS Cluster and Node Groups.\n# This role grants permissions for EKS to manage resources and for nodes to join the cluster.\neks_cluster_role = aws.iam.Role(\"eks-cluster-role\",\n    assume_role_policy=aws.iam.get_policy_document(\n        statements=[aws.iam.GetPolicyDocumentStatementArgs(\n            actions=[\"sts:AssumeRole\"],\n            principals=[aws.iam.GetPolicyDocumentStatementPrincipalArgs(\n                type=\"Service\",\n                identifiers=[\"eks.amazonaws.com\"],\n            )],\n        )]\n    ).json\n)\n\naws.iam.RolePolicyAttachment(\"eks-cluster-policy\",\n    role=eks_cluster_role.name,\n    policy_arn=\"arn:aws:iam::aws:policy/AmazonEKSClusterPolicy\"\n)\naws.iam.RolePolicyAttachment(\"eks-vpc-cni-policy\",\n    role=eks_cluster_role.name,\n    policy_arn=\"arn:aws:iam::aws:policy/AmazonEKSVPCResourceController\"\n)\n\n# Create the EKS cluster.\n# By omitting `vpc_id` and `subnet_ids`, pulumi-eks will create a new VPC and public subnets.\ncluster = eks.Cluster(\"my-eks-cluster\",\n    role_arn=eks_cluster_role.arn,\n    instance_type=\"t2.medium\", # Default instance type for worker nodes\n    desired_capacity=2,\n    min_size=1,\n    max_size=3,\n    version=\"1.28\" # Explicitly pin EKS Kubernetes version\n)\n\n# Export the cluster's name and kubeconfig\npulumi.export(\"cluster_name\", cluster.name)\npulumi.export(\"kubeconfig\", cluster.kubeconfig)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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).","severity":"breaking","affected_versions":">=3.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install pulumi-eks`","cause":"The `pulumi-eks` Python package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'pulumi_eks'"},{"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`.","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.","error":"error: configuring AWS: no region was provided"},{"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.","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).","error":"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"},{"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.","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.","error":"InvalidParameterException: No default VPC for this user"}]}