pulumiyaml

package
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2024 License: Apache-2.0 Imports: 35 Imported by: 2

README

pulumiyaml Implementation Guide

The pulumiyaml package handles the core logic of Pulumi YAML.

Token Resolution

Algorithm

Given a schema token T (for either a resource or function), Pulumi YAML attempts to resolve it to a schema defined resource/function with the following algorithm:

  1. If T is prefixed with pulumi:provider: and T is a resource token, resolve it as a provider and return.
  2. If T is mentioned explicitly in the schema, either as a resource name or an alias, return the named resource.
  3. If T is of the form ${package}:${resource}, set T to ${package}:index:${resource}. Goto 2.
  4. If T is of the form ${package}:${mod}:${resource}, set T to ${package}:${mod}/${camelCase(resource)}:${resource}. Goto 2.
  5. Return no resource found.

where ${...} matches any characters except for : and /.

Examples
  • foo:Bar will resolve to itself, then foo:index:Bar, then foo:index/bar:Bar.
  • foo:mod:Bar will resolve to itself, then foo:mod/bar:Bar.
  • foo:mod/bar:Bar will resolve only to itself.
  • pulumi:provider:Foo will resolve only to itself.

Documentation

Index

Constants

View Source 
const MainTemplate = "Main"

MainTemplate is the assumed name of the JSON template file. TODO: would be nice to permit multiple files, but we'd need to know which is "main", and there's no notion of "import" so we'd need to be a bit more clever. Might be nice to mimic e.g. Kustomize. One idea is to hijack Pulumi.yaml's "main" directive and then just globally toposort the rest.

View Source 
const PulumiVarName = "pulumi"

Variables

View Source 
var TagDecoder = tagDecoder(0)

The TagDecoder is responsible for decoding YAML tags that represent calls to builtin functions.

No tags are presently supported, but the machinery to support tags is useful to preserve until we are confident that we won't re-introduce.

Functions

func GetResourceDependencies 

func GetResourceDependencies(r *ast.ResourceDecl) []*ast.StringExpr

GetResourceDependencies gets the full set of implicit and explicit dependencies for a Resource.

func GetVariableDependencies 

func GetVariableDependencies(e ast.VariablesMapEntry) []*ast.StringExpr

GetVariableDependencies gets the full set of implicit and explicit dependencies for a Variable.

func HasDiagnostics 

func HasDiagnostics(err error) (syntax.Diagnostics, bool)

func Load 

func Load() (*ast.TemplateDecl, syntax.Diagnostics, error)

Load a template from the current working directory

func LoadDir 

func LoadDir(cwd string) (*ast.TemplateDecl, syntax.Diagnostics, error)

Load a template from the current working directory.

func LoadFile 

func LoadFile(path string) (*ast.TemplateDecl, syntax.Diagnostics, error)

Load a template from the current working directory

func LoadFromCompiler 

func LoadFromCompiler(compiler string, workingDirectory string) (*ast.TemplateDecl, syntax.Diagnostics, error)

func LoadTemplate 

func LoadTemplate(t *Template) (*ast.TemplateDecl, syntax.Diagnostics)

LoadTemplate decodes a Template value into a YAML template.

func LoadYAML 

func LoadYAML(filename string, r io.Reader) (*ast.TemplateDecl, syntax.Diagnostics, error)

LoadYAML decodes a YAML template from an io.Reader.

func LoadYAMLBytes 

func LoadYAMLBytes(filename string, source []byte) (*ast.TemplateDecl, syntax.Diagnostics, error)

LoadYAMLBytes decodes a YAML template from a byte array.

func ParseVersion added in v1.0.4 

func ParseVersion(v *ast.StringExpr) (*semver.Version, error)

func ResolveFunction 

func ResolveFunction(loader PackageLoader, typeString string, version *semver.Version) (Package, FunctionTypeToken, error)

ResolveFunction determines the appropriate package for a function, loads that package, then calls the package's ResolveFunction method to determine the canonical name of the function, returning both the package and the canonical name.

func ResolvePkgName added in v1.0.4 

func ResolvePkgName(typeString string) string

func ResolveResource 

func ResolveResource(loader PackageLoader, typeString string, version *semver.Version) (Package, ResourceTypeToken, error)

ResolveResource determines the appropriate package for a resource, loads that package, then calls the package's ResolveResource method to determine the canonical name of the resource, returning both the package and the canonical name.

func ResourceOptionsTypeHint 

func ResourceOptionsTypeHint() map[string]struct{}

Compute the set of fields valid for the resource options.

func RunTemplate 

func RunTemplate(ctx *pulumi.Context, t *ast.TemplateDecl, config map[string]string, configPropertyMap resource.PropertyMap, loader PackageLoader) error

RunTemplate runs the programEvaluator against a template using the given request/settings.

Types

type Configuration 

type Configuration struct {

	// Type is the  data type for the parameter. It can be one of: `String`, `Number`,
	// `List<Number>`, or `List<String>`.
	Type string `yaml:",omitempty"`
	// Default is a value of the appropriate type for the template to use if no value is specified.
	Default interface{} `json:",omitempty" yaml:",omitempty"`
	// Secret masks the parameter by marking it a secret.
	Secret bool `yaml:",omitempty"`
}

Configuration represents a single configurable parameter for this template. The parameters are validated before evaluating the template and may be specified using the Pulumi configuration system.

type CustomTimeoutResourceOption 

type CustomTimeoutResourceOption struct {
	// Create is the custom timeout for create operations.
	Create string `json:",omitempty" yaml:",omitempty"`
	// Delete is the custom timeout for delete operations.
	Delete string `json:",omitempty" yaml:",omitempty"`
	// Update is the custom timeout for update operations.
	Update string `json:",omitempty" yaml:",omitempty"`
}

CustomTimeoutResourceOption provides a set of custom timeouts for create, update, and delete operations on a resource. These timeouts are specified using a duration string like "5m" (5 minutes), "40s" (40 seconds), or "1d" (1 day). Supported duration units are "ns", "us" (or "µs"), "ms", "s", "m", and "h" (nanoseconds, microseconds, milliseconds, seconds, minutes, and hours, respectively).

type Evaluator 

type Evaluator interface {
	EvalConfig(r *Runner, node configNode) bool
	EvalVariable(r *Runner, node variableNode) bool
	EvalResource(r *Runner, node resourceNode) bool
	EvalOutput(r *Runner, node ast.PropertyMapEntry) bool
}

type FunctionTypeToken 

type FunctionTypeToken string

func (FunctionTypeToken) String 

func (ftt FunctionTypeToken) String() string

type OrderedTypeSet added in v0.5.1 

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

func (*OrderedTypeSet) Add added in v0.5.1 

func (o *OrderedTypeSet) Add(t schema.Type) bool

func (*OrderedTypeSet) First added in v0.5.1 

func (o *OrderedTypeSet) First() schema.Type

First returns the first element added, panicking if no element exists.

func (*OrderedTypeSet) Len added in v0.5.1 

func (o *OrderedTypeSet) Len() int

func (*OrderedTypeSet) Values added in v0.5.1 

func (o *OrderedTypeSet) Values() []schema.Type

type Package 

type Package interface {
	// Returns the name of the package.
	Name() string
	// Returns the version of the package.
	Version() *semver.Version
	// Given a type name, look up that type in a package's defined resources and return a canonical
	// type name. The lookup may take the form of trying alternate names or aliases.
	//
	// e.g.: given "aws:s3:Bucket", it will return "aws:s3/bucket:Bucket".
	ResolveResource(typeName string) (ResourceTypeToken, error)
	// Given a type name, look up that type in a package's defined resources and return a canonical
	// type name. The lookup may take the form of trying alternate names or aliases.
	//
	// e.g.: given "aws:s3:Bucket", it will return "aws:s3/bucket:Bucket".
	ResolveFunction(typeName string) (FunctionTypeToken, error)
	// Given the canonical name of a resource, return the IsComponent property of the resource schema.
	IsComponent(typeName ResourceTypeToken) (bool, error)
	// Information on the properties of a resource. All resource type tokens generated by a
	// package must return a non-nil instance of `TypeHint` when called.
	ResourceTypeHint(typeName ResourceTypeToken) *schema.ResourceType
	// Information on the argument to a function.
	FunctionTypeHint(typeName FunctionTypeToken) *schema.Function
	// Gets properties with constant values that must be added to the register resource API call.
	ResourceConstants(typeName ResourceTypeToken) map[string]interface{}
}

Package is our external facing term, e.g.: a provider package in the registry. Packages are delivered via plugins, and this interface provides enough surface area to get information about resources in a package.

func NewResourcePackage 

func NewResourcePackage(pkg schema.PackageReference) Package

type PackageLoader 

type PackageLoader interface {
	LoadPackage(name string, version *semver.Version) (Package, error)
	Close()
}

func NewPackageLoader 

func NewPackageLoader() (PackageLoader, error)

func NewPackageLoaderFromSchemaLoader 

func NewPackageLoaderFromSchemaLoader(loader schema.ReferenceLoader) PackageLoader

Unsafely create a PackageLoader from a schema.Loader, forfeiting the ability to close the host and clean up plugins when finished. Useful for test cases.

type Plugin 

type Plugin struct {
	Package           string
	Version           string
	PluginDownloadURL string
}

Plugin is metadata containing a package name, possibly empty version and download URL. Used to inform the engine of the required plugins at the beginning of program execution.

func GetReferencedPlugins 

func GetReferencedPlugins(tmpl *ast.TemplateDecl) ([]Plugin, syntax.Diagnostics)

GetReferencedPlugins returns the packages and (if provided) versions for each referenced provider used in the program.

type Resource 

type Resource struct {
	// Type is the Pulumi type token for this resource.
	Type string `yaml:""`
	// Properties contains the primary resource-specific keys and values to initialize the resource state.
	Properties map[string]interface{} `json:",omitempty" yaml:",omitempty"`
	// Options contains all Pulumi resource options used to register the resource.
	ResourceOptions *ResourceOptions `json:",omitempty" yaml:",omitempty"`

	// Condition makes this resource's creation conditional upon a predefined Condition attribute;
	// see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html.
	Condition string `json:",omitempty" yaml:",omitempty"`
	// Metadata enables arbitrary metadata values to be associated with a resource.
	Metadata map[string]interface{} `json:",omitempty" yaml:",omitempty"`
}

Resource declares a single infrastructure resource, such as an AWS S3 bucket or EC2 instance, complete with its properties and various other behavioral elements.

type ResourceOptions 

type ResourceOptions struct {
	// AdditionalSecretOutputs specifies properties that must be encrypted as secrets
	AdditionalSecretOutputs []string `json:",omitempty" yaml:",omitempty"`
	// Aliases specifies names that this resource used to be have so that renaming or refactoring doesn’t replace it
	Aliases []string `json:",omitempty" yaml:"Aliases,omitempty"`
	// CustomTimeouts overrides the default retry/timeout behavior for resource provisioning
	CustomTimeouts *CustomTimeoutResourceOption `json:",omitempty" yaml:",omitempty"`
	// DeleteBeforeReplace  overrides the default create-before-delete behavior when replacing
	DeleteBeforeReplace bool `json:",omitempty" yaml:",omitempty"`
	// DependsOn makes this resource explicitly depend on another resource, by name, so that it won't
	// be created before the dependent finishes being created (and the reverse for destruction). Normally,
	// Pulumi automatically tracks implicit dependencies through inputs/outputs, but this can be used when
	// dependencies aren't captured purely from input/output edges.
	DependsOn []string `json:",omitempty" yaml:",omitempty"`
	// IgnoreChangs declares that changes to certain properties should be ignored during diffing
	IgnoreChanges []string `json:",omitempty" yaml:",omitempty"`
	// Import adopts an existing resource from your cloud account under the control of Pulumi
	Import string `json:",omitempty" yaml:",omitempty"`
	// Parent specifies a parent for the resource
	Parent string `json:",omitempty" yaml:",omitempty"`
	// Protect prevents accidental deletion of a resource
	Protect bool `json:",omitempty" yaml:",omitempty"`
	// Provider specifies an explicitly configured provider, instead of using the default global provider
	Provider string `json:",omitempty" yaml:",omitempty"`
	// Version specifies a provider plugin version that should be used when operating on a resource
	Version string `json:",omitempty" yaml:",omitempty"`
	// ReplaceOnChanges forces a resource to be replaced when the targeted property is changed.
	ReplaceOnChanges []string `json:",omitempty" yaml:",omitempty"`
	// If set, the provider's Delete method will not be called for this resource if the specified resource is being
	// deleted as well.
	DeletedWith string `json:",omitempty" yaml:",omitempty"`
}

ResourceOptions describes additional options common to all Pulumi resources.

type ResourceTypeToken 

type ResourceTypeToken string

func (ResourceTypeToken) String 

func (rtt ResourceTypeToken) String() string

type Runner added in v0.5.6 

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

func PrepareTemplate added in v0.5.6 

func PrepareTemplate(t *ast.TemplateDecl, r *Runner, loader PackageLoader) (*Runner, syntax.Diagnostics, error)

PrepareTemplate prepares a template for converting or running

func (*Runner) Evaluate added in v0.5.6 

func (r *Runner) Evaluate(ctx *pulumi.Context) syntax.Diagnostics

func (*Runner) Run added in v0.5.6 

func (r *Runner) Run(e Evaluator) syntax.Diagnostics

type Template 

type Template struct {
	// Name is the project name
	Name string `json:",omitempty" yaml:",omitempty"`
	// Description is an informational bit of metadata about this template.
	Description string `json:",omitempty" yaml:",omitempty"`
	// Configuration allows the template to be conditional based on Pulumi configuration values.
	Configuration map[string]*Configuration `json:",omitempty" yaml:",omitempty"`
	// Config is the configuration from the project-level `config` block.
	Config map[string]interface{} `json:",omitempty" yaml:",omitempty"`
	// Variables declares variables that will be used in the template.
	Variables map[string]interface{} `json:",omitempty" yaml:",omitempty"`
	// Resources is a required section that declares resources you want to include in the stack.
	Resources map[string]*Resource `json:",omitempty" yaml:",omitempty"`
	// Outputs declares a set of output values that will be exported from the stack and usable from other stacks.
	Outputs map[string]interface{} `json:",omitempty" yaml:",omitempty"`

	// Mappings provides the ability to have a static set of maps for programs that need to
	// perform lookups using fn::FindInMap. For instance, we can map from region name to AMI IDs:
	//      "Mappings": {
	//          "RegionMap": {
	//              "us-east-1"     : { "HVM64": "ami-0ff8a91507f77f867" },
	//              "us-west-1"     : { "HVM64": "ami-0bdb828fd58c52235" },
	//              "eu-west-1"     : { "HVM64": "ami-047bb4163c506cd98" },
	//              "ap-southeast-1": { "HVM64": "ami-08569b978cc4dfa10" },
	//              "ap-northeast-1": { "HVM64": "ami-06cd52961ce9f0d85" }
	//          }
	//      }
	// Read more at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html.
	Mappings map[string]map[string]map[string]string `json:",omitempty" yaml:",omitempty"`
	// Conditions can optionally contain a set of statements that defines the circumstances under which
	// entities are created or configured. This can be based on parameters to enable dynamic resource creation.
	// Read more at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html.
	Conditions map[string]interface{} `json:",omitempty" yaml:",omitempty"`
}

Template is a YAML or JSON structure which defines a Pulumi stack containing cloud infrastructure resources.

type Typing 

type Typing interface {
	TypeResource(name string) schema.Type
	TypeVariable(name string) schema.Type
	TypeConfig(name string) schema.Type
	TypeOutput(name string) schema.Type

	// TypeExpr can compare `ast.Expr` by pointer, so only expressions taken directly from
	// the program will return non-nil results.
	TypeExpr(expr ast.Expr) schema.Type
}

Query the typing of a typed program.

If the program failed to establish the type of a variable, then `*schema.InvalidType` is returned. If the the variable/expr is unknown to the typed program, `nil` is returned.

func TypeCheck 

func TypeCheck(r *Runner) (Typing, syntax.Diagnostics)

Source Files

View all Source files

Directories

Path Synopsis
The codegen package provides utilities for converting Pulumi YAML templates to other forms (e.g.
 The codegen package provides utilities for converting Pulumi YAML templates to other forms (e.g.
encoding

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.