Getting Started - Khanh Docs

This guide will help you get up and running with Pulumi Any Terraform providers in minutes.

Prerequisites#

Before you begin, make sure you have:

Node.js 18.0 or later (for TypeScript/JavaScript)
Pulumi CLI 3.190.0 or later
Package Manager: npm, yarn, or pnpm
A Pulumi account (sign up at app.pulumi.com)

Installing Pulumi#

If you don't have Pulumi installed:

# macOSbrew install pulumi/tap/pulumi# Windowschoco install pulumi# Linuxcurl -fsSL https://get.pulumi.com | sh

Verify your installation:

pulumi version

Installation#

Each provider can be installed independently as an npm package.

Using npm#

npm install pulumi-namecheap

Using yarn#

yarn add pulumi-namecheap

Using pnpm#

pnpm add pulumi-namecheap

Creating Your First Project#

1. Initialize a Pulumi Project#

Create a new directory and initialize a Pulumi project:

mkdir my-infrastructurecd my-infrastructurepulumi new typescript

Follow the prompts to set up your project. This creates:

Pulumi.yaml - Project configuration
index.ts - Your infrastructure code
package.json - Node.js dependencies

2. Install a Provider#

Add a provider to your project:

npm install pulumi-namecheap

3. Configure Provider Credentials#

Most providers require API credentials. Configure them using Pulumi config:

# For Namecheappulumi config set namecheap:apiUser YOUR_API_USERpulumi config set namecheap:apiKey YOUR_API_KEY --secretpulumi config set namecheap:userName YOUR_USERNAME

Alternatively, use environment variables:

export NAMECHEAP_API_USER="your-api-user"export NAMECHEAP_API_KEY="your-api-key"export NAMECHEAP_USER_NAME="your-username"

4. Write Your Infrastructure Code#

Edit index.ts to define your infrastructure:

import * as pulumi from "@pulumi/pulumi";import * as namecheap from "pulumi-namecheap";// Create a DNS recordconst wwwRecord = new namecheap.Record("www-record", {    domain: "example.com",    hostname: "www",    type: "A",    address: "192.168.1.1",    ttl: 300,});// Export the record IDexport const recordId = wwwRecord.id;

5. Deploy Your Infrastructure#

Preview and deploy your infrastructure:

# Preview changespulumi preview# Deploy changespulumi up

Pulumi will show you what resources will be created. Type "yes" to proceed.

6. Update and Manage#

To update your infrastructure, modify your code and run pulumi up again:

// Update the IP addressconst wwwRecord = new namecheap.Record("www-record", {    domain: "example.com",    hostname: "www",    type: "A",    address: "192.168.1.2", // Changed    ttl: 300,});

pulumi up

7. Clean Up#

When you're done, destroy your resources:

pulumi destroy

Example: Multi-Resource Deployment#

Here's a more complete example using Better Uptime to set up monitoring:

import * as pulumi from "@pulumi/pulumi";import * as betteruptime from "pulumi-better-uptime";// Create a monitorconst monitor = new betteruptime.Monitor("api-monitor", {    url: "https://api.example.com/health",    monitorType: "status",    checkFrequency: 60, // Check every 60 seconds    confirmationPeriod: 120,    requestTimeout: 30,    recoveryPeriod: 0,    ssl: {        checkExpiry: true,        expiryThreshold: 30,    },    pronounceableName: "API Health Monitor",});// Create an incident policyconst policy = new betteruptime.Policy("critical-policy", {    name: "Critical Alerts",    repeatCount: 3,    repeatDelay: 300,});// Associate monitor with policyconst policyMonitor = new betteruptime.MonitorGroupPolicy("monitor-policy", {    monitorGroupId: monitor.id,    policyId: policy.id,});// Export monitor URLexport const monitorUrl = pulumi.interpolate`https://betteruptime.com/monitors/${monitor.id}`;

Using Multiple Providers#

You can use multiple providers in the same project:

import * as pulumi from "@pulumi/pulumi";import * as namecheap from "pulumi-namecheap";import * as betteruptime from "pulumi-better-uptime";// Domain configurationconst apiRecord = new namecheap.Record("api-record", {    domain: "example.com",    hostname: "api",    type: "A",    address: "192.168.1.100",});// Monitor the domainconst apiMonitor = new betteruptime.Monitor("api-monitor", {    url: pulumi.interpolate`https://api.example.com/health`,    monitorType: "status",    checkFrequency: 60,});export const apiUrl = pulumi.interpolate`https://api.example.com`;export const monitorId = apiMonitor.id;

Configuration Best Practices#

1. Use Pulumi Config for Secrets#

Always use --secret flag for sensitive data:

pulumi config set myProvider:apiKey xyz123 --secret

2. Organize with Stacks#

Use different stacks for different environments:

# Create production stackpulumi stack init productionpulumi config set myProvider:endpoint https://api.production.com# Create staging stackpulumi stack init stagingpulumi config set myProvider:endpoint https://api.staging.com

3. Use Stack References#

Share outputs between stacks:

import * as pulumi from "@pulumi/pulumi";// Reference another stack's outputsconst networkStack = new pulumi.StackReference("my-org/network/production");const vpcId = networkStack.getOutput("vpcId");

Next Steps#

Now that you've created your first infrastructure:

Architecture

Learn how the bridge works internally

Provider Documentation

Explore specific provider features

Contributing

Help improve the project

Troubleshooting

Solve common issues

Common Commands#

Here's a quick reference of Pulumi commands:

Command	Description
`pulumi new`	Create a new project
`pulumi preview`	Preview changes before deploying
`pulumi up`	Deploy infrastructure
`pulumi destroy`	Destroy all resources
`pulumi stack`	Manage stacks
`pulumi config`	Manage configuration
`pulumi state`	Manage state
`pulumi refresh`	Refresh state to match actual resources
`pulumi cancel`	Cancel an in-progress update

Getting Help#

If you run into issues:

Check the Troubleshooting Guide
Review Pulumi Documentation
Search GitHub Issues
Open a new issue with details about your problem