Documentation ¶
Overview ¶
info contains the types that bridged provider authors use to describe the mapping between Pulumi and Terraform providers.
As much as possible, this package should restrict itself to type declarations. Runtime behavior and advanced configuration should go in /pkg/tfbridge or more specialized packages.
Index ¶
- Constants
- func ComputeAutoNameDefault(ctx context.Context, options AutoNameOptions, ...) (interface{}, error)
- type Alias
- type AssetTranslation
- func (a *AssetTranslation) IsArchive() bool
- func (a *AssetTranslation) IsAsset() bool
- func (a *AssetTranslation) TranslateArchive(archive *resource.Archive) (interface{}, error)
- func (a *AssetTranslation) TranslateAsset(asset *resource.Asset) (interface{}, error)
- func (a *AssetTranslation) Type() string
- type AssetTranslationKind
- type AutoNameOptions
- type CSharp
- type ComputeDefaultOptions
- type ComputeID
- type Config
- type DataSource
- type DataSourceStrategy
- type Default
- type Doc
- type DocRule
- type DocsEdit
- type DocsPath
- type EditPhase
- type ElementStrategy
- type Golang
- type HclExampler
- type Java
- type JavaScript
- type MakeEditRules
- type MarshallableDataSource
- type MarshallableDefault
- type MarshallableElemShim
- type MarshallableProvider
- type MarshallableProviderShim
- type MarshallableResource
- type MarshallableResourceShim
- type MarshallableSchema
- type MarshallableSchemaShim
- type Metadata
- type MuxProvider
- type Overlay
- type PreCheckCallback
- type PreConfigureCallback
- type PreConfigureCallbackWithLogger
- type PreStateUpgradeHook
- type PreStateUpgradeHookArgs
- type PropertyTransform
- type Provider
- func (info *Provider) ApplyAutoAliases() error
- func (info *Provider) ComputeTokens(opts Strategy) error
- func (info *Provider) GetConfig() map[string]*Schema
- func (info Provider) GetGitHubHost() string
- func (info Provider) GetGitHubOrg() string
- func (info Provider) GetMetadata() ProviderMetadata
- func (info Provider) GetProviderModuleVersion() string
- func (info Provider) GetResourcePrefix() string
- func (info Provider) GetTFProviderLicense() TFProviderLicense
- func (info *Provider) MustApplyAutoAliases()
- func (info *Provider) MustComputeTokens(opts Strategy)
- func (p *Provider) RenameDataSource(dataSourceName string, legacyTok tokens.ModuleMember, ...)
- func (p *Provider) RenameResourceWithAlias(resourceName string, legacyTok tokens.Type, newTok tokens.Type, ...)
- func (p *Provider) SetAutonaming(maxLength int, separator string)
- func (p *Provider) Validate(context.Context) error
- type ProviderMetadata
- type PulumiResource
- type Python
- type PythonInputType
- type Resource
- type ResourceOrDataSource
- type ResourceStrategy
- type Schema
- type SkipExamplesArgs
- type Strategy
- type TFProviderLicense
- type Transformer
Constants ¶
const ( // Use the default type generation from pulumi/pulumi. PythonInputTypeDefault = "" // Generate args classes only. PythonInputTypeClasses = "classes" // Generate TypedDicts side-by-side with args classes. PythonInputTypeClassesAndDicts = "classes-and-dicts" )
const RenamedEntitySuffix string = "_legacy"
Variables ¶
This section is empty.
Functions ¶
func ComputeAutoNameDefault ¶
func ComputeAutoNameDefault( ctx context.Context, options AutoNameOptions, defaultOptions ComputeDefaultOptions, ) (interface{}, error)
Configures a property to automatically populate with an auto-computed name when no value is given to it by the user.
The easiest way to get started with auto-computed names is by using the AutoName function. ComputeAutoNameDefault is intended for advanced use cases, to be invoked like this:
&Default{ AutoNamed: true, ComputeDefault: func(ctx context.Context, opts ComputeDefaultOptions) (interface{}, error) { return ComputeAutoNameDefault(ctx, autoNameOptions, opts) }, }
If the user did not provide any values for the configured field, ComputeAutoNameDefault will create a default value based on the name of the resource and a random suffix, and populate the property with this default value. For example, if the resource is named "deployer", the new value may look like "deployer-6587896".
ComputeAutoNameDefault respects the prior state of the resource and will never attempt to replace a value that is already populated in the state with a fresh auto-name default.
See AutoNameOptions for configuring how the generated default values look like.
Types ¶
type Alias ¶
Alias is a partial description of prior named used for a resource. It can be processed in the context of a resource creation to determine what the full aliased URN would be.
It can be used by Pulumi resource providers to change the aspects of it (i.e. what module it is contained in), without causing resources to be recreated for customers who migrate from the original resource to the current resource.
type AssetTranslation ¶
type AssetTranslation struct { Kind AssetTranslationKind // the kind of translation to perform. Format resource.ArchiveFormat // an archive format, required if this is an archive. HashField string // a field to store the hash into, if any. }
AssetTranslation instructs the bridge how to translate assets into something Terraform can use.
func (*AssetTranslation) IsArchive ¶
func (a *AssetTranslation) IsArchive() bool
IsArchive returns true if the translation deals with an archive (rather than asset).
func (*AssetTranslation) IsAsset ¶
func (a *AssetTranslation) IsAsset() bool
IsAsset returns true if the translation deals with an asset (rather than archive).
func (*AssetTranslation) TranslateArchive ¶
func (a *AssetTranslation) TranslateArchive(archive *resource.Archive) (interface{}, error)
TranslateArchive translates the given archive using the directives provided by the translation info.
func (*AssetTranslation) TranslateAsset ¶
func (a *AssetTranslation) TranslateAsset(asset *resource.Asset) (interface{}, error)
TranslateAsset translates the given asset using the directives provided by the translation info.
func (*AssetTranslation) Type ¶
func (a *AssetTranslation) Type() string
Type fetches the Pulumi runtime type corresponding to values of this asset kind.
type AssetTranslationKind ¶
type AssetTranslationKind int
AssetTranslationKind may be used to choose from various source and dest translation targets.
const ( // FileAsset turns the asset into a file on disk and passes the filename in its place. FileAsset AssetTranslationKind = iota // BytesAsset turns the asset into a []byte and passes it directly in-memory. BytesAsset // FileArchive turns the archive into a file on disk and passes the filename in its place. FileArchive // BytesArchive turns the asset into a []byte and passes that directly in-memory. BytesArchive )
type AutoNameOptions ¶
type AutoNameOptions struct { // A separator between name and random portions of the Separator string // Maximum length of the generated name Maxlen int // Number of random characters to add to the name Randlen int // What characters to use for the random portion of the name, defaults to hex digits Charset []rune // A transform to apply to the name prior to adding random characters Transform func(string) string // A transform to apply after the auto naming has been computed PostTransform func(res *PulumiResource, name string) (string, error) }
AutoNameOptions provides parameters to AutoName to control how names will be generated
type CSharp ¶
type CSharp struct { PackageReferences map[string]string // NuGet package reference information. Overlay *Overlay // optional overlay information for augmented code-generation. Namespaces map[string]string // Known .NET namespaces with proper capitalization. RootNamespace string // The root namespace if setting to something other than Pulumi in the package name Compatibility string DictionaryConstructors bool ProjectReferences []string // Determines whether to make single-return-value methods return an output object or the single value. LiftSingleValueMethodReturns bool // Allow the Pkg.Version field to filter down to emitted code. RespectSchemaVersion bool }
CSharp contains optional overlay information for C# code-generation.
type ComputeDefaultOptions ¶
type ComputeDefaultOptions struct { // URN identifying the Resource. Set when computing default properties for a Resource, and unset for functions. URN resource.URN // Property map before computing the defaults. Properties resource.PropertyMap // Property map representing prior state, only set for non-Create Resource operations. PriorState resource.PropertyMap // PriorValue represents the last value of the current property in PriorState. It will have zero value if there // is no PriorState or if the property did not have a value in PriorState. PriorValue resource.PropertyValue // The engine provides a stable seed useful for generating random values consistently. This guarantees, for // example, that random values generated across "pulumi preview" and "pulumi up" in the same deployment are // consistent. This currently is only available for resource changes. Seed []byte }
Configures [Default.ComputeDefault].
type Config ¶
type Config struct { // Info is the Pulumi schema for this variable. Info *Schema // Schema is the Terraform schema for this variable. Schema shim.Schema }
Config represents a synthetic configuration variable that is Pulumi-only, and not passed to Terraform.
type DataSource ¶
type DataSource struct { Tok tokens.ModuleMember Fields map[string]*Schema Docs *Doc // overrides for finding and mapping TF docs. DeprecationMessage string // message to use in deprecation warning }
DataSource can be used to override a data source's standard name mangling and argument/return information.
func (*DataSource) GetDocs ¶
func (info *DataSource) GetDocs() *Doc
GetDocs returns a datasource docs override from the Pulumi provider
func (*DataSource) GetFields ¶
func (info *DataSource) GetFields() map[string]*Schema
GetFields returns information about the datasource's custom fields
func (*DataSource) GetTok ¶
func (info *DataSource) GetTok() tokens.Token
GetTok returns a datasource type token
func (*DataSource) ReplaceExamplesSection ¶
func (info *DataSource) ReplaceExamplesSection() bool
ReplaceExamplesSection returns whether to replace the upstream examples with our own source
type DataSourceStrategy ¶
type DataSourceStrategy = ElementStrategy[DataSource]
A strategy for generating missing datasources.
type Default ¶
type Default struct { // AutoNamed is true if this default represents an autogenerated name. AutoNamed bool // Config uses a configuration variable from this package as the default value. Config string // Deprecated. Use [Default.ComputeDefault]. From func(res *PulumiResource) (interface{}, error) // ComputeDefault specifies a strategy for how to pick a default value when the user has not specified any value // in their program. // // One common use case for this functionality is auto-naming, see [AutoName] for a recommended starting point // and [ComputeAutoNameDefault] for the specific implementation. ComputeDefault func(ctx context.Context, opts ComputeDefaultOptions) (interface{}, error) // Value injects a raw literal value as the default. // Note that only simple types such as string, int and boolean are currently supported here. // Structs, slices and maps are not yet supported. Value interface{} // EnvVars to use for defaults. If none of these variables have values at runtime, the value of `Value` (if any) // will be used as the default. EnvVars []string }
Default lets fields get default values at runtime, before they are even passed to Terraform.
type Doc ¶
type Doc struct { Source string // an optional override to locate TF docs; "" uses the default. Markdown []byte // an optional override for the source markdown. IncludeAttributesFrom string // optionally include attributes from another raw resource for docs. IncludeArgumentsFrom string // optionally include arguments from another raw resource for docs. IncludeAttributesFromArguments string // optionally include attributes from another raw resource's arguments. ImportDetails string // Overwrite for import instructions // Replace examples with the contents of a specific document // this document will satisfy the criteria `docs/pulumiToken.md` // The examples need to wrapped in the correct shortcodes ReplaceExamplesSection bool // Don't error when this doc is missing. // // This applies when PULUMI_MISSING_DOCS_ERROR="true". AllowMissing bool }
Doc contains optional overrides for finding and mapping TF docs.
func (*Doc) GetImportDetails ¶
GetImportDetails returns a string of import instructions defined in the Pulumi provider. Defaults to empty.
type DocRule ¶
type DocRule struct { // The function called to get the set of edit rules to use. // // defaults represents suggested edit rules. If EditRules is `nil`, defaults is // used as is. EditRules MakeEditRules // A function to suggest alternative file names for a TF element. // // When the bridge loads the documentation for a resource or a datasource, it // infers the name of the file that contains the documentation. AlternativeNames // allows you to provide a provider specific extension to the override list. // // For example, when attempting to find the documentation for the resource token // aws_waf_instances, the bridge will check the following files (in order): // // "waf_instance.html.markdown" // "waf_instance.markdown" // "waf_instance.html.md" // "waf_instance.md" // "aws_waf_instance.html.markdown" // "aws_waf_instance.markdown" // "aws_waf_instance.html.md" // "aws_waf_instance.md" // // The bridge will check any file names returned by AlternativeNames before // checking it's standard list. AlternativeNames func(DocsPath) []string }
DocRule controls file discovery and edits for any subset of docs in a provider.
type DocsEdit ¶
type DocsEdit struct { // The file name at which this rule applies. File names are matched via filepath.Match. // // To match all files, supply "*". // // All 4 of these names will match "waf_instances.html.markdown": // // - "waf_instances.html.markdown" // - "waf_instances.*" // - "waf*" // - "*" // // Provider resources are sourced directly from the TF schema, and as such have an // empty path. Path string // The function that performs the edit on the file bytes. // // Must not be nil. Edit func(path string, content []byte) ([]byte, error) // Phase determines when the edit rule will run. // // The default phase is [PreCodeTranslation]. Phase EditPhase }
type EditPhase ¶ added in v3.92.0
type EditPhase int
const ( // PreCodeTranslation directs an info.DocsEdit to occur before resource example code is translated. PreCodeTranslation EditPhase = iota // PostCodeTranslation directs an info.DocsEdit to occur after resource example code is translated. // It should be used when a docs edit would otherwise affect the code conversion mechanics. // TODO[https://github.com/pulumi/pulumi-terraform-bridge/issues/2459]: Right now, PostCodeTranslation is only // called on installation docs. PostCodeTranslation )
type ElementStrategy ¶
type ElementStrategy[T Resource | DataSource] func(tfToken string, elem *T) error
A generic remapping strategy.
func (ElementStrategy[T]) Ignore ¶
func (ts ElementStrategy[T]) Ignore(substring string) ElementStrategy[T]
Instruct the strategy not to apply to a token that contains substring.
type Golang ¶
type Golang struct { GenerateResourceContainerTypes bool // Generate container types for resources e.g. arrays, maps, pointers etc. ImportBasePath string // Base import path for package. Overlay *Overlay // optional overlay information for augmented code-generation. // Module path for go.mod // // go get github.com/pulumi/pulumi-aws-native/sdk/go/aws@v0.16.0 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ module path // ~~~~~~ package path - can be any number of path parts // ~~~~~~~ version ModulePath string // Explicit package name, which may be different to the import path. RootPackageName string // Map from module -> package name // // { "flowcontrol.apiserver.k8s.io/v1alpha1": "flowcontrol/v1alpha1" } // ModuleToPackage map[string]string // Map from package name -> package alias // // { "github.com/pulumi/pulumi-kubernetes/sdk/go/kubernetes/flowcontrol/v1alpha1": "flowcontrolv1alpha1" } // PackageImportAliases map[string]string // The version of the Pulumi SDK used with this provider, e.g. 3. // Used to generate doc links for pulumi builtin types. If omitted, the latest SDK version is used. PulumiSDKVersion int // Feature flag to disable generating `$fnOutput` invoke // function versions to save space. DisableFunctionOutputVersions bool // Determines whether to make single-return-value methods return an output struct or the value. LiftSingleValueMethodReturns bool // Feature flag to disable generating input type registration. This is a // space saving measure. DisableInputTypeRegistrations bool // Feature flag to disable generating Pulumi object default functions. This is a // space saving measure. DisableObjectDefaults bool // GenerateExtraInputTypes determines whether or not the code generator generates input (and output) types for // all plain types, instead of for only types that are used as input/output types. GenerateExtraInputTypes bool // omitExtraInputTypes determines whether the code generator generates input (and output) types // for all plain types, instead of for only types that are used as input/output types. OmitExtraInputTypes bool // Respect the Pkg.Version field for emitted code. RespectSchemaVersion bool // InternalDependencies are blank imports that are emitted in the SDK so that `go mod tidy` does not remove the // associated module dependencies from the SDK's go.mod. InternalDependencies []string // Specifies how to handle generating a variant of the SDK that uses generics. // Allowed values are the following: // - "none" (default): do not generate a generics variant of the SDK // - "side-by-side": generate a side-by-side generics variant of the SDK under the x subdirectory // - "only-generics": generate a generics variant of the SDK only Generics string }
Golang contains optional overlay information for Golang code-generation.
type HclExampler ¶
type HclExampler interface { // GetToken returns the fully qualified path to the resource or function in the schema, e.g. // "provider:module/getFoo:getFoo" (function), or // "provider:module/bar:Bar" (resource) GetToken() string // GetMarkdown returns the Markdown that comprises the entire example, including the header. // // Headers should be an H3 ("###") and the header content should not contain any prefix, e.g. "Foo with Bar" not, // "Example Usage - Foo with Bar". // // Code should be surrounded with code fences with an indicator of the language on the opening fence, e.g. "“`hcl". GetMarkdown() (string, error) }
HclExampler represents a supplemental HCL example for a given resource or function.
type Java ¶
type Java struct { BasePackage string // the Base package for the Java SDK // If set to "gradle" enables a generation of a basic set of // Gradle build files. BuildFiles string // If non-empty and BuildFiles="gradle", enables the use of a // given version of io.github.gradle-nexus.publish-plugin in // the generated Gradle build files. GradleNexusPublishPluginVersion string Packages map[string]string `json:"packages,omitempty"` Dependencies map[string]string `json:"dependencies,omitempty"` GradleTest string `json:"gradleTest"` }
See https://github.com/pulumi/pulumi-java/blob/main/pkg/codegen/java/package_info.go#L35C1-L108C1 documenting supported options.
type JavaScript ¶
type JavaScript struct { PackageName string // Custom name for the NPM package. Dependencies map[string]string // NPM dependencies to add to package.json. DevDependencies map[string]string // NPM dev-dependencies to add to package.json. PeerDependencies map[string]string // NPM peer-dependencies to add to package.json. Resolutions map[string]string // NPM resolutions to add to package.json. Overlay *Overlay // optional overlay information for augmented code-generation. TypeScriptVersion string // A specific version of TypeScript to include in package.json. PluginName string // The name of the plugin, which might be // different from the package name. The version of the plugin, which might be // different from the version of the package. PluginVersion string // A map containing overrides for module names to package names. ModuleToPackage map[string]string // An indicator for whether the package contains enums. ContainsEnums bool // A map allowing you to map the name of a provider to the name of the module encapsulating the provider. ProviderNameToModuleName map[string]string // Additional files to include in TypeScript compilation. These paths are added to the `files` section of the // generated `tsconfig.json`. A typical use case for this is compiling hand-authored unit test files that check // the generated code. ExtraTypeScriptFiles []string // Determines whether to make single-return-value methods return an output object or the single value. LiftSingleValueMethodReturns bool // Respect the Pkg.Version field in the schema RespectSchemaVersion bool // Experimental flag that permits `import type *` style code to be generated to optimize startup time of // programs consuming the provider by minimizing the set of Node modules loaded at startup. Turning this on may // currently generate non-compiling code for some providers; but if the code compiles it is safe to use. Also, // turning this on requires TypeScript 3.8 or higher to compile the generated code. UseTypeOnlyReferences bool }
JavaScript contains optional overlay information for Python code-generation.
type MakeEditRules ¶
The function used to produce the set of edit rules for a provider.
For example, if you want to skip default edits, you would use the function:
func([]DocsEdit) []DocsEdit { return nil }
If you wanted to incorporate custom edits, default edits, and then a check that the resulting document is valid, you would use the function:
func(defaults []DocsEdit) []DocsEdit { return append(customEdits, append(defaults, validityCheck)...) }
type MarshallableDataSource ¶
type MarshallableDataSource struct { Tok tokens.ModuleMember `json:"tok"` Fields map[string]*MarshallableSchema `json:"fields"` }
MarshallableDataSource is the JSON-marshallable form of a Pulumi DataSourceInfo value.
func MarshalDataSource ¶
func MarshalDataSource(d *DataSource) *MarshallableDataSource
MarshalDataSource converts a Pulumi DataSourceInfo value into a MarshallableDataSourceInfo value.
func (*MarshallableDataSource) Unmarshal ¶
func (m *MarshallableDataSource) Unmarshal() *DataSource
Unmarshal creates a mostly-=initialized Pulumi DataSourceInfo value from the given MarshallableDataSourceInfo.
type MarshallableDefault ¶
type MarshallableDefault struct { AutoNamed bool `json:"autonamed,omitempty"` IsFunc bool `json:"isFunc,omitempty"` Value interface{} `json:"value,omitempty"` EnvVars []string `json:"envvars,omitempty"` }
MarshallableDefault is the JSON-marshallable form of a Pulumi Default value.
func MarshalDefault ¶
func MarshalDefault(d *Default) *MarshallableDefault
MarshalDefault converts a Pulumi DefaultInfo value into a MarshallableDefault value.
func (*MarshallableDefault) Unmarshal ¶
func (m *MarshallableDefault) Unmarshal() *Default
Unmarshal creates a mostly-initialized Pulumi Default value from the given MarshallableDefault.
type MarshallableElemShim ¶
type MarshallableElemShim struct { Schema *MarshallableSchemaShim `json:"schema,omitempty"` Resource MarshallableResourceShim `json:"resource,omitempty"` }
MarshallableElemShim is the JSON-marshallable form of a Terraform schema's element field.
func MarshalElemShim ¶
func MarshalElemShim(e interface{}) *MarshallableElemShim
MarshalElemShim converts a Terraform schema's element field into a MarshallableElemShim.
func (*MarshallableElemShim) Unmarshal ¶
func (m *MarshallableElemShim) Unmarshal() interface{}
Unmarshal creates a Terraform schema element from a MarshallableElemShim.
type MarshallableProvider ¶
type MarshallableProvider struct { Provider *MarshallableProviderShim `json:"provider"` Name string `json:"name"` Version string `json:"version"` Config map[string]*MarshallableSchema `json:"config,omitempty"` Resources map[string]*MarshallableResource `json:"resources,omitempty"` DataSources map[string]*MarshallableDataSource `json:"dataSources,omitempty"` TFProviderVersion string `json:"tfProviderVersion,omitempty"` }
MarshallableProvider is the JSON-marshallable form of a Pulumi ProviderInfo value.
func MarshalProvider ¶
func MarshalProvider(p *Provider) *MarshallableProvider
MarshalProvider converts a Pulumi ProviderInfo value into a MarshallableProviderInfo value.
func (*MarshallableProvider) Unmarshal ¶
func (m *MarshallableProvider) Unmarshal() *Provider
Unmarshal creates a mostly-=initialized Pulumi ProviderInfo value from the given MarshallableProviderInfo.
type MarshallableProviderShim ¶
type MarshallableProviderShim struct { Schema map[string]*MarshallableSchemaShim `json:"schema,omitempty"` Resources map[string]MarshallableResourceShim `json:"resources,omitempty"` DataSources map[string]MarshallableResourceShim `json:"dataSources,omitempty"` }
MarshallableProviderShim is the JSON-marshallable form of a Terraform provider schema.
func MarshalProviderShim ¶
func MarshalProviderShim(p shim.Provider) *MarshallableProviderShim
MarshalProviderShim converts a Terraform provider schema into a MarshallableProviderShim.
func (*MarshallableProviderShim) Unmarshal ¶
func (m *MarshallableProviderShim) Unmarshal() shim.Provider
Unmarshal creates a mostly-initialized Terraform provider schema from a MarshallableProvider
type MarshallableResource ¶
type MarshallableResource struct { Tok tokens.Type `json:"tok"` CSharpName string `json:"csharpName,omitempty"` Fields map[string]*MarshallableSchema `json:"fields"` // Deprecated: IDFields is not currently used and will be deprecated in the next major version of // pulumi-terraform-bridge. IDFields []string `json:"idFields"` }
MarshallableResource is the JSON-marshallable form of a Pulumi ResourceInfo value.
func MarshalResource ¶
func MarshalResource(r *Resource) *MarshallableResource
MarshalResource converts a Pulumi ResourceInfo value into a MarshallableResourceInfo value.
func (*MarshallableResource) Unmarshal ¶
func (m *MarshallableResource) Unmarshal() *Resource
Unmarshal creates a mostly-=initialized Pulumi ResourceInfo value from the given MarshallableResourceInfo.
type MarshallableResourceShim ¶
type MarshallableResourceShim map[string]*MarshallableSchemaShim
MarshallableResourceShim is the JSON-marshallable form of a Terraform resource schema.
func MarshalResourceShim ¶
func MarshalResourceShim(r shim.Resource) MarshallableResourceShim
MarshalResourceShim converts a Terraform resource schema into a MarshallableResourceShim.
func (MarshallableResourceShim) Unmarshal ¶
func (m MarshallableResourceShim) Unmarshal() shim.Resource
Unmarshal creates a mostly-initialized Terraform resource schema from the given MarshallableResourceShim.
type MarshallableSchema ¶
type MarshallableSchema struct { Name string `json:"name,omitempty"` CSharpName string `json:"csharpName,omitempty"` Type tokens.Type `json:"typeomitempty"` AltTypes []tokens.Type `json:"altTypes,omitempty"` Elem *MarshallableSchema `json:"element,omitempty"` Fields map[string]*MarshallableSchema `json:"fields,omitempty"` Asset *AssetTranslation `json:"asset,omitempty"` Default *MarshallableDefault `json:"default,omitempty"` MaxItemsOne *bool `json:"maxItemsOne,omitempty"` Deprecated string `json:"deprecated,omitempty"` ForceNew *bool `json:"forceNew,omitempty"` Secret *bool `json:"secret,omitempty"` }
MarshallableSchema is the JSON-marshallable form of a Pulumi SchemaInfo value.
func MarshalSchema ¶
func MarshalSchema(s *Schema) *MarshallableSchema
MarshalSchema converts a Pulumi SchemaInfo value into a MarshallableSchemaInfo value.
func (*MarshallableSchema) Unmarshal ¶
func (m *MarshallableSchema) Unmarshal() *Schema
Unmarshal creates a mostly-=initialized Pulumi SchemaInfo value from the given MarshallableSchemaInfo.
type MarshallableSchemaShim ¶
type MarshallableSchemaShim struct { Type shim.ValueType `json:"type"` Optional bool `json:"optional,omitempty"` Required bool `json:"required,omitempty"` Computed bool `json:"computed,omitempty"` ForceNew bool `json:"forceNew,omitempty"` Elem *MarshallableElemShim `json:"element,omitempty"` MaxItems int `json:"maxItems,omitempty"` MinItems int `json:"minItems,omitempty"` DeprecationMessage string `json:"deprecated,omitempty"` }
MarshallableSchemaShim is the JSON-marshallable form of a Terraform schema.
func MarshalSchemaShim ¶
func MarshalSchemaShim(s shim.Schema) *MarshallableSchemaShim
MarshalSchemaShim converts a Terraform schema into a MarshallableSchema.
func (*MarshallableSchemaShim) Unmarshal ¶
func (m *MarshallableSchemaShim) Unmarshal() shim.Schema
Unmarshal creates a mostly-initialized Terraform schema from the given MarshallableSchemaShim.
type Metadata ¶
type Metadata struct { // The path (relative to schema.json) of the metadata file. Path string // The parsed metadata. Data ProviderMetadata }
Information necessary to persist and use provider level metadata.
func NewProviderMetadata ¶
Describe a metadata file called `bridge-metadata.json`.
`bytes` is the embedded metadata file.
type MuxProvider ¶
type MuxProvider interface { GetSpec(ctx context.Context, name, version string) (schema.PackageSpec, error) GetInstance(ctx context.Context, name, version string, host *provider.HostClient) (pulumirpc.ResourceProviderServer, error) }
MuxProvider defines an interface which must be implemented by providers that shall be used as mixins of a wrapped Terraform provider
type Overlay ¶
type Overlay struct { DestFiles []string // Additional files to include in the index file. Must exist in the destination. Modules map[string]*Overlay // extra modules to inject into the structure. }
Overlay contains optional overlay information. Each info has a 1:1 correspondence with a module and permits extra files to be included from the overlays/ directory when building up packs/. This allows augmented code-generation for convenient things like helper functions, modules, and gradual typing.
type PreCheckCallback ¶
type PreCheckCallback = func( ctx context.Context, config resource.PropertyMap, meta resource.PropertyMap, ) (resource.PropertyMap, error)
type PreConfigureCallback ¶
type PreConfigureCallback func(vars resource.PropertyMap, config shim.ResourceConfig) error
PreConfigureCallback is a function to invoke prior to calling the TF provider Configure
type PreConfigureCallbackWithLogger ¶
type PreConfigureCallbackWithLogger func( ctx context.Context, host *provider.HostClient, vars resource.PropertyMap, config shim.ResourceConfig, ) error
PreConfigureCallbackWithLogger is a function to invoke prior to calling the T
type PreStateUpgradeHook ¶
type PreStateUpgradeHook = func(PreStateUpgradeHookArgs) (int64, resource.PropertyMap, error)
If specified, the hook will run just prior to executing Terraform state upgrades to transform the resource state as stored in Pulumi. It can be used to perform idempotent corrections on corrupt state and to compensate for Terraform-level state upgrade not working as expected. Returns the corrected resource state and version. To be used with care.
See also: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource/schema#Schema.Version
type PreStateUpgradeHookArgs ¶
type PreStateUpgradeHookArgs struct { PriorState resource.PropertyMap PriorStateSchemaVersion int64 ResourceSchemaVersion int64 }
type PropertyTransform ¶
type PropertyTransform = func(context.Context, resource.PropertyMap) (resource.PropertyMap, error)
type Provider ¶
type Provider struct { P shim.Provider // the TF provider/schema. Name string // the TF provider name (e.g. terraform-provider-XXXX). ResourcePrefix string // the prefix on resources the provider exposes, if different to `Name`. // GitHubOrg is the segment of the upstream provider's Go module path that comes after GitHubHost and before // terraform-provider-${Name}. Defaults to `terraform-providers`. // // Note that this value should match the require directive for the upstream provider, not any replace directives. // // For example, GitHubOrg should be set to "my-company" given the following go.mod: // // require github.com/my-company/terraform-repo-example v1.0.0 // replace github.com/my-company/terraform-repo-example => github.com/some-fork/terraform-repo-example v1.0.0 GitHubOrg string // the GitHub org of the provider. Defaults to `terraform-providers`. GitHubHost string // the GitHub host for the provider. Defaults to `github.com`. Description string // an optional descriptive overview of the package (a default supplied). Keywords []string // an optional list of keywords to help discovery of this package. e.g. "category/cloud, category/infrastructure" License string // the license, if any, the resulting package has (default is none). LogoURL string // an optional URL to the logo of the package DisplayName string // the human friendly name of the package used in the Pulumi registry Publisher string // the name of the person or organization that authored and published the package. Homepage string // the URL to the project homepage. Repository string // the URL to the project source code repository. Version string // the version of the provider package. Config map[string]*Schema // a map of TF name to config schema overrides. ExtraConfig map[string]*Config // a list of Pulumi-only configuration variables. Resources map[string]*Resource // a map of TF name to Pulumi name; standard mangling occurs if no entry. DataSources map[string]*DataSource // a map of TF name to Pulumi resource info. ExtraTypes map[string]pschema.ComplexTypeSpec // a map of Pulumi token to schema type for extra types. ExtraResources map[string]pschema.ResourceSpec // a map of Pulumi token to schema type for extra resources. ExtraFunctions map[string]pschema.FunctionSpec // a map of Pulumi token to schema type for extra functions. // ExtraResourceHclExamples is a slice of additional HCL examples attached to resources which are converted to the // relevant target language(s) ExtraResourceHclExamples []HclExampler // ExtraFunctionHclExamples is a slice of additional HCL examples attached to functions which are converted to the // relevant target language(s) ExtraFunctionHclExamples []HclExampler // IgnoreMappings is a list of TF resources and data sources that are known to be unmapped. // // These resources/data sources do not generate missing mappings errors and will not be automatically // mapped. // // If there is a mapping in Resources or DataSources, it can override IgnoreMappings. This is common // when you need to ignore a datasource but not the resource with the same name, or vice versa. IgnoreMappings []string PluginDownloadURL string // an optional URL to download the provider binary from. JavaScript *JavaScript // optional overlay information for augmented JavaScript code-generation. Python *Python // optional overlay information for augmented Python code-generation. Golang *Golang // optional overlay information for augmented Golang code-generation. CSharp *CSharp // optional overlay information for augmented C# code-generation. Java *Java // optional overlay information for augmented C# code-generation. TFProviderVersion string // the version of the TF provider on which this was based TFProviderLicense *TFProviderLicense // license that the TF provider is distributed under. Default `MPL 2.0`. TFProviderModuleVersion string // the Go module version of the provider. Default is unversioned e.g. v1 // a provider-specific callback to invoke prior to TF Configure // Any CheckFailureErrors returned from PreConfigureCallback are converted to // CheckFailures and returned as failures instead of errors in CheckConfig PreConfigureCallback PreConfigureCallback // Any CheckFailureErrors returned from PreConfigureCallbackWithLogger are // converted to CheckFailures and returned as failures instead of errors in CheckConfig PreConfigureCallbackWithLogger PreConfigureCallbackWithLogger // Information for the embedded metadata file. // // See NewProviderMetadata for in-place construction of a *MetadataInfo. // If a provider should be mixed in with the Terraform provider with MuxWith (see below) // this field must be initialized. MetadataInfo *Metadata // Rules that control file discovery and edits for any subset of docs in a provider. DocRules *DocRule // An optional file path to the root of the upstream provider's git repo, for use in docs generation. // // If UpstreamRepoPath is left blank, it is inferred to the location where Go downloaded the build // dependency of the provider. The following fields influence the inference decision: // // - GitHubHost // - GitHubOrg // - Name // - TFProviderModuleVersion // // This list may change over time. UpstreamRepoPath string // EXPERIMENTAL: the signature may change in minor releases. // // If set, allows selecting individual examples to skip generating into the PackageSchema (and eventually API // docs). The primary use case for this hook is to ignore problematic or flaky examples temporarily until the // underlying issues are resolved and the examples can be rendered correctly. SkipExamples func(SkipExamplesArgs) bool // EXPERIMENTAL: the signature may change in minor releases. // // Optional function to post-process the generated schema spec after // the bridge completed its original version based on the TF schema. // A hook to enable custom schema modifications specific to a provider. SchemaPostProcessor func(spec *pschema.PackageSpec) // The MuxWith array allows the mixin (muxing) of other providers to the wrapped upstream Terraform provider. // With a provider mixin it's possible to add or replace resources and/or functions (data sources) in the wrapped // Terraform provider without having to change the upstream code itself. If multiple provider mixins are specified // the schema generator in pkg/tfgen will call the GetSpec() method of muxer.Provider in sequence. Thus, if more or two // of the mixins define the same resource/function, the last definition will end up in the combined schema of the // compiled provider. MuxWith []MuxProvider // Disables validation of provider-level configuration for Plugin Framework based providers. // Hybrid providers that utilize a mixture of Plugin Framework and SDKv2 based resources may // opt into this to workaround slowdown in PF validators, since their configuration is // already being checked by SDKv2 based validators. // // See also: pulumi/pulumi-terraform-bridge#1448 SkipValidateProviderConfigForPluginFramework bool // Enables generation of a trimmed, runtime-only metadata file // to help reduce resource plugin start time // // See also pulumi/pulumi-terraform-bridge#1524 GenerateRuntimeMetadata bool // EnableZeroDefaultSchemaVersion makes the provider default // to version 0 when no version is specified in the state of a resource. EnableZeroDefaultSchemaVersion bool // EnableAccurateBridgePreview makes the bridge use an experimental feature // to generate more accurate diffs and previews for resources EnableAccurateBridgePreview bool }
Provider contains information about a Terraform provider plugin that we will use to generate the Pulumi metadata. It primarily contains a pointer to the Terraform schema, but can also contain specific name translations.
func (*Provider) ApplyAutoAliases ¶
func (*Provider) ComputeTokens ¶
Assigns resource and data source tokens unless already specified by the user.
Context: bridging a provider requires every TF resource and data source have a matching entry in [Resources] and [DataSources]. Each entry needs to minimally specifying the Pulumi token in [ResourceInfo.Tok]. The mapping entries can be done by hand for smaller provides but become a chore for providers with 1000s of entries.
ComputeTokens scans TF resources and datasources to populate missing entries as needed with automatically computed Pulumi tokens.
ComputeTokens always respects and does not modify pre-existing entires. The user can therefore manually override the token decision by providing [ResourceInfo] or [DataSourceInfo] entry prior to calling ComputeTokens.
ComputeTokens respects [ProviderInfo.IgnoreMappings]. It will not create a mapping for any token in [ProviderInfo.IgnoreMappings].
func (Provider) GetGitHubHost ¶
func (Provider) GetGitHubOrg ¶
func (Provider) GetMetadata ¶
func (info Provider) GetMetadata() ProviderMetadata
func (Provider) GetProviderModuleVersion ¶
func (Provider) GetResourcePrefix ¶
GetResourcePrefix returns the resource prefix for the provider: info.ResourcePrefix if that is set, or info.Name if not. This is to avoid unexpected behavior with providers which have no need to set ResourcePrefix following its introduction.
func (Provider) GetTFProviderLicense ¶
func (info Provider) GetTFProviderLicense() TFProviderLicense
func (*Provider) MustApplyAutoAliases ¶
func (info *Provider) MustApplyAutoAliases()
func (*Provider) MustComputeTokens ¶
Add mapped resources and datasources according to the given strategies.
Panics if ApplyStrategy would return an error.
func (*Provider) RenameDataSource ¶
func (p *Provider) RenameDataSource(dataSourceName string, legacyTok tokens.ModuleMember, newTok tokens.ModuleMember, legacyModule string, newModule string, info *DataSource, )
RenameDataSource adds an alias to a data source and marks the original as deprecated.
func (*Provider) RenameResourceWithAlias ¶
func (*Provider) SetAutonaming ¶
SetAutonaming auto-names all resource properties that are literally called "name".
The effect is identical to configuring each matching property with AutoName. Pulumi will propose an auto-computed value for these properties when no value is given by the user program. If a property was required before auto-naming, it becomes optional.
The maxLength and separator parameters configure how AutoName generates default values. See AutoNameOptions.
SetAutonaming will skip properties that already have a [SchemaInfo] entry in [ResourceInfo.Fields], assuming those are already customized by the user. If those properties need AutoName functionality, please use AutoName directly to populate their SchemaInfo entry.
Note that when constructing a ProviderInfo incrementally, some care is required to make sure SetAutonaming is called after [ProviderInfo.Resources] map is fully populated, as it relies on this map to find resources to auto-name.
type ProviderMetadata ¶
A KV store persisted between `tfgen` and a running provider.
The store is read-write when the schema is being generated, and is persisted to disk with schema.json. During normal provider operation (pulumi-resource-${PKG}), the store if not persisted (making it effectively read-only).
type PulumiResource ¶
type PulumiResource struct { URN resource.URN Properties resource.PropertyMap Seed []byte }
PulumiResource is just a little bundle that carries URN, seed and properties around.
type Python ¶
type Python struct { Requires map[string]string // Pip install_requires information. Overlay *Overlay // optional overlay information for augmented code-generation. UsesIOClasses bool // Deprecated: No longer required, all providers use IO classes. PackageName string // Name of the Python package to generate // PythonRequires determines the Python versions that the generated provider supports PythonRequires string // Optional overrides for Pulumi module names // // { "flowcontrol.apiserver.k8s.io/v1alpha1": "flowcontrol/v1alpha1" } // ModuleNameOverrides map[string]string // Determines whether to make single-return-value methods return an output object or the single value. LiftSingleValueMethodReturns bool // Respect the Pkg.Version field for emitted code. RespectSchemaVersion bool // If enabled, a pyproject.toml file will be generated. PyProject struct { Enabled bool } // Specifies what types are used for inputs. InputTypes PythonInputType }
Python contains optional overlay information for Python code-generation.
type PythonInputType ¶ added in v3.85.0
type PythonInputType string
type Resource ¶
type Resource struct { Tok tokens.Type // a type token to override the default; "" uses the default. Fields map[string]*Schema // a map of custom field names; if a type is missing, uses the default. // Deprecated: IDFields is not currently used and will be removed in the next major version of // pulumi-terraform-bridge. See [ComputeID]. IDFields []string // list of parameters that we can trust that any change will allow a createBeforeDelete UniqueNameFields []string Docs *Doc // overrides for finding and mapping TF docs. DeleteBeforeReplace bool // if true, Pulumi will delete before creating new replacement resources. Aliases []Alias // aliases for this resources, if any. DeprecationMessage string // message to use in deprecation warning CSharpName string // .NET-specific name // Optional hook to run before upgrading the state. TODO[pulumi/pulumi-terraform-bridge#864] this is currently // only supported for Plugin-Framework based providers. PreStateUpgradeHook PreStateUpgradeHook // An experimental way to augment the Check function in the Pulumi life cycle. PreCheckCallback PreCheckCallback // Resource operations such as Create, Read, and Update return the resource outputs to be // recored in Pulumi statefile. TransformOutputs provides the last chance to edit these // outputs before they are stored. In particular, it can be used as a last resort hook to // make corrections in the default translation of the resource state from TF to Pulumi. // Should be used sparingly. TransformOutputs PropertyTransform // Check, Diff, Read, Update and Delete refer to old inputs sourced from the // Pulumi statefile. TransformFromState lets providers edit these outputs before they // are accessed by other provider functions or by terraform. In particular, it can // be used to perform upgrades on old pulumi state. Should be used sparingly. TransformFromState PropertyTransform // Customizes inferring resource identity from state. // // The vast majority of resources define an "id" field that is recognized as the resource // identity. This is the default behavior when ComputeID is nil. There are some exceptions, // however, such as the RandomBytes resource, that base identity on a different field // ("base64" in the case of RandomBytes). ComputeID customization option supports such // resources. It is called in Create(preview=false) and Read provider methods. // // This option is currently only supported for Plugin Framework based resources. // // To delegate the resource ID to another string field in state, use the helper function // [DelegateIDField]. ComputeID ComputeID }
Resource is a top-level type exported by a provider. This structure can override the type to generate. It can also give custom metadata for fields, using the SchemaInfo structure below. Finally, a set of composite keys can be given; this is used when Terraform needs more than just the ID to uniquely identify and query for a resource.
func (*Resource) ReplaceExamplesSection ¶
ReplaceExamplesSection returns whether to replace the upstream examples with our own source
type ResourceOrDataSource ¶
type ResourceOrDataSource interface { GetTok() tokens.Token // a type token to override the default; "" uses the default. GetFields() map[string]*Schema // a map of custom field names; if a type is missing, uses the default. GetDocs() *Doc // overrides for finding and mapping TF docs. ReplaceExamplesSection() bool // whether we are replacing the upstream TF examples generation }
ResourceOrDataSource is a shared interface to ResourceInfo and DataSourceInfo mappings
type ResourceStrategy ¶
type ResourceStrategy = ElementStrategy[Resource]
A strategy for generating missing resources.
type Schema ¶
type Schema struct { // a name to override the default; "" uses the default. Name string // a name to override the default when targeting C#; "" uses the default. CSharpName string // An optional Pulumi type token to use for the Pulumi type projection of the current property. When unset, the // default behavior is to generate fresh named Pulumi types as needed to represent the schema. To force the use // of a known type and avoid generating unnecessary types, use both [Type] and [OmitType]. Type tokens.Type // Used together with [Type] to omit generating any Pulumi types whatsoever for the current property, and // instead use the object type identified by the token setup in [Type]. // // It is an error to set [OmitType] to true without specifying [Type]. // // Experimental. OmitType bool // alternative types that can be used instead of the override. AltTypes []tokens.Type // a type to override when the property is a nested structure. NestedType tokens.Type // an optional idemponent transformation, applied before passing to TF. Transform Transformer // a schema override for elements for arrays, maps, and sets. Elem *Schema // a map of custom field names; if a type is missing, the default is used. Fields map[string]*Schema // a map of asset translation information, if this is an asset. Asset *AssetTranslation // an optional default directive to be applied if a value is missing. Default *Default // to override whether a property is stable or not. Stable *bool // to override whether this property should project as a scalar or array. MaxItemsOne *bool // to remove empty object array elements SuppressEmptyMapElements *bool // this will make the parameter as computed and not allow the user to set it MarkAsComputedOnly *bool // this will make the parameter optional in the schema MarkAsOptional *bool // the deprecation message for the property DeprecationMessage string // whether a change in the configuration would force a new resource ForceNew *bool // Controls whether a change in the provider configuration should trigger a provider // replacement. While there is no matching concept in TF, Pulumi supports replacing explicit // providers and cascading the replacement to all resources provisioned with the given // provider configuration. // // This property is only relevant for [Provider.Config] properties. ForcesProviderReplace *bool // whether or not this property has been removed from the Terraform schema Removed bool // if set, this property will not be added to the schema and no bindings will be generated for it Omit bool // whether or not to treat this property as secret Secret *bool // Specifies the exact name to use for the generated type. // // When generating types for properties, by default Pulumi picks reasonable names based on the property path // prefix and the name of the property. Use [TypeName] to override this decision when the default names for // nested properties are too long or otherwise undesirable. The choice will further affect the automatically // generated names for any properties nested under the current one. // // Example use: // // TypeName: tfbridge.Ref("Visual") // // Note that the type name, and not the full token like "aws:quicksight/Visual:Visual" is specified. The token // will be picked based on the current module ("quicksight" in the above example) where the parent resource or // data source is found. // // Experimental. TypeName *string // XAlwaysIncludeInImport prevents the field from pruning zero values when generating import inputs. // // This is necessary to accommodate Terraform providers that distinguish between the zero value of a property // and no value of the property. // // For example, consider cloudflare_ruleset resource (https://github.com/pulumi/pulumi-cloudflare/issues/957): // // resources: // cache_rules: // type: cloudflare:Ruleset // properties: // kind: zone // rules: // - action: set_cache_settings // action_parameters: // cache: false // // Importing cache_rules will result in the following code: // // resources: // cache_rules: // type: cloudflare:Ruleset // properties: // kind: zone // rules: // - action: set_cache_settings // // action_parameters.cache is dropped because "false" is the default value of boolean. Unfortunately, the // cloudflare provider treats "cache: false" very differently from "cache: null". Setting XAlwaysIncludeInImport // ensures that "cache: false" is always included in the resulting output. // // Experimental. XAlwaysIncludeInImport bool }
Schema contains optional name transformations to apply.
func AutoName ¶
AutoName configures a property to automatically populate with auto-computed names when no values are given to it by the user program.
The auto-computed names will be based on the resource name extracted from the resource URN, and have a random suffix. The lifecycle of automatic names is tied to the Pulumi resource lifecycle, so the automatic name will not change during normal updates and will persist until the resource is replaced.
If a required property is configured with AutoName, it becomes optional in the Pulumi Package Schema. Therefore removing AutoName from a required property is a breaking change.
For a quick example, consider aws.ec2.Keypair that has this code in its definition:
ResourceInfo{ Fields: map[string]*SchemaInfo{ "key_name": AutoName("keyName", 255, "-"), }, }
Deploying a KeyPair allocates an automatic keyName without the user having to specify it:
const deployer = new aws.ec2.KeyPair("deployer", {publicKey: pubKey}); export const keyName = deployer.keyName;
Running this example produces:
Outputs: keyName: "deployer-6587896"
Note how the automatic name combines the resource name from the program with a random suffix.
func (Schema) HasDefault ¶
HasDefault returns true if there is a default value for this property.
type SkipExamplesArgs ¶
type SkipExamplesArgs struct { // token will be a resource, function, or type token from Pulumi Package Schema. For instance, // "aws:acm/certificate:Certificate" would indicate the example pertains to the Certificate resource in the AWS // provider. Token string // examplePath will provide even more information on where the example is found. For instance, // "#/resources/aws:acm/certificate:Certificate/arn" would encode that the example pertains to the arn property // of the Certificate resource in the AWS provider. ExamplePath string }
EXPERIMENTAL: the signature may change in minor releases.
type Strategy ¶
type Strategy struct { Resource ResourceStrategy DataSource DataSourceStrategy }
type TFProviderLicense ¶
type TFProviderLicense string
TFProviderLicense is a way to be able to pass a license type for the upstream Terraform provider.
const ( MPL20LicenseType TFProviderLicense = "MPL 2.0" MITLicenseType TFProviderLicense = "MIT" Apache20LicenseType TFProviderLicense = "Apache 2.0" UnlicensedLicenseType TFProviderLicense = "UNLICENSED" )
type Transformer ¶
type Transformer func(resource.PropertyValue) (resource.PropertyValue, error)
Transformer is given the option to transform a value in situ before it is processed by the bridge. This transformation must be deterministic and idempotent, and any value produced by this transformation must be a legal alternative input value. A good example is a resource that accepts either a string or JSON-stringable map; a resource provider may opt to store the raw string, but let users pass in maps as a convenience mechanism, and have the transformer stringify them on the fly. This is safe to do because the raw string is still accepted as a possible input value.