terraform/internal/configs/provisioner.go

238 lines
6.9 KiB
Go
Raw Normal View History

package configs
import (
"fmt"
"github.com/hashicorp/hcl/v2"
)
// Provisioner represents a "provisioner" block when used within a
// "resource" block in a module or file.
type Provisioner struct {
Type string
Config hcl.Body
Connection *Connection
When ProvisionerWhen
OnFailure ProvisionerOnFailure
DeclRange hcl.Range
TypeRange hcl.Range
}
func decodeProvisionerBlock(block *hcl.Block) (*Provisioner, hcl.Diagnostics) {
pv := &Provisioner{
Type: block.Labels[0],
TypeRange: block.LabelRanges[0],
DeclRange: block.DefRange,
When: ProvisionerWhenCreate,
OnFailure: ProvisionerOnFailureFail,
}
content, config, diags := block.Body.PartialContent(provisionerBlockSchema)
pv.Config = config
switch pv.Type {
case "chef", "habitat", "puppet", "salt-masterless":
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: fmt.Sprintf("The \"%s\" provisioner has been removed", pv.Type),
Detail: fmt.Sprintf("The \"%s\" provisioner was deprecated in Terraform 0.13.4 has been removed from Terraform. Visit https://learn.hashicorp.com/collections/terraform/provision for alternatives to using provisioners that are a better fit for the Terraform workflow.", pv.Type),
Subject: &pv.TypeRange,
})
return nil, diags
}
if attr, exists := content.Attributes["when"]; exists {
expr, shimDiags := shimTraversalInString(attr.Expr, true)
diags = append(diags, shimDiags...)
switch hcl.ExprAsKeyword(expr) {
case "create":
pv.When = ProvisionerWhenCreate
case "destroy":
pv.When = ProvisionerWhenDestroy
default:
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Invalid \"when\" keyword",
Detail: "The \"when\" argument requires one of the following keywords: create or destroy.",
Subject: expr.Range().Ptr(),
})
}
}
// destroy provisioners can only refer to self
if pv.When == ProvisionerWhenDestroy {
diags = append(diags, onlySelfRefs(config)...)
}
if attr, exists := content.Attributes["on_failure"]; exists {
expr, shimDiags := shimTraversalInString(attr.Expr, true)
diags = append(diags, shimDiags...)
switch hcl.ExprAsKeyword(expr) {
case "continue":
pv.OnFailure = ProvisionerOnFailureContinue
case "fail":
pv.OnFailure = ProvisionerOnFailureFail
default:
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Invalid \"on_failure\" keyword",
Detail: "The \"on_failure\" argument requires one of the following keywords: continue or fail.",
Subject: attr.Expr.Range().Ptr(),
})
}
}
var seenConnection *hcl.Block
configs: Meta-argument escaping blocks Several top-level block types in the Terraform language have a body where two different schemas are overlayed on top of one another: Terraform first looks for "meta-arguments" that are built into the language, and then evaluates all of the remaining arguments against some externally-defined schema whose content is not fully controlled by Terraform. So far we've been cautiously adding new meta-arguments in these namespaces after research shows us that there are relatively few existing providers or modules that would have functionality masked by those additions, but that isn't really a viable path forward as we prepare to make stronger compatibility promises. In an earlier commit we've introduced the foundational parts of a new language versioning mechanism called "editions" which should allow us to make per-module-opt-in breaking changes in the future, but these shared namespaces remain a liability because it would be annoying if adopting a new edition made it impossible to use a feature of a third-party provider or module that was already using a name that has now become reserved in the new edition. This commit introduces a new syntax intended to be a rarely-used escape hatch for that situation. When we're designing new editions we will do our best to choose names that don't conflict with commonly-used providers and modules, but there are many providers and modules that we cannot see and so there is a risk that any name we might choose could collide with at least one existing provider or module. The automatic migration tool to upgrade an existing module to a new edition should therefore detect that situation and make use of this escaping block syntax in order to retain the existing functionality until all the called providers or modules are updated to no longer use conflicting names. Although we can't put in technical constraints on using this feature for other purposes (because we don't know yet what future editions will add), this mechanism is intentionally not documented for now because it serves no immediate purpose. In effect, this change is just squatting on the syntax of a special block type named "_" so that later editions can make use of it without it _also_ conflicting, creating a confusing nested escaping situation. However, the first time a new edition actually makes use of this syntax we should then document alongside the meta-arguments so folks can understand the meaning of escaping blocks produced by edition upgrade tools.
2021-05-15 01:09:51 +02:00
var seenEscapeBlock *hcl.Block
for _, block := range content.Blocks {
switch block.Type {
configs: Meta-argument escaping blocks Several top-level block types in the Terraform language have a body where two different schemas are overlayed on top of one another: Terraform first looks for "meta-arguments" that are built into the language, and then evaluates all of the remaining arguments against some externally-defined schema whose content is not fully controlled by Terraform. So far we've been cautiously adding new meta-arguments in these namespaces after research shows us that there are relatively few existing providers or modules that would have functionality masked by those additions, but that isn't really a viable path forward as we prepare to make stronger compatibility promises. In an earlier commit we've introduced the foundational parts of a new language versioning mechanism called "editions" which should allow us to make per-module-opt-in breaking changes in the future, but these shared namespaces remain a liability because it would be annoying if adopting a new edition made it impossible to use a feature of a third-party provider or module that was already using a name that has now become reserved in the new edition. This commit introduces a new syntax intended to be a rarely-used escape hatch for that situation. When we're designing new editions we will do our best to choose names that don't conflict with commonly-used providers and modules, but there are many providers and modules that we cannot see and so there is a risk that any name we might choose could collide with at least one existing provider or module. The automatic migration tool to upgrade an existing module to a new edition should therefore detect that situation and make use of this escaping block syntax in order to retain the existing functionality until all the called providers or modules are updated to no longer use conflicting names. Although we can't put in technical constraints on using this feature for other purposes (because we don't know yet what future editions will add), this mechanism is intentionally not documented for now because it serves no immediate purpose. In effect, this change is just squatting on the syntax of a special block type named "_" so that later editions can make use of it without it _also_ conflicting, creating a confusing nested escaping situation. However, the first time a new edition actually makes use of this syntax we should then document alongside the meta-arguments so folks can understand the meaning of escaping blocks produced by edition upgrade tools.
2021-05-15 01:09:51 +02:00
case "_":
if seenEscapeBlock != nil {
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Duplicate escaping block",
Detail: fmt.Sprintf(
"The special block type \"_\" can be used to force particular arguments to be interpreted as provisioner-typpe-specific rather than as meta-arguments, but each provisioner block can have only one such block. The first escaping block was at %s.",
seenEscapeBlock.DefRange,
),
Subject: &block.DefRange,
})
continue
}
seenEscapeBlock = block
// When there's an escaping block its content merges with the
// existing config we extracted earlier, so later decoding
// will see a blend of both.
pv.Config = hcl.MergeBodies([]hcl.Body{pv.Config, block.Body})
case "connection":
if seenConnection != nil {
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Duplicate connection block",
Detail: fmt.Sprintf("This provisioner already has a connection block at %s.", seenConnection.DefRange),
Subject: &block.DefRange,
})
continue
}
seenConnection = block
// destroy provisioners can only refer to self
if pv.When == ProvisionerWhenDestroy {
diags = append(diags, onlySelfRefs(block.Body)...)
}
pv.Connection = &Connection{
Config: block.Body,
DeclRange: block.DefRange,
}
default:
// Any other block types are ones we've reserved for future use,
// so they get a generic message.
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Reserved block type name in provisioner block",
Detail: fmt.Sprintf("The block type name %q is reserved for use by Terraform in a future version.", block.Type),
Subject: &block.TypeRange,
})
}
}
return pv, diags
}
func onlySelfRefs(body hcl.Body) hcl.Diagnostics {
var diags hcl.Diagnostics
// Provisioners currently do not use any blocks in their configuration.
// Blocks are likely to remain solely for meta parameters, but in the case
// that blocks are supported for provisioners, we will want to extend this
// to find variables in nested blocks.
attrs, _ := body.JustAttributes()
for _, attr := range attrs {
for _, v := range attr.Expr.Variables() {
valid := false
switch v.RootName() {
case "self", "path", "terraform":
valid = true
case "count":
// count must use "index"
if len(v) == 2 {
if t, ok := v[1].(hcl.TraverseAttr); ok && t.Name == "index" {
valid = true
}
}
case "each":
if len(v) == 2 {
if t, ok := v[1].(hcl.TraverseAttr); ok && t.Name == "key" {
valid = true
}
}
}
if !valid {
diags = append(diags, &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Invalid reference from destroy provisioner",
Detail: "Destroy-time provisioners and their connection configurations may only " +
"reference attributes of the related resource, via 'self', 'count.index', " +
"or 'each.key'.\n\nReferences to other resources during the destroy phase " +
"can cause dependency cycles and interact poorly with create_before_destroy.",
Subject: attr.Expr.Range().Ptr(),
})
}
}
}
return diags
}
// Connection represents a "connection" block when used within either a
// "resource" or "provisioner" block in a module or file.
type Connection struct {
Config hcl.Body
DeclRange hcl.Range
}
// ProvisionerWhen is an enum for valid values for when to run provisioners.
type ProvisionerWhen int
//go:generate go run golang.org/x/tools/cmd/stringer -type ProvisionerWhen
const (
ProvisionerWhenInvalid ProvisionerWhen = iota
ProvisionerWhenCreate
ProvisionerWhenDestroy
)
// ProvisionerOnFailure is an enum for valid values for on_failure options
// for provisioners.
type ProvisionerOnFailure int
//go:generate go run golang.org/x/tools/cmd/stringer -type ProvisionerOnFailure
const (
ProvisionerOnFailureInvalid ProvisionerOnFailure = iota
ProvisionerOnFailureContinue
ProvisionerOnFailureFail
)
var provisionerBlockSchema = &hcl.BodySchema{
Attributes: []hcl.AttributeSchema{
{Name: "when"},
{Name: "on_failure"},
},
Blocks: []hcl.BlockHeaderSchema{
configs: Meta-argument escaping blocks Several top-level block types in the Terraform language have a body where two different schemas are overlayed on top of one another: Terraform first looks for "meta-arguments" that are built into the language, and then evaluates all of the remaining arguments against some externally-defined schema whose content is not fully controlled by Terraform. So far we've been cautiously adding new meta-arguments in these namespaces after research shows us that there are relatively few existing providers or modules that would have functionality masked by those additions, but that isn't really a viable path forward as we prepare to make stronger compatibility promises. In an earlier commit we've introduced the foundational parts of a new language versioning mechanism called "editions" which should allow us to make per-module-opt-in breaking changes in the future, but these shared namespaces remain a liability because it would be annoying if adopting a new edition made it impossible to use a feature of a third-party provider or module that was already using a name that has now become reserved in the new edition. This commit introduces a new syntax intended to be a rarely-used escape hatch for that situation. When we're designing new editions we will do our best to choose names that don't conflict with commonly-used providers and modules, but there are many providers and modules that we cannot see and so there is a risk that any name we might choose could collide with at least one existing provider or module. The automatic migration tool to upgrade an existing module to a new edition should therefore detect that situation and make use of this escaping block syntax in order to retain the existing functionality until all the called providers or modules are updated to no longer use conflicting names. Although we can't put in technical constraints on using this feature for other purposes (because we don't know yet what future editions will add), this mechanism is intentionally not documented for now because it serves no immediate purpose. In effect, this change is just squatting on the syntax of a special block type named "_" so that later editions can make use of it without it _also_ conflicting, creating a confusing nested escaping situation. However, the first time a new edition actually makes use of this syntax we should then document alongside the meta-arguments so folks can understand the meaning of escaping blocks produced by edition upgrade tools.
2021-05-15 01:09:51 +02:00
{Type: "_"}, // meta-argument escaping block
{Type: "connection"},
{Type: "lifecycle"}, // reserved for future use
},
}