Documentation
¶
Overview ¶
Package depsfile contains the logic for reading and writing Terraform's dependency lock and development override configuration files.
These files are separate from the main Terraform configuration files (.tf) for a number of reasons. The first is to help establish a distinction where .tf files configure a particular module while these configure a whole configuration tree. Another, more practical consideration is that we intend both of these files to be primarily maintained automatically by Terraform itself, rather than by human-originated edits, and so keeping them separate means that it's easier to distinguish the files that Terraform will change automatically during normal workflow from the files that Terraform only edits on direct request.
Both files use HCL syntax, for consistency with other files in Terraform that we expect humans to (in this case, only occasionally) edit directly. A dependency lock file tracks the most recently selected upstream versions of each dependency, and is intended for checkin to version control. A development override file allows for temporarily overriding upstream dependencies with local files/directories on disk as an aid to testing a cross-codebase change during development, and should not be saved in version control.
Index ¶
Constants ¶
const DevOverrideFilePath = ".terraform/dev-overrides.hcl"
DevOverrideFilePath is the path, relative to a configuration's root module directory, where Terraform will look to find a possible override file that represents a request to temporarily (within a single working directory only) use specific local directories in place of packages that would normally need to be installed from a remote location.
const LockFilePath = ".terraform.lock.hcl"
LockFilePath is the path, relative to a configuration's root module directory, where Terraform expects to find the dependency lock file for that configuration.
This file is intended to be kept in version control, so it lives directly in the root module directory. The ".terraform" prefix is intended to suggest that it's metadata about several types of objects that ultimately end up in the .terraform directory after running "terraform init".
Variables ¶
This section is empty.
Functions ¶
func ProviderIsLockable ¶
ProviderIsLockable returns true if the given provider is eligible for version locking.
Currently, all providers except builtin and legacy providers are eligible for locking.
func SaveLocksToFile ¶
func SaveLocksToFile(locks *Locks, filename string) tfdiags.Diagnostics
SaveLocksToFile writes the given locks object to the given file, entirely replacing any content already in that file, or returns error diagnostics explaining why that was not possible.
SaveLocksToFile attempts an atomic replacement of the file, as an aid to external tools such as text editor integrations that might be monitoring the file as a signal to invalidate cached metadata. Consequently, other temporary files may be temporarily created in the same directory as the given filename during the operation.
Types ¶
type Locks ¶
type Locks struct {
// contains filtered or unexported fields
}
Locks is the top-level type representing the information retained in a dependency lock file.
Locks and the other types used within it are mutable via various setter methods, but they are not safe for concurrent modifications, so it's the caller's responsibility to prevent concurrent writes and writes concurrent with reads.
func LoadLocksFromFile ¶
func LoadLocksFromFile(filename string) (*Locks, tfdiags.Diagnostics)
LoadLocksFromFile reads locks from the given file, expecting it to be a valid dependency lock file, or returns error diagnostics explaining why that was not possible.
The returned locks are a snapshot of what was present on disk at the time the method was called. It does not take into account any subsequent writes to the file, whether through this package's functions or by external writers.
If the returned diagnostics contains errors then the returned Locks may be incomplete or invalid.
func NewLocks ¶
func NewLocks() *Locks
NewLocks constructs and returns a new Locks object that initially contains no locks at all.
func (*Locks) Provider ¶
func (l *Locks) Provider(addr addrs.Provider) *ProviderLock
Provider returns the stored lock for the given provider, or nil if that provider currently has no lock.
func (*Locks) SetProvider ¶
func (l *Locks) SetProvider(addr addrs.Provider, version getproviders.Version, constraints getproviders.VersionConstraints, hashes []getproviders.Hash) *ProviderLock
SetProvider creates a new lock or replaces the existing lock for the given provider.
SetProvider returns the newly-created provider lock object, which invalidates any ProviderLock object previously returned from Provider or SetProvider for the given provider address.
Only lockable providers can be passed to this method. If you pass a non-lockable provider address then this function will panic. Use function ProviderIsLockable to determine whether a particular provider should participate in the version locking mechanism.
func (*Locks) Sources ¶
Sources returns the source code of the file the receiver was generated from, or an empty map if the receiver wasn't generated from a file.
This return type matches the one expected by HCL diagnostics printers to produce source code snapshots, which is the only intended use for this method.
type ProviderLock ¶
type ProviderLock struct {
// contains filtered or unexported fields
}
ProviderLock represents lock information for a specific provider.
func (*ProviderLock) AllHashes ¶
func (l *ProviderLock) AllHashes() []getproviders.Hash
AllHashes returns all of the package hashes that were recorded when this lock was created. If no hashes were recorded for that platform, the result is a zero-length slice.
If your intent is to verify a package against the recorded hashes, use PreferredHashes to get only the hashes which the current version of Terraform considers the strongest of the available hashing schemes, one of which must match in order for verification to be considered successful.
Do not modify the backing array of the returned slice.
func (*ProviderLock) PreferredHashes ¶
func (l *ProviderLock) PreferredHashes() []getproviders.Hash
PreferredHashes returns a filtered version of the AllHashes return value which includes only the strongest of the availabile hash schemes, in case legacy hash schemes are deprecated over time but still supported for upgrade purposes.
At least one of the given hashes must match for a package to be considered valud.
func (*ProviderLock) Provider ¶
func (l *ProviderLock) Provider() addrs.Provider
Provider returns the address of the provider this lock applies to.
func (*ProviderLock) Version ¶
func (l *ProviderLock) Version() getproviders.Version
Version returns the currently-selected version for the corresponding provider.
func (*ProviderLock) VersionConstraints ¶
func (l *ProviderLock) VersionConstraints() getproviders.VersionConstraints
VersionConstraints returns the version constraints that were recorded as being used to choose the version returned by Version.
These version constraints are not authoritative for future selections and are included only so Terraform can detect if the constraints in configuration have changed since a selection was made, and thus hint to the user that they may need to run terraform init -upgrade to apply the new constraints.
Source Files