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, enc encryption.PlanEncryption) error
- type CreateArgs
- type ErrUnusableLocalPlan
- type Reader
- 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)
- type WrappedPlanFile
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Create ¶
func Create(filename string, args CreateArgs, enc encryption.PlanEncryption) 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 OpenTofu 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 ErrUnusableLocalPlan ¶
type ErrUnusableLocalPlan struct {
// contains filtered or unexported fields
}
ErrUnusableLocalPlan is an error wrapper to indicate that we *think* the input represents plan file data, but can't use it for some reason (as explained in the error text). Callers can check against this type with errors.As() if they need to distinguish between corrupt plan files and more fundamental problems like an empty file.
func (*ErrUnusableLocalPlan) Error ¶
func (e *ErrUnusableLocalPlan) Error() string
func (*ErrUnusableLocalPlan) Unwrap ¶
func (e *ErrUnusableLocalPlan) Unwrap() error
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, enc encryption.PlanEncryption) (*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. NOTE: Most commands that accept a plan file should use OpenWrapped instead, so they can support both local and cloud plan files.
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 ¶
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 OpenTofu, if it is invalid, etc.
func (*Reader) ReadPrevStateFile ¶
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 ¶
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.
type WrappedPlanFile ¶
type WrappedPlanFile struct {
// contains filtered or unexported fields
}
WrappedPlanFile is a sum type that represents a saved plan, loaded from a file path passed on the command line. If the specified file was a thick local plan file, the Local field will be populated; if it was a bookmark for a remote cloud plan, the Cloud field will be populated. In both cases, the other field is expected to be nil. Finally, the outer struct is also expected to be used as a pointer, so that a nil value can represent the absence of any plan file.
func NewWrappedCloud ¶
func NewWrappedCloud(c *cloudplan.SavedPlanBookmark) *WrappedPlanFile
NewWrappedCloud constructs a WrappedPlanFile from an already loaded cloud plan file. Most cases should use OpenWrapped to load from disk instead. If the provided plan file is nil, the returned pointer is nil.
func NewWrappedLocal ¶
func NewWrappedLocal(l *Reader) *WrappedPlanFile
NewWrappedLocal constructs a WrappedPlanFile from an already loaded local plan file reader. Most cases should use OpenWrapped to load from disk instead. If the provided reader is nil, the returned pointer is nil.
func OpenWrapped ¶
func OpenWrapped(filename string, enc encryption.PlanEncryption) (*WrappedPlanFile, error)
OpenWrapped loads a local or cloud plan file from a specified file path, or returns an error if the file doesn't seem to be a plan file of either kind. Most consumers should use this and switch behaviors based on the kind of plan they expected, rather than directly using Open.
func (*WrappedPlanFile) Cloud ¶
func (w *WrappedPlanFile) Cloud() (*cloudplan.SavedPlanBookmark, bool)
Cloud checks whether the wrapped value is a cloud plan file, and returns it if available.
func (*WrappedPlanFile) IsCloud ¶
func (w *WrappedPlanFile) IsCloud() bool
func (*WrappedPlanFile) IsLocal ¶
func (w *WrappedPlanFile) IsLocal() bool
func (*WrappedPlanFile) Local ¶
func (w *WrappedPlanFile) Local() (*Reader, bool)
Local checks whether the wrapped value is a local plan file, and returns it if available.
Source Files