planfile

Documentation

Overview

Package planfile deals with the file format used to serialize plans to disk and then deserialize them back into memory later.

A plan file contains the planned changes along with the configuration and state snapshot that they are based on.

Index

• func Create(filename string, args CreateArgs) error
• type CreateArgs
• type Reader
  • func Open(filename string) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) ReadConfig() (*configs.Config, tfdiags.Diagnostics)
  • func (r *Reader) ReadConfigSnapshot() (*configload.Snapshot, error)
  • func (r *Reader) ReadDependencyLocks() (*depsfile.Locks, tfdiags.Diagnostics)
  • func (r *Reader) ReadPlan() (*plans.Plan, error)
  • func (r *Reader) ReadPrevStateFile() (*statefile.File, error)
  • func (r *Reader) ReadStateFile() (*statefile.File, error)

Functions

func Create

func Create(filename string, args CreateArgs) error

Create creates a new plan file with the given filename, overwriting any file that might already exist there.

A plan file contains both a snapshot of the configuration and of the latest state file in addition to the plan itself, so that Terraform can detect if the world has changed since the plan was created and thus refuse to apply it.

Types

type CreateArgs

type CreateArgs struct {
	// ConfigSnapshot is a snapshot of the configuration that the plan
	// was created from.
	ConfigSnapshot *configload.Snapshot

	// PreviousRunStateFile is a representation of the state snapshot we used
	// as the original input when creating this plan, containing the same
	// information as recorded at the end of the previous apply except for
	// upgrading managed resource instance data to the provider's latest
	// schema versions.
	PreviousRunStateFile *statefile.File

	// BaseStateFile is a representation of the state snapshot we used to
	// create the plan, which is the result of asking the providers to refresh
	// all previously-stored objects to match the current situation in the
	// remote system. (If this plan was created with refreshing disabled,
	// this should be the same as PreviousRunStateFile.)
	StateFile *statefile.File

	// Plan records the plan itself, which is the main artifact inside a
	// saved plan file.
	Plan *plans.Plan

	// DependencyLocks records the dependency lock information that we
	// checked prior to creating the plan, so we can make sure that all of the
	// same dependencies are still available when applying the plan.
	DependencyLocks *depsfile.Locks
}

type Reader

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

Reader is the main type used to read plan files. Create a Reader by calling Open.

A plan file is a random-access file format, so methods of Reader must be used to access the individual portions of the file for further processing.

func Open

func Open(filename string) (*Reader, error)

Open creates a Reader for the file at the given filename, or returns an error if the file doesn't seem to be a planfile.

func (*Reader) Close

func (r *Reader) Close() error

Close closes the file, after which no other operations may be performed.

func (*Reader) ReadConfig

func (r *Reader) ReadConfig() (*configs.Config, tfdiags.Diagnostics)

ReadConfig reads the configuration embedded in the plan file.

Internally this function delegates to the configs/configload package to parse the embedded configuration and so it returns diagnostics (rather than a native Go error as with other methods on Reader).

func (*Reader) ReadConfigSnapshot

func (r *Reader) ReadConfigSnapshot() (*configload.Snapshot, error)

ReadConfigSnapshot reads the configuration snapshot embedded in the plan file.

This is a lower-level alternative to ReadConfig that just extracts the source files, without attempting to parse them.

func (*Reader) ReadDependencyLocks

func (r *Reader) ReadDependencyLocks() (*depsfile.Locks, tfdiags.Diagnostics)

ReadDependencyLocks reads the dependency lock information embedded in the plan file.

Some test codepaths create plan files without dependency lock information, but all main codepaths should populate this. If reading a file without the dependency information, this will return error diagnostics.

func (*Reader) ReadPlan

func (r *Reader) ReadPlan() (*plans.Plan, error)

ReadPlan reads the plan embedded in the plan file.

Errors can be returned for various reasons, including if the plan file is not of an appropriate format version, if it was created by a different version of Terraform, if it is invalid, etc.

func (*Reader) ReadPrevStateFile

func (r *Reader) ReadPrevStateFile() (*statefile.File, error)

ReadPrevStateFile reads the previous state file embedded in the plan file, which represents the "PrevRunState" as defined in plans.Plan.

If the plan file contains no embedded previous state file, the returned error is statefile.ErrNoState.

func (*Reader) ReadStateFile

func (r *Reader) ReadStateFile() (*statefile.File, error)

ReadStateFile reads the state file embedded in the plan file, which represents the "PriorState" as defined in plans.Plan.

If the plan file contains no embedded state file, the returned error is statefile.ErrNoState.