Skip to content

Commit fdb4bfa

Browse files
tgummerercnunciatounblocked[bot]claude
authored
add getting started guide (#20837)
* add getting started guide Add a getting-started guide for `pulumi do` to explain the basic functionality. * fix some code review comments * review comments * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/cli/direct-resource-operations/get-started.md * Update content/docs/iac/cli/direct-resource-operations/get-started.md Co-authored-by: unblocked[bot] <98133410+unblocked[bot]@users.noreply.github.com> * fix trailing whitespace Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VUkFu54qPipYCm1SWywpJu --------- Co-authored-by: Christian Nunciato <c@nunciato.org> Co-authored-by: unblocked[bot] <98133410+unblocked[bot]@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent b82e07f commit fdb4bfa

2 files changed

Lines changed: 185 additions & 0 deletions

File tree

content/docs/iac/cli/direct-resource-operations.md renamed to content/docs/iac/cli/direct-resource-operations/_index.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ aliases:
1919

2020
The `pulumi do` command provides direct operations on cloud resources through the Pulumi CLI without requiring a project, program, or state file. It exposes the full Pulumi provider ecosystem as a CLI, with commands generated dynamically from each provider's schema.
2121

22+
New to `pulumi do`? Follow the [getting started guide](/docs/iac/cli/direct-resource-operations/get-started/) to run your first resource operations in a few minutes.
23+
2224
## Overview
2325

2426
`pulumi do` supports two types of operations:

‎content/docs/iac/cli/direct-resource-operations/get-started.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title_tag: "Get Started with pulumi do | Pulumi CLI"
3+
meta_desc: "Get started with pulumi do: create, query, update, and delete cloud resources directly from the Pulumi CLI without writing a program."
4+
title: Get Started with pulumi do
5+
h1: Get started with pulumi do
6+
menu:
7+
iac:
8+
name: Get Started
9+
parent: iac-cli-do
10+
identifier: iac-cli-do-get-started
11+
weight: 1
12+
---
13+
14+
{{% notes type="info" %}}
15+
`pulumi do` is in **research preview**. The command interface may change based on feedback.
16+
{{% /notes %}}
17+
18+
The `pulumi do` command gives you direct create, read, update, delete, and query access to cloud resources from the terminal. It works with every Pulumi provider, so covers thousands of resource types across every cloud.
19+
20+
This guide takes you from zero to your first resource operations, and shows you what you can do with `pulumi do`.
21+
22+
## Prerequisites
23+
24+
1. [Install the Pulumi CLI](/docs/install/), version 3.257.0 or later. Because `pulumi do` is in research preview and evolving quickly, we recommend the latest version.
25+
1. Credentials for a cloud provider. The examples use AWS, but any [Pulumi provider](/registry/) works the same way.
26+
27+
## Create your first resource
28+
29+
`pulumi do` picks up provider credentials the same way the provider itself does — from standard environment variables and credential files (for AWS, for example, `AWS_PROFILE`, `AWS_REGION`, or `~/.aws/credentials`). You can also pass explicit provider configuration in a file with `--provider-file`.
30+
31+
Create an S3 bucket, giving it a name:
32+
33+
```bash
34+
$ pulumi do aws:s3:Bucket create my-bucket
35+
```
36+
37+
The provider plugin is installed automatically on first use. The CLI shows you the planned changes and asks for confirmation (which can be skipped by passing `--yes`), then creates the bucket:
38+
39+
```
40+
+ aws:s3:Bucket my-bucket created
41+
Outputs:
42+
arn : "arn:aws:s3:::my-bucket-f998a37"
43+
bucket: "my-bucket-f998a37"
44+
id : "my-bucket-f998a37"
45+
...
46+
47+
Created my-bucket (snippet c7901139-b263-4572-9a57-6e393c2eae2c)
48+
```
49+
50+
Note that the bucket name uses the same provider defaults and [auto-naming](/docs/iac/concepts/resources/names/#autonaming) rules as a full Pulumi program.
51+
52+
By default, `pulumi do` runs in stateful mode: the bucket is recorded as a snippet in the state file, and its lifecycle is tracked. You can bypass this tracking by passing the `--stateless` flag.
53+
54+
## Add an object to the bucket
55+
56+
A bucket wouldn't be useful without anything to put into it. Create a bucket object in the bucket.
57+
58+
The object needs to reference the bucket you just created. `pulumi do` auto-assigns every tracked resource an identifier, derived from its name with hyphens converted to underscores — so `my-bucket` becomes `my_bucket`. To check the identifiers Pulumi assigned, run `pulumi do show-resources`:
59+
60+
```bash
61+
$ pulumi do show-resources
62+
63+
NAME URN
64+
my_bucket urn:pulumi:default::default-global-project::aws:s3/bucket:Bucket::my-bucket
65+
```
66+
67+
You can also supply your own identifiers by passing a JSON file that maps identifiers to resource URNs with `--resources-file`; its entries take precedence over the auto-assigned ones.
68+
69+
Inputs can be passed to `pulumi do` either via `--<input>` flags for scalar inputs, or through a YAML formatted file that's passed with `--input-file`. Inside an input file, reference another resource by its identifier with `${...}`. The following example passes the bucket reference through the YAML file, while passing the content through an `--<input>` flag:
70+
71+
```yaml
72+
# object.yaml
73+
bucket: ${my_bucket}
74+
```
75+
76+
```bash
77+
$ pulumi do aws:s3:BucketObject create my-object --input-file object.yaml --content "Hello from pulumi do" --yes
78+
```
79+
80+
```
81+
+ aws:s3:BucketObject my-object created
82+
Outputs:
83+
arn : "arn:aws:s3:::my-bucket-f998a37/my-object"
84+
contentType: "application/octet-stream"
85+
etag : "a7008c67f9dcdd81b4d0bde99ebf21c2"
86+
id : "my-bucket-f998a37/my-object"
87+
...
88+
89+
Created my-object (snippet 08de6783-0957-415d-98f8-e304399a1d09)
90+
```
91+
92+
## Read, update, and delete
93+
94+
Read the current state of any resource by its cloud provider ID, which is shown in the `id` output when the resource is created.
95+
96+
```bash
97+
$ pulumi do aws:s3:Bucket read my-bucket-f998a37
98+
$ pulumi do aws:s3:BucketObject read my-bucket-f998a37/my-object
99+
```
100+
101+
Update a resource with `patch`, which reads the current state, merges your changes, and shows you a diff to confirm. For example, to tag the bucket:
102+
103+
```yaml
104+
# tags.yaml
105+
tags:
106+
environment: dev
107+
```
108+
109+
```bash
110+
$ pulumi do aws:s3:Bucket patch my-bucket --input-file tags.yaml
111+
```
112+
113+
And when you're done, delete both resources by the names you gave them. The object first, because a bucket must be empty before it can be deleted:
114+
115+
```bash
116+
$ pulumi do aws:s3:BucketObject delete my-object --yes
117+
$ pulumi do aws:s3:Bucket delete my-bucket --yes
118+
```
119+
120+
## Explore a provider from the terminal
121+
122+
Every `pulumi do` command addresses a resource or function by its [type token](/docs/iac/concepts/resources/names/#types) in the form `<package:module:type>`. For example, `aws:s3:Bucket` is the `Bucket` resource in the `s3` module of the `aws` package. For single-module packages, you can omit the module segment.
123+
124+
You don't need to know the token up front; you can pass a partial token and `pulumi do` will list what's available at that level:
125+
126+
```bash
127+
$ pulumi do aws:s3
128+
129+
Functions and resources for the s3 module.
130+
131+
Functions:
132+
aws:s3:getBucket
133+
aws:s3:getBucketObject
134+
...
135+
136+
Resources:
137+
aws:s3:AccessPoint
138+
aws:s3:Bucket
139+
...
140+
```
141+
142+
`--help` works at every level of the command tree. On a resource, it shows the available operations plus every input and output with its type and documentation:
143+
144+
```bash
145+
$ pulumi do aws:s3:Bucket --help
146+
```
147+
148+
## Query the cloud with provider functions
149+
150+
Providers also expose read-only functions for querying cloud APIs. You can invoke them directly by name, with inputs as flags or with an optional `--input-file`:
151+
152+
```bash
153+
$ pulumi do aws:ec2:getVpc --default
154+
155+
{
156+
"arn": "arn:aws:ec2:us-west-2:123456789012:vpc/vpc-d7b311af",
157+
"cidrBlock": "172.31.0.0/16",
158+
"enableDnsHostnames": true,
159+
"id": "vpc-d7b311af",
160+
...
161+
}
162+
```
163+
164+
`--default` isn't a `pulumi do` flag — it's the `default` input of `getVpc`, passed with the same `--<input>` form used for resource inputs. When passed as CLI inputs in this way, Boolean values like this one are interpreted as `true`.
165+
166+
## Use it in scripts
167+
168+
Pass `--output json` to get machine-readable output for resource operations, which lets you compose `pulumi do` with tools like `jq`:
169+
170+
```bash
171+
$ pulumi do aws:s3:Bucket create --stateless --yes --output json | jq -r '.id'
172+
bucket-9f7f27f
173+
174+
$ pulumi do aws:s3:Bucket delete bucket-9f7f27f --stateless --yes
175+
```
176+
177+
Keeping this same command shape and output format across all Pulumi providers makes `pulumi do` work especially well for coding agents, too. See [Pulumi CLI for agents](/docs/ai/cli-for-agents/) to learn more.
178+
179+
## Next steps
180+
181+
1. Read the [direct resource operations reference](/docs/iac/cli/direct-resource-operations/) for the full command syntax, flags, and provider configuration options.
182+
1. Browse the [Pulumi Registry](/registry/) to see the providers and resources you can operate on.
183+
1. When it's time to collect the resources you've created with `pulumi do` into a new or existing Pulumi [project](/docs/iac/concepts/projects/), you can import them using their type tokens and resource IDs. See [Importing resources](/docs/iac/guides/migration/import/) to learn more.

0 commit comments

Comments
 (0)