Pulumi AWSX

3.5.0 · active · verified Thu Apr 16

Pulumi Amazon Web Services (AWS) AWSX Components is a collection of higher-level Pulumi components that simplify common AWS infrastructure patterns, such as VPCs, ECS clusters, and EC2 instances. It abstracts away much of the complexity of the underlying `pulumi-aws` provider. The current version is 3.5.0, and it follows a frequent release cadence, often aligning with updates to the core `pulumi-aws` provider.

Common errors

```
ModuleNotFoundError: No module named 'pulumi_awsx'
```
cause The `pulumi-awsx` library is not installed in your Python environment.

fix Run `pip install pulumi_awsx` to install the library.
```
AttributeError: module 'pulumi_awsx.ec2' has no attribute 'Vpc'
```
cause You might be trying to access a component that doesn't exist under that name, or there's a typo, or the component signature has changed in a major version upgrade.

fix Double-check the Pulumi AWSX documentation for the correct component name and usage. Ensure your `pulumi-awsx` version is compatible with the code you are running. For VPC, it's `awsx.ec2.Vpc`.
```
pulumi:up failed with an unhandled exception: awsx:ec2/vpc:Vpc 'my-vpc' failed to update: Input 'cidrBlock' cannot be empty.
```
cause A required input property for the `Vpc` component, such as `cidr_block`, was not provided or was passed an empty/null value.

fix Review the component's required inputs in the Pulumi documentation and ensure all mandatory arguments are provided with valid values. For `Vpc`, ensure `cidr_block` is a valid CIDR string (e.g., '10.0.0.0/16').
```
TypeError: Expected argument of type pulumi.Input[str] but received argument of type pulumi.Input[Sequence[str]] for property 'advancedEventSelectors'
```
cause This error often indicates a type mismatch in resource inputs, commonly occurring after a major version upgrade of `pulumi-awsx` or `pulumi-aws`, where the expected type of a property has changed (e.g., from a single string to a list of strings).

fix Consult the changelog for the `pulumi-awsx` and `pulumi-aws` versions you are using, especially for `v3.0.0` or `v7.0.0` of `pulumi-aws`. Adjust the input argument to match the new expected type (e.g., wrap a single value in a list if it's now expecting a sequence).

Warnings

breaking Major breaking changes were introduced in `pulumi-awsx` v3.0.0, primarily due to its dependency on `pulumi-aws` v7.0.0. These changes affected resource input types and schemas across various components (e.g., `cloudtrail:Trail`, `ec2:Vpc`).
Fix: Review the `pulumi-aws` v7.0.0 upgrade guide and corresponding `pulumi-awsx` changelog. Update your Pulumi code to match the new schema and input types. Use `pulumi preview` carefully to identify specific changes.
gotcha `pulumi-awsx` is built on `pulumi-aws`. Mismatched versions between `pulumi-awsx` and `pulumi-aws` (e.g., `pulumi-awsx` expecting `pulumi-aws` v7.x but `pulumi-aws` v6.x is installed) can lead to unexpected runtime errors or incorrect resource provisioning.
Fix: Always install the latest versions of both `pulumi-awsx` and `pulumi-aws` together. Regularly run `pip freeze` or check `requirements.txt` to ensure compatible dependency versions. Refer to the `pulumi-awsx` changelog for specific `pulumi-aws` version dependencies.
gotcha Pulumi automatically generates names for resources if not explicitly provided, often appending a random suffix for uniqueness. While convenient, this can lead to hard-to-track resource names in complex projects or unexpected resource recreation if the base name changes.
Fix: For critical or long-lived resources, explicitly provide `name` or `resource_name` arguments to ensure consistent, predictable naming. Be aware of naming conventions for resources that must be globally unique.
deprecated As `pulumi-awsx` evolves, certain patterns or older resource properties might be deprecated in favor of newer, more robust abstractions. Using deprecated features can lead to warnings or unexpected behavior in future versions.
Fix: Pay attention to `pulumi up` warnings and documentation updates. Migrate code to use the recommended, up-to-date component properties and patterns as they are introduced.

Install

pip install pulumi_awsx Install pulumi-awsx

Imports

ec2
wrong:
```
from pulumi_aws.ec2 import Vpc
```
correct:
```
from pulumi_awsx import ec2
```
Pulumi AWSX (pulumi_awsx) is a separate component library from the base AWS provider (pulumi_aws). Components are typically accessed via the top-level `pulumi_awsx` package.
ecs
wrong:
```
from pulumi_aws.ecs import Cluster
```
correct:
```
from pulumi_awsx import ecs
```
Ensure you are importing from `pulumi_awsx` for the high-level components.
lb
wrong:
```
from pulumi_aws.lb import LoadBalancer
```
correct:
```
from pulumi_awsx import lb
```
Use the `pulumi_awsx.lb` module for simplified load balancer components.

Quickstart

This quickstart demonstrates how to create a complete AWS Virtual Private Cloud (VPC) with public and private subnets across multiple availability zones using the `pulumi-awsx.ec2.Vpc` component. This component handles the creation of all necessary networking resources like internet gateways, NAT gateways, route tables, and subnet associations automatically. To run, ensure AWS credentials and region are configured for your Pulumi project.

import pulumi
import pulumi_awsx as awsx
import os

# Pulumi requires AWS credentials and a region to be configured.
# This can be done via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION)
# or Pulumi configuration (pulumi config set aws:region us-east-1).
# For demonstration, ensure credentials are set up in your environment.
aws_region = os.environ.get('AWS_REGION', 'us-east-1') # Default to us-east-1 if not set

# Create an AWS VPC using pulumi-awsx.ec2.Vpc component.
# This component simplifies creating a VPC with public, private, and isolated subnets
# across multiple availability zones automatically.
my_vpc = awsx.ec2.Vpc("my-awsx-vpc",
                   cidr_block="10.0.0.0/16",
                   number_of_availability_zones=2, # Specify number of AZs
                   tags={
                       "Project": "PulumiAWSXQuickstart",
                       "ManagedBy": "Pulumi"
                   })

# Export the VPC ID and the IDs of its public and private subnets.
pulumi.export("vpc_id", my_vpc.vpc_id)
pulumi.export("public_subnet_ids", my_vpc.public_subnet_ids)
pulumi.export("private_subnet_ids", my_vpc.private_subnet_ids)

view raw JSON →