Module runtime
Modules
Resources
Others
- allConfig
- cacheDynamicProviders
- call
- deserializeProperties
- deserializeProperty
- disconnect
- disconnectSync
- excessiveDebugOutput
- getConfig
- getEngine
- getMaximumListeners
- getMonitor
- getOrganization
- getProject
- getResource
- getResourceModule
- getResourcePackage
- getStack
- getStackResource
- hasEngine
- hasMonitor
- invoke
- invokeSingle
- isDryRun
- isLegacyApplyEnabled
- isQueryMode
- isRpcSecret
- listResourceOutputs
- MockCallArgs
- MockCallResult
- MockMonitor
- MockResourceArgs
- MockResourceResult
- Mocks
- monitorSupportsDeletedWith
- monitorSupportsFeature
- monitorSupportsOutputValues
- monitorSupportsResourceReferences
- monitorSupportsSecrets
- Options
- OutputResolvers
- readResource
- registerResource
- registerResourceModule
- registerResourceOutputs
- registerResourcePackage
- registerStackTransformation
- resetOptions
- resolveProperties
- ResourceModule
- ResourcePackage
- rootPulumiStackTypeName
- rpcKeepAlive
- runInPulumiStack
- SerializationOptions
- serialize
- serializeProperties
- serializeProperty
- serializeResourceProperties
- setAllConfig
- setConfig
- setMockOptions
- setMocks
- setRootResource
- SourcePosition
- specialArchiveSig
- specialAssetSig
- specialOutputValueSig
- specialResourceSig
- specialSecretSig
- specialSigKey
- streamInvoke
- StreamInvokeResponse
- suppressUnhandledGrpcRejections
- terminateRpcs
- transferProperties
- unknownValue
- unwrapRpcSecret
Resources
Resource Stack
class Stack extends ComponentResource<Inputs>
Stack is the root resource for a Pulumi stack. Before invoking the init
callback, it registers itself as the root
resource with the Pulumi engine.
constructor
new Stack(init: () => Promise<Inputs>)
method getData
protected getData(): Promise<Inputs>
Retrieves the data produces by [initialize]. The data is immediately available in a
derived class’s constructor after the super(...)
call to ComponentResource
.
method getProvider
public getProvider(moduleMember: string): ProviderResource | undefined
method initialize
initialize(args: {
init: () => Promise<Inputs>;
}): Promise<Inputs>
runInit invokes the given init callback with this resource set as the root resource. The return value of init is used as the stack’s output properties.
method isInstance
public static isInstance(obj: any): obj is ComponentResource
Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.
method registerOutputs
protected registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void
registerOutputs registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.
ComponentResources can call this at the end of their constructor to indicate that they are
done creating child resources. This is not strictly necessary as this will automatically be
called after the initialize
method completes.
property outputs
public outputs: Output<Inputs>;
The outputs of this stack, if the init
callback exited normally.
property urn
public urn: Output<URN>;
urn is the stable logical URN used to distinctly address a resource, both before and after deployments.
Others
function allConfig
allConfig(): {[key: string]: string}
allConfig returns a copy of the full config map.
function cacheDynamicProviders
cacheDynamicProviders(): boolean
Returns true (default) if we will cache serialized dynamic providers on the program side
function call
call<T>(tok: string, props: Inputs, res?: Resource): Output<T>
call
dynamically calls the function, tok
, which is offered by a provider plugin.
function deserializeProperties
deserializeProperties(outputsStruct: any): any
deserializeProperties fetches the raw outputs and deserializes them from a gRPC call result.
function deserializeProperty
deserializeProperty(prop: any): any
deserializeProperty unpacks some special types, reversing the above process.
function disconnect
disconnect(): Promise<void>
disconnect permanently disconnects from the server, closing the connections. It waits for the existing RPC queue to drain. If any RPCs come in afterwards, however, they will crash the process.
function disconnectSync
disconnectSync(): void
disconnectSync permanently disconnects from the server, closing the connections. Unlike disconnect
. it does not
wait for the existing RPC queue to drain. Any RPCs that come in after this call will crash the process.
const excessiveDebugOutput
const excessiveDebugOutput: boolean = false;
excessiveDebugOutput enables, well, pretty excessive debug output pertaining to resources and properties.
function getConfig
getConfig(k: string): string | undefined
getConfig returns a configuration variable’s value or undefined if it is unset.
function getEngine
getEngine(): Object | undefined
getEngine returns the current engine, if any, for RPC communications back to the resource engine.
function getMaximumListeners
getMaximumListeners(): number
getMaximumListeners returns the configured number of process listeners available
function getMonitor
getMonitor(): Object | undefined
getMonitor returns the current resource monitoring service client for RPC communications.
function getOrganization
getOrganization(): string
Get the organization being run by the current update.
function getProject
getProject(): string
Get the project being run by the current update.
function getResource
getResource(res: Resource, parent: Resource | undefined, props: Inputs, custom: boolean, urn: string): void
Get an existing resource’s state from the engine.
function getResourceModule
getResourceModule(pkg: string, mod: string, version: string): ResourceModule | undefined
function getResourcePackage
getResourcePackage(pkg: string, version: string): ResourcePackage | undefined
function getStack
getStack(): string
Get the stack being targeted by the current update.
function getStackResource
getStackResource(): Stack | undefined
function hasEngine
hasEngine(): boolean
hasEngine returns true if we are currently connected to an engine.
function hasMonitor
hasMonitor(): boolean
hasMonitor returns true if we are currently connected to a resource monitoring service.
function invoke
invoke(tok: string, props: Inputs, opts: InvokeOptions): Promise<any>
invoke
dynamically invokes the function, tok
, which is offered by a provider plugin. invoke
behaves differently in the case that options contains {async:true}
or not.
In the case where {async:true}
is present in the options bag:
- the result of
invoke
will be a Promise resolved to the result value of the provider plugin. - the
props
inputs can be a bag of computed values (including,T
s,Promise<T>
s,Output<T>
s etc.).
In the case where {async:true}
is not present in the options bag:
the result of
invoke
will be a Promise resolved to the result value of the provider call. However, that Promise will also have the respective values of the Provider result exposed directly on it as properties.The inputs must be a bag of simple values, and the result is the result that the Provider produced.
Simple values are:
undefined
,null
, string, number or boolean values.- arrays of simple values.
- objects containing only simple values.
Importantly, simple values do not include:
Promise
sOutput
sAsset
s orArchive
sResource
s.
All of these contain async values that would prevent `invoke from being able to operate synchronously.
function invokeSingle
invokeSingle(tok: string, props: Inputs, opts: InvokeOptions): Promise<any>
function isDryRun
isDryRun(): boolean
Returns whether or not we are currently doing a preview.
When writing unit tests, you can set this flag via either setMocks
or _setIsDryRun
.
function isLegacyApplyEnabled
isLegacyApplyEnabled(): boolean
Returns true if we will resolve missing outputs to inputs during preview (PULUMI_ENABLE_LEGACY_APPLY).
function isQueryMode
isQueryMode(): boolean
Returns true if query mode is enabled.
function isRpcSecret
isRpcSecret(obj: any): boolean
isRpcSecret returns true if obj is a wrapped secret value (i.e. it’s an object with the special key set).
function listResourceOutputs
listResourceOutputs<U>(typeFilter?: undefined | (o: any) => boolean, stackName?: undefined | string): AsyncQueryable<ResolvedResource<U>>
listResourceOutputs returns the resource outputs (if any) for a stack, or an error if the stack cannot be found. Resources are retrieved from the latest stack snapshot, which may include ongoing updates.
interface MockCallArgs
interface MockCallArgs
MockResourceArgs is used to construct call Mock.
property inputs
inputs: any;
The arguments provided to the function call.
property provider
provider?: undefined | string;
If provided, the identifier of the provider instance being used to make the call.
property token
token: string;
The token that indicates which function is being called. This token is of the form “package:module:function”.
type MockCallResult
type MockCallResult = Record<string, any>;
MockCallResult is the result of a call Mock.
class MockMonitor
class MockMonitor
constructor
new MockMonitor(mocks: Mocks)
method invoke
public invoke(req: any, callback: (err: any, innerResponse: any) => void): Promise<void>
method readResource
public readResource(req: any, callback: (err: any, innterResponse: any) => void): Promise<void>
method registerResource
public registerResource(req: any, callback: (err: any, innerResponse: any) => void): Promise<void>
method registerResourceOutputs
public registerResourceOutputs(req: any, callback: (err: any, innerResponse: any) => void): void
method supportsFeature
public supportsFeature(req: any, callback: (err: any, innerResponse: any) => void): void
property mocks
mocks: Mocks;
property resources
resources: Map<string, {
id: string | null;
state: any;
urn: string;
}> = new Map<string, { urn: string; id: string | null; state: any }>();
interface MockResourceArgs
interface MockResourceArgs
MockResourceArgs is used to construct a newResource Mock.
property custom
custom?: undefined | false | true;
Specifies whether or not the resource is Custom (i.e. managed by a resource provider).
property id
id?: undefined | string;
If provided, the physical identifier of an existing resource to read or import.
property inputs
inputs: any;
The inputs for the resource.
property name
name: string;
The logical name of the resource instance.
property provider
provider?: undefined | string;
If provided, the identifier of the provider instance being used to manage this resource.
property type
type: string;
The token that indicates which resource type is being constructed. This token is of the form “package:module:type”.
type MockResourceResult
type MockResourceResult = {
id: string | undefined;
state: Record<string, any>;
};
MockResourceResult is the result of a newResource Mock, returning a physical identifier and the output properties for the resource being constructed.
interface Mocks
interface Mocks
Mocks allows implementations to replace operations normally implemented by the Pulumi engine with their own implementations. This can be used during testing to ensure that calls to provider functions and resource constructors return predictable values.
method call
call(args: MockCallArgs): MockCallResult | Promise<MockCallResult>
Mocks provider-implemented function calls (e.g. aws.get_availability_zones).
method newResource
newResource(args: MockResourceArgs): MockResourceResult | Promise<MockResourceResult>
Mocks resource construction calls. This function should return the physical identifier and the output properties for the resource being constructed.
function monitorSupportsDeletedWith
monitorSupportsDeletedWith(): Promise<boolean>
monitorSupportsDeletedWith returns a promise that when resolved tells you if the resource monitor we are connected to is able to support the deletedWith resource option across its RPC interface.
function monitorSupportsFeature
monitorSupportsFeature(feature: string): Promise<boolean>
monitorSupportsFeature returns a promise that when resolved tells you if the resource monitor we are connected to is able to support a particular feature.
function monitorSupportsOutputValues
monitorSupportsOutputValues(): Promise<boolean>
monitorSupportsOutputValues returns a promise that when resolved tells you if the resource monitor we are connected to is able to support output values across its RPC interface. When it does, we marshal outputs in a special way.
function monitorSupportsResourceReferences
monitorSupportsResourceReferences(): Promise<boolean>
monitorSupportsResourceReferences returns a promise that when resolved tells you if the resource monitor we are connected to is able to support resource references across its RPC interface. When it does, we marshal resources in a special way.
function monitorSupportsSecrets
monitorSupportsSecrets(): Promise<boolean>
monitorSupportsSecrets returns a promise that when resolved tells you if the resource monitor we are connected to is able to support secrets across its RPC interface. When it does, we marshal outputs marked with the secret bit in a special way.
interface Options
interface Options
Options is a bag of settings that controls the behavior of previews and deployments
property cacheDynamicProviders
cacheDynamicProviders?: undefined | false | true;
property dryRun
dryRun?: undefined | false | true;
property engineAddr
engineAddr?: undefined | string;
property legacyApply
legacyApply?: undefined | false | true;
property monitorAddr
monitorAddr?: undefined | string;
property organization
organization?: undefined | string;
property parallel
parallel?: undefined | number;
property project
project?: undefined | string;
property queryMode
queryMode?: undefined | false | true;
property stack
stack?: undefined | string;
property syncDir
syncDir?: undefined | string;
Directory containing the send/receive files for making synchronous invokes to the engine.
property testModeEnabled
testModeEnabled?: undefined | false | true;
type OutputResolvers
type OutputResolvers = Record<string, (value: any, isStable: boolean, isSecret: boolean, deps?: Resource[], err?: Error) => void>;
function readResource
readResource(res: Resource, parent: Resource | undefined, t: string, name: string, props: Inputs, opts: ResourceOptions, sourcePosition?: SourcePosition): void
Reads an existing custom resource’s state from the resource monitor. Note that resources read in this way will not be part of the resulting stack’s state, as they are presumed to belong to another.
function registerResource
registerResource(res: Resource, parent: Resource | undefined, t: string, name: string, custom: boolean, remote: boolean, newDependency: (urn: URN) => Resource, props: Inputs, opts: ResourceOptions, sourcePosition?: SourcePosition): void
registerResource registers a new resource object with a given type t and name. It returns the auto-generated URN and the ID that will resolve after the deployment has completed. All properties will be initialized to property objects that the registration operation will resolve at the right time (or remain unresolved for deployments).
function registerResourceModule
registerResourceModule(pkg: string, mod: string, module: ResourceModule): void
registerResourceModule registers a resource module that will be used to construct resources for any URNs matching the module name and version that are deserialized by the current instance of the Pulumi JavaScript SDK.
function registerResourceOutputs
registerResourceOutputs(res: Resource, outputs: Inputs | Promise<Inputs> | Output<Inputs>): void
registerResourceOutputs completes the resource registration, attaching an optional set of computed outputs.
function registerResourcePackage
registerResourcePackage(pkg: string, resourcePackage: ResourcePackage): void
registerResourcePackage registers a resource package that will be used to construct providers for any URNs matching the package name and version that are deserialized by the current instance of the Pulumi JavaScript SDK.
function registerStackTransformation
registerStackTransformation(t: ResourceTransformation): void
Add a transformation to all future resources constructed in this Pulumi stack.
function resetOptions
resetOptions(project: string, stack: string, parallel: number, engineAddr: string, monitorAddr: string, preview: boolean, organization: string): void
function resolveProperties
resolveProperties(res: Resource, resolvers: Record<string, (v: any, isKnown: boolean, isSecret: boolean, deps?: Resource[], err?: Error) => void>, t: string, name: string, allProps: any, deps: Record<string, Resource[]>, err?: Error): void
resolveProperties takes as input a gRPC serialized proto.google.protobuf.Struct and resolves all of the resource’s matching properties to the values inside.
NOTE: it is imperative that the properties in allProps
were produced by deserializeProperties
in order for
output properties to work correctly w.r.t. knowns/unknowns: this function assumes that any undefined value in
allProps
represents an unknown value that was returned by an engine operation.
interface ResourceModule
interface ResourceModule
A ResourceModule is a type that understands how to construct resources given a name, type, args, and URN.
method construct
construct(name: string, type: string, urn: string): Resource
property version
version?: undefined | string;
interface ResourcePackage
interface ResourcePackage
A ResourcePackage is a type that understands how to construct resource providers given a name, type, args, and URN.
method constructProvider
constructProvider(name: string, type: string, urn: string): ProviderResource
property version
version?: undefined | string;
const rootPulumiStackTypeName
const rootPulumiStackTypeName: "pulumi:pulumi:Stack" = "pulumi:pulumi:Stack";
rootPulumiStackTypeName is the type name that should be used to construct the root component in the tree of Pulumi
resources allocated by a deployment. This must be kept up to date with
github.com/pulumi/pulumi/sdk/v3/go/common/resource/stack.RootStackType
.
function rpcKeepAlive
rpcKeepAlive(): () => void
rpcKeepAlive registers a pending call to ensure that we don’t prematurely disconnect from the server. It returns a function that, when invoked, signals that the RPC has completed.
function runInPulumiStack
runInPulumiStack(init: () => Promise<any>): Promise<Inputs | undefined>
runInPulumiStack creates a new Pulumi stack resource and executes the callback inside of it. Any outputs returned by the callback will be stored as output properties on this resulting Stack object.
interface SerializationOptions
interface SerializationOptions
Controls the serialization of RPC structures.
property keepOutputValues
keepOutputValues?: undefined | false | true;
true if we are keeping output values. If the monitor does not support output values, they will not be kept, even when this is set to true.
function serialize
serialize(): boolean
serialize returns true if resource operations should be serialized.
function serializeProperties
serializeProperties(label: string, props: Inputs, opts?: SerializationOptions): Promise<Record<string, any>>
serializeProperties walks the props object passed in, awaiting all interior promises, creating a reasonable POJO object that can be remoted over to registerResource.
function serializeProperty
serializeProperty(ctx: string, prop: Input<any>, dependentResources: Set<Resource>, opts?: SerializationOptions): Promise<any>
serializeProperty serializes properties deeply. This understands how to wait on any unresolved promises, as appropriate, in addition to translating certain “special” values so that they are ready to go on the wire.
function serializeResourceProperties
serializeResourceProperties(label: string, props: Inputs, opts?: SerializationOptions): Promise<[, Record<string, any>, Map<string, Set<Resource>>]>
serializeResourceProperties walks the props object passed in, awaiting all interior promises besides those for id
and urn
, creating a reasonable POJO object that can be remoted over to registerResource.
function setAllConfig
setAllConfig(c: {[key: string]: string}, secretKeys?: string[]): void
setAllConfig overwrites the config map.
function setConfig
setConfig(k: string, v: string): void
setConfig sets a configuration variable.
function setMockOptions
setMockOptions(mockMonitor: any, project?: undefined | string, stack?: undefined | string, preview?: undefined | false | true, organization?: undefined | string): void
function setMocks
setMocks(mocks: Mocks, project?: undefined | string, stack?: undefined | string, preview?: undefined | false | true, organization?: undefined | string): void
setMocks configures the Pulumi runtime to use the given mocks for testing.
function setRootResource
setRootResource(res: ComponentResource): Promise<void>
setRootResource registers a resource that will become the default parent for all resources without explicit parents.
interface SourcePosition
interface SourcePosition
property column
column: number;
property line
line: number;
property uri
uri: string;
const specialArchiveSig
const specialArchiveSig: "0def7320c3a5731c473e5ecbe6d01bc7" = "0def7320c3a5731c473e5ecbe6d01bc7";
specialArchiveSig is a randomly assigned hash used to identify archives in maps. See sdk/go/common/resource/asset.go.
const specialAssetSig
const specialAssetSig: "c44067f5952c0a294b673a41bacd8c17" = "c44067f5952c0a294b673a41bacd8c17";
specialAssetSig is a randomly assigned hash used to identify assets in maps. See sdk/go/common/resource/asset.go.
const specialOutputValueSig
const specialOutputValueSig: "d0e6a833031e9bbcd3f4e8bde6ca49a4" = "d0e6a833031e9bbcd3f4e8bde6ca49a4";
specialOutputValueSig is a randomly assigned hash used to identify outputs in maps. See sdk/go/common/resource/properties.go.
const specialResourceSig
const specialResourceSig: "5cf8f73096256a8f31e491e813e4eb8e" = "5cf8f73096256a8f31e491e813e4eb8e";
specialResourceSig is a randomly assigned hash used to identify resources in maps. See sdk/go/common/resource/properties.go.
const specialSecretSig
const specialSecretSig: "1b47061264138c4ac30d75fd1eb44270" = "1b47061264138c4ac30d75fd1eb44270";
specialSecretSig is a randomly assigned hash used to identify secrets in maps. See sdk/go/common/resource/properties.go.
const specialSigKey
const specialSigKey: "4dabf18193072939515e22adb298388d" = "4dabf18193072939515e22adb298388d";
specialSigKey is sometimes used to encode type identity inside of a map. See sdk/go/common/resource/properties.go.
function streamInvoke
streamInvoke(tok: string, props: Inputs, opts: InvokeOptions): Promise<StreamInvokeResponse<any>>
class StreamInvokeResponse
implements AsyncIterable<T>
constructor
new StreamInvokeResponse(source: AsyncIterable<T>, cancelSource: () => void)
method [Symbol.asyncIterator]
[Symbol.asyncIterator](): AsyncIterator<T>
method cancel
public cancel(): void
function suppressUnhandledGrpcRejections
suppressUnhandledGrpcRejections<T>(p: Promise<T>): Promise<T>
suppressUnhandledGrpcRejections silences any unhandled promise rejections that occur due to gRPC errors. The input promise may still be rejected.
function terminateRpcs
terminateRpcs(): void
function transferProperties
transferProperties(onto: Resource, label: string, props: Inputs): OutputResolvers
transferProperties mutates the ‘onto’ resource so that it has Promise-valued properties for all the ‘props’ input/output props. Importantly all these promises are completely unresolved. This is because we don’t want anyone to observe the values of these properties until the rpc call to registerResource actually returns. This is because the registerResource call may actually override input values, and we only want people to see the final value.
The result of this call (beyond the stateful changes to ‘onto’) is the set of Promise resolvers that will be called post-RPC call. When the registerResource RPC call comes back, the values that the engine actualy produced will be used to resolve all the unresolved promised placed on ‘onto’.
const unknownValue
const unknownValue: "04da6b54-80e4-46f7-96ec-b56ff0331ba9" = "04da6b54-80e4-46f7-96ec-b56ff0331ba9";
Unknown values are encoded as a distinguished string value.
function unwrapRpcSecret
unwrapRpcSecret(obj: any): any
unwrapRpcSecret returns the underlying value for a secret, or the value itself if it was not a secret.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.