Language hosts

pulumi/pulumi:proto/pulumi/language.proto

Services

🔌 LanguageRuntime

The LanguageRuntime service defines a standard interface for language hosts/runtimes. At a high level, a language runtime provides the ability to execute programs, install and query dependencies, and generate code for a specific language.

📞 Handshake

⤵️ LanguageHandshakeRequest ⤴️ LanguageHandshakeResponse

Handshake is the first call made by the engine to a language host. It is used to pass the engine’s address to the language host so that it may establish its own connections back, and to establish protocol configuration that will be used to communicate between the two parties.

📞 GetRequiredPlugins

⤵️ GetRequiredPluginsRequest ⤴️ GetRequiredPluginsResponse

GetRequiredPlugins computes the complete set of anticipated plugins required by a Pulumi program. Among other things, it is intended to be used to pre-install plugins before running a program with 📞 Run, to avoid the need to install them on-demand in response to resource registrations sent back from the running program to the engine.

Important

The use of GetRequiredPlugins is deprecated in favour of 📞 GetRequiredPackages, which returns more granular information about which plugins are required by which packages.

📞 GetRequiredPackages

⤵️ GetRequiredPackagesRequest ⤴️ GetRequiredPackagesResponse

GetRequiredPackages computes the complete set of anticipated packages required by a program. It is used to pre-install packages before running a program with 📞 Run, to avoid the need to install them on-demand in response to resource registrations sent back from the running program to the engine. Moreover, when importing resources into a stack, it is used to determine which plugins are required to service the import of a given resource, since given the presence of parameterized providers, it is not in general true that a package name corresponds 1:1 with a plugin name. It replaces 📞 GetRequiredPlugins in the face of parameterized providers, which as mentioned above can enable multiple instances of the same plugin to provide multiple packages.

📞 Run

⤵️ RunRequest ⤴️ RunResponse

Run executes a Pulumi program, returning information about whether or not the program produced an error.

📞 GetPluginInfo

⤵️ .google.protobuf.Empty ⤴️ PluginInfo

GetPluginInfo returns information about the plugin implementing this language runtime.

📞 InstallDependencies

⤵️ InstallDependenciesRequest ⤴️ InstallDependenciesResponse

InstallDependencies accepts a request specifying a Pulumi project and program that can be executed with 📞 Run and installs the dependencies for that program (e.g. by running npm install for NodeJS, or pip install for Python). Since dependency installation could take a while, and callers may wish to report on its progress, this method returns a stream of 📨 InstallDependenciesResponse messages containing information about standard error and output.

📞 RuntimeOptionsPrompts

⤵️ RuntimeOptionsRequest ⤴️ RuntimeOptionsResponse

RuntimeOptionsPrompts accepts a request specifying a Pulumi project and returns a list of additional prompts to ask during pulumi new.

📞 Template

⤵️ TemplateRequest ⤴️ TemplateResponse

Template allows the language runtime to perform additional templating on a newly instantiated project template. For example the Python runtime might want to convert a requirements.txt into a pyproject.toml suitable for use with uv or poetry.

📞 About

⤵️ AboutRequest ⤴️ AboutResponse

About returns information about the language runtime being used.

📞 GetProgramDependencies

⤵️ GetProgramDependenciesRequest ⤴️ GetProgramDependenciesResponse

GetProgramDependencies computes the set of language-level dependencies (e.g. NPM packages for NodeJS, or Maven libraries for Java) required by a program.

📞 RunPlugin

⤵️ RunPluginRequest ⤴️ RunPluginResponse

RunPlugin is used to execute a program written in this host’s language that implements a Pulumi plugin. It is to plugins what 📞 Run is to programs. Since a plugin is not expected to terminate until instructed/for a long time, this method returns a stream of 📨 RunPluginResponse messages containing information about standard error and output, as well as the exit code of the plugin when it does terminate.

📞 GenerateProgram

⤵️ GenerateProgramRequest ⤴️ GenerateProgramResponse

GenerateProgram generates code in this host’s language that implements the given PCL program. Unlike 📞 GenerateProject, this method only generates program code, and does not e.g. generate a package.json for a NodeJS project that details how to run that code. 📞 GenerateProject, this method underpins “programgen” and the main functionality powering pulumi convert.

📞 GenerateProject

⤵️ GenerateProjectRequest ⤴️ GenerateProjectResponse

GenerateProject generates code in this host’s language that implements the given PCL program and wraps it in some language-specific notion of a “project”, where a project is a buildable or runnable artifact. In this sense, GenerateProject’s output is a superset of that of 📞 GenerateProgram. For instance, when generating a NodeJS project, this method might generate a corresponding package.json file, as well as the relevant NodeJS program code. Along with 📞 GenerateProgram, this method underpins “programgen” and the main functionality powering pulumi convert.

📞 GeneratePackage

⤵️ GeneratePackageRequest ⤴️ GeneratePackageResponse

GeneratePackage generates code in this host’s language that implements an SDK (“sdkgen”) for the given Pulumi package, as specified by a schema.

📞 Pack

⤵️ PackRequest ⤴️ PackResponse

Pack accepts a request specifying a generated SDK package and packs it into a language-specific artifact. For instance, in the case of Java, it might produce a JAR file from a list of .java sources; in the case of NodeJS, a .tgz file might be produced from a list of .js sources; and so on. Presently, Pack is primarily used in language conformance tests, though it is intended to be used more widely in future to standardise e.g. provider publishing workflows.

📞 Link

⤵️ LinkRequest ⤴️ LinkResponse

Link links local dependencies into a project (program or plugin). The dependencies can be binary artifacts such as wheel or tar.gz files, or source directories. Link will update the language specific project files, such as package.json, pyproject.toml, go.mod, etc, to include the dependency. Link returns instructions for the user on how to use the linked package in the project.

📞 Cancel

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

Cancel signals the language runtime to gracefully shut down and abort any ongoing operations. Operations aborted in this way will return an error.

Messages

📨 AboutRequest

AboutRequest is the type of requests sent as part of an 📞 About call.

info ProgramInfo

The program to use.

📨 AboutResponse

AboutResponse is the type of responses sent by an 📞 About call. It contains information about the language runtime being used.

executable string

The primary executable for the runtime of this language. This should be an absolute path. E.g. for NodeJS on a POSIX system, this might be something like /usr/bin/node.

version string

The version of the runtime underpinning the language host. E.g. for a NodeJS host, this might be the version of node being used.

metadata AboutResponse.MetadataEntry

Other host-specific metadata about the runtime underpinning the language host.

📨 MetadataEntry

key string

<No description>

value string

<No description>

📨 DependencyInfo

DependencyInfo is a struct that captures information about a language-specific dependency required by a program (e.g. an NPM package for NodeJS, or a Maven library for Java). It is returned as part of a pulumirpc.LanguageRuntime.GetProgramDependenciesResponse.

name string

The name of the dependency.

version string

The version of the dependency.

📨 GeneratePackageRequest

GeneratePackageRequest is the type of requests sent as part of a 📞 GeneratePackage call.

directory string

The directory to generate the package in. This should be an absolute path on the filesystem that is accessible to the language host.

schema string

A JSON-encoded string containing the schema from which the SDK package should be generated.

extra_files GeneratePackageRequest.ExtraFilesEntry

Extra files that should be copied as-is to the generated output.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

local_dependencies GeneratePackageRequest.LocalDependenciesEntry

Local dependencies that the generated package should reference explicitly, instead of e.g. using the language’s package system. This is a map of package names to local paths of language-specific artifacts that should be used. For instance, in the case of a NodeJS package, this might be a map of NPM package names to local paths to be used, such as { "@pulumi/aws": "/some/path/to/aws.tgz" } if a local tarball is to be used instead of the published @pulumi/aws package.

local bool

If true, generates an SDK appropriate for local usage. This may differ from a standard publishable SDK depending on the language (e.g. for a NodeJS package that is intended to be imported locally, the language host may choose not to generate a package.json).

📨 ExtraFilesEntry

key string

<No description>

value bytes

<No description>

📨 LocalDependenciesEntry

key string

<No description>

value string

<No description>

📨 GeneratePackageResponse

GeneratePackageResponse is the type of responses sent by a 📞 GeneratePackage call.

diagnostics codegen.Diagnostic

Any diagnostics raised by code generation.

📨 GenerateProgramRequest

GenerateProgramRequest is the type of requests sent as part of a 📞 GenerateProgram call.

source GenerateProgramRequest.SourceEntry

The source of the project, represented as a map of file names to PCL source code.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

strict bool

True if PCL binding should be strict.

📨 SourceEntry

key string

<No description>

value string

<No description>

📨 GenerateProgramResponse

GenerateProgramResponse is the type of responses sent by a 📞 GenerateProgram call.

diagnostics codegen.Diagnostic

Any diagnostics raised by code generation.

source GenerateProgramResponse.SourceEntry

The generated program source code, represented as a map of file names to byte contents.

📨 SourceEntry

key string

<No description>

value bytes

<No description>

📨 GenerateProjectRequest

GenerateProjectRequest is the type of requests sent as part of a 📞 GenerateProject call.

source_directory string

The directory containing PCL source code, from which the project should be generated.

target_directory string

The directory in which generated project files should be written. This should be an absolute path on the filesystem that is accessible to the language host.

project string

A string containing JSON to be used as the Pulumi project file (that is, as the contents of Pulumi.yaml).

strict bool

True if PCL binding should be strict.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

local_dependencies GenerateProjectRequest.LocalDependenciesEntry

Local dependencies that the generated project should reference explicitly, instead of e.g. using the language’s package system. This is a map of package names to local paths of language-specific artifacts that should be used. For instance, in the case of a NodeJS project, this might be a map of NPM package names to local paths to be used, such as { "@pulumi/aws": "/some/path/to/aws.tgz" } if a local tarball is to be used instead of the published @pulumi/aws package.

📨 LocalDependenciesEntry

key string

<No description>

value string

<No description>

📨 GenerateProjectResponse

GenerateProjectResponse is the type of responses sent by a 📞 GenerateProject call.

diagnostics codegen.Diagnostic

Any diagnostics raised by code generation.

📨 GetProgramDependenciesRequest

GetProgramDependenciesRequest is the type of requests sent as part of a 📞 GetProgramDependencies call.

project string

The project name.

Important

This is deprecated in favour of passing a program info struct as the info field. Newer versions of the engine will always set this field to the string "deprecated".

pwd string

The program’s working directory.

Important

This is deprecated in favour of passing a program info struct as the info field, with the program_directory field set to this value.

program string

The path to the program.

Important

This is deprecated in favour of passing a program info struct as the info field, with the entry_point field set to this value.

transitiveDependencies bool

True if transitive dependencies should be included in the response.

info ProgramInfo

The program to use.

📨 GetProgramDependenciesResponse

GetProgramDependenciesResponse is the type of responses sent by a 📞 GetProgramDependencies call. It contains information about the dependencies of a program.

dependencies DependencyInfo

The dependencies of the program specified by the request.

📨 GetRequiredPackagesRequest

GetRequiredPackagesRequest is the type of requests sent as part of a 📞 GetRequiredPackages call.

info ProgramInfo

The program to use.

📨 GetRequiredPackagesResponse

GetRequiredPackagesResponse is the type of responses sent by a 📞 GetRequiredPackages call. It contains information about the packages required by a program.

packages PackageDependency

The packages required by the program specified by the request.

📨 GetRequiredPluginsRequest

GetRequiredPluginsRequest is the type of requests sent as part of a 📞 GetRequiredPlugins call.

project string

The project name.

Important

This is deprecated in favour of passing a program info struct as the info field. Newer versions of the engine will always set this field to the string "deprecated".

pwd string

The program’s working directory.

Important

This is deprecated in favour of passing a program info struct as the info field, with the program_directory field set to this value.

program string

The path to the program.

Important

This is deprecated in favour of passing a program info struct as the info field, with the entry_point field set to this value.

info ProgramInfo

The program to use.

📨 GetRequiredPluginsResponse

GetRequiredPluginsResponse is the type of responses sent by a 📞 GetRequiredPlugins call. It contains information about the plugins required by a program.

plugins PluginDependency

The plugins required by the program specified by the request.

📨 InstallDependenciesRequest

InstallDependenciesRequest is the type of requests sent as part of an 📞 InstallDependencies call.

directory string

The program’s working directory.

Important

This is deprecated in favour of passing a program info struct as the info field, with the program_directory field set to this value.

is_terminal bool

True if we are running in a terminal and may use ANSI escape codes in our output.

info ProgramInfo

The program to use.

use_language_version_tools bool

True if the host should use language-specific version managers, such as pyenv or nvm, to set up the version of the language toolchain used.

is_plugin bool

True if this install is for a plugin, as opposed to a top level Pulumi program.

📨 InstallDependenciesResponse

InstallDependenciesResponse is the type of responses streamed by an 📞 InstallDependencies call.

stdout bytes

A line of standard output.

stderr bytes

A line of standard error.

📨 LanguageHandshakeRequest

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

engine_address string

The gRPC address of the engine calling the language host.

root_directory string

The optional root directory, where the PulumiPlugin.yaml file or language binary is located. This can’t be sent when the engine is attaching to a language via a port number.

program_directory string

The optional absolute path to the directory of the language program to execute. Generally, but not required to be, underneath the root directory. This can’t be sent when the engine is attaching to a language via a port number.

📨 LanguageHandshakeResponse

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

📨 LinkRequest

LinkRequest is the type of requests sent as part of a 📞 Link call.

info ProgramInfo

The program to use.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

packages LinkRequest.LinkDependency

Local dependencies that should be linked into the program or plugin’s language specific project files. Each dependency has a path to a language specific artifact. This can be a binary artifact like a Python wheel or a tar.gz for Node.js, or a source directory.

📨 LinkDependency

package PackageDependency

<No description>

path string

<No description>

📨 LinkResponse

LinkResponse is the type of responses sent by a 📞 Link call.

import_instructions string

The instructions on how to use a linked package in a program or plugin. These instructions are meant to be displayed to the user. For example when linking a local Python dependency, this might return import my_namespace_mypkg as mypkg.

📨 PackRequest

PackRequest is the type of requests sent as part of a 📞 Pack call.

package_directory string

The directory containing the package to pack. This should be an absolute path on the filesystem that is accessible to the language host.

destination_directory string

The directory to write the packed artifact to. This should be an absolute path on the filesystem that is accessible to the language host.

📨 PackResponse

PackResponse is the type of responses sent by a 📞 Pack call.

artifact_path string

The path to the packed artifact. This should be an absolute path on the filesystem that is accessible to the language host.

📨 ProgramInfo

A ProgramInfo struct specifies a Pulumi program, and is built typically based on the location of a Pulumi.yaml file and the runtime, main and other properties within that file.

root_directory string

The root of the project containing the program, where the Pulumi.yaml file is located. This should be an absolute path on the filesystem that is accessible to the language host.

program_directory string

The directory containing the program to execute (e.g. the location of the index.ts for a TypeScript NodeJS program). This should be an absolute path on the filesystem that is accessible to the language host. If ProgramInfo is being built from a Pulumi.yaml, this will typically be the directory portion of the main property in that file.

entry_point string

The entry point of the program to execute. This should be a relative path from the program_directory, and is often just . to indicate the program directory itself, but it can also be a filename inside the directory.. If ProgramInfo is being built from a Pulumi.yaml, this will typically be the filename specified main property in that file if it is present, or the aforementioned . if not.

options google.protobuf.Struct

A struct capturing any language-specific options. If ProgramInfo is being built from a Pulumi.yaml, this will contain the runtime.options property from that file.

📨 RunPluginRequest

RunPluginRequest is the type of requests sent as part of a 📞 RunPlugin call.

pwd string

The plugin program’s working directory.

program string

The path to the plugin program.

Important

This is deprecated in favour of passing a program info struct as the info field, with the entry_point field set to this value.

args string

Any arguments to pass to the plugin program.

env string

Any environment variables to set prior to executing the plugin program.

info ProgramInfo

The plugin program to use.

kind string

The kind of plugin to run (resource/analyzer/etc).

name string

The name of the plugin (for display purposes)

attach_debugger bool

True if a plugin should be started under a debugger.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

📨 RunPluginResponse

RunPluginResponse is the type of responses streamed by a 📞 RunPlugin call.

stdout bytes

A line of standard output.

stderr bytes

A line of standard error.

exitcode int32

An exit code that the plugin program has terminated with. This should be the last message sent by the host.

📨 RunRequest

RunRequest is the type of requests sent as part of a 📞 Run call.

project string

The project name.

stack string

The name of the stack being deployed into.

pwd string

The program’s working directory.

program string

The path to the program.

Important

This is deprecated in favour of passing a program info struct as the info field, with the entry_point field set to this value.

args string

Any arguments to pass to the program.

config RunRequest.ConfigEntry

Configuration variables to apply before running the program.

dryRun bool

True if we are only doing a dry run (preview).

parallel int32

The degree of parallelism that should be used for resource operations. A value less than or equal to 1 indicates serial execution.

monitor_address string

The address of the 🔌 ResourceMonitor that the program should connect to send resource registrations and other calls to.

queryMode bool

This is deprecated, query mode is no longer a supported feature.

configSecretKeys string

A list of configuration keys whose values should be treated as secrets.

organization string

The organization of the stack being deployed into.

configPropertyMap google.protobuf.Struct

This is deprecated, runtimes should look at the string based config as that maintains the full textual data from the users config file.

info ProgramInfo

The program to use.

loader_target string

The target of a codegen.LoaderServer to use for loading schemas.

attach_debugger bool

True if and only if the host should start the program under a debugger.

📨 ConfigEntry

key string

<No description>

value string

<No description>

📨 RunResponse

RunResponse is the type of responses sent by a 📞 Run call.

error string

Information about any unhandled error that occurred during the run.

bail bool

True if an error happened, but it was reported to the user. Work should halt immediately, reporting nothing further to the user (since this reporting has already happened). This corresponds to a result.Bail() value being raised in the Go application layer.

📨 RuntimeOptionPrompt

RuntimeOptionPrompt is a struct that captures information about a runtime option that should be prompted for during pulumi new.

key string

A unique key that identifies the runtime option.

description string

A human-readable description of the runtime option.

promptType RuntimeOptionPrompt.RuntimeOptionType

The type of the runtime option.

choices RuntimeOptionPrompt.RuntimeOptionValue

A set of choices for the runtime option that may be displayed as part of the prompting process.

default RuntimeOptionPrompt.RuntimeOptionValue

The default value of the runtime option.

📨 RuntimeOptionValue

RuntimeOptionValue is a struct that captures the value of a runtime option.

promptType RuntimeOptionPrompt.RuntimeOptionType

The type of the runtime option.

stringValue string

The string value of the runtime option, if and only if the type is STRING.

int32Value int32

The 32-bit integer value of the runtime option, if and only if the type is INT32.

displayName string

The display name of the runtime option, to be used in prompts.

📨 RuntimeOptionsRequest

RuntimeOptionsRequest is the type of requests sent as part of a 📞 RuntimeOptionsPrompts call.

info ProgramInfo

The program to use.

📨 RuntimeOptionsResponse

RuntimeOptionsResponse is the type of responses sent by a 📞 RuntimeOptionsPrompts call. It contains information about additional prompts to ask during pulumi new.

prompts RuntimeOptionPrompt

Prompts to ask the user.

📨 TemplateRequest

TemplateRequest is the type of requests sent as part of a 📞 Template call.

info ProgramInfo

The plugin program to use.

project_name string

The name of the project we are templating.

📨 TemplateResponse

TemplateResponse is the type of responses sent by a 📞 Template call.