checks

Documentation

Overview

Package checks contains the models for representing various kinds of declarative condition checks that can be defined in a Terraform module and then evaluated and reported by Terraform Core during plan and apply operations.

Index

• type State
  • func NewState(config *configs.Config) *State
  • func (c *State) AggregateCheckStatus(addr addrs.ConfigCheckable) Status
  • func (c *State) AllConfigAddrs() addrs.Set[addrs.ConfigCheckable]
  • func (c *State) ConfigHasChecks(addr addrs.ConfigCheckable) bool
  • func (c *State) ObjectAddrs(configAddr addrs.ConfigCheckable) addrs.Set[addrs.Checkable]
  • func (c *State) ObjectCheckStatus(addr addrs.Checkable) Status
  • func (c *State) ObjectFailureMessages(addr addrs.Checkable) []string
  • func (c *State) ReportCheckFailure(objectAddr addrs.Checkable, checkType addrs.CheckType, index int, ...)
  • func (c *State) ReportCheckResult(objectAddr addrs.Checkable, checkType addrs.CheckType, index int, ...)
  • func (c *State) ReportCheckableObjects(configAddr addrs.ConfigCheckable, objectAddrs addrs.Set[addrs.Checkable])
• type Status
  • func StatusForCtyValue(v cty.Value) Status
  • func (i Status) String() string

Types

type State

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

State is a container for state tracking of all of the the checks declared in a particular Terraform configuration and their current statuses.

A State object is mutable during plan and apply operations but should otherwise be treated as a read-only snapshot of the status of checks at a particular moment.

The checks State tracks a few different concepts:

• configuration objects: items in the configuration which statically declare some checks associated with zero or more checkable objects.
• checkable objects: dynamically-determined objects that are each associated with one configuration object.
• checks: a single check that is declared as part of a configuration object and then resolved once for each of its associated checkable objects.
• check statuses: the current state of a particular check associated with a particular checkable object.

This container type is concurrency-safe for both reads and writes through its various methods.

func NewState

func NewState(config *configs.Config) *State

NewState returns a new State object representing the check statuses of objects declared in the given configuration.

The configuration determines which configuration objects and associated checks we'll be expecting to see, so that we can seed their statuses as all unknown until we see affirmative reports sent by the Report-prefixed methods on Checks.

func (*State) AggregateCheckStatus

func (c *State) AggregateCheckStatus(addr addrs.ConfigCheckable) Status

AggregateCheckStatus returns a summarization of all of the check results for a particular configuration object into a single status.

The given address must refer to an object within the configuration that this Checks was instantiated from, or this method will panic.

func (*State) AllConfigAddrs

func (c *State) AllConfigAddrs() addrs.Set[addrs.ConfigCheckable]

AllConfigAddrs returns all of the addresses of all configuration objects that could potentially produce checkable objects at runtime.

This is a good starting point for reporting on the outcome of all of the configured checks at the configuration level of granularity, e.g. for automated testing reports where we want to report the status of all configured checks even if the graph walk aborted before we reached any of their objects.

func (*State) ConfigHasChecks

func (c *State) ConfigHasChecks(addr addrs.ConfigCheckable) bool

ConfigHasChecks returns true if and only if the given address refers to a configuration object that this State object is expecting to recieve statuses for.

Other methods of Checks will typically panic if given a config address that would not have returned true from ConfigHasChecked.

func (*State) ObjectAddrs

func (c *State) ObjectAddrs(configAddr addrs.ConfigCheckable) addrs.Set[addrs.Checkable]

ObjectAddrs returns the addresses of individual checkable objects belonging to the configuration object with the given address.

This will panic if the given address isn't a known configuration object that has checks.

func (*State) ObjectCheckStatus

func (c *State) ObjectCheckStatus(addr addrs.Checkable) Status

ObjectCheckStatus returns a summarization of all of the check results for a particular checkable object into a single status.

The given address must refer to a checkable object that Terraform Core previously reported while doing a graph walk, or this method will panic.

func (*State) ObjectFailureMessages

func (c *State) ObjectFailureMessages(addr addrs.Checkable) []string

ObjectFailureMessages returns the zero or more failure messages reported for the object with the given address.

Failure messages are recorded only for checks whose status is StatusFail, but since this aggregates together the results of all of the checks on the given object it's possible for there to be a mixture of failures and errors at the same time, which would aggregate as StatusError in ObjectCheckStatus's result because errors are defined as "stronger" than failures.

func (*State) ReportCheckFailure

func (c *State) ReportCheckFailure(objectAddr addrs.Checkable, checkType addrs.CheckType, index int, errorMessage string)

ReportCheckFailure is a more specialized version of ReportCheckResult which captures a failure outcome in particular, giving the opportunity to capture an author-specified error message string along with the failure.

This always records the given check as having StatusFail. Don't use this for situations where the check condition was itself invalid, because that should be represented by StatusError instead, and the error signalled via diagnostics as normal.

func (*State) ReportCheckResult

func (c *State) ReportCheckResult(objectAddr addrs.Checkable, checkType addrs.CheckType, index int, status Status)

ReportCheckResult is the interface by which Terraform Core should tell the State object the result of a specific check for an object that was previously registered with ReportCheckableObjects.

If the given object address doesn't match a previously-reported object, or if the check index is out of bounds for the number of checks expected of the given type, this method will panic to indicate a bug in the caller.

This method will also panic if the specified check already had a known status; each check should have its result reported only once.

func (*State) ReportCheckableObjects

func (c *State) ReportCheckableObjects(configAddr addrs.ConfigCheckable, objectAddrs addrs.Set[addrs.Checkable])

ReportCheckableObjects is the interface by which Terraform Core should tell the State object which specific checkable objects were declared by the given configuration object.

This method will panic if the given configuration address isn't one known by this Checks to have pending checks, and if any of the given object addresses don't belong to the given configuration address.

type Status

type Status rune

Status represents the status of an individual check associated with a checkable object.

const (
	// StatusUnknown represents that there is not yet a conclusive result
	// for the check, either because we haven't yet visited its associated
	// object or because the check condition itself depends on a value not
	// yet known during planning.
	StatusUnknown Status = 0

	// StatusPass represents that Terraform Core has evaluated the check's
	// condition and it returned true, indicating success.
	StatusPass Status = 'P'

	// StatusFail represents that Terraform Core has evaluated the check's
	// condition and it returned false, indicating failure.
	StatusFail Status = 'F'

	// StatusError represents that Terraform Core tried to evaluate the check's
	// condition but encountered an error while evaluating the check expression.
	//
	// This is different than StatusFail because StatusFail indiciates that
	// the condition was valid and returned false, whereas StatusError
	// indicates that the condition was not valid at all.
	StatusError Status = 'E'
)

func StatusForCtyValue

func StatusForCtyValue(v cty.Value) Status

StatusForCtyValue returns the Status value corresponding to the given cty Value, which must be one of either cty.True, cty.False, or cty.UnknownVal(cty.Bool) or else this function will panic.

The current behavior of this function is:

cty.True                  StatusPass
cty.False                 StatusFail
cty.UnknownVal(cty.Bool)  StatusUnknown

Any other input will panic. Note that there's no value that can produce StatusError, because in case of a condition error there will not typically be a result value at all.

func (Status) String

func (i Status) String() string