experiment

Documentation

Overview

experiment package contains helper functions for tracking experimental features throughout Terraform.

This package should be used for creating, enabling, querying, and deleting experimental features. By unifying all of that onto a single interface, we can have the Go compiler help us by enforcing every place we touch an experimental feature.

To create a new experiment:

1. Add the experiment to the global vars list below, prefixed with X_

2. Add the experiment variable to the All listin the init() function

3. Use it!

To remove an experiment:

1. Delete the experiment global var.

2. Try to compile and fix all the places where the var was referenced.

To use an experiment:

1. Use Flag() if you want the experiment to be available from the CLI.

2. Use Enabled() to check whether it is enabled.

As a general user:

1. The `-Xexperiment-name` flag
2. The `TF_X_<experiment-name>` env var.
3. The `TF_X_FORCE` env var can be set to force an experimental feature without human verifications.

Index

• Variables
• func Enabled(id ID) bool
• func Flag(fs *flag.FlagSet)
• func Force() bool
• func SetEnabled(id ID, v bool)
• type ID

Variables

var (
	// all is the list of all experiements. Do not modify this.
	All []ID
)

Global variables this package uses because we are a package with global state.

var (
	// Shadow graph. This is already on by default. Disabling it will be
	// allowed for awhile in order for it to not block operations.
	X_shadow = newBasicID("shadow", "SHADOW", false)
)

The experiments that are available are listed below. Any package in Terraform defining an experiment should define the experiments below. By keeping them all within the experiment package we force a single point of definition and use. This allows the compiler to enforce references so it becomes easy to remove the features.

Functions

func Enabled

func Enabled(id ID) bool

Enabled returns whether an experiment has been enabled or not.

func Flag

func Flag(fs *flag.FlagSet)

Flag configures the given FlagSet with the flags to configure all active experiments.

func Force

func Force() bool

Force returns true if the -Xforce of TF_X_FORCE flag is present, which advises users of this package to not verify with the user that they want experimental behavior and to just continue with it.

func SetEnabled

func SetEnabled(id ID, v bool)

SetEnabled sets an experiment to enabled/disabled. Please check with the experiment docs for when calling this actually affects the experiment.

Types

type ID

type ID interface {
	Env() string
	Flag() string
	Default() bool
	// contains filtered or unexported methods
}

ID represents an experimental feature.

The global vars defined on this package should be used as ID values. This interface is purposely not implement-able outside of this package so that we can rely on the Go compiler to enforce all experiment references.