workspace

package
v3.181.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 27, 2025 License: Apache-2.0 Imports: 65 Imported by: 118

Documentation

Index

Constants

View Source 
const (
	// BackupDir is the name of the folder where backup stack information is stored.
	BackupDir = "backups"
	// BookkeepingDir is the name of our bookkeeping folder, we store state here (like .git for git).
	BookkeepingDir = ".pulumi"
	// ConfigDir is the name of the folder that holds local configuration information.
	ConfigDir = "config"
	// GitDir is the name of the folder git uses to store information.
	GitDir = ".git"
	// HistoryDir is the name of the directory that holds historical information for projects.
	HistoryDir = "history"
	// PluginDir is the name of the directory containing plugins.
	PluginDir = "plugins"
	// PolicyDir is the name of the directory that holds policy packs.
	PolicyDir = "policies"
	// StackDir is the name of the directory that holds stack information for projects.
	StackDir = "stacks"
	// LockDir is the name of the directory that holds locking information for projects.
	LockDir = "locks"
	// TemplateDir is the name of the directory containing templates.
	TemplateDir = "templates"
	// TemplatePolicyDir is the name of the directory containing templates for Policy Packs.
	TemplatePolicyDir = "templates-policy"
	// WorkspaceDir is the name of the directory that holds workspace information for projects.
	WorkspaceDir = "workspaces"

	// IgnoreFile is the name of the file that we use to control what to upload to the service.
	IgnoreFile = ".pulumiignore"

	// ProjectFile is the base name of a project file.
	ProjectFile = "Pulumi"
	// DeploymentSuffix is the base suffix for deployment settings files (e.g. "Pulumi.<stack>.deploy.yaml").
	DeploymentSuffix = "deploy"
	// RepoFile is the name of the file that holds information specific to the entire repository.
	RepoFile = "settings.json"
	// WorkspaceFile is the name of the file that holds workspace information.
	WorkspaceFile = "workspace.json"
	// CachedVersionFile is the name of the file we use to store when we last checked if the CLI was out of date
	CachedVersionFile = ".cachedVersionInfo"

	// PulumiHomeEnvVar is a path to the '.pulumi' folder with plugins, access token, etc.
	// The folder can have any name, not necessarily '.pulumi'.
	// It defaults to the '<user's home>/.pulumi' if not specified.
	PulumiHomeEnvVar = "PULUMI_HOME"

	// PolicyPackFile is the base name of a Pulumi policy pack file.
	PolicyPackFile = "PulumiPolicy"

	// PluginFile is the base name of a Pulumi plugin file.
	PluginFile = "PulumiPlugin"
)
View Source 
const (
	AnalyzerPlugin  = apitype.AnalyzerPlugin
	LanguagePlugin  = apitype.LanguagePlugin
	ResourcePlugin  = apitype.ResourcePlugin
	ConverterPlugin = apitype.ConverterPlugin
	ToolPlugin      = apitype.ToolPlugin
)

ProductKind types definition

Deprecated: PluginKind type was moved to "github.com/pulumi/pulumi/sdk/v3/go/common/apitype"

View Source 
const PulumiCredentialsPathEnvVar = "PULUMI_CREDENTIALS_PATH"

PulumiCredentialsPathEnvVar is a path to the folder where credentials are stored. We use this in testing so that tests which log in and out do not impact the local developer's credentials or tests interacting with one another

View Source 
const PulumiTagsConfigKey = "pulumi:tags"

To mitigate an import cycle, we define this here.

View Source 
const RetryCount = 6

Variables

View Source 
var ErrProjectNotFound = errors.New("no project file found")
View Source 
var ErrPulumiCloudUnauthorized = errors.New("unauthorized")
View Source 
var PluginNameRegexp = func() *regexp.Regexp {
	part := func(name string) string {
		return "(?P<" + name + ">[a-zA-Z0-9-][a-zA-Z0-9-_.]*[a-zA-Z0-9])"
	}

	return regexp.MustCompile(`^((` + part("Source") + `/)?(` + part("Publisher") + `/))?` + part("Name") + `$`)
}()
View Source 
var ProjectSchema *jsonschema.Schema

Functions

func ApplyProjectConfig added in v3.44.0 

func ApplyProjectConfig(
	ctx context.Context,
	stackName string,
	project *Project,
	stackEnv esc.Value,
	stackConfig config.Map,
	encrypter config.Encrypter,
) error

ApplyConfigDefaults applies the default values for the project configuration onto the stack configuration without validating the contents of stack config values. This is because sometimes during pulumi config ls and pulumi config get, if users are using PassphraseDecrypter, we don't want to always prompt for the values when not necessary

func CopyTemplateFiles 

func CopyTemplateFiles(
	sourceDir, destDir string, force bool, projectName string, projectDescription string,
) error

CopyTemplateFiles does the actual copy operation to a destination directory.

func CopyTemplateFilesDryRun 

func CopyTemplateFilesDryRun(sourceDir, destDir, projectName string) error

CopyTemplateFilesDryRun does a dry run of copying a template to a destination directory, to ensure it won't overwrite any files.

func DeleteAccount 

func DeleteAccount(key string) error

DeleteAccount deletes an account underneath the given key.

func DeleteAllAccounts 

func DeleteAllAccounts() error

func DetectPluginPathFrom added in v3.171.0 

func DetectPluginPathFrom(dir string) (string, error)

DetectPluginPathFrom locates the closest plugin from the given path, searching "upwards" in the directory hierarchy. If no project is found, an empty path is returned.

func DetectPolicyPackPathAt added in v3.128.0 

func DetectPolicyPackPathAt(path string) (string, error)

DetectPolicyPackPathAt locates the PulumiPolicy file at the given path. If no project is found, an empty path is returned. Unlike DetectPolicyPackPathFrom, this function does not search upwards in the directory hierarchy.

func DetectPolicyPackPathFrom 

func DetectPolicyPackPathFrom(path string) (string, error)

DetectPolicyPackPathFrom locates the closest Pulumi policy project from the given path, searching "upwards" in the directory hierarchy. If no project is found, an empty path is returned.

func DetectProjectPath 

func DetectProjectPath() (string, error)

DetectProjectPath locates the closest project from the current working directory, or an error if not found.

func DetectProjectPathFrom 

func DetectProjectPathFrom(dir string) (string, error)

DetectProjectPathFrom locates the closest project from the given path, searching "upwards" in the directory hierarchy. If no project is found, an empty path is returned.

func DetectProjectStackDeploymentPath added in v3.121.0 

func DetectProjectStackDeploymentPath(stackName tokens.QName) (string, error)

func DownloadToFile added in v3.37.0 

func DownloadToFile(
	ctx context.Context,
	pkgPlugin PluginSpec,
	wrapper func(stream io.ReadCloser, size int64) io.ReadCloser,
	retry func(err error, attempt int, limit int, delay time.Duration),
) (*os.File, error)

DownloadToFile downloads the given PluginInfo to a temporary file and returns that temporary file. This has some retry logic to re-attempt the download if it errors for any reason. The context supplied may be used for cancellable I/O.

func GetCachedVersionFilePath 

func GetCachedVersionFilePath() (string, error)

GetCachedVersionFilePath returns the location where the CLI caches information from pulumi.com on the newest available version of the CLI

func GetPluginDir 

func GetPluginDir() (string, error)

GetPluginDir returns the directory in which plugins on the current machine are managed.

func GetPluginPath 

func GetPluginPath(ctx context.Context, d diag.Sink, spec PluginSpec, projectPlugins []ProjectPlugin,
) (string, error)

GetPluginPath finds a plugin's path by its kind, name, and optional version. It will match the latest version that is >= the version specified. If no version is supplied, the latest plugin for that given kind/name pair is loaded, using standard semver sorting rules. A plugin may be overridden entirely by placing it on your $PATH, though it is possible to opt out of this behavior by setting PULUMI_IGNORE_AMBIENT_PLUGINS to any non-empty value.

func GetPolicyDir 

func GetPolicyDir(orgName string) (string, error)

GetPolicyDir returns the directory in which an organization's Policy Packs on the current machine are managed.

func GetPolicyPath 

func GetPolicyPath(orgName, name, version string) (string, bool, error)

GetPolicyPath finds a PolicyPack by its name version, as well as a bool marked true if the path already exists and is a directory.

func GetPulumiHomeDir 

func GetPulumiHomeDir() (string, error)

GetPulumiHomeDir returns the path of the '.pulumi' folder where Pulumi puts its artifacts.

func GetPulumiPath 

func GetPulumiPath(elem ...string) (string, error)

GetPulumiPath returns the path to a file or directory under the '.pulumi' folder. It joins the path of the '.pulumi' folder with elements passed as arguments.

func GetTemplateDir 

func GetTemplateDir(templateKind TemplateKind) (string, error)

GetTemplateDir returns the directory in which templates on the current machine are stored.

func HasPlugin 

func HasPlugin(spec PluginSpec) bool

HasPlugin returns true if the given plugin exists.

func HasPluginGTE 

func HasPluginGTE(spec PluginSpec) (bool, error)

HasPluginGTE returns true if the given plugin exists at the given version number or greater.

func InferFullTypeName added in v3.44.0 

func InferFullTypeName(typeName string, itemsType *ProjectConfigItemsType) string

func IsPluginBundled added in v3.78.0 

func IsPluginBundled(kind apitype.PluginKind, name string) bool

We currently bundle some plugins with "pulumi" and thus expect them to be next to the pulumi binary. Eventually we want to fix this so new plugins are true plugins in the plugin cache.

func IsPluginKind deprecated 

func IsPluginKind(k string) bool

IsPluginKind returns true if k is a valid plugin kind, and false otherwise.

Deprecated: IsPluginKind type was moved to "github.com/pulumi/pulumi/sdk/v3/go/common/apitype"

func IsTemplateURL 

func IsTemplateURL(templateNamePathOrURL string) bool

IsTemplateURL returns true if templateNamePathOrURL starts with "https://" (SSL) or "git@" (SSH).

func NewMissingError 

func NewMissingError(
	spec PluginSpec, includeAmbient bool,
) error

NewMissingError allocates a new error indicating the given plugin info was not found.

func NewRetryableClient added in v3.99.0 

func NewRetryableClient() *http.Client

func ReadCloserProgressBar 

func ReadCloserProgressBar(
	closer io.ReadCloser, size int64, message string, colorization colors.Colorization,
) io.ReadCloser

ReadCloserProgressBar displays a progress bar for the given closer and returns a wrapper closer to manipulate it.

func RetrieveGitFolder 

func RetrieveGitFolder(ctx context.Context, rawurl string, path string) (string, error)

RetrieveGitFolder downloads the repo to path and returns the full path on disk.

func RetrieveZIPTemplateFolder added in v3.92.0 

func RetrieveZIPTemplateFolder(templateURL *url.URL, tempDir string, opts ...RequestOption) (string, error)

func RewriteConfigPathIntoStackConfigDir added in v3.44.0 

func RewriteConfigPathIntoStackConfigDir(project map[string]interface{}) (map[string]interface{}, error)

RewriteConfigPathIntoStackConfigDir checks if the project is using the old "config" property to declare a path to the stack configuration directory. If that is the case, we rewrite it such that the value in config: {value} is moved to stackConfigDir: {value}. if the user defines both values as strings, we error out.

func RewriteShorthandConfigValues added in v3.44.0 

func RewriteShorthandConfigValues(project map[string]interface{}) map[string]interface{}

RewriteShorthandConfigValues rewrites short-hand version of configuration into a configuration type for example the following config block definition: 

config:
	  instanceSize: t3.mirco
	  aws:region: us-west-2

will be rewritten into a typed value: 

config:
   instanceSize:
      default: t3.micro
   aws:region:
      value: us-west-2

Note that short-hand values without namespaces (project config) are turned into a type where as short-hand values with namespaces (such as aws:region) are turned into a value.

func SaveProject 

func SaveProject(proj *Project) error

SaveProject saves the project file on top of the existing one, using the standard location.

func SaveProjectStack 

func SaveProjectStack(stackName tokens.QName, stack *ProjectStack) error

func SaveProjectStackDeployment added in v3.121.0 

func SaveProjectStackDeployment(stackName tokens.QName, deployment *ProjectStackDeployment) error

func SetBackendConfigDefaultOrg added in v3.18.0 

func SetBackendConfigDefaultOrg(backendURL, defaultOrg string) error

func SimplifyMarshalledProject added in v3.44.0 

func SimplifyMarshalledProject(raw interface{}) (map[string]interface{}, error)

func SimplifyMarshalledValue added in v3.45.0 

func SimplifyMarshalledValue(raw interface{}) (interface{}, error)

Cast any map[interface{}] from the yaml decoder to map[string]

func SortPackageDescriptors added in v3.146.0 

func SortPackageDescriptors(x PackageDescriptor, y PackageDescriptor) int

SortPackageDescriptors is a comparison function for PackageDescriptors that sorts by version, with version-less package descriptors appearing first. It returns -1 if the first argument should appear before the second, 0 if they are equal, and 1 if the first argument should appear after the second. Designed for use with functions like slices.SortFunc.

func StoreAccount 

func StoreAccount(key string, account Account, current bool) error

StoreAccount saves the given account underneath the given key.

func StoreCredentials 

func StoreCredentials(creds Credentials) error

StoreCredentials updates the stored credentials on the machine, replacing the existing set. If the credentials are empty, the auth file will be deleted rather than just serializing an empty map.

func StorePulumiConfig added in v3.18.0 

func StorePulumiConfig(config PulumiConfig) error

func ValidateConfigValue added in v3.44.0 

func ValidateConfigValue(typeName string, itemsType *ProjectConfigItemsType, value interface{}) bool

ValidateConfig validates the config value against its config type definition. We use this to validate the default config values alongside their type definition but also to validate config values coming from individual stacks.

func ValidateProject added in v3.40.1 

func ValidateProject(raw interface{}) error

func ValidateStackConfigAndApplyProjectConfig added in v3.44.0 

func ValidateStackConfigAndApplyProjectConfig(
	ctx context.Context,
	stackName string,
	project *Project,
	stackEnv esc.Value,
	stackConfig config.Map,
	encrypter config.Encrypter,
	decrypter config.Decrypter,
) error

Types

type Account 

type Account struct {
	// The access token for this account.
	AccessToken string `json:"accessToken,omitempty"`
	// The username for this account.
	Username string `json:"username,omitempty"`
	// The organizations for this account.
	Organizations []string `json:"organizations,omitempty"`
	// The last time this token was validated.
	LastValidatedAt time.Time `json:"lastValidatedAt,omitempty"`
	// Allow insecure server connections when using SSL.
	Insecure bool `json:"insecure,omitempty"`
	// Information about the token used to authenticate.
	TokenInformation *TokenInformation `json:"tokenInformation,omitempty"`
}

Account holds the information associated with a Pulumi account.

func GetAccount 

func GetAccount(key string) (Account, error)

GetAccount returns an account underneath a given key.

Note that the account may not be fully populated: it may only have a valid AccessToken. In that case, it is up to the caller to fill in the username and last validation time.

type Analyzers 

type Analyzers []tokens.QName

Analyzers is a list of analyzers to run on this project.

type BackendConfig added in v3.18.0 

type BackendConfig struct {
	DefaultOrg string `json:"defaultOrg,omitempty"` // The default org for this backend config.
}

type Credentials 

type Credentials struct {
	Current      string             `json:"current,omitempty"`      // the currently selected key.
	AccessTokens map[string]string  `json:"accessTokens,omitempty"` // a map of arbitrary key strings to tokens.
	Accounts     map[string]Account `json:"accounts,omitempty"`     // a map of arbitrary keys to account info.
}

Credentials hold the information necessary for authenticating Pulumi Cloud API requests. It contains a map from the cloud API URL to the associated access token.

func GetStoredCredentials 

func GetStoredCredentials() (Credentials, error)

GetStoredCredentials returns any credentials stored on the local machine.

type Environment added in v3.88.0 

type Environment struct {
	// contains filtered or unexported fields
}

func NewEnvironment added in v3.89.0 

func NewEnvironment(envs []string) *Environment

func (*Environment) Append added in v3.95.0 

func (e *Environment) Append(envs ...string) *Environment

func (*Environment) Definition added in v3.95.0 

func (e *Environment) Definition() []byte

func (*Environment) Imports added in v3.95.0 

func (e *Environment) Imports() []string

func (Environment) MarshalJSON added in v3.88.0 

func (e Environment) MarshalJSON() ([]byte, error)

func (Environment) MarshalYAML added in v3.88.0 

func (e Environment) MarshalYAML() (any, error)

func (*Environment) Remove added in v3.95.0 

func (e *Environment) Remove(env string) *Environment

func (*Environment) UnmarshalJSON added in v3.88.0 

func (e *Environment) UnmarshalJSON(b []byte) error

func (*Environment) UnmarshalYAML added in v3.88.0 

func (e *Environment) UnmarshalYAML(n *yaml.Node) error

type MissingError 

type MissingError struct {
	// contains filtered or unexported fields
}

MissingError is returned by functions that attempt to load plugins if a plugin can't be located.

func (*MissingError) Error 

func (err *MissingError) Error() string

type PackageDescriptor added in v3.133.0 

type PackageDescriptor struct {
	// A specification for the plugin that provides the package.
	PluginSpec

	// An optional parameterization to apply to the providing plugin to produce
	// the package.
	Parameterization *Parameterization
}

A PackageDescriptor specifies a package: the source PluginSpec that provides it, and any parameterization that must be applied to that plugin in order to produce the package.

func NewPackageDescriptor added in v3.159.0 

func NewPackageDescriptor(spec PluginSpec, parameterization *Parameterization) PackageDescriptor

func (PackageDescriptor) PackageName added in v3.144.0 

func (pd PackageDescriptor) PackageName() string

PackageName returns the name of the package.

func (PackageDescriptor) PackageVersion added in v3.144.0 

func (pd PackageDescriptor) PackageVersion() *semver.Version

PackageVersion returns the version of the package.

func (PackageDescriptor) String added in v3.144.0 

func (pd PackageDescriptor) String() string

type PackageSpec added in v3.157.0 

type PackageSpec struct {
	Source     string   `json:"source" yaml:"source"`
	Version    string   `json:"version,omitempty" yaml:"version,omitempty"`
	Parameters []string `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

PackageSpec defines the structured format for a package dependency

type Parameterization added in v3.133.0 

type Parameterization struct {
	// The name of the package that will be produced by the parameterization.
	Name string
	// The version of the package that will be produced by the parameterization.
	Version semver.Version
	// A plugin-dependent bytestring representing the value of the parameter to be
	// passed to the plugin.
	Value []byte
}

A Parameterization may be applied to a supporting plugin to yield a package.

type PluginContent added in v3.37.0 

type PluginContent interface {
	io.Closer
	// contains filtered or unexported methods
}

func DirPlugin added in v3.37.0 

func DirPlugin(rootPath string) PluginContent

func SingleFilePlugin added in v3.37.0 

func SingleFilePlugin(f *os.File, spec PluginSpec) PluginContent

func TarPlugin added in v3.37.0 

func TarPlugin(tgz io.ReadCloser) PluginContent

type PluginInfo 

type PluginInfo struct {
	Name         string             // the simple name of the plugin.
	Path         string             // the path that a plugin was loaded from (this will always be a directory)
	Kind         apitype.PluginKind // the kind of the plugin (language, resource, etc).
	Version      *semver.Version    // the plugin's semantic version, if present.
	Size         uint64             // the size of the plugin, in bytes.
	InstallTime  time.Time          // the time the plugin was installed.
	LastUsedTime time.Time          // the last time the plugin was used.
	SchemaPath   string             // if set, used as the path for loading and caching the schema
	SchemaTime   time.Time          // if set and newer than the file at SchemaPath, used to invalidate a cached schema
}

PluginInfo provides basic information about a plugin. Each plugin gets installed into a system-wide location, by default `~/.pulumi/plugins/<kind>-<name>-<version>/`. A plugin may contain multiple files, however the primary loadable executable must be named `pulumi-<kind>-<name>`.

func GetPluginInfo added in v3.35.0 

func GetPluginInfo(ctx context.Context, d diag.Sink, spec PluginSpec, projectPlugins []ProjectPlugin,
) (*PluginInfo, error)

func GetPlugins 

func GetPlugins() ([]PluginInfo, error)

GetPlugins returns a list of installed plugins without size info and last accessed metadata. Plugin size requires recursively traversing the plugin directory, which can be extremely expensive with the introduction of nodejs multilang components that have deeply nested node_modules folders.

func GetPluginsWithMetadata added in v3.4.0 

func GetPluginsWithMetadata() ([]PluginInfo, error)

GetPluginsWithMetadata returns a list of installed plugins with metadata about size, and last access (POOR RUNTIME PERF). Plugin size requires recursively traversing the plugin directory, which can be extremely expensive with the introduction of nodejs multilang components that have deeply nested node_modules folders.

func LegacySelectCompatiblePlugin added in v3.96.0 

func LegacySelectCompatiblePlugin(
	plugins []PluginInfo, spec PluginSpec,
) *PluginInfo

LegacySelectCompatiblePlugin selects a plugin from the list of plugins with the given kind and name that satisfies the requested version. It returns the highest version plugin greater than the requested version, or an error if no such plugin could be found.

If there exist plugins in the plugin list that don't have a version, LegacySelectCompatiblePlugin will select them if there are no other compatible plugins available.

func SelectCompatiblePlugin 

func SelectCompatiblePlugin(
	plugins []PluginInfo, spec PluginSpec,
) *PluginInfo

SelectCompatiblePlugin selects a plugin from the list of plugins with the given kind and name that sastisfies the requested semver range. It returns the highest version plugin that satisfies the requested constraints, or an error if no such plugin could be found.

If there exist plugins in the plugin list that don't have a version, SelectCompatiblePlugin will select them if there are no other compatible plugins available.

func SelectPrereleasePlugin added in v3.147.0 

func SelectPrereleasePlugin(
	plugins []PluginInfo, spec PluginSpec,
) *PluginInfo

SelectPrereleasePlugin selects a plugin from the list of plugins, which matches the exact version we are looking for, based on the commit hash.

func (*PluginInfo) Delete 

func (info *PluginInfo) Delete() error

Delete removes the plugin from the cache. It also deletes any supporting files in the cache, which includes any files that contain the same prefix as the plugin itself.

func (*PluginInfo) SetFileMetadata 

func (info *PluginInfo) SetFileMetadata(path string) error

SetFileMetadata adds extra metadata from the given file, representing this plugin's directory.

func (*PluginInfo) Spec added in v3.39.0 

func (info *PluginInfo) Spec() PluginSpec

Spec returns the PluginSpec for this PluginInfo

func (PluginInfo) String 

func (info PluginInfo) String() string

type PluginKind deprecated 

type PluginKind = apitype.PluginKind

Re exporting PluginKind to keep backward compatibility, this should be kept in sync with the definitions in sdk/go/common/apitype/plugins.go

Deprecated: PluginKind type was moved to "github.com/pulumi/pulumi/sdk/v3/go/common/apitype"

type PluginOptions added in v3.37.0 

type PluginOptions struct {
	Name    string `json:"name" yaml:"name"`
	Version string `json:"version,omitempty" yaml:"version,omitempty"`
	Path    string `json:"path" yaml:"path"`
}

type PluginProject 

type PluginProject struct {
	// Runtime is a required runtime that executes code.
	Runtime ProjectRuntimeInfo `json:"runtime" yaml:"runtime"`
}

func LoadPluginProject 

func LoadPluginProject(path string) (*PluginProject, error)

LoadPluginProject reads a plugin project definition from a file.

func (*PluginProject) Validate 

func (proj *PluginProject) Validate() error

type PluginSource added in v3.26.0 

type PluginSource interface {
	// Download fetches an io.ReadCloser for this plugin and also returns the size of the response (if known).
	// The context supplied enables I/O to be canceled as needed.
	Download(ctx context.Context,
		version semver.Version, opSy string, arch string,
		getHTTPResponse func(*http.Request) (io.ReadCloser, int64, error)) (io.ReadCloser, int64, error)

	// GetLatestVersion tries to find the latest version for this plugin. This is currently only supported for
	// plugins we can get from GitHub releases. The context supplied enables I/O to be canceled as needed.
	GetLatestVersion(ctx context.Context,
		getHTTPResponse func(*http.Request) (io.ReadCloser, int64, error)) (*semver.Version, error)

	// A base URL that can uniquely identify the source. Has the same structure as the PluginDownloadURL
	// schema option. Example: "github://api.github.com/pulumi/pulumi-aws".
	URL() string
}

PluginSource deals with downloading a specific version of a plugin, or looking up the latest version of it.

type PluginSpec added in v3.39.0 

type PluginSpec struct {
	Name              string             // the simple name of the plugin.
	Kind              apitype.PluginKind // the kind of the plugin (language, resource, etc).
	Version           *semver.Version    // the plugin's semantic version, if present.
	PluginDownloadURL string             // an optional server to use when downloading this plugin.
	PluginDir         string             // if set, will be used as the root plugin dir instead of ~/.pulumi/plugins.

	// if set will be used to validate the plugin downloaded matches. This is keyed by "$os-$arch", e.g. "linux-x64".
	Checksums map[string][]byte
}

PluginSpec provides basic specification for a plugin.

func NewPluginSpec added in v3.145.0 

func NewPluginSpec(
	ctx context.Context,
	source string,
	kind apitype.PluginKind,
	version *semver.Version,
	pluginDownloadURL string,
	checksums map[string][]byte,
) (PluginSpec, error)

func (PluginSpec) Dir added in v3.39.0 

func (spec PluginSpec) Dir() string

Dir gets the expected plugin directory for this plugin.

func (PluginSpec) DirPath added in v3.39.0 

func (spec PluginSpec) DirPath() (string, error)

DirPath returns the directory where this plugin should be installed.

func (PluginSpec) Download added in v3.39.0 

func (spec PluginSpec) Download(ctx context.Context) (io.ReadCloser, int64, error)

Download fetches an io.ReadCloser for this plugin and also returns the size of the response (if known). The context allows for I/O cancellation.

func (PluginSpec) File added in v3.39.0 

func (spec PluginSpec) File() string

File gets the expected filename for this plugin, excluding any platform specific suffixes (e.g. ".exe" on windows).

func (PluginSpec) GetLatestVersion added in v3.39.0 

func (spec PluginSpec) GetLatestVersion(ctx context.Context) (*semver.Version, error)

GetLatestVersion tries to find the latest version for this plugin. This is currently only supported for plugins we can get from github releases. The context allows for I/O cancellation.

func (PluginSpec) GetSource added in v3.39.0 

func (spec PluginSpec) GetSource() (PluginSource, error)

func (PluginSpec) Install added in v3.39.0 

func (spec PluginSpec) Install(tgz io.ReadCloser, reinstall bool) error

Install installs a plugin's tarball into the cache. See InstallWithContext for details.

func (PluginSpec) InstallDependencies added in v3.148.0 

func (spec PluginSpec) InstallDependencies(ctx context.Context) error

func (PluginSpec) InstallWithContext added in v3.39.0 

func (spec PluginSpec) InstallWithContext(ctx context.Context, content PluginContent, reinstall bool) error

InstallWithContext installs a plugin's tarball into the cache. It validates that plugin names are in the expected format. Previous versions of Pulumi extracted the tarball to a temp directory first, and then renamed the temp directory to the final directory. The rename operation fails often enough on Windows due to aggressive virus scanners opening files in the temp directory. To address this, we now extract the tarball directly into the final directory, and use file locks to prevent concurrent installs.

Each plugin has its own file lock, with the same name as the plugin directory, with a `.lock` suffix. During installation an empty file with a `.partial` suffix is created, indicating that installation is in-progress. The `.partial` file is deleted when installation is complete, indicating that the plugin has finished installing. If a failure occurs during installation, the `.partial` file will remain, indicating the plugin wasn't fully installed. The next time the plugin is installed, the old installation directory will be removed and replaced with a fresh installation.

func (PluginSpec) IsGitPlugin added in v3.159.0 

func (spec PluginSpec) IsGitPlugin() bool

IsGitPlugin returns if the plugin comes from the git source

func (PluginSpec) LocalName added in v3.147.0 

func (spec PluginSpec) LocalName() (string, string)

LocalName returns the local name of the plugin, which is used in the directory name, and a path within that directory if the plugin is located in a subdirectory.

func (PluginSpec) LockFilePath added in v3.39.0 

func (spec PluginSpec) LockFilePath() (string, error)

LockFilePath returns the full path to the plugin's lock file used during installation to prevent concurrent installs.

func (PluginSpec) PartialFilePath added in v3.39.0 

func (spec PluginSpec) PartialFilePath() (string, error)

PartialFilePath returns the full path to the plugin's partial file used during installation to indicate installation of the plugin hasn't completed yet.

func (PluginSpec) String added in v3.39.0 

func (spec PluginSpec) String() string

func (PluginSpec) SubDir added in v3.148.0 

func (spec PluginSpec) SubDir() string

SubDir gets the expected subdirectory for this plugin.

type PluginVersionNotFoundError added in v3.166.0 

type PluginVersionNotFoundError error

type Plugins added in v3.37.0 

type Plugins struct {
	Providers []PluginOptions `json:"providers,omitempty" yaml:"providers,omitempty"`
	Languages []PluginOptions `json:"languages,omitempty" yaml:"languages,omitempty"`
	Analyzers []PluginOptions `json:"analyzers,omitempty" yaml:"analyzers,omitempty"`
}

type PolicyPackProject 

type PolicyPackProject struct {
	// Runtime is a required runtime that executes code.
	Runtime ProjectRuntimeInfo `json:"runtime" yaml:"runtime"`
	// Version specifies the version of the policy pack. If set, it will override the
	// version specified in `package.json` for Node.js policy packs.
	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	// Main is an optional override for the program's main entry-point location.
	Main string `json:"main,omitempty" yaml:"main,omitempty"`

	// Description is an optional informational description.
	Description *string `json:"description,omitempty" yaml:"description,omitempty"`
	// Author is an optional author that created this project.
	Author *string `json:"author,omitempty" yaml:"author,omitempty"`
	// Website is an optional website for additional info about this project.
	Website *string `json:"website,omitempty" yaml:"website,omitempty"`
	// License is the optional license governing this project's usage.
	License *string `json:"license,omitempty" yaml:"license,omitempty"`
	// contains filtered or unexported fields
}

func LoadPolicyPack 

func LoadPolicyPack(path string) (*PolicyPackProject, error)

LoadPolicyPack reads a policy pack definition from a file.

func (PolicyPackProject) RawValue added in v3.50.0 

func (proj PolicyPackProject) RawValue() []byte

func (*PolicyPackProject) Save 

func (proj *PolicyPackProject) Save(path string) error

Save writes a project definition to a file.

func (*PolicyPackProject) Validate 

func (proj *PolicyPackProject) Validate() error

type PolicyPackTemplate 

type PolicyPackTemplate struct {
	Dir         string // The directory containing PulumiPolicy.yaml.
	Name        string // The name of the template.
	Description string // Description of the template.
	Error       error  // Non-nil if the template is broken.
}

PolicyPackTemplate represents a Policy Pack template.

func LoadPolicyPackTemplate 

func LoadPolicyPackTemplate(path string) (PolicyPackTemplate, error)

LoadPolicyPackTemplate returns a Policy Pack template from a path.

func (PolicyPackTemplate) Errored added in v3.49.0 

func (t PolicyPackTemplate) Errored() bool

Errored returns if the template has an error

type Project 

type Project struct {
	// Name is a required fully qualified name.
	Name tokens.PackageName `json:"name" yaml:"name"`
	// Runtime is a required runtime that executes code.
	Runtime ProjectRuntimeInfo `json:"runtime" yaml:"runtime"`
	// Main is an optional override for the program's main entry-point location.
	Main string `json:"main,omitempty" yaml:"main,omitempty"`

	// Description is an optional informational description.
	Description *string `json:"description,omitempty" yaml:"description,omitempty"`
	// Author is an optional author that created this project.
	Author *string `json:"author,omitempty" yaml:"author,omitempty"`
	// Website is an optional website for additional info about this project.
	Website *string `json:"website,omitempty" yaml:"website,omitempty"`
	// License is the optional license governing this project's usage.
	License *string `json:"license,omitempty" yaml:"license,omitempty"`

	// Config has been renamed to StackConfigDir.
	Config map[string]ProjectConfigType `json:"config,omitempty" yaml:"config,omitempty"`

	// StackConfigDir indicates where to store the Pulumi.<stack-name>.yaml files, combined with the folder
	// Pulumi.yaml is in.
	StackConfigDir string `json:"stackConfigDir,omitempty" yaml:"stackConfigDir,omitempty"`

	// Template is an optional template manifest, if this project is a template.
	Template *ProjectTemplate `json:"template,omitempty" yaml:"template,omitempty"`

	// Backend is an optional backend configuration
	Backend *ProjectBackend `json:"backend,omitempty" yaml:"backend,omitempty"`

	// Options is an optional set of project options
	Options *ProjectOptions `json:"options,omitempty" yaml:"options,omitempty"`

	// Packages is a map of package dependencies that can be either strings or PackageSpecs
	Packages map[string]packageValue `json:"packages,omitempty" yaml:"packages,omitempty"`

	Plugins *Plugins `json:"plugins,omitempty" yaml:"plugins,omitempty"`

	// Handle additional keys, albeit in a way that will remove comments and trivia.
	AdditionalKeys map[string]interface{} `yaml:",inline"`
	// contains filtered or unexported fields
}

Project is a Pulumi project manifest.

We explicitly add yaml tags (instead of using the default behavior from https://github.com/ghodss/yaml which works in terms of the JSON tags) so we can directly marshall and unmarshall this struct using go-yaml an have the fields in the serialized object match the order they are defined in this struct.

TODO[pulumi/pulumi#423]: use DOM based marshalling so we can roundtrip the seralized structure perfectly.

func DetectProject 

func DetectProject() (*Project, error)

DetectProject loads the closest project from the current working directory, or an error if not found.

func DetectProjectAndPath 

func DetectProjectAndPath() (*Project, string, error)

DetectProjectAndPath loads the closest package from the current working directory, or an error if not found. It also returns the path where the package was found.

func DetectProjectStackPath 

func DetectProjectStackPath(stackName tokens.QName) (*Project, string, error)

DetectProjectStackPath returns the name of the file to store stack specific project settings in. We place stack specific settings next to the Pulumi.yaml file, named like: Pulumi.<stack-name>.yaml

func LoadProject 

func LoadProject(path string) (*Project, error)

LoadProject reads a project definition from a file.

func LoadProjectBytes added in v3.95.0 

func LoadProjectBytes(b []byte, path string, marshaller encoding.Marshaler) (*Project, error)

LoadProjectBytes reads a project definition from a byte slice.

func (*Project) AddConfigStackTags added in v3.103.0 

func (proj *Project) AddConfigStackTags(tags map[string]string)

AddConfigStackTags sets the project tags config to the given map of tags.

func (*Project) AddPackage added in v3.163.0 

func (proj *Project) AddPackage(name string, spec PackageSpec)

func (*Project) GetPackageSpecs added in v3.157.0 

func (proj *Project) GetPackageSpecs() map[string]PackageSpec

GetPackageSpecs returns a map of package names to their corresponding PackageSpecs

func (Project) RawValue added in v3.50.0 

func (proj Project) RawValue() []byte

func (*Project) Save 

func (proj *Project) Save(path string) error

Save writes a project definition to a file.

func (*Project) Validate 

func (proj *Project) Validate() error

type ProjectBackend 

type ProjectBackend struct {
	// URL is optional field to explicitly set backend url
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
}

ProjectBackend is the configuration for where the backend state is stored. If unset, will use the system's currently logged-in backend.

Use the same URL format that is passed to "pulumi login", see https://www.pulumi.com/docs/cli/commands/pulumi_login/

To explicitly use the Pulumi Cloud backend, use URL "https://api.pulumi.com"

type ProjectConfigItemsType added in v3.44.0 

type ProjectConfigItemsType struct {
	Type  string                  `json:"type,omitempty" yaml:"type,omitempty"`
	Items *ProjectConfigItemsType `json:"items,omitempty" yaml:"items,omitempty"`
}

type ProjectConfigKey added in v3.44.0 

type ProjectConfigKey = string

type ProjectConfigType added in v3.44.0 

type ProjectConfigType struct {
	Type        *string                 `json:"type,omitempty" yaml:"type,omitempty"`
	Description string                  `json:"description,omitempty" yaml:"description,omitempty"`
	Items       *ProjectConfigItemsType `json:"items,omitempty" yaml:"items,omitempty"`
	Default     interface{}             `json:"default,omitempty" yaml:"default,omitempty"`
	Value       interface{}             `json:"value,omitempty" yaml:"value,omitempty"`
	Secret      bool                    `json:"secret,omitempty" yaml:"secret,omitempty"`
}

func (*ProjectConfigType) IsExplicitlyTyped added in v3.45.0 

func (configType *ProjectConfigType) IsExplicitlyTyped() bool

IsExplicitlyTyped returns whether the project config type is explicitly typed. When that is the case, we validate stack config values against this type, given that the stack config value is namespaced by the project.

func (*ProjectConfigType) TypeName added in v3.45.0 

func (configType *ProjectConfigType) TypeName() string

type ProjectOptions added in v3.14.0 

type ProjectOptions struct {
	// Refresh is the ability to always run a refresh as part of a pulumi update / preview / destroy
	Refresh string `json:"refresh,omitempty" yaml:"refresh,omitempty"`
}

type ProjectPlugin added in v3.39.0 

type ProjectPlugin struct {
	Name    string             // the simple name of the plugin.
	Kind    apitype.PluginKind // the kind of the plugin (language, resource, etc).
	Version *semver.Version    // the plugin's semantic version, if present.
	Path    string             // the path that a plugin is to be loaded from (this will always be a directory)
}

ProjectPlugin Information about a locally installed plugin specified by the project.

func (ProjectPlugin) Spec added in v3.39.0 

func (pp ProjectPlugin) Spec(ctx context.Context) (PluginSpec, error)

Spec Return a PluginSpec object for this project plugin.

type ProjectRuntimeInfo 

type ProjectRuntimeInfo struct {
	// contains filtered or unexported fields
}

func NewProjectRuntimeInfo 

func NewProjectRuntimeInfo(name string, options map[string]interface{}) ProjectRuntimeInfo

func (ProjectRuntimeInfo) MarshalJSON 

func (info ProjectRuntimeInfo) MarshalJSON() ([]byte, error)

func (ProjectRuntimeInfo) MarshalYAML 

func (info ProjectRuntimeInfo) MarshalYAML() (interface{}, error)

func (*ProjectRuntimeInfo) Name 

func (info *ProjectRuntimeInfo) Name() string

func (*ProjectRuntimeInfo) Options 

func (info *ProjectRuntimeInfo) Options() map[string]interface{}

func (*ProjectRuntimeInfo) SetOption 

func (info *ProjectRuntimeInfo) SetOption(key string, value interface{})

func (*ProjectRuntimeInfo) UnmarshalJSON 

func (info *ProjectRuntimeInfo) UnmarshalJSON(data []byte) error

func (*ProjectRuntimeInfo) UnmarshalYAML 

func (info *ProjectRuntimeInfo) UnmarshalYAML(unmarshal func(interface{}) error) error

type ProjectStack 

type ProjectStack struct {
	// SecretsProvider is this stack's secrets provider.
	SecretsProvider string `json:"secretsprovider,omitempty" yaml:"secretsprovider,omitempty"`
	// EncryptedKey is the KMS-encrypted ciphertext for the data key used for secrets encryption.
	// Only used for cloud-based secrets providers.
	EncryptedKey string `json:"encryptedkey,omitempty" yaml:"encryptedkey,omitempty"`
	// EncryptionSalt is this stack's base64 encoded encryption salt.  Only used for
	// passphrase-based secrets providers.
	EncryptionSalt string `json:"encryptionsalt,omitempty" yaml:"encryptionsalt,omitempty"`
	// Config is an optional config bag.
	Config config.Map `json:"config,omitempty" yaml:"config,omitempty"`
	// Environment is an optional environment definition or list of environments.
	Environment *Environment `json:"environment,omitempty" yaml:"environment,omitempty"`
	// contains filtered or unexported fields
}

ProjectStack holds stack specific information about a project.

func DetectProjectStack 

func DetectProjectStack(diags diag.Sink, stackName tokens.QName) (*ProjectStack, error)

func LoadProjectStack 

func LoadProjectStack(sink diag.Sink, project *Project, path string) (*ProjectStack, error)

LoadProjectStack reads a stack definition from a file.

func LoadProjectStackBytes added in v3.95.0 

func LoadProjectStackBytes(
	diags diag.Sink,
	project *Project,
	b []byte,
	path string,
	marshaller encoding.Marshaler,
) (*ProjectStack, error)

LoadProjectStack reads a stack definition from a byte slice.

func (ProjectStack) EnvironmentBytes added in v3.88.0 

func (ps ProjectStack) EnvironmentBytes() []byte

func (ProjectStack) RawValue added in v3.50.0 

func (ps ProjectStack) RawValue() []byte

func (*ProjectStack) Save 

func (ps *ProjectStack) Save(path string) error

Save writes a project definition to a file.

type ProjectStackDeployment added in v3.121.0 

type ProjectStackDeployment struct {
	DeploymentSettings apitype.DeploymentSettings `json:"settings" yaml:"settings"`
}

func DetectProjectStackDeployment added in v3.121.0 

func DetectProjectStackDeployment(stackName tokens.QName) (*ProjectStackDeployment, error)

func LoadProjectStackDeployment added in v3.121.0 

func LoadProjectStackDeployment(path string) (*ProjectStackDeployment, error)

func LoadProjectStackDeploymentBytes added in v3.121.0 

func LoadProjectStackDeploymentBytes(
	b []byte,
	path string,
	marshaller encoding.Marshaler,
) (*ProjectStackDeployment, error)

func (*ProjectStackDeployment) Save added in v3.121.0 

func (psd *ProjectStackDeployment) Save(path string) error

type ProjectTemplate 

type ProjectTemplate = apitype.ProjectTemplate

ProjectTemplate is a Pulumi project template manifest.

type ProjectTemplateConfigValue 

type ProjectTemplateConfigValue = apitype.ProjectTemplateConfigValue

ProjectTemplateConfigValue is a config value included in the project template manifest.

type PulumiConfig added in v3.18.0 

type PulumiConfig struct {
	BackendConfig map[string]BackendConfig `json:"backends,omitempty"` // a map of arbitrary backends configs.
}

func GetPulumiConfig added in v3.18.0 

func GetPulumiConfig() (PulumiConfig, error)

type RequestOption added in v3.146.0 

type RequestOption func(*http.Request)

RequestOption is a function that modifies an http.Request.

type Settings 

type Settings struct {
	// Stack is an optional default stack to use.
	Stack string `json:"stack,omitempty" yaml:"env,omitempty"`
}

Settings defines workspace settings shared amongst many related projects.

func (*Settings) IsEmpty 

func (s *Settings) IsEmpty() bool

IsEmpty returns true when the settings object is logically empty (no selected stack and nothing in the deprecated configuration bag).

type SortedPluginInfo 

type SortedPluginInfo []PluginInfo

SortedPluginInfo is a wrapper around PluginInfo that allows for sorting by version.

func (SortedPluginInfo) Len 

func (sp SortedPluginInfo) Len() int

func (SortedPluginInfo) Less 

func (sp SortedPluginInfo) Less(i, j int) bool

func (SortedPluginInfo) Swap 

func (sp SortedPluginInfo) Swap(i, j int)

type StackName added in v3.44.0 

type StackName = string

type Template 

type Template struct {
	Dir         string                                // The directory containing Pulumi.yaml.
	Name        string                                // The name of the template.
	Description string                                // Description of the template.
	Quickstart  string                                // Optional text to be displayed after template creation.
	Config      map[string]ProjectTemplateConfigValue // Optional template config.
	Error       error                                 // Non-nil if the template is broken.

	ProjectName        string // Name of the project.
	ProjectDescription string // Optional description of the project.
}

Template represents a project template.

func LoadTemplate 

func LoadTemplate(path string) (Template, error)

LoadTemplate returns a template from a path.

func (Template) Errored added in v3.48.0 

func (t Template) Errored() bool

Errored returns if the template has an error

type TemplateKind 

type TemplateKind int

TemplateKind describes the form of a template. 

const (
	// TemplateKindPulumiProject is a template for a Pulumi stack.
	TemplateKindPulumiProject TemplateKind = 0

	// TemplateKindPolicyPack is a template for a Policy Pack.
	TemplateKindPolicyPack TemplateKind = 1
)

type TemplateNotFoundError added in v3.154.0 

type TemplateNotFoundError struct {
	// contains filtered or unexported fields
}

func (TemplateNotFoundError) Error added in v3.154.0 

func (err TemplateNotFoundError) Error() string

type TemplateRepository 

type TemplateRepository struct {
	Root         string // The full path to the root directory of the repository.
	SubDirectory string // The full path to the sub directory within the repository.
	ShouldDelete bool   // Whether the root directory should be deleted.
}

TemplateRepository represents a repository of templates.

func RetrieveTemplates 

func RetrieveTemplates(ctx context.Context, templateNamePathOrURL string, offline bool,
	templateKind TemplateKind,
) (TemplateRepository, error)

RetrieveTemplates retrieves a "template repository" based on the specified name, path, or URL.

func RetrieveZIPTemplates added in v3.146.0 

func RetrieveZIPTemplates(templateURL string, opts ...RequestOption) (TemplateRepository, error)

func (TemplateRepository) Delete 

func (repo TemplateRepository) Delete() error

Delete deletes the template repository.

func (TemplateRepository) PolicyTemplates 

func (repo TemplateRepository) PolicyTemplates() ([]PolicyPackTemplate, error)

PolicyTemplates lists the policy templates in the repository.

func (TemplateRepository) Templates 

func (repo TemplateRepository) Templates() ([]Template, error)

Templates lists the templates in the repository.

type TokenInformation added in v3.86.0 

type TokenInformation struct {
	Name         string `json:"name"`                   // The name of the token.
	Organization string `json:"organization,omitempty"` // If this was an organization token, the organization it was for.
	Team         string `json:"team,omitempty"`         // If this was a team token, the team it was for.
}

Information about the token that was used to authenticate the current user. One (or none) of Team or Organization will be set, but not both.

type W 

type W interface {
	Settings() *Settings // returns a mutable pointer to the optional workspace settings info.
	Save() error         // saves any modifications to the workspace.
}

W offers functionality for interacting with Pulumi workspaces.

func New 

func New() (W, error)

New creates a new workspace using the current working directory.

func NewFrom 

func NewFrom(dir string) (W, error)

NewFrom creates a new Pulumi workspace in the given directory. Requires a Pulumi.yaml file be present in the folder hierarchy between dir and the .pulumi folder.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.