terraform

Documentation

Overview

Package terraform handles creation/destruction of a Constellation cluster using Terraform.

Since Terraform does not provide a stable Go API, we use the `terraform-exec` package to interact with Terraform.

The Terraform templates are located in the "terraform" subdirectory. The templates are embedded into the CLI binary using `go:embed`. On use the relevant template is extracted to the working directory and the user customized variables are written to a `terraform.tfvars` file.

Index

• Variables
• func CreateGCP(ctx context.Context, cl terraformClient) (retErr error)
• func GetExecutable(ctx context.Context, workingDir string) (terraform *tfexec.Terraform, remove func(), err error)
• type Client
  • func New(ctx context.Context, workingDir string) (*Client, error)
  • func (c *Client) CleanUpWorkspace() error
  • func (c *Client) CreateCluster(ctx context.Context, logLevel LogLevel, targets ...string) (CreateOutput, error)
  • func (c *Client) CreateIAMConfig(ctx context.Context, logLevel LogLevel) (IAMOutput, error)
  • func (c *Client) Destroy(ctx context.Context, logLevel LogLevel) error
  • func (c *Client) Plan(ctx context.Context, logLevel LogLevel, planFile string, targets ...string) (bool, error)
  • func (c *Client) PrepareWorkspace(path string, vars Variables) error
  • func (c *Client) RemoveInstaller()
  • func (c *Client) Show(ctx context.Context) (*tfjson.State, error)
  • func (c *Client) ShowPlan(ctx context.Context, logLevel LogLevel, planFilePath string, output io.Writer) error
• type CommonVariables
  • func (v *CommonVariables) String() string
• type CreateOutput
• type GCPClusterVariables
  • func (v *GCPClusterVariables) String() string
• type GCPIAMOutput
• type GCPIAMVariables
  • func (v *GCPIAMVariables) String() string
• type IAMOutput
• type LogLevel
  • func ParseLogLevel(level string) (LogLevel, error)
  • func (l LogLevel) String() string
• type QEMUVariables
  • func (v *QEMUVariables) String() string
• type Variables

Variables

var ErrTerraformWorkspaceDifferentFiles = errors.New("creating cluster: trying to overwrite an existing Terraform file with a different version")

ErrTerraformWorkspaceDifferentFiles is returned when a re-used existing Terraform workspace has different files than the ones to be extracted (e.g. due to a version mix-up or incomplete writes).

var ErrTerraformWorkspaceExistsWithDifferentVariables = errors.New("creating cluster: a Terraform workspace already exists with different variables")

ErrTerraformWorkspaceExistsWithDifferentVariables is returned when existing Terraform files differ from the version the CLI wants to extract.

Functions

func CreateGCP

func CreateGCP(ctx context.Context, cl terraformClient) (retErr error)

CreateGCP creates a GCP cluster.

func GetExecutable

func GetExecutable(ctx context.Context, workingDir string) (terraform *tfexec.Terraform, remove func(), err error)

GetExecutable returns a Terraform executable either from the local filesystem, or downloads the latest version fulfilling the version constraint.

Types

type Client

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

Client manages interaction with Terraform.

func New

func New(ctx context.Context, workingDir string) (*Client, error)

New sets up a new Client for Terraform.

func (*Client) CleanUpWorkspace

func (c *Client) CleanUpWorkspace() error

CleanUpWorkspace removes terraform files from the current directory.

func (*Client) CreateCluster

func (c *Client) CreateCluster(ctx context.Context, logLevel LogLevel, targets ...string) (CreateOutput, error)

CreateCluster creates a Constellation cluster using Terraform.

func (*Client) CreateIAMConfig

func (c *Client) CreateIAMConfig(ctx context.Context, logLevel LogLevel) (IAMOutput, error)

CreateIAMConfig creates an IAM configuration using Terraform.

func (*Client) Destroy

func (c *Client) Destroy(ctx context.Context, logLevel LogLevel) error

Destroy destroys Terraform-created cloud resources.

func (*Client) Plan

func (c *Client) Plan(ctx context.Context, logLevel LogLevel, planFile string, targets ...string) (bool, error)

Plan determines the diff that will be applied by Terraform. The plan output is written to the planFile. If there is a diff, the returned bool is true. Otherwise, it is false.

func (*Client) PrepareWorkspace

func (c *Client) PrepareWorkspace(path string, vars Variables) error

PrepareWorkspace prepares a Terraform workspace for a Constellation cluster.

func (*Client) RemoveInstaller

func (c *Client) RemoveInstaller()

RemoveInstaller removes the Terraform installer, if it was downloaded for this command.

func (*Client) Show

func (c *Client) Show(ctx context.Context) (*tfjson.State, error)

Show reads the default state path and outputs the state.

func (*Client) ShowPlan

func (c *Client) ShowPlan(ctx context.Context, logLevel LogLevel, planFilePath string, output io.Writer) error

ShowPlan formats the diff in planFilePath and writes it to the specified output.

type CommonVariables

type CommonVariables struct {
	// Name of the cluster.
	Name string
	// CountControlPlanes is the number of control-plane nodes to create.
	CountControlPlanes int
	// CountWorkers is the number of worker nodes to create.
	CountWorkers int
	// StateDiskSizeGB is the size of the state disk to allocate to each node, in GB.
	StateDiskSizeGB int
}

CommonVariables is user configuration for creating a cluster with Terraform.

func (*CommonVariables) String

func (v *CommonVariables) String() string

String returns a string representation of the variables, formatted as Terraform variables.

type CreateOutput

type CreateOutput struct {
	IP     string
	Secret string
	UID    string
	// AttestationURL is the URL of the attestation provider.
	// It is only set if the cluster is created on Azure.
	AttestationURL string
}

CreateOutput contains the Terraform output values of a cluster creation.

type GCPClusterVariables

type GCPClusterVariables struct {
	// CommonVariables contains common variables.
	CommonVariables

	// Project is the ID of the GCP project to use.
	Project string
	// Region is the GCP region to use.
	Region string
	// Zone is the GCP zone to use.
	Zone string
	// CredentialsFile is the path to the GCP credentials file.
	CredentialsFile string
	// InstanceType is the GCP instance type to use.
	InstanceType string
	// StateDiskType is the GCP disk type to use for the state disk.
	StateDiskType string
	// ImageID is the ID of the GCP image to use.
	ImageID string
	// Debug is true if debug mode is enabled.
	Debug bool
}

GCPClusterVariables is user configuration for creating resources with Terraform on GCP.

func (*GCPClusterVariables) String

func (v *GCPClusterVariables) String() string

String returns a string representation of the variables, formatted as Terraform variables.

type GCPIAMOutput

type GCPIAMOutput struct {
	SaKey string
}

GCPIAMOutput contains the output information of the Terraform IAM operation on GCP.

type GCPIAMVariables

type GCPIAMVariables struct {
	// Project is the ID of the GCP project to use.
	Project string
	// Region is the GCP region to use.
	Region string
	// Zone is the GCP zone to use.
	Zone string
	// ServiceAccountID is the ID of the service account to use.
	ServiceAccountID string
}

GCPIAMVariables is user configuration for creating the IAM confioguration with Terraform on GCP.

func (*GCPIAMVariables) String

func (v *GCPIAMVariables) String() string

String returns a string representation of the IAM-specific variables, formatted as Terraform variables.

type IAMOutput

type IAMOutput struct {
	GCP GCPIAMOutput
}

IAMOutput contains the output information of the Terraform IAM operations.

type LogLevel

type LogLevel int

LogLevel is a Terraform log level. As per https://developer.hashicorp.com/terraform/internals/debugging

const (
	// LogLevelNone represents a log level that does not produce any output.
	LogLevelNone LogLevel = iota
	// LogLevelError enables log output at ERROR level.
	LogLevelError
	// LogLevelWarn enables log output at WARN level.
	LogLevelWarn
	// LogLevelInfo enables log output at INFO level.
	LogLevelInfo
	// LogLevelDebug enables log output at DEBUG level.
	LogLevelDebug
	// LogLevelTrace enables log output at TRACE level.
	LogLevelTrace
	// LogLevelJSON enables log output at TRACE level in JSON format.
	LogLevelJSON
)

func ParseLogLevel

func ParseLogLevel(level string) (LogLevel, error)

ParseLogLevel parses a log level string into a Terraform log level.

func (LogLevel) String

func (l LogLevel) String() string

String returns the string representation of a Terraform log level.

type QEMUVariables

type QEMUVariables struct {
	// CommonVariables contains common variables.
	CommonVariables

	// LibvirtURI is the libvirt connection URI.
	LibvirtURI string
	// LibvirtSocketPath is the path to the libvirt socket in case of unix socket.
	LibvirtSocketPath string
	// BootMode is the boot mode to use.
	// Can be either "uefi" or "direct-linux-boot".
	BootMode string
	// CPUCount is the number of CPUs to allocate to each node.
	CPUCount int
	// MemorySizeMiB is the amount of memory to allocate to each node, in MiB.
	MemorySizeMiB int
	// IPRangeStart is the first IP address in the IP range to allocate to the cluster.
	ImagePath string
	// ImageFormat is the format of the image from ImagePath.
	ImageFormat string
	// MetadataAPIImage is the container image to use for the metadata API.
	MetadataAPIImage string
	// MetadataLibvirtURI is the libvirt connection URI used by the metadata container.
	// In case of unix socket, this should be "qemu:///system".
	// Other wise it should be the same as LibvirtURI.
	MetadataLibvirtURI string
	// NVRAM is the path to the NVRAM template.
	NVRAM string
	// Firmware is the path to the firmware.
	Firmware string
	// BzImagePath is the path to the bzImage (kernel).
	BzImagePath string
	// InitrdPath is the path to the initrd.
	InitrdPath string
	// KernelCmdline is the kernel command line.
	KernelCmdline string
}

QEMUVariables is user configuration for creating a QEMU cluster with Terraform.

func (*QEMUVariables) String

func (v *QEMUVariables) String() string

String returns a string representation of the variables, formatted as Terraform variables.

type Variables

type Variables interface {
	fmt.Stringer
}

Variables is a struct that holds all variables that are passed to Terraform.