0
# Runtime Operations
1

2
Pulumi's runtime system provides low-level functions for resource registration, serialization, state management, and execution orchestration. These functions are typically used by provider implementations and advanced use cases.
3

4
## Resource Registration
5

6
```typescript { .api }
7
function registerResource(
8
  res: Resource,
9
  type: string,
10
  name: string,
11
  props: Inputs,
12
  opts?: ResourceOptions,
13
  remote?: boolean
14
): Promise<void>;
15

16
function registerResourceOutputs(
17
  res: Resource,
18
  outputs: Inputs | Promise<Inputs> | Output<Inputs> | undefined
19
): void;
20

21
function readResource(
22
  res: Resource,
23
  type: string,
24
  name: string,
25
  props: Inputs,
26
  opts: ResourceOptions,
27
  remote?: boolean
28
): Promise<void>;
29

30
function getResource(
31
  res: Resource,
32
  type: string,
33
  name: string,
34
  props: Inputs,
35
  opts: ResourceOptions
36
): Promise<void>;
37
```
38

39
## Invoke Operations
40

41
```typescript { .api }
42
function invoke(
43
  token: string,
44
  props: Inputs,
45
  opts?: InvokeOptions,
46
  res?: Resource
47
): Promise<any>;
48

49
function invokeOutput(
50
  token: string,
51
  props: Inputs,
52
  opts?: InvokeOutputOptions
53
): Output<any>;
54

55
function invokeSingle(
56
  token: string,
57
  props: Inputs,
58
  opts?: InvokeOptions
59
): Promise<any>;
60

61
function invokeSingleOutput(
62
  token: string,
63
  props: Inputs,
64
  opts?: InvokeOutputOptions
65
): Output<any>;
66

67
function call(
68
  token: string,
69
  props: Inputs,
70
  res?: Resource
71
): Promise<any>;
72

73
function callSingle(
74
  token: string,
75
  props: Inputs,
76
  res?: Resource
77
): Promise<any>;
78
```
79

80
## Invoke Options
81

82
```typescript { .api }
83
interface InvokeOptions {
84
  parent?: Resource;
85
  provider?: ProviderResource;
86
  version?: string;
87
  pluginDownloadURL?: string;
88
  async?: boolean;
89
}
90

91
interface InvokeOutputOptions extends InvokeOptions {
92
  dependsOn?: Input<Input<Resource>[]> | Input<Resource>;
93
}
94
```
95

96
## Configuration Management
97

98
```typescript { .api }
99
function allConfig(): {[key: string]: string};
100
function setAllConfig(c: {[key: string]: string}, secretKeys?: string[]): void;
101
function setConfig(k: string, v: string): void;
102
function getConfig(k: string): string | undefined;
103
function isConfigSecret(k: string): boolean;
104
```
105

106
## State Management
107

108
```typescript { .api }
109
function getStackResource(): Stack | undefined;
110
function setStackResource(newStackResource?: Stack): void;
111
function getStore(): Map<any, any>;
112
function getLocalStore(): Map<any, any>;
113
function getGlobalStore(): Map<any, any>;
114
```
115

116
## Runtime Settings
117

118
```typescript { .api }
119
function isDryRun(): boolean;
120
function getProject(): string;
121
function getStack(): string;
122
function getOrganization(): string;
123
function getRootDirectory(): string;
124
function hasMonitor(): boolean;
125
function getMonitor(): any;
126
function hasEngine(): boolean;
127
function getEngine(): any;
128
```
129

130
## Serialization System
131

132
```typescript { .api }
133
function serializeResourceProperties(
134
  label: string,
135
  props: Inputs,
136
  opts?: SerializationOptions
137
): Promise<any>;
138

139
function serializeProperties(
140
  label: string,
141
  props: Inputs,
142
  opts?: SerializationOptions
143
): Promise<any>;
144

145
function deserializeProperties(
146
  outputsStruct: any,
147
  keepUnknowns?: boolean
148
): any;
149

150
function serializeProperty(
151
  prop: Input<any>,
152
  labels: Set<Resource>,
153
  dependsOn: Resource[],
154
  secret: boolean,
155
  opts?: SerializationOptions
156
): any;
157

158
function deserializeProperty(prop: any, keepUnknowns?: boolean): any;
159

160
interface SerializationOptions {
161
  keepOutputValues?: boolean;
162
  keepSecrets?: boolean;
163
  keepResources?: boolean;
164
}
165
```
166

167
## Mocking System
168

169
```typescript { .api }
170
function setMocks(
171
  mocks: Mocks,
172
  project?: string,
173
  stack?: string,
174
  preview?: boolean
175
): void;
176

177
interface Mocks {
178
  newResource?: (args: MockResourceArgs) => MockResourceResult;
179
  call?: (args: MockCallArgs) => MockCallResult;
180
}
181

182
interface MockResourceArgs {
183
  type: string;
184
  name: string;
185
  inputs: any;
186
  provider?: string;
187
  id?: string;
188
}
189

190
interface MockResourceResult {
191
  id?: string;
192
  state?: any;
193
}
194

195
interface MockCallArgs {
196
  token: string;
197
  inputs: any;
198
  provider?: string;
199
}
200

201
interface MockCallResult {
202
  result?: any;
203
}
204

205
class MockMonitor {
206
  // Mock implementation for testing
207
}
208
```
209

210
## Closure Serialization
211

212
```typescript { .api }
213
function serializeFunction(func: Function, args?: any): Promise<string>;
214
function serializeFunctionAsync(func: Function, serialize?: boolean): Promise<string>;
215
function computeCodePaths(options?: any): Promise<string[]>;
216
```
217

218
## Constants and Utilities
219

220
```typescript { .api }
221
const unknownValue: any;
222
const specialSigKey: string;
223
const specialAssetSig: string;
224
const specialArchiveSig: string;
225
const specialSecretSig: string;
226
const specialResourceSig: string;
227
const specialOutputValueSig: string;
228
```
229

230
## Usage Examples
231

232
### Custom Resource Implementation
233

234
```typescript
235
import * as pulumi from "@pulumi/pulumi";
236
import * as runtime from "@pulumi/pulumi/runtime";
237

238
class CustomS3Bucket extends pulumi.CustomResource {
239
  public readonly bucketName!: pulumi.Output<string>;
240
  public readonly arn!: pulumi.Output<string>;
241

242
  constructor(name: string, args: S3BucketArgs, opts?: pulumi.CustomResourceOptions) {
243
    const props: any = {
244
      bucketName: args.bucketName,
245
      region: args.region,
246
    };
247

248
    super("custom:s3:Bucket", name, props, opts);
249
  }
250
}
251

252
interface S3BucketArgs {
253
  bucketName?: pulumi.Input<string>;
254
  region?: pulumi.Input<string>;
255
}
256

257
// Register the resource
258
runtime.registerResource(
259
  new CustomS3Bucket("my-bucket", { bucketName: "my-custom-bucket" }),
260
  "custom:s3:Bucket",
261
  "my-bucket",
262
  { bucketName: "my-custom-bucket" }
263
);
264
```
265

266
### Invoke Function Usage
267

268
```typescript
269
import * as runtime from "@pulumi/pulumi/runtime";
270

271
// Invoke a provider function
272
const result = await runtime.invoke("aws:s3/getBucket:getBucket", {
273
  bucket: "my-bucket-name",
274
});
275

276
console.log("Bucket region:", result.region);
277

278
// Invoke with Output result
279
const bucketInfo = runtime.invokeOutput("aws:s3/getBucket:getBucket", {
280
  bucket: pulumi.output("my-bucket-name"),
281
});
282

283
export const bucketRegion = bucketInfo.region;
284
```
285

286
### Configuration Access
287

288
```typescript
289
import * as runtime from "@pulumi/pulumi/runtime";
290

291
// Get all configuration
292
const allConfig = runtime.allConfig();
293
console.log("All config:", allConfig);
294

295
// Set configuration programmatically
296
runtime.setConfig("myapp:environment", "production");
297
runtime.setConfig("myapp:debug", "false");
298

299
// Check if config is secret
300
if (runtime.isConfigSecret("myapp:apiKey")) {
301
  console.log("API key is stored as secret");
302
}
303
```
304

305
### Testing with Mocks
306

307
```typescript
308
import * as runtime from "@pulumi/pulumi/runtime";
309

310
// Set up mocks for testing
311
runtime.setMocks({
312
  newResource: (args) => {
313
    switch (args.type) {
314
      case "aws:s3/bucket:Bucket":
315
        return {
316
          id: `${args.name}-id`,
317
          state: {
318
            bucket: args.inputs.bucket || `${args.name}-bucket`,
319
            arn: `arn:aws:s3:::${args.inputs.bucket || args.name}`,
320
          },
321
        };
322
      default:
323
        return { id: `${args.name}-id`, state: args.inputs };
324
    }
325
  },
326
  call: (args) => {
327
    switch (args.token) {
328
      case "aws:index/getRegion:getRegion":
329
        return { result: { name: "us-east-1" } };
330
      default:
331
        return { result: {} };
332
    }
333
  },
334
}, "test-project", "test-stack", false);
335

336
// Now create resources - they will use mocks
337
const bucket = new aws.s3.Bucket("test-bucket", {
338
  bucket: "test-bucket-name",
339
});
340

341
// Test assertions
342
bucket.id.apply(id => {
343
  console.assert(id === "test-bucket-id", "Expected mocked ID");
344
});
345
```
346

347
### Serialization Examples
348

349
```typescript
350
import * as runtime from "@pulumi/pulumi/runtime";
351

352
// Serialize resource properties
353
const serialized = await runtime.serializeProperties("test", {
354
  name: "my-resource",
355
  count: pulumi.output(5),
356
  config: {
357
    enabled: true,
358
    tags: ["prod", "web"],
359
  },
360
});
361

362
console.log("Serialized properties:", serialized);
363

364
// Deserialize properties
365
const deserialized = runtime.deserializeProperties({
366
  name: "my-resource",
367
  count: { sig: "cGx1bWk6c3RhY2s=", value: 5 },
368
});
369

370
console.log("Deserialized properties:", deserialized);
371
```
372

373
### State Management
374

375
```typescript
376
import * as runtime from "@pulumi/pulumi/runtime";
377

378
// Access runtime state
379
const stackResource = runtime.getStackResource();
380
if (stackResource) {
381
  console.log("Stack resource available");
382
}
383

384
// Use runtime stores for caching
385
const globalStore = runtime.getGlobalStore();
386
globalStore.set("cached-value", { timestamp: Date.now(), data: "value" });
387

388
const cachedValue = globalStore.get("cached-value");
389
console.log("Cached value:", cachedValue);
390

391
// Check runtime mode
392
if (runtime.isDryRun()) {
393
  console.log("Running in preview mode");
394
} else {
395
  console.log("Running actual deployment");
396
}
397
```
398

399
### Function Serialization
400

401
```typescript
402
import * as runtime from "@pulumi/pulumi/runtime";
403

404
// Serialize function for remote execution
405
const handler = async (event: any) => {
406
  console.log("Processing event:", event);
407
  return { statusCode: 200, body: "Hello World" };
408
};
409

410
const serializedFunction = await runtime.serializeFunction(handler, {
411
  dependencies: ["some-module"],
412
});
413

414
console.log("Serialized function:", serializedFunction);
415

416
// Compute code paths for packaging
417
const codePaths = await runtime.computeCodePaths({
418
  excludePackages: ["aws-sdk"],
419
});
420

421
console.log("Code paths to include:", codePaths);
422
```
423

424
## Best Practices
425

426
- Use runtime functions primarily in provider implementations
427
- Handle serialization errors gracefully
428
- Use mocks extensively for unit testing
429
- Cache expensive serialization operations when possible
430
- Be careful with direct state manipulation functions
431
- Use appropriate serialization options for your use case
432
- Test function serialization thoroughly before deployment
433
- Monitor runtime performance in production
434
- Use configuration functions for dynamic provider configuration
435
- Implement proper error handling for invoke operations
436
- Use type assertions when deserializing properties
437
- Clean up stores and caches appropriately