terraform/internal/configs/configschema/schema.go

172 lines
6.1 KiB
Go
Raw Normal View History

package configschema
import (
"github.com/zclconf/go-cty/cty"
)
type StringKind int
const (
StringPlain StringKind = iota
StringMarkdown
)
// Block represents a configuration block.
//
// "Block" here is a logical grouping construct, though it happens to map
// directly onto the physical block syntax of Terraform's native configuration
// syntax. It may be a more a matter of convention in other syntaxes, such as
// JSON.
//
// When converted to a value, a Block always becomes an instance of an object
// type derived from its defined attributes and nested blocks
type Block struct {
// Attributes describes any attributes that may appear directly inside
// the block.
Attributes map[string]*Attribute
// BlockTypes describes any nested block types that may appear directly
// inside the block.
BlockTypes map[string]*NestedBlock
Description string
DescriptionKind StringKind
Deprecated bool
}
// Attribute represents a configuration attribute, within a block.
type Attribute struct {
// Type is a type specification that the attribute's value must conform to.
// It conflicts with NestedType.
Type cty.Type
// NestedType indicates that the attribute is a NestedBlock-style object.
// This field conflicts with Type.
NestedType *Object
// Description is an English-language description of the purpose and
// usage of the attribute. A description should be concise and use only
// one or two sentences, leaving full definition to longer-form
// documentation defined elsewhere.
Description string
DescriptionKind StringKind
// Required, if set to true, specifies that an omitted or null value is
// not permitted.
Required bool
// Optional, if set to true, specifies that an omitted or null value is
// permitted. This field conflicts with Required.
Optional bool
// Computed, if set to true, specifies that the value comes from the
// provider rather than from configuration. If combined with Optional,
// then the config may optionally provide an overridden value.
Computed bool
// Sensitive, if set to true, indicates that an attribute may contain
// sensitive information.
//
// At present nothing is done with this information, but callers are
// encouraged to set it where appropriate so that it may be used in the
// future to help Terraform mask sensitive information. (Terraform
// currently achieves this in a limited sense via other mechanisms.)
Sensitive bool
Deprecated bool
}
// Object represents the embedding of a structural object inside an Attribute.
type Object struct {
// Attributes describes the nested attributes which may appear inside the
// Object.
Attributes map[string]*Attribute
// Nesting provides the nesting mode for this Object, which determines how
// many instances of the Object are allowed, how many labels it expects, and
// how the resulting data will be converted into a data structure.
Nesting NestingMode
// MinItems and MaxItems set, for the NestingList and NestingSet nesting
// modes, lower and upper limits on the number of child blocks allowed
// of the given type. If both are left at zero, no limit is applied.
// These fields are ignored for other nesting modes and must both be left
// at zero.
MinItems, MaxItems int
}
// NestedBlock represents the embedding of one block within another.
type NestedBlock struct {
// Block is the description of the block that's nested.
Block
// Nesting provides the nesting mode for the child block, which determines
// how many instances of the block are allowed, how many labels it expects,
// and how the resulting data will be converted into a data structure.
Nesting NestingMode
// MinItems and MaxItems set, for the NestingList and NestingSet nesting
// modes, lower and upper limits on the number of child blocks allowed
// of the given type. If both are left at zero, no limit is applied.
//
// As a special case, both values can be set to 1 for NestingSingle in
// order to indicate that a particular single block is required.
//
// These fields are ignored for other nesting modes and must both be left
// at zero.
MinItems, MaxItems int
}
// NestingMode is an enumeration of modes for nesting blocks inside other
// blocks.
type NestingMode int
// Object represents the embedding of a NestedBl
//go:generate go run golang.org/x/tools/cmd/stringer -type=NestingMode
const (
nestingModeInvalid NestingMode = iota
// NestingSingle indicates that only a single instance of a given
// block type is permitted, with no labels, and its content should be
// provided directly as an object value.
NestingSingle
configs/configschema: Introduce the NestingGroup mode for blocks In study of existing providers we've found a pattern we werent previously accounting for of using a nested block type to represent a group of arguments that relate to a particular feature that is always enabled but where it improves configuration readability to group all of its settings together in a nested block. The existing NestingSingle was not a good fit for this because it is designed under the assumption that the presence or absence of the block has some significance in enabling or disabling the relevant feature, and so for these always-active cases we'd generate a misleading plan where the settings for the feature appear totally absent, rather than showing the default values that will be selected. NestingGroup is, therefore, a slight variation of NestingSingle where presence vs. absence of the block is not distinguishable (it's never null) and instead its contents are treated as unset when the block is absent. This then in turn causes any default values associated with the nested arguments to be honored and displayed in the plan whenever the block is not explicitly configured. The current SDK cannot activate this mode, but that's okay because its "legacy type system" opt-out flag allows it to force a block to be processed in this way anyway. We're adding this now so that we can introduce the feature in a future SDK without causing a breaking change to the protocol, since the set of possible block nesting modes is not extensible.
2019-04-09 00:32:53 +02:00
// NestingGroup is similar to NestingSingle in that it calls for only a
// single instance of a given block type with no labels, but it additonally
// guarantees that its result will never be null, even if the block is
// absent, and instead the nested attributes and blocks will be treated
// as absent in that case. (Any required attributes or blocks within the
// nested block are not enforced unless the block is explicitly present
// in the configuration, so they are all effectively optional when the
// block is not present.)
//
// This is useful for the situation where a remote API has a feature that
// is always enabled but has a group of settings related to that feature
// that themselves have default values. By using NestingGroup instead of
// NestingSingle in that case, generated plans will show the block as
// present even when not present in configuration, thus allowing any
// default values within to be displayed to the user.
NestingGroup
// NestingList indicates that multiple blocks of the given type are
// permitted, with no labels, and that their corresponding objects should
// be provided in a list.
NestingList
// NestingSet indicates that multiple blocks of the given type are
// permitted, with no labels, and that their corresponding objects should
// be provided in a set.
NestingSet
// NestingMap indicates that multiple blocks of the given type are
// permitted, each with a single label, and that their corresponding
// objects should be provided in a map whose keys are the labels.
//
// It's an error, therefore, to use the same label value on multiple
// blocks.
NestingMap
)