Pulumi Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Pulumi integration in nx-extend is a dedicated Nx plugin (@nx-extend/pulumi) that allows you to manage Infrastructure as Code (IaC) within an Nx workspace. It provides a structured way to deploy, preview, and manage cloud resources using the Pulumi CLI directly through Nx executors.
This integration supports major cloud providers including AWS, Azure, and Google Cloud Platform (GCP). It abstracts the Pulumi CLI commands into Nx targets, enabling consistent infrastructure management alongside application code.
Sources: packages/pulumi/README.md:1-12, packages/pulumi/src/generators/init/schema.json:30-53, README.md:1-15
Core Features and Architecture
The integration relies on the Pulumi CLI being installed on the host system. It bridges Nx project configurations with Pulumi's stack-based deployment model.
Functional Components
- Initialization Generator: Automates the setup of new Pulumi projects within the Nx workspace.
- Resource Executors: Map standard Pulumi operations (
up,preview,refresh,import) to Nx tasks. - Configuration Manager: Provides tools to set stack-specific configuration variables and secrets.
Sources: packages/pulumi/README.md:14-25, packages/pulumi/src/generators/init/init.impl.ts:121-160
System Workflow
The following diagram illustrates the initialization and execution flow of a Pulumi project within the Nx environment.
The initialization process ensures the project environment is sanitized by removing standard Pulumi files (like .gitignore or package.json in the sub-directory) and relocating index.ts to pulumi.ts to fit the Nx library structure.
Sources: packages/pulumi/src/generators/init/init.impl.ts:44-59, packages/pulumi/src/generators/init/init.impl.ts:100-119
Initialization and Project Setup
You initialize the Pulumi integration using the init generator. This generator performs several critical setup steps to integrate a standard Pulumi project into the Nx workspace hierarchy.
Setup Steps
- Template Selection: Selects a cloud-specific template based on the provider (AWS, Azure, or GCP).
- Project Generation: Runs
pulumi new --generate-onlyto create the scaffolding in the specified project root. - Authentication: Executes
pulumi loginif a login URL or file path is provided. - Dependency Synchronization: Reads the generated Pulumi
package.jsonand adds those dependencies to the root workspacepackage.json. - File Normalization: Moves the entry point to
pulumi.tsand deletes redundant configuration files to prevent conflict with Nx workspace roots.
Sources: packages/pulumi/src/generators/init/init.impl.ts:44-119, packages/pulumi/src/generators/init/schema.json:1-55
Generator Configuration Options
| Option | Type | Description |
|---|---|---|
name | string | The name of the Pulumi project. |
provider | string | The cloud provider (aws, azure, gcp). |
directory | string | The directory where the project is placed. |
secretsProvider | string | The Pulumi secrets provider to use. |
login | string | Pulumi login URL or state file path. |
Sources: packages/pulumi/src/generators/init/schema.json:8-53, packages/pulumi/src/generators/init/init.impl.ts:22-26
Executors and Usage
The Pulumi plugin defines several executors that wrap Pulumi CLI operations. Each executor typically accepts a stack and a root directory.
Available Executors
| Executor | Pulumi Command | Description |
|---|---|---|
up | pulumi up | Deploys resources to the target stack. |
preview | pulumi preview | Shows changes that would be made to the stack. |
refresh | pulumi refresh | Syncs the state with actual cloud resources. |
import | pulumi import | Brings existing cloud resources under Pulumi management. |
Sources: packages/pulumi/README.md:33-85, packages/pulumi/src/generators/init/init.impl.ts:133-149
Configuration Management
Deployment specific variables are managed through the nx config interface, which wraps pulumi config set.
# Set a standard variable
nx config <project-name> set --name="region" --value="us-east-1"
# Set a secret variable
nx config <project-name> set --secret --name="api-key" --value="secret-value"
Sources: packages/pulumi/README.md:104-123
Project Dependency and Structure
The Pulumi plugin is structured as an Nx library with specific peer dependencies to ensure compatibility with both Nx and the Pulumi ecosystem.
Package Specifications
- Peer Dependencies: Requires
@nx/devkit(^22.0.0) and@pulumi/pulumi(^3.129.0). - Optional Dependencies: Includes
@pulumi/gcpfor Google Cloud Platform support. - Project Type: Defined as a
librarywithinproject.json.
Sources: packages/pulumi/package.json:15-22, packages/pulumi/project.json:1-10
Build Configuration
The build process uses @nx/js:tsc and includes non-TypeScript assets like generators.json and executors.json to the output directory.
"assets": [
"packages/pulumi/*.md",
{
"input": "./packages/pulumi/src",
"glob": "**/*.!(ts)",
"output": "./src"
}
]
Sources: packages/pulumi/project.json:28-45
Conclusion
The Pulumi integration provides a robust framework for managing cloud infrastructure within an Nx workspace. By centralizing infrastructure commands through Nx executors and synchronizing dependencies at the workspace level, it enables developers to maintain a single source of truth for both application logic and deployment environments. Success of the integration depends on a properly configured Pulumi CLI and the correct selection of cloud providers during the project initialization phase.