Providers#

pulumi/pulumi:proto/pulumi/provider.proto

Services#

🔌 ResourceProvider#

The ResourceProvider service defines a standard interface for resource providers. A resource provider manages a set of configuration, resources, functions and so on in a single package, and offers methods such as CRUD operations on resources and invocations of functions. Resource providers are primarily managed by the Pulumi engine as part of a deployment in order to interact with the cloud providers underpinning a Pulumi application.

📞 Handshake#

⤵️ ProviderHandshakeRequest ⤴️ ProviderHandshakeResponse

Handshake is the first call made by the engine to a provider. It is used to pass the engine’s address to the provider so that it may establish its own connections back, and to establish protocol configuration that will be used to communicate between the two parties. Providers that support Handshake should return responses consistent with those returned in response to 📞 Configure calls where there is overlap due to the use of Configure prior to Handshake’s introduction.

📞 Parameterize#

⤵️ ParameterizeRequest ⤴️ ParameterizeResponse

Parameterize is the primary means of supporting parameterized providers, which allow a caller to change a provider’s behavior ahead of its configuration and subsequent use. Where a 📞 Configure call allows a caller to influence provider behaviour at a high level (e.g. by specifying the region in which an AWS provider should operate), a Parameterize call may change the set of resources and functions that a provider offers (that is, its schema). This is useful in any case where some “set” of providers can be captured by a single implementation that may power fundamentally different schemata – dynamically bridging Terraform providers, or managing Kubernetes clusters with custom resource definitions, for instance, are good examples. The parameterized package that Parameterize yields is known as a sub-package of the original (unparameterized) package.

Parameterize supports two types of parameterization:

Replacement parameterization, whereby a Parameterize call results in a schema that completely replaces the original provider schema. Bridging a Terraform provider dynamically might be an example of this – following the call to Parameterize, the provider’s schema will become that of the Terraform provider that was bridged. Providers that implement replacement parameterization expect a single call to Parameterize.
Extension parameterization, in which a Parameterize call results in a schema that is a superset of the original. This is useful in cases where a provider can be extended with additional resources or functions, such as a Kubernetes provider that can be extended with resources representing custom resource definitions. Providers that implement extension parameterization should accept multiple calls to Parameterize. Extension packages may even be called multiple times with the same package name, but with different versions. The CRUD operations of extension resources must include the version of which sub-package they correspond to.

Parameterize should work the same whether it is provided with ParametersArgs or ParametersValue input. In each case it should return the sub-package name and version (which when a ParametersValue is supplied should match the given input).

📞 GetSchema#

⤵️ GetSchemaRequest ⤴️ GetSchemaResponse

GetSchema fetches the schema for this resource provider.

📞 CheckConfig#

⤵️ CheckRequest ⤴️ CheckResponse

CheckConfig validates a set of configuration inputs that will be passed to this provider instance. CheckConfig is to provider resources what 📞 Check is to individual resources, and is the first stage in configuring (that is, eventually executing a 📞 Configure call) a provider using user-supplied values. In the case that provider inputs are coming from some source that has been checked previously (e.g. a Pulumi state), it is not necessary to call CheckConfig.

A CheckConfig call returns either a set of checked, known-valid inputs that may subsequently be passed to 📞 DiffConfig and/or 📞 Configure, or a set of errors explaining why the inputs are invalid. In the case that a set of inputs are successfully validated and returned, CheckConfig may also populate default values for provider configuration, returning them so that they may be passed to a subsequent 📞 Configure call and persisted in the Pulumi state. In the case that CheckConfig fails and returns a set of errors, it is expected that the caller (typically the Pulumi engine) will fail provider registration.

As a rule, the provider inputs returned by a call to CheckConfig should preserve the original representation of the properties as present in the program inputs. Though this rule is not required for correctness, violations thereof can negatively impact the end-user experience, as the provider inputs are used for detecting and rendering diffs.

📞 DiffConfig#

⤵️ DiffRequest ⤴️ DiffResponse

DiffConfig compares an existing (“old”) provider configuration with a new configuration and computes the difference (if any) between them. DiffConfig is to provider resources what 📞 Diff is to individual resources. DiffConfig should only be called with values that have at some point been validated by a 📞 CheckConfig call. The 📨 DiffResponse returned by a DiffConfig call is used primarily to determine whether or not the newly configured provider is capable of managing resources owned by the old provider. If DiffConfig indicates that the provider resource needs to be replaced, for instance, then all resources owned by that provider will also need to be replaced. Replacement semantics should thus be reserved for changes to configuration properties that are guaranteed to make old resources unmanageable. Changes to an AWS region, for example, will almost certainly require a provider replacement, but changes to an AWS access key, should almost certainly not.

Implementations must satisfy the invariants documented on DiffResponse.

📞 Configure#

⤵️ ConfigureRequest ⤴️ ConfigureResponse

Configure is the final stage in configuring a provider instance. Callers may supply two sets of data:

Provider-specific configuration, which is the set of inputs that have been validated by a previous 📞 CheckConfig call.
Provider-agnostic (“protocol”) configuration, such as whether or not the caller supports secrets.

The provider is expected to return its own set of protocol configuration, indicating which features it supports in turn so that the caller and the provider can interact appropriately.

Providers may expect a single call to Configure. If a call to Configure is missing required configuration, the provider may return a set of error details containing 📨 ConfigureErrorMissingKeys values to indicate which keys are missing.

Important

The use of Configure to configure protocol features is deprecated in favour of the 📞 Handshake method, which should be implemented by newer providers. To enable compatibility between older engines and providers:

Callers which call Handshake must call Configure with flags such as acceptSecrets and acceptResources set to true, since these features predate the introduction of Handshake and thus Handshake-aware callers must support them. See 📨 ConfigureRequest for more information.
Providers which implement Handshake must support flags such as acceptSecrets and acceptResources, and indicate as such by always returning true for these fields in 📨 ConfigureResponse. See 📨 ConfigureResponse for more information.

📞 Invoke#

⤵️ InvokeRequest ⤴️ InvokeResponse

Invoke dynamically executes a built-in function in the provider.

📞 Call#

⤵️ CallRequest ⤴️ CallResponse

Call dynamically executes a method in the provider associated with a component resource.

📞 Check#

⤵️ CheckRequest ⤴️ CheckResponse

Check validates a set of input properties against a given resource type. A Check call returns either a set of checked, known-valid inputs that may subsequently be passed to 📞 Diff, 📞 Create, or 📞 Update; or a set of errors explaining why the inputs are invalid. In the case that a set of inputs are successfully validated and returned, Check may also populate default values for resource inputs, returning them so that they may be passed to a subsequent call and persisted in the Pulumi state. In the case that Check fails and returns a set of errors, it is expected that the caller (typically the Pulumi engine) will fail resource registration.

As a rule, the provider inputs returned by a call to Check should preserve the original representation of the properties as present in the program inputs. Though this rule is not required for correctness, violations thereof can negatively impact the end-user experience, as the provider inputs are used for detecting and rendering diffs.

📞 Diff#

⤵️ DiffRequest ⤴️ DiffResponse

Diff compares an existing (“old”) set of resource properties with a new set of properties and computes the difference (if any) between them. Diff should only be called with values that have at some point been validated by a 📞 Check call.

Implementations must satisfy the invariants documented on DiffResponse.

📞 Create#

⤵️ CreateRequest ⤴️ CreateResponse

Create provisions a new instance of the specified (custom) resource. It returns a provider-assigned ID for the resource as well as the output properties that arose from the creation properties. Output properties are typically the union of the resource’s input properties and any additional values that were computed or made available during creation.

If creation fails, Create may return an 📨 ErrorResourceInitFailed error detail explaining why. Moreover, if Create does return an error, it must be the case that the resource was not created (that is, Create can be thought of as transactional or atomic).

📞 Read#

⤵️ ReadRequest ⤴️ ReadResponse

Read reads the current live state associated with a resource identified by the supplied state. The given state must be sufficient to uniquely identify the resource. This is typically just the resource ID, but may also include other properties.

📞 Update#

⤵️ UpdateRequest ⤴️ UpdateResponse

Update updates an existing resource according to a new set of inputs, returning a new set of output properties.

📞 Delete#

⤵️ DeleteRequest ⤴️ .google.protobuf.Empty

Delete deprovisions an existing resource as specified by its ID. Delete should be transactional/atomic – if a call to Delete fails, it must be the case that the resource was not deleted and can be assumed to still exist.

📞 Construct#

⤵️ ConstructRequest ⤴️ ConstructResponse

Construct provisions a new component resource. Providers that implement Construct are referred to as component providers. Construct is to component resources what 📞 Create is to custom resources. Components do not have any lifecycle of their own, and instead embody the lifecycles of the resources that they are composed of. As such, Construct is effectively a subprogram whose resources will be persisted in the caller’s state. It is consequently passed enough information to manage fully these resources. At a high level, this comprises:

A 🔌 ResourceMonitor endpoint which the provider can use to register nested custom or component resources that belong to the component.
A set of input properties.
A full set of resource options that the component should propagate to resources it registers against the supplied resource monitor.

📞 Cancel#

⤵️ .google.protobuf.Empty ⤴️ .google.protobuf.Empty

Cancel signals the provider to gracefully shut down and abort any ongoing resource operations. Operations aborted in this way will return an error (e.g., Update and Create will either return a creation error or an initialization error). Since Cancel is advisory and non-blocking, it is up to the host to decide how long to wait after Cancel is called before (e.g.) hard-closing any gRPC connection.

📞 GetPluginInfo#

⤵️ .google.protobuf.Empty ⤴️ PluginInfo

GetPluginInfo returns generic information about this plugin, like its version.

📞 Attach#

⤵️ PluginAttach ⤴️ .google.protobuf.Empty

Attach sends the engine address to an already running plugin.

📞 GetMapping#

⤵️ GetMappingRequest ⤴️ GetMappingResponse

GetMapping returns mappings designed to aid in converting programs and state from other ecosystems. It accepts a “conversion key”, which effectively corresponds to a source language, such as terraform, and a source provider name, which is the name of the provider in the source language. Given these, it returns source-specific mapping data for the provider requested. As an example, the Pulumi AWS provider, which is bridged from the Terraform AWS provider and thus capable of mapping names between the two, might respond to a call with key terraform and source provider name aws with mapping data for transforming (among other things) Terraform AWS names such as aws_s3_bucket into Pulumi AWS types such as aws:s3/bucket:Bucket. If a provider only supports a single source provider, or has some sensible default, it may respond also to a call in which the source provider name is empty (""), which will be made when the engine does not have sufficient knowledge to work out which provider offers a specific mapping.

In general, it is expected that providers implemented by bridging an equivalent provider from another ecosystem (such as bridged Terraform providers built atop the pulumi-terraform-bridge, for instance) implement GetMapping to support conversion from that ecosystem into Pulumi using the same logic that underpins the bridging itself.

📞 GetMappings#

⤵️ GetMappingsRequest ⤴️ GetMappingsResponse

GetMappings is an optional method designed to aid in converting programs and state from other ecosystems. GetMappings accepts a “conversion key”. This corresponds to a source language, for which we want to retrieve mappings for names etc. from that source language into Pulumi. An example key might therefore be terraform in the event that we wish to map e.g. Terraform resource names to Pulumi resource types. Given a key, GetMappings returns a list of source provider names for which calls to GetMapping will return mappings. So, continuing the Terraform example, the Pulumi AWS provider, which is bridged from the Terraform AWS provider and thus capable of mapping names between the two, might return the list ["aws"] in response to a call with key terraform.

If a provider does not implement GetMappings, the engine will fall back to calling GetMapping blindly without a source provider name (that is, with the value "").

Messages#

📨 CallRequest#

tok string: the function token to invoke.
args google.protobuf.Struct: the arguments for the function invocation.
argDependencies CallRequest.ArgDependenciesEntry: a map from argument keys to the dependencies of the argument.
project string: the project name.
stack string: the name of the stack being deployed into.
config CallRequest.ConfigEntry: the configuration variables to apply before running.
configSecretKeys string: the configuration keys that have secret values.
dryRun bool: true if we’re only doing a dryrun (preview).
parallel int32: the degree of parallelism for resource operations (<=1 for serial).
monitorEndpoint string: the address for communicating back to the resource monitor.
organization string: the organization of the stack being deployed into.
accepts_output_values bool: the engine can be passed output values back, returnDependencies can be left blank if returning output values.
stack_trace_handle string: The stack trace handle for the call. Supports stitching stack traces together across plugins.

📨 ArgDependenciesEntry#

key string: <No description>
value CallRequest.ArgumentDependencies: <No description>

📨 ArgumentDependencies#

ArgumentDependencies describes the resources that a particular argument depends on.

urns string: A list of URNs this argument depends on.

📨 ConfigEntry#

key string: <No description>
value string: <No description>

📨 CallResponse#

return google.protobuf.Struct

the returned values, if call was successful.

failures CheckFailure

the failures if any arguments didn’t pass verification.

returnDependencies CallResponse.ReturnDependenciesEntry

a map from return value keys to the dependencies of the return value.

returnDependencies will be augmented by the set of dependencies specified in return via output property values.

📨 ReturnDependencies#

ReturnDependencies describes the resources that a particular return value depends on.

urns string: A list of URNs this return value depends on.

📨 ReturnDependenciesEntry#

key string: <No description>
value CallResponse.ReturnDependencies: <No description>

📨 CheckFailure#

A CheckFailure describes a single validation error that arose as part of a 📞 CheckConfig or 📞 Check call.

property string: The input property that failed validation.
reason string: The reason that the named property failed validation.

📨 CheckRequest#

CheckRequest is the type of requests sent as part of 📞 CheckConfig and 📞 Check calls. A CheckRequest primarily captures the URN and inputs of the resource being checked. In the case of 📞 CheckConfig, the URN will be the URN of the provider resource being constructed, which may or may not be a default provider, and the inputs will be the provider configuration.

urn string: The URN of the resource whose inputs are being checked. In the case of 📞 CheckConfig, this will be the URN of the provider resource being constructed, which may or may not be a default provider.
olds google.protobuf.Struct: The old input properties or configuration for the resource, if any.
news google.protobuf.Struct: The new input properties or configuration for the resource, if any.

Note

If this resource has been specified with the ignoreChanges, then the values in news may differ from those written in the Pulumi program registering this resource. In such cases, the caller (e.g. the Pulumi engine) is expected to preprocess the news value by replacing every property matched by ignoreChanges with its corresponding olds value (effectively ignoring the change).
randomSeed bytes: A random but deterministically computed hash, intended to be used for generating globally unique names.
name string: The name of the resource being checked. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
type string: The type of the resource being checked. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
autonaming CheckRequest.AutonamingOptions: <No description>

📨 AutonamingOptions#

Configuration for automatic resource naming behavior. This structure contains fields that control how the provider handles resource names, including proposed names and naming modes.

proposed_name string: The proposed name for the resource being checked. This may be used by the provider as a suggestion for the final resource name, depending on the specified mode.
mode CheckRequest.AutonamingOptions.Mode: <No description>

📨 CheckResponse#

CheckResponse is the type of responses sent by a 📞 CheckConfig or 📞 Check call. A CheckResponse may contain either:

a set of checked, known-valid inputs. In the case of 📞 CheckConfig, these may subsequently be passed to 📞 DiffConfig and/or 📞 Configure. In the case of 📞 Check, these may be passed to any of the supported lifecycle methods that accept provider inputs.
a set of failures detailing invalid inputs.

In cases where the supplied set of inputs is valid, a CheckResponse may contain default values that should persisted to Pulumi state and passed to subsequent calls.

inputs google.protobuf.Struct: A valid, checked set of inputs. May contain defaults.
failures CheckFailure: Any validation failures that occurred.

📨 ConfigureErrorMissingKeys#

ConfigureErrorMissingKeys is the type of error details that may be sent in response to a 📞 Configure call when required configuration keys are missing.

missingKeys ConfigureErrorMissingKeys.MissingKey: A list of required configuration keys that were not supplied.

📨 MissingKey#

The type of key-value pairs representing keys that are missing from a 📞 Configure call.

name string: The name of the missing configuration key.

Note

This should be the Pulumi name of the missing key, and not any provider-internal or upstream name. Names that differ between Pulumi and an upstream provider should be translated prior to being returned.
description string: A description of the missing config key, as reported by the provider.

📨 ConfigureRequest#

ConfigureRequest is the type of requests sent as part of a 📞 Configure call. Requests include both provider-specific inputs (variables or args) and provider-agnostic (“protocol”) configuration (acceptSecrets, acceptResources, and so on).

variables ConfigureRequest.VariablesEntry

Warning

variables is deprecated; args should be used instead wherever possible.

A map of input properties for the provider. Compound values, such as nested objects, should be JSON encoded so that they too can be passed as strings. For instance, the following configuration:

{
  "a": 42,
  "b": {
    "c": "hello",
    "d": true
  }
}

should be encoded as:

{
  "a": "42",
  "b": "{\"c\":\"hello\",\"d\":true}"
}

args google.protobuf.Struct

A map of input properties for the provider.

Warning

args may include secrets. Because ConfigureRequest is sent before 📨 ConfigureResponse can specify whether or not the provider accepts secrets in general, providers must handle secrets if they appear in args.

acceptSecrets bool

True if and only if the caller supports secrets. If true, operations should return strongly typed secrets if the provider supports them also. Must be true if the caller has previously called 📞 Handshake.

acceptResources bool

True if and only if the caller supports strongly typed resources. If true, operations should return resources as strongly typed values if the provider supports them also. Must be true if the caller has previously called 📞 Handshake.

sends_old_inputs bool

True if and only if the caller supports sending old inputs as part of 📞 Diff and 📞 Update calls. If true, the provider should expect these fields to be populated in these calls. Must be true if the caller has previously called 📞 Handshake.

sends_old_inputs_to_delete bool

True if and only if the caller supports sending old inputs and outputs as part of 📞 Delete calls. If true, the provider should expect these fields to be populated in these calls. Must be true if the caller has previously called 📞 Handshake.

id string

The ID of the provider being configured. N.B. This will be null if configure_with_urn was false in Handshake.

urn string

The URN of the provider being configured. N.B. This will be null if configure_with_urn was false in Handshake.

name string

The name of the provider being configured. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the provider. N.B. This will be null if configure_with_urn was false in Handshake.

type string

The type of the provider being configured. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the provider. N.B. This will be null if configure_with_urn was false in Handshake.

📨 VariablesEntry#

key string: <No description>
value string: <No description>

📨 ConfigureResponse#

ConfigureResponse is the type of responses sent by a 📞 Configure call. Its primary purpose is to communicate features that the provider supports back to the caller.

acceptSecrets bool: True if and only if the provider supports secrets. If true, the caller should pass secrets as strongly typed values to the provider. Must match the value returned in response to 📞 Handshake if the provider supports handshaking.
supportsPreview bool: True if and only if the provider supports the preview field on 📞 Create and 📞 Update calls. If true, the engine should invoke these calls with preview set to true during previews. Must be true if the provider implements 📞 Handshake.
acceptResources bool: True if and only if the provider supports strongly typed resources. If true, the caller should pass resources as strongly typed values to the provider. Must match the value returned in response to 📞 Handshake if the provider supports handshaking.
acceptOutputs bool: True if and only if the provider supports output values as inputs. If true, the engine should pass output values to the provider where possible. Must match the value returned in response to 📞 Handshake if the provider supports handshaking.
supports_autonaming_configuration bool: True if the provider accepts and respects autonaming configuration that the engine provides on behalf of the user. Must match the value returned in response to 📞 Handshake if the provider supports handshaking.

📨 ConstructRequest#

ConstructRequest is the type of requests sent as part of a 📞 Construct call. A ConstructRequest captures enough data to be able to register nested components against the caller’s resource monitor.

project string: The project to which this resource and its nested resources will belong.
stack string: The name of the stack being deployed into.
config ConstructRequest.ConfigEntry: Configuration for the specified project and stack.
dryRun bool: True if and only if the request is being made as part of a preview/dry run, in which case the provider should not actually construct the component.
parallel int32: The degree of parallelism that may be used for resource operations. A value less than or equal to 1 indicates that operations should be performed serially.
monitorEndpoint string: The address of the 🔌 ResourceMonitor that the provider should connect to in order to send resource registrations for its nested resources.
type string: The type of the component resource being constructed. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
name string: The name of the component resource being constructed. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
parent string: An optional parent resource that the component (and by extension, its nested resources) should be children of.
inputs google.protobuf.Struct: The component resource’s input properties. Unlike the inputs of custom resources, these will not have been passed to a call to 📞 Check. By virtue of their being a composition of other resources, component resources are able to (and therefore expected) to validate their own inputs. Moreover, 📞 Check will be called on any inputs passed to nested custom resources as usual.
inputDependencies ConstructRequest.InputDependenciesEntry: A map of property dependencies for the component resource and its nested resources.
providers ConstructRequest.ProvidersEntry: A map of package names to provider references for the component resource and its nested resources.
dependencies string: A list of URNs that this resource and its nested resources depend on.
configSecretKeys string: A set of configuration keys whose values are secret.
organization string: The organization to which this resource and its nested resources will belong.
protect bool: True if and only if the resource (and by extension, its nested resources) should be marked as protected. Protected resources cannot be deleted without first being unprotected.
additionalSecretOutputs string: A list of input properties whose values should be treated as secret.
customTimeouts ConstructRequest.CustomTimeouts: A set of custom timeouts that specify how long the caller is prepared to wait for the various CRUD operations of this resource’s nested resources.
deletedWith string: The URN of a resource that this resource (and thus its nested resources) will be implicitly deleted with. If the resource referred to by this URN is deleted in the same operation that this resource would be deleted, the 📞 Delete call for this resource will be elided (since this dependency signals that it will have already been deleted).
deleteBeforeReplace bool: If true, this resource (and its nested resources) must be deleted before its replacement is created.
ignoreChanges string: A set of property paths that should be treated as unchanged.
replaceOnChanges string: A set of properties that, when changed, trigger a replacement.
retainOnDelete bool: True if 📞 Delete should not be called when the resource (and by extension, its nested resources) are removed from a Pulumi program.
accepts_output_values bool: True if the caller is capable of accepting output values in response to the call. If this is set, these outputs may be used to communicate dependency information and so there is no need to populate 📨 ConstructResponse‘s stateDependencies field.
resource_hooks ConstructRequest.ResourceHooksBinding: <No description>
stack_trace_handle string: The stack trace handle for the construct call. Supports stitching stack traces together across plugins.
replace_with string: The URNs of resources whose replaces will trigger a replace on this resource.
aliases Alias: a list of additional aliases that should be considered the same.
replacement_trigger google.protobuf.Value: If set, the engine will diff this value with the last recorded value, and trigger a replace if they are not equal.

📨 ConfigEntry#

key string: <No description>
value string: <No description>

📨 CustomTimeouts#

A CustomTimeouts object encapsulates a set of timeouts for the various CRUD operations that might be performed on this resource’s nested resources. Timeout values are specified as duration strings, such as "5ms" (5 milliseconds), "40s" (40 seconds), or "1m30s" (1 minute and 30 seconds). The following units of time are supported:

ns: nanoseconds
us or µs: microseconds
ms: milliseconds
s: seconds
m: minutes
h: hours

create string: How long a caller is prepared to wait for a nested resource’s 📞 Create operation to complete.
update string: How long a caller is prepared to wait for a nested resource’s 📞 Update operation to complete.
delete string: How long a caller is prepared to wait for a nested resource’s 📞 Delete operation to complete.

📨 InputDependenciesEntry#

key string: <No description>
value ConstructRequest.PropertyDependencies: <No description>

📨 PropertyDependencies#

A PropertyDependencies list is a set of URNs that a particular property may depend on.

urns string: A list of URNs that this property depends on.

📨 ProvidersEntry#

key string: <No description>
value string: <No description>

📨 ResourceHooksBinding#

before_create string: <No description>
after_create string: <No description>
before_update string: <No description>
after_update string: <No description>
before_delete string: <No description>
after_delete string: <No description>
on_error string: <No description>

📨 ConstructResponse#

ConstructResponse is the type of responses sent by a 📞 Construct call.

urn string: The URN of the constructed component resource.
state google.protobuf.Struct: Any output properties that the component registered as part of its construction.
stateDependencies ConstructResponse.StateDependenciesEntry: A map of property dependencies for the component’s outputs. This will be set if the caller indicated that it could not receive dependency-communicating output values by setting 📨 ConstructRequest‘s accepts_output_values field to false.

📨 PropertyDependencies#

A PropertyDependencies list is a set of URNs that a particular property may depend on.

urns string: A list of URNs that this property depends on.

📨 StateDependenciesEntry#

key string: <No description>
value ConstructResponse.PropertyDependencies: <No description>

📨 CreateRequest#

CreateRequest is the type of requests sent as part of a 📞 Create call.

urn string: The URN of the resource being created.
properties google.protobuf.Struct: The resource’s input properties, to be set during creation. These should have been validated by a call to 📞 Check.
timeout double: A timeout in seconds that the caller is prepared to wait for the operation to complete.
preview bool: True if and only if the request is being made as part of a preview/dry run, in which case the provider should not actually create the resource.
name string: The name of the resource being created. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
type string: The type of the resource being created. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
resource_status_address string: The address of a pulumirpc.ResourceStatus service which can be used to e.g. create or update view resources.
resource_status_token string: The pulumirpc.ResourceStatus service context token to pass when calling methods on the service.

📨 CreateResponse#

CreateResponse is the type of responses sent by a 📞 Create call. A CreateResponse contains the ID of the created resource, as well as any output properties that arose from the creation process.

id string: The ID of the created resource.
properties google.protobuf.Struct: The resource’s output properties. Typically this will be a union of the resource’s input properties and any additional values that were computed or made available during creation.
refresh_before_update bool: Indicates that this resource should always be refreshed prior to updates.

📨 DeleteRequest#

DeleteRequest is the type of requests sent as part of a 📞 Delete call.

id string

The ID of the resource to delete.

urn string

The URN of the resource to delete.

properties google.protobuf.Struct

The old output properties of the resource being deleted.

timeout double

A timeout in seconds that the caller is prepared to wait for the operation to complete.

old_inputs google.protobuf.Struct

The old input properties of the resource being deleted.

the old input values of the resource to delete.

name string

The name of the resource being deleted. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.

type string

The type of the resource being deleted. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.

resource_status_address string

The address of a pulumirpc.ResourceStatus service which can be used to e.g. create or update view resources.

resource_status_token string

The pulumirpc.ResourceStatus service context token to pass when calling methods on the service.

old_views View

The old views for the resource being read.

📨 DiffRequest#

DiffRequest is the type of requests sent as part of 📞 DiffConfig and 📞 Diff calls. A DiffRequest primarily captures:

the URN of the resource whose properties are being compared;
the old and new input properties of the resource; and
the old output properties of the resource.

In the case of 📞 DiffConfig, the URN will be the URN of the provider resource being examined, which may or may not be a default provider, and the inputs and outputs will be the provider configuration and state. Inputs supplied to a 📞 DiffConfig call should have been previously checked by a call to 📞 CheckConfig; inputs supplied to a 📞 Diff call should have been previously checked by a call to 📞 Check.

id string: The ID of the resource being diffed.
urn string: The URN of the resource being diffed.
olds google.protobuf.Struct: The old output properties of the resource being diffed.
news google.protobuf.Struct: The new input properties of the resource being diffed. These should have been validated by an appropriate call to 📞 CheckConfig or 📞 Check.
ignoreChanges string: A set of property paths that should be treated as unchanged.
old_inputs google.protobuf.Struct: The old input properties of the resource being diffed.
name string: The name of the resource being diffed. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
type string: The type of the resource being diffed. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.

📨 DiffResponse#

DiffResponse is the type of responses sent by a 📞 DiffConfig or 📞 Diff call. A DiffResponse indicates whether a resource is unchanged, requires updating (that is, can be changed “in place”), or requires replacement (that is, must be destroyed and recreated anew). Legacy implementations may also signal that it is unknown whether there are changes or not.

DiffResponse has evolved since its inception and there are now a number of ways that providers can signal their intent to callers:

Simple diffs utilise the changes field to signal which fields are responsible for a change, and the replaces field to further communicate which changes (if any) require a replacement as opposed to an update.
Detailed diffs are those with hasDetailedDiff set, and utilise the detailedDiff field to provide a more granular view of the changes that have occurred. Detailed diffs are designed to allow providers to control precisely which field names are displayed as responsible for a change, and to signal more accurately what kind of change occurred (e.g. a field was added, deleted or updated).

The response must satisfy the following invariants:

For each top-level key in diff there is at least one matching property path, starting at that key, in detailedDiff.
For each entry in detailedDiff, its top-level property is in diff.
diff does not contain duplicates.
detailedDiff does not contain duplicate keys.

replaces string: A set of properties which have changed and whose changes require the resource being diffed to be replaced. The caller should replace the resource if this set is non-empty, or if any of the properties specified in detailedDiff have a *_REPLACE kind.
stables string: An optional list of properties that will not ever change (are stable).
deleteBeforeReplace bool: If true, this resource must be deleted before its replacement is created.
changes DiffResponse.DiffChanges: The result of the diff. Indicates at a high level whether the resource has changed or not (or, in legacy cases, if the provider does not know).
diffs string: The set of properties which have changed. This field only supports top-level properties. It does not support full property paths; implementations should use detailedDiff when this is required.
detailedDiff DiffResponse.DetailedDiffEntry: detailedDiff can be used to implement more detailed diffs. A detailed diff is a map from property paths to 📨 PropertyDiffs, which describe the kind of change that occurred to the property located at that path. If a provider does not implement this, the caller (typically the Pulumi engine) will compute a representation based on the simple diff fields (changes, replaces, and so on).
hasDetailedDiff bool: True if and only if this response contains a detailedDiff.

📨 DetailedDiffEntry#

key string: <No description>
value PropertyDiff: <No description>

📨 ErrorResourceInitFailed#

ErrorResourceInitFailed is sent as a Detail ResourceProvider.{Create, Update} fail because a resource was created successfully, but failed to initialize.

id string: the ID of the created resource.
properties google.protobuf.Struct: any properties that were computed during updating.
reasons string: error messages associated with initialization failure.
inputs google.protobuf.Struct: the current inputs to this resource (only applicable for Read)
refresh_before_update bool: Indicates that this resource should always be refreshed prior to updates.

📨 GetMappingRequest#

GetMappingRequest is the type of requests sent as part of a 📞 GetMapping call.

key string: The conversion key for the mapping being requested. This typically corresponds to the source language, such as terraform in the case of mapping Terraform names to Pulumi names.
provider string: An optional source provider key for the mapping being requested. If this is empty, the provider should assume that this request is from an old engine prior to the introduction of 📞 GetMappings. In these cases the request should be answered with the “primary” mapping. If this field is set, the provider field in the corresponding 📨 GetMappingResponse should contain the same value.

📨 GetMappingResponse#

GetMappingResponse is the type of responses sent by a 📞 GetMapping call. The data within a GetMappingResponse will normally be human-readable JSON (e.g. an object mapping names from the source to Pulumi), but the engine doesn’t mandate any specific format.

provider string: The source provider key that this mapping contains data for.
data bytes: Mapping data in a format specific to the conversion plugin/source language.

📨 GetMappingsRequest#

GetMappingsRequest is the type of requests sent as part of a 📞 GetMappings call.

key string: The conversion key for the mapping being requested. This typically corresponds to the source language, such as terraform in the case of mapping Terraform names to Pulumi names.

📨 GetMappingsResponse#

GetMappingsResponse is the type of responses sent by a 📞 GetMappings call.

providers string: The set of source provider keys this provider can supply mappings for. For example the Pulumi provider terraform-template would return ["template"] for this.

📨 GetSchemaRequest#

version int32: the schema version.
subpackage_name string: the name of the sub-package to lookup
subpackage_version string: the version of the sub-package to lookup

📨 GetSchemaResponse#

schema string: the JSON-encoded schema.

📨 InvokeRequest#

tok string: the function token to invoke.
args google.protobuf.Struct: the arguments for the function invocation.
preview bool: This is only set if HandshakeRequest.invoke_with_preview was true. If this is true then the engine is currently running a preview deployment.

📨 InvokeResponse#

return google.protobuf.Struct: the returned values, if invoke was successful.
failures CheckFailure: the failures if any arguments didn’t pass verification.

📨 ParameterizeRequest#

ParameterizeRequest is the type of requests sent as part of a 📞 Parameterize call. A ParameterizeRequest may contain either:

a string array (ParametersArgs), intended to represent a set of command-line arguments so as to support instantiating a parameterized provider from a command-line invocation (e.g. to generate an SDK).
a byte array accompanied by a name and version (ParametersValue), intended to represent a parameter embedded in a previously generated SDK.

Embedding parameter values in SDKs allows programs to consume parameterized providers without needing to know the details of the parameterization. Allowing the representation embedded into an SDK to differ from that supplied on the command-line permits providers to implement optimizations for the common, fast-path case (program execution), such as embedding a generated schema as opposed to generating it on-demand for each resource registration.

args ParameterizeRequest.ParametersArgs: Arguments from the command line.
value ParameterizeRequest.ParametersValue: Values from a generated SDK.

📨 ParametersArgs#

A parameter value, represented as an array of strings, as might be provided by a command-line invocation, such as that used to generate an SDK.

args string: <No description>

📨 ParametersValue#

A parameter value, represented by an arbitrary array of bytes accompanied by a name and version. This is expected to be the format used by parameterized provider SDKs.

name string: The sub-package name for this sub-schema parameterization.
version string: The sub-package version for this sub-schema parameterization.
value bytes: The embedded value from the sub-package.

📨 ParameterizeResponse#

ParameterizeResponse is the type of responses sent by a 📞 Parameterize call. It contains a name and version that can be used to identify the sub-package that now exists as a result of parameterization.

name string: The name of the sub-package parameterized.
version string: The version of the sub-package parameterized.

📨 PropertyDiff#

PropertyDiff describes the kind of change that occurred to a property during a diff operation. A PropertyDiff may indicate that a property was added, deleted, or updated, and may further indicate that the change requires a replacement.

kind PropertyDiff.Kind: The kind of diff associated with this property.
inputDiff bool: True if and only if this difference represents one between a pair of old and new inputs, as opposed to a pair of old and new states.

📨 ProviderHandshakeRequest#

ProviderHandshakeRequest is the type of requests sent as part of a 📞 Handshake call.

engine_address string: The gRPC address of the engine handshaking with the provider. At a minimum, this address will expose an instance of the 🔌 Engine service.
root_directory string: A root directory where the provider’s binary, PulumiPlugin.yaml, or other identifying source code is located. In the event that the provider is not being booted by the engine (e.g. in the case that the engine has been asked to attach to an existing running provider instance via a host/port number), this field will be empty.
program_directory string: A program directory in which the provider should execute. This is generally a subdirectory of the root directory, though this is not required. In the event that the provider is not being booted by the engine (e.g. in the case that the engine has been asked to attach to an existing running provider instance via a host/port number), this field will be empty.
configure_with_urn bool: If true the engine will send URN, Name, Type, and ID to the provider as part of the configuration.
supports_views bool: If true the engine supports views and can send the address of a pulumirpc.ResourceStatus service which can be used to e.g. create or update view resources.
supports_refresh_before_update bool: If true the engine supports letting the provider mark resource states as requiring refresh before update.
invoke_with_preview bool: If true the engine will send preview to Invoke methods to let them know if the current operation is a preview or up.

📨 ProviderHandshakeResponse#

ProviderHandshakeResponse is the type of responses sent by a 📞 Handshake call.

accept_secrets bool: True if and only if the provider supports secrets. If true, the caller should pass secrets as strongly typed values to the provider. Must match the value returned in response to 📞 Configure.
accept_resources bool: True if and only if the provider supports strongly typed resources. If true, the caller should pass resources as strongly typed values to the provider. Must match the value returned in response to 📞 Configure.
accept_outputs bool: True if and only if the provider supports output values as inputs. If true, the engine should pass output values to the provider where possible. Must match the value returned in response to 📞 Configure.
supports_autonaming_configuration bool: True if the provider accepts and respects autonaming configuration that the engine provides on behalf of the user. Must match the value returned in response to 📞 Configure.

📨 ReadRequest#

ReadRequest is the type of requests sent as part of a 📞 Read call.

id string: The ID of the resource to read.
urn string: The URN of the resource being read.
properties google.protobuf.Struct: Any current state for the resource being read. This state should be sufficient to uniquely identify the resource.
inputs google.protobuf.Struct: Any current input properties for the resource being read. These will only be populated when the 📞 Read call is being made as part of a refresh operation.
name string: The name of the resource being read. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
type string: The type of the resource being read. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
resource_status_address string: The address of a pulumirpc.ResourceStatus service which can be used to e.g. create or update view resources.
resource_status_token string: The pulumirpc.ResourceStatus service context token to pass when calling methods on the service.
old_views View: The old views for the resource being read. These will only be populated when the 📞 Read call is being made as part of a refresh operation.

📨 ReadResponse#

ReadResponse is the type of responses sent by a 📞 Read call. A ReadResponse contains the ID of the resource being read, as well as any state that was successfully read from the live environment.

id string: The ID of the read resource.
properties google.protobuf.Struct: The output properties of the resource read from the live environment.
inputs google.protobuf.Struct: Output-derived input properties for the resource. These are returned as they would be returned from a 📞 Check call with the same values.
refresh_before_update bool: Indicates that this resource should always be refreshed prior to updates.

📨 UpdateRequest#

UpdateRequest is the type of requests sent as part of a 📞 Update call.

id string: The ID of the resource being updated.
urn string: The URN of the resource being updated.
olds google.protobuf.Struct: The old output properties of the resource being updated.
news google.protobuf.Struct: The new input properties of the resource being updated. These should have been validated by a call to 📞 Check.
timeout double: A timeout in seconds that the caller is prepared to wait for the operation to complete.
ignoreChanges string: A set of property paths that should be treated as unchanged.
preview bool: True if and only if the request is being made as part of a preview/dry run, in which case the provider should not actually update the resource.
old_inputs google.protobuf.Struct: The old input properties of the resource being updated.
name string: The name of the resource being updated. This must match the name specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
type string: The type of the resource being updated. This must match the type specified by the urn field, and is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
resource_status_address string: The address of a pulumirpc.ResourceStatus service which can be used to e.g. create or update view resources.
resource_status_token string: The pulumirpc.ResourceStatus service context token to pass when calling methods on the service.
old_views View: The old views for the resource being updated.

📨 UpdateResponse#

UpdateResponse is the type of responses sent by a 📞 Update call.

properties google.protobuf.Struct: An updated set of resource output properties. Typically this will be a union of the resource’s inputs and any additional values that were computed or made available during the update.
refresh_before_update bool: Indicates that this resource should always be refreshed prior to updates.

📨 View#

View represents the state of a view resource.

type string: The type of the view resource.
name string: The name of the view resource.
parent_type string: An optional type of the parent view resource.
parent_name string: An optional name of the parent view resource.
inputs google.protobuf.Struct: The view resource’s inputs.
outputs google.protobuf.Struct: The view resource’s outputs.

Providers

Contents

Providers#

Services#

🔌 ResourceProvider#

📞 Handshake#

📞 Parameterize#

📞 GetSchema#

📞 CheckConfig#

📞 DiffConfig#

📞 Configure#

📞 Invoke#

📞 Call#

📞 Check#

📞 Diff#

📞 Create#

📞 Read#

📞 Update#

📞 Delete#

📞 Construct#

📞 Cancel#

📞 GetPluginInfo#

📞 Attach#

📞 GetMapping#

📞 GetMappings#

Messages#

📨 CallRequest#

📨 ArgDependenciesEntry#

📨 ArgumentDependencies#

📨 ConfigEntry#

📨 CallResponse#

📨 ReturnDependencies#

📨 ReturnDependenciesEntry#

📨 CheckFailure#

📨 CheckRequest#

📨 AutonamingOptions#

📨 CheckResponse#

📨 ConfigureErrorMissingKeys#

📨 MissingKey#

📨 ConfigureRequest#

📨 VariablesEntry#

📨 ConfigureResponse#

📨 ConstructRequest#

📨 ConfigEntry#

📨 CustomTimeouts#

📨 InputDependenciesEntry#

📨 PropertyDependencies#

📨 ProvidersEntry#

📨 ResourceHooksBinding#

📨 ConstructResponse#

📨 PropertyDependencies#

📨 StateDependenciesEntry#

📨 CreateRequest#

📨 CreateResponse#

📨 DeleteRequest#

📨 DiffRequest#

📨 DiffResponse#

📨 DetailedDiffEntry#

📨 ErrorResourceInitFailed#

📨 GetMappingRequest#

📨 GetMappingResponse#

📨 GetMappingsRequest#

📨 GetMappingsResponse#

📨 GetSchemaRequest#

📨 GetSchemaResponse#

📨 InvokeRequest#

📨 InvokeResponse#

📨 ParameterizeRequest#

📨 ParametersArgs#

📨 ParametersValue#

📨 ParameterizeResponse#

📨 PropertyDiff#

📨 ProviderHandshakeRequest#

📨 ProviderHandshakeResponse#

📨 ReadRequest#

📨 ReadResponse#

📨 UpdateRequest#

📨 UpdateResponse#

📨 View#