terraformer

Documentation

Index

• Constants
• Variables
• type Command
• type Config
  • func (c *Config) MarshalLogObject(enc zapcore.ObjectEncoder) error
• type ConfigMapStore
  • func (c *ConfigMapStore) Object() client.Object
  • func (c *ConfigMapStore) Read(key string) (io.Reader, error)
  • func (c *ConfigMapStore) Store(key string, data io.Reader) error
• type KeyNotFoundError
  • func (k KeyNotFoundError) Error() string
• type PathSet
  • func DefaultPaths() *PathSet
  • func (p *PathSet) EnsureDirs(log logr.Logger) error
  • func (p *PathSet) WithBaseDir(baseDir string) *PathSet
• type SecretStore
  • func (s *SecretStore) Object() client.Object
  • func (s *SecretStore) Read(key string) (io.Reader, error)
  • func (s *SecretStore) Store(key string, data io.Reader) error
• type Store
• type Terraformer
  • func NewDefaultTerraformer(config *Config) (*Terraformer, error)
  • func NewTerraformer(config *Config, log logr.Logger, paths *PathSet, clock clock.Clock) (*Terraformer, error)
  • func (t *Terraformer) EnsureTFDirs() error
  • func (t *Terraformer) FetchConfigAndState(ctx context.Context) error
  • func (t *Terraformer) InjectClient(client client.Client) error
  • func (t *Terraformer) LogStateContentsToStdout() error
  • func (t *Terraformer) Run(command Command) error
  • func (t *Terraformer) StartFileWatcher() (func(), error)
  • func (t *Terraformer) StartStateUpdateWorker() func()
  • func (t *Terraformer) StoreState(ctx context.Context) error
  • func (t *Terraformer) TriggerAndWaitForFinalStateUpdate() error

Constants

const (
	// FinalStateUpdateKey is a key, which will be added to the state-update queue to trigger the final state update.
	// It indicates, that the state update should be retried on any error (i.e. the worker should add the key back
	// to the queue after the update failed).
	FinalStateUpdateKey = iota
	// ContinuousStateUpdateKey is a key, which will be added to the state-update queue to trigger a state update during
	// runtime of terraformer, i.e. on changes to the state file. It indicates, that the state doesn't need to be
	// retried (i.e. the worker should not add the key back to the queue).
	ContinuousStateUpdateKey
)

const (

	// FinalStateUpdateTimeout is the overall timeout for waiting for the final state update to succeed
	// (including retries with exponential backoff)
	FinalStateUpdateTimeout = time.Hour
)

const (
	// TerraformerFinalizer is the finalizer used by the terraformer on the terraform configmaps and secrets
	TerraformerFinalizer = "gardener.cloud/terraformer"
)

Variables

var (
	// TerraformBinary is the name of the terraform binary, it allows to overwrite it for testing purposes
	TerraformBinary = "terraform"

	// Stdout alias to os.Stdout allowing output redirection in tests
	Stdout io.Writer = os.Stdout

	// Stderr alias to os.Stderr allowing output redirection in tests
	Stderr io.Writer = os.Stderr

	// SignalNotify allows mocking signal.Notify in tests
	SignalNotify = signal.Notify
)

var SupportedCommands = map[Command]struct{}{
	Apply:    {},
	Destroy:  {},
	Validate: {},
}

SupportedCommands contains the set of supported terraform commands, that can be run as `terraformer <command>`.

Types

type Command

type Command string

Command is a terraform command

const (
	// Init is the terraform `init` command.
	Init Command = "init"
	// Apply is the terraform `apply` command.
	Apply Command = "apply"
	// Destroy is the terraform `destroy` command.
	Destroy Command = "destroy"
	// Validate is the terraform `validate` command.
	Validate Command = "validate"
	// Plan is the terraform `plan` command.
	Plan Command = "plan"
	// StateReplaceProvider is the terraform `state` command with the `replace-provider` subcommand.
	StateReplaceProvider Command = "state replace-provider"
)

known terraform commands

type Config

type Config struct {
	// ConfigurationConfigMapName is the name of the ConfigMap that holds the `main.tf` and `variables.tf` files.
	ConfigurationConfigMapName string
	// StateConfigMapName is the name of the ConfigMap that the `terraform.tfstate` file should be stored in.
	StateConfigMapName string
	// VariablesSecretName is the name of the Secret that holds the `terraform.tfvars` file.
	VariablesSecretName string
	// Namespace is the namespace to store the configuration resources in.
	Namespace string

	// RESTConfig holds the completed rest.Config.
	RESTConfig *rest.Config

	// BaseDir is the base directory to be used for all terraform files (defaults to '/').
	BaseDir string
}

Config holds configuration options for Terraformer.

func (*Config) MarshalLogObject

func (c *Config) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements zapcore.ObjectMarshaler.

type ConfigMapStore

type ConfigMapStore struct {
	*corev1.ConfigMap
}

ConfigMapStore implements Store by storing data in a ConfigMap.

func (*ConfigMapStore) Object

func (c *ConfigMapStore) Object() client.Object

Object returns the underlying ConfigMap.

func (*ConfigMapStore) Read

func (c *ConfigMapStore) Read(key string) (io.Reader, error)

Read returns a reader for reading the value of the given key in the ConfigMap.

func (*ConfigMapStore) Store

func (c *ConfigMapStore) Store(key string, data io.Reader) error

Store reads from the given reader and stores the contents under the given key in the ConfigMap.

type KeyNotFoundError

type KeyNotFoundError string

KeyNotFoundError is returned from a Store.Read if the store does not contain a value for the requested key.

func (KeyNotFoundError) Error

func (k KeyNotFoundError) Error() string

Error implements error.

type PathSet

type PathSet struct {
	// ConfigDir is the directory to hold the main terraform scripts (`main.tf` and `variables.tf`)
	ConfigDir string
	// VarsDir is the directory to hold the terraform variables values file (`terraform.tfvars`)
	VarsDir string
	// StateDir is the directory to hold the terraform state file (`terraform.tfstate`)
	StateDir string
	// ProvidersDir is the directory which contains the provider plugin binaries
	ProvidersDir string

	// TerminationMessagePath is the file, which the termination log should be written to.
	// Should be used as spec.containers[].terminationMessagePath in the terraformer pod spec,
	// see https://kubernetes.io/docs/tasks/debug-application-cluster/determine-reason-pod-failure/
	TerminationMessagePath string

	// VarsPath is the complete path the the variables values file
	VarsPath string
	// StatePath is the complete path the the state file
	StatePath string
}

PathSet carries the set of file paths for terraform files and allows to set different paths in tests

func DefaultPaths

func DefaultPaths() *PathSet

DefaultPaths returns the default PathSet used in terraformer

func (*PathSet) EnsureDirs

func (p *PathSet) EnsureDirs(log logr.Logger) error

EnsureDirs ensures that the needed directories for the terraform files are present.

func (*PathSet) WithBaseDir

func (p *PathSet) WithBaseDir(baseDir string) *PathSet

WithBaseDir returns a copy of the PathSet with all paths rooted in baseDir. This is used for testing purposes to use paths located e.g. under temporary directories.

type SecretStore

type SecretStore struct {
	*corev1.Secret
}

SecretStore implements Store by storing data in a Secret.

func (*SecretStore) Object

func (s *SecretStore) Object() client.Object

Object returns the underlying Secret.

func (*SecretStore) Read

func (s *SecretStore) Read(key string) (io.Reader, error)

Read returns a reader for reading the value of the given key in the Secret.

func (*SecretStore) Store

func (s *SecretStore) Store(key string, data io.Reader) error

Store reads from the given reader and stores the contents under the given key in the Secret.

type Store

type Store interface {
	// Object returns the underlying Object to pass it to a client (for retrieving and updating).
	Object() client.Object
	// Read returns a reader for reading the contents stored under the given key.
	Read(key string) (io.Reader, error)
	// Store reads the given data and stores it under the given key.
	Store(key string, data io.Reader) error
}

Store models storing arbitrary data in a runtime.Object. Implementations have to define how to read and store data under a certain key.

type Terraformer

type Terraformer struct {

	// StateUpdateQueue is the queue in which file watch events are inserted to trigger a state update.
	// It is also used for triggering the final state update.
	StateUpdateQueue workqueue.RateLimitingInterface
	// FinalStateUpdateSucceeded is a channel over which a value will be send by the state update worker
	// to signal that the final state update has succeeded and terraformer can safely exit.
	FinalStateUpdateSucceeded chan struct{}
	// contains filtered or unexported fields
}

Terraformer can execute terraform commands and fetch/store config and state from/into Secrets/ConfigMaps

func NewDefaultTerraformer

func NewDefaultTerraformer(config *Config) (*Terraformer, error)

NewDefaultTerraformer creates a new Terraformer with the default PathSet and logger.

func NewTerraformer

func NewTerraformer(config *Config, log logr.Logger, paths *PathSet, clock clock.Clock) (*Terraformer, error)

NewTerraformer creates a new Terraformer with the given options.

func (*Terraformer) EnsureTFDirs

func (t *Terraformer) EnsureTFDirs() error

EnsureTFDirs ensures that the needed directories for the terraform files are present.

func (*Terraformer) FetchConfigAndState

func (t *Terraformer) FetchConfigAndState(ctx context.Context) error

FetchConfigAndState fetches the needed config and state objects from the Kubernetes API and stores their contents in separate files.

func (*Terraformer) InjectClient

func (t *Terraformer) InjectClient(client client.Client) error

InjectClient allows injecting a mock client for some test cases.

func (*Terraformer) LogStateContentsToStdout

func (t *Terraformer) LogStateContentsToStdout() error

LogStateContentsToStdout copies the contents of the state file to Stdout. This is the last resort in case we couldn't update the state ConfigMap before timing out (e.g. in catastrophic situations where the API server is unavailable for over 1h). Maybe the logs can help in such situations to recover the state.

func (*Terraformer) Run

func (t *Terraformer) Run(command Command) error

Run starts to terraformer execution with the given terraform command.

func (*Terraformer) StartFileWatcher

func (t *Terraformer) StartFileWatcher() (func(), error)

StartFileWatcher watches the state file for changes and stores the file contents in the state ConfigMap as soon as the file gets updated. It returns a func that should be executed as part of the shutdown procedure, which stops the file watcher and waits for the event handler goroutine to finish.

func (*Terraformer) StartStateUpdateWorker

func (t *Terraformer) StartStateUpdateWorker() func()

StartStateUpdateWorker starts a worker goroutine, that will read from the state-update queue and call StoreState for every item. It returns a func that should be executed as part of the shutdown procedure, which shuts down the workqueue and the worker and then waits until the worker has finished the last work item.

func (*Terraformer) StoreState

func (t *Terraformer) StoreState(ctx context.Context) error

StoreState stores the state file in the configured state ConfigMap. It uses a hard timeout of 2m and doesn't retry the update on any error.

func (*Terraformer) TriggerAndWaitForFinalStateUpdate

func (t *Terraformer) TriggerAndWaitForFinalStateUpdate() error

TriggerAndWaitForFinalStateUpdate triggers the final state update and waits until it has succeeded or timed out.