template

Documentation

Overview

Package template helps plugins parse the Packer template into golang structures.

This package should be imported and used by all plugins. It implements the golang template engines that Packer documentes on its website, along with input validation, custom type decoding, and template variable interpolation.

A simple usage example that defines a config and then unpacks a user-provided json template into the provided config:

import (
	// ...
	"github.com/hashicorp/packer-plugin-sdk/template/config"
	"github.com/hashicorp/packer-plugin-sdk/template/interpolate"
)

type Config struct {
	Field1   string `mapstructure:"field_1"`
	Field2   bool   `mapstructure:"field_2"`
	Field3   bool   `mapstructure:"field_3"`

	ctx interpolate.Context
}

type Provisioner struct {
	config Config
}

func (p *CommentProvisioner) Prepare(raws ...interface{}) error {
	err := config.Decode(&p.config, &config.DecodeOpts{
		Interpolate:        true,
		InterpolateContext: &p.config.ctx,
	}, raws...)
	if err != nil {
		return err
	}

	return nil
}

More implementation details for plugins can be found in the [extending packer](https://www.packer.io/docs/extending) section of the website.

Index

• func Consul(k string) (string, error)
• func DeprecatedTemplateFunc(funcName, useInstead string, deprecated func(string) string) func(string) string
• func GetAWSSecret(name, key string) (string, error)
• func Vault(path string, key string) (string, error)
• type Builder
  • func (b *Builder) GoString() string
  • func (b *Builder) MarshalJSON() ([]byte, error)
• type FlatProvisioner
  • func (*FlatProvisioner) HCL2Spec() map[string]hcldec.Spec
• type OnlyExcept
  • func (o *OnlyExcept) Skip(n string) bool
  • func (o *OnlyExcept) Validate(t *Template) error
• type PostProcessor
  • func (p *PostProcessor) GoString() string
  • func (p *PostProcessor) MarshalJSON() ([]byte, error)
• type Provisioner
  • func (*Provisioner) FlatMapstructure() interface{ ... }
  • func (p *Provisioner) GoString() string
  • func (p *Provisioner) MarshalJSON() ([]byte, error)
• type Push
• type Template
  • func Parse(r io.Reader) (*Template, error)
  • func ParseFile(path string) (*Template, error)
  • func (t *Template) Raw() (*rawTemplate, error)
  • func (t *Template) Validate() error
• type Variable
  • func (v *Variable) GoString() string
  • func (v *Variable) MarshalJSON() ([]byte, error)

Functions

func Consul

func Consul(k string) (string, error)

Consul retrieves a value from a HashiCorp Consul KV store. It assumes the necessary environment variables are set.

func DeprecatedTemplateFunc

func DeprecatedTemplateFunc(funcName, useInstead string, deprecated func(string) string) func(string) string

DeprecatedTemplateFunc wraps a template func to warn users that it's deprecated. The deprecation warning is called only once.

func GetAWSSecret

func GetAWSSecret(name, key string) (string, error)

GetAwsSecret retrieves a value from an AWS Secrets Manager. It assumes that credentials are properly set in the AWS SDK's credential chain.

func Vault

func Vault(path string, key string) (string, error)

Vault retrieves a secret from a HashiCorp Vault KV store. It assumes the necessary environment variables are set.

Types

type Builder

type Builder struct {
	Name   string                 `json:"name,omitempty"`
	Type   string                 `json:"type"`
	Config map[string]interface{} `json:"config,omitempty"`
}

Builder represents a builder configured in the template

func (*Builder) GoString

func (b *Builder) GoString() string

func (*Builder) MarshalJSON

func (b *Builder) MarshalJSON() ([]byte, error)

MarshalJSON conducts the necessary flattening of the Builder struct to provide valid Packer template JSON

type FlatProvisioner

type FlatProvisioner struct {
	Only        []string               `json:"only,omitempty" cty:"only" hcl:"only"`
	Except      []string               `json:"except,omitempty" cty:"except" hcl:"except"`
	Type        *string                `json:"type" cty:"type" hcl:"type"`
	Config      map[string]interface{} `json:"config,omitempty" cty:"config" hcl:"config"`
	Override    map[string]interface{} `json:"override,omitempty" cty:"override" hcl:"override"`
	PauseBefore *string                `mapstructure:"pause_before" json:"pause_before,omitempty" cty:"pause_before" hcl:"pause_before"`
	MaxRetries  *string                `mapstructure:"max_retries" json:"max_retries,omitempty" cty:"max_retries" hcl:"max_retries"`
	Timeout     *string                `mapstructure:"timeout" json:"timeout,omitempty" cty:"timeout" hcl:"timeout"`
}

FlatProvisioner is an auto-generated flat version of Provisioner. Where the contents of a field with a `mapstructure:,squash` tag are bubbled up.

func (*FlatProvisioner) HCL2Spec

func (*FlatProvisioner) HCL2Spec() map[string]hcldec.Spec

HCL2Spec returns the hcl spec of a Provisioner. This spec is used by HCL to read the fields of Provisioner. The decoded values from this spec will then be applied to a FlatProvisioner.

type OnlyExcept

type OnlyExcept struct {
	Only   []string `json:"only,omitempty"`
	Except []string `json:"except,omitempty"`
}

OnlyExcept is a struct that is meant to be embedded that contains the logic required for "only" and "except" meta-parameters.

func (*OnlyExcept) Skip

func (o *OnlyExcept) Skip(n string) bool

Skip says whether or not to skip the build with the given name.

func (*OnlyExcept) Validate

func (o *OnlyExcept) Validate(t *Template) error

Validate validates that the OnlyExcept settings are correct for a thing.

type PostProcessor

type PostProcessor struct {
	OnlyExcept `mapstructure:",squash" json:",omitempty"`

	Name              string                 `json:"name,omitempty"`
	Type              string                 `json:"type"`
	KeepInputArtifact *bool                  `mapstructure:"keep_input_artifact" json:"keep_input_artifact,omitempty"`
	Config            map[string]interface{} `json:"config,omitempty"`
}

PostProcessor represents a post-processor within the template.

func (*PostProcessor) GoString

func (p *PostProcessor) GoString() string

func (*PostProcessor) MarshalJSON

func (p *PostProcessor) MarshalJSON() ([]byte, error)

MarshalJSON conducts the necessary flattening of the PostProcessor struct to provide valid Packer template JSON

type Provisioner

type Provisioner struct {
	OnlyExcept `mapstructure:",squash" json:",omitempty"`

	Type        string                 `json:"type"`
	Config      map[string]interface{} `json:"config,omitempty"`
	Override    map[string]interface{} `json:"override,omitempty"`
	PauseBefore time.Duration          `mapstructure:"pause_before" json:"pause_before,omitempty"`
	MaxRetries  string                 `mapstructure:"max_retries" json:"max_retries,omitempty"`
	Timeout     time.Duration          `mapstructure:"timeout" json:"timeout,omitempty"`
}

Provisioner represents a provisioner within the template.

func (*Provisioner) FlatMapstructure

func (*Provisioner) FlatMapstructure() interface{ HCL2Spec() map[string]hcldec.Spec }

FlatMapstructure returns a new FlatProvisioner. FlatProvisioner is an auto-generated flat version of Provisioner. Where the contents a fields with a `mapstructure:,squash` tag are bubbled up.

func (*Provisioner) GoString

func (p *Provisioner) GoString() string

func (*Provisioner) MarshalJSON

func (p *Provisioner) MarshalJSON() ([]byte, error)

MarshalJSON conducts the necessary flattening of the Provisioner struct to provide valid Packer template JSON

type Push

type Push struct {
	Name    string
	Address string
	BaseDir string `mapstructure:"base_dir"`
	Include []string
	Exclude []string
	Token   string
	VCS     bool
}

Push represents the configuration for pushing the template to Atlas.

type Template

type Template struct {
	// Path is the path to the template. This will be blank if Parse is
	// used, but will be automatically populated by ParseFile.
	Path string

	Description string
	MinVersion  string

	Comments           map[string]string
	Variables          map[string]*Variable
	SensitiveVariables []*Variable
	Builders           map[string]*Builder
	Provisioners       []*Provisioner
	CleanupProvisioner *Provisioner
	PostProcessors     [][]*PostProcessor

	// RawContents is just the raw data for this template
	RawContents []byte
}

Template represents the parsed template that is used to configure Packer builds.

func Parse

func Parse(r io.Reader) (*Template, error)

Parse takes the given io.Reader and parses a Template object out of it.

func ParseFile

func ParseFile(path string) (*Template, error)

ParseFile is the same as Parse but is a helper to automatically open a file for parsing.

func (*Template) Raw

func (t *Template) Raw() (*rawTemplate, error)

Raw converts a Template struct back into the raw Packer template structure

func (*Template) Validate

func (t *Template) Validate() error

Validate does some basic validation of the template on top of the validation that occurs while parsing. If possible, we try to defer validation to here. The validation errors that occur during parsing are the minimal necessary to make sure parsing builds a reasonable Template structure.

type Variable

type Variable struct {
	Key      string
	Default  string
	Required bool
}

Variable represents a variable within the template

func (*Variable) GoString

func (v *Variable) GoString() string

func (*Variable) MarshalJSON

func (v *Variable) MarshalJSON() ([]byte, error)