tfr

Documentation

Overview

Package tfr contains functions and routines for interacting with terraform registries using the Module Registry Protocol documented in the official terraform docs: https://www.terraform.io/docs/internals/module-registry-protocol.html

MAINTAINER'S NOTE: Ideally we would be able to reuse code from Terraform. However, terraform has moved to packaging all its libraries under internal so that you can't use them as a library outside of Terraform. To respect the direction and spirit of the Terraform team, we opted for not doing anything funky to workaround the limitation (like copying those files in here). We also opted to keep this functionality internal to align with the Terraform team's decision to not support client libraries for accessing the Terraform Registry.

Index

• type MalformedRegistryURLErr
  • func (err MalformedRegistryURLErr) Error() string
• type ModuleDownloadErr
  • func (err ModuleDownloadErr) Error() string
• type RegistryAPIErr
  • func (err RegistryAPIErr) Error() string
• type ServiceDiscoveryErr
  • func (err ServiceDiscoveryErr) Error() string
• type TerraformRegistryGetter
  • func (tfrGetter *TerraformRegistryGetter) ClientMode(u *url.URL) (getter.ClientMode, error)
  • func (tfrGetter *TerraformRegistryGetter) Context() context.Context
  • func (tfrGetter *TerraformRegistryGetter) Get(dstPath string, srcURL *url.URL) error
  • func (tfrGetter *TerraformRegistryGetter) GetFile(dst string, src *url.URL) error
  • func (tfrGetter *TerraformRegistryGetter) SetClient(client *getter.Client)
• type TerraformRegistryServicePath

Types

type MalformedRegistryURLErr

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

MalformedRegistryURLErr is returned if the Terraform Registry URL passed to the Getter is malformed.

func (MalformedRegistryURLErr) Error

func (err MalformedRegistryURLErr) Error() string

type ModuleDownloadErr

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

ModuleDownloadErr is returned if Terragrunt failed to download the module.

func (ModuleDownloadErr) Error

func (err ModuleDownloadErr) Error() string

type RegistryAPIErr

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

RegistryAPIErr is returned if we get an unsuccessful HTTP return code from the registry.

func (RegistryAPIErr) Error

func (err RegistryAPIErr) Error() string

type ServiceDiscoveryErr

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

ServiceDiscoveryErr is returned if Terragrunt failed to identify the module API endpoint through the service discovery protocol.

func (ServiceDiscoveryErr) Error

func (err ServiceDiscoveryErr) Error() string

type TerraformRegistryGetter

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

TerraformRegistryGetter is a Getter (from go-getter) implementation that will download from the terraform module registry. This supports getter URLs encoded in the following manner:

tfr://REGISTRY_DOMAIN/MODULE_PATH?version=VERSION

Where the REGISTRY_DOMAIN is the terraform registry endpoint (e.g., registry.terraform.io), MODULE_PATH is the registry path for the module (e.g., terraform-aws-modules/vpc/aws), and VERSION is the specific version of the module to download (e.g., 2.2.0).

This protocol will use the Module Registry Protocol (documented at https://www.terraform.io/docs/internals/module-registry-protocol.html) to lookup the module source URL and download it.

Authentication to private module registries is handled via environment variables. The authorization API token is expected to be provided to Terragrunt via the TG_TF_REGISTRY_TOKEN environment variable. This token can be any registry API token generated on Terraform Cloud / Enterprise.

MAINTAINER'S NOTE: Ideally we implement the full credential system that terraform uses as part of `terraform login`, but all the relevant packages are internal to the terraform repository, thus making it difficult to use as a library. For now, we keep things simple by supporting providing tokens via env vars and in the future, we can consider implementing functionality to load credentials from terraform. GH issue: https://github.com/gruntwork-io/terragrunt/issues/1771

MAINTAINER'S NOTE: Ideally we can support a shorthand notation that omits the tfr:// protocol to detect that it is referring to a terraform registry, but this requires implementing a complex detector and ensuring it has precedence over the file detector. We deferred the implementation for that to a future release. GH issue: https://github.com/gruntwork-io/terragrunt/issues/1772

func (*TerraformRegistryGetter) ClientMode

func (tfrGetter *TerraformRegistryGetter) ClientMode(u *url.URL) (getter.ClientMode, error)

ClientMode returns the download mode based on the given URL. Since this getter is designed around the Terraform module registry, we always use Dir mode so that we can download the full Terraform module.

func (*TerraformRegistryGetter) Context

func (tfrGetter *TerraformRegistryGetter) Context() context.Context

Context returns the go context to use for the underlying fetch routines. This depends on what client is set.

func (*TerraformRegistryGetter) Get

func (tfrGetter *TerraformRegistryGetter) Get(dstPath string, srcURL *url.URL) error

Get is the main routine to fetch the module contents specified at the given URL and download it to the dstPath. This routine assumes that the srcURL points to the Terraform registry URL, with the Path configured to the module path encoded as `:namespace/:name/:system` as expected by the Terraform registry. Note that the URL query parameter must have the `version` key to specify what version to download.

func (*TerraformRegistryGetter) GetFile

func (tfrGetter *TerraformRegistryGetter) GetFile(dst string, src *url.URL) error

GetFile is not implemented for the Terraform module registry Getter since the terraform module registry doesn't serve a single file.

func (*TerraformRegistryGetter) SetClient

func (tfrGetter *TerraformRegistryGetter) SetClient(client *getter.Client)

SetClient allows the getter to know what getter client (different from the underlying HTTP client) to use for progress tracking.

type TerraformRegistryServicePath

type TerraformRegistryServicePath struct {
	ModulesPath string `json:"modules.v1"`
}

TerraformRegistryServicePath is a struct for extracting the modules service path in the Registry.