addrs

Documentation

Index

• Constants
• func MustParseProviderPart(given string) string
• func ParseProviderPart(given string) (string, error)
• type LocalProviderConfig
  • func ParseProviderConfigCompact(traversal hcl.Traversal) (LocalProviderConfig, error)
  • func ParseProviderConfigCompactStr(str string) (LocalProviderConfig, error)
  • func (pc LocalProviderConfig) String() string
  • func (pc LocalProviderConfig) StringCompact() string
• type ParserError
  • func (pe *ParserError) Error() string
• type Provider
  • func ImpliedProviderForUnqualifiedType(typeName string) Provider
  • func NewBuiltInProvider(name string) Provider
  • func NewDefaultProvider(name string) Provider
  • func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider
  • func ParseProviderSourceString(str string) (Provider, error)
  • func (pt Provider) Equals(other Provider) bool
  • func (pt Provider) ForDisplay() string
  • func (pt Provider) IsBuiltIn() bool
  • func (pt Provider) IsDefault() bool
  • func (pt Provider) IsLegacy() bool
  • func (pt Provider) IsZero() bool
  • func (pt Provider) LegacyString() string
  • func (pt Provider) String() string
• type ProviderReferences
  • func (pr ProviderReferences) LocalNameByAddr(addr Provider) (LocalProviderConfig, bool)

Constants

const BuiltInProviderHost = svchost.Hostname("terraform.io")

BuiltInProviderHost is the pseudo-hostname used for the "built-in" provider namespace. Built-in provider addresses must also have their namespace set to BuiltInProviderNamespace in order to be considered as built-in.

const BuiltInProviderNamespace = "builtin"

BuiltInProviderNamespace is the provider namespace used for "built-in" providers. Built-in provider addresses must also have their hostname set to BuiltInProviderHost in order to be considered as built-in.

The this namespace is literally named "builtin", in the hope that users who see FQNs containing this will be able to infer the way in which they are special, even if they haven't encountered the concept formally yet.

const DefaultRegistryHost = svchost.Hostname("registry.terraform.io")

DefaultRegistryHost is the hostname used for provider addresses that do not have an explicit hostname.

const LegacyProviderNamespace = "-"

LegacyProviderNamespace is the special string used in the Namespace field of type Provider to mark a legacy provider address. This special namespace value would normally be invalid, and can be used only when the hostname is DefaultRegistryHost because that host owns the mapping from legacy name to FQN.

Functions

func MustParseProviderPart

func MustParseProviderPart(given string) string

MustParseProviderPart is a wrapper around ParseProviderPart that panics if it returns an error.

func ParseProviderPart

func ParseProviderPart(given string) (string, error)

ParseProviderPart processes an addrs.Provider namespace or type string provided by an end-user, producing a normalized version if possible or an error if the string contains invalid characters.

A provider part is processed in the same way as an individual label in a DNS domain name: it is transformed to lowercase per the usual DNS case mapping and normalization rules and may contain only letters, digits, and dashes. Additionally, dashes may not appear at the start or end of the string.

These restrictions are intended to allow these names to appear in fussy contexts such as directory/file names on case-insensitive filesystems, repository names on GitHub, etc. We're using the DNS rules in particular, rather than some similar rules defined locally, because the hostname part of an addrs.Provider is already a hostname and it's ideal to use exactly the same case folding and normalization rules for all of the parts.

In practice a provider type string conventionally does not contain dashes either. Such names are permitted, but providers with such type names will be hard to use because their resource type names will not be able to contain the provider type name and thus each resource will need an explicit provider address specified. (A real-world example of such a provider is the "google-beta" variant of the GCP provider, which has resource types that start with the "google_" prefix instead.)

It's valid to pass the result of this function as the argument to a subsequent call, in which case the result will be identical.

Types

type LocalProviderConfig

type LocalProviderConfig struct {
	LocalName string

	// If not empty, Alias identifies which non-default (aliased) provider
	// configuration this address refers to.
	Alias string
}

LocalProviderConfig is the address of a provider configuration from the perspective of references in a particular module.

Finding the corresponding AbsProviderConfig will require looking up the LocalName in the providers table in the module's configuration; there is no syntax-only translation between these types.

func ParseProviderConfigCompact

func ParseProviderConfigCompact(traversal hcl.Traversal) (LocalProviderConfig, error)

ParseProviderConfigCompact parses the given absolute traversal as a relative provider address in compact form. The following are examples of traversals that can be successfully parsed as compact relative provider configuration addresses:

aws
aws.foo

This function will panic if given a relative traversal.

If the returned diagnostics contains errors then the result value is invalid and must not be used.

func ParseProviderConfigCompactStr

func ParseProviderConfigCompactStr(str string) (LocalProviderConfig, error)

ParseProviderConfigCompactStr is a helper wrapper around ParseProviderConfigCompact that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

This should be used only in specialized situations since it will cause the created references to not have any meaningful source location information. If a reference string is coming from a source that should be identified in error messages then the caller should instead parse it directly using a suitable function from the HCL API and pass the traversal itself to ParseProviderConfigCompact.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned then the returned address is invalid.

func (LocalProviderConfig) String

func (pc LocalProviderConfig) String() string

func (LocalProviderConfig) StringCompact

func (pc LocalProviderConfig) StringCompact() string

StringCompact is an alternative to String that returns the form that can be parsed by ParseProviderConfigCompact, without the "provider." prefix.

type ParserError

type ParserError struct {
	Summary string
	Detail  string
}

func (*ParserError) Error

func (pe *ParserError) Error() string

type Provider

type Provider struct {
	Type      string
	Namespace string
	Hostname  svchost.Hostname
}

Provider encapsulates a single provider type. In the future this will be extended to include additional fields including Namespace and SourceHost

func ImpliedProviderForUnqualifiedType

func ImpliedProviderForUnqualifiedType(typeName string) Provider

ImpliedProviderForUnqualifiedType represents the rules for inferring what provider FQN a user intended when only a naked type name is available.

For all except the type name "terraform" this returns a so-called "default" provider, which is under the registry.terraform.io/hashicorp/ namespace.

As a special case, the string "terraform" maps to "terraform.io/builtin/terraform" because that is the more likely user intent than the now-unmaintained "registry.terraform.io/hashicorp/terraform" which remains only for compatibility with older Terraform versions.

func NewBuiltInProvider

func NewBuiltInProvider(name string) Provider

NewBuiltInProvider returns the address of a "built-in" provider. See the docs for Provider.IsBuiltIn for more information.

func NewDefaultProvider

func NewDefaultProvider(name string) Provider

NewDefaultProvider returns the default address of a HashiCorp-maintained, Registry-hosted provider.

func NewProvider

func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider

NewProvider constructs a provider address from its parts, and normalizes the namespace and type parts to lowercase using unicode case folding rules so that resulting addrs.Provider values can be compared using standard Go equality rules (==).

The hostname is given as a svchost.Hostname, which is required by the contract of that type to have already been normalized for equality testing.

This function will panic if the given namespace or type name are not valid. When accepting namespace or type values from outside the program, use ParseProviderPart first to check that the given value is valid.

func ParseProviderSourceString

func ParseProviderSourceString(str string) (Provider, error)

ParseProviderSourceString parses the source attribute and returns a provider. This is intended primarily to parse the FQN-like strings returned by terraform-config-inspect.

The following are valid source string formats:

name
namespace/name
hostname/namespace/name

func (Provider) Equals

func (pt Provider) Equals(other Provider) bool

Equals returns true if the receiver and other provider have the same attributes.

func (Provider) ForDisplay

func (pt Provider) ForDisplay() string

ForDisplay returns a user-friendly FQN string, simplified for readability. If the provider is using the default hostname, the hostname is omitted.

func (Provider) IsBuiltIn

func (pt Provider) IsBuiltIn() bool

IsBuiltIn returns true if the receiver is the address of a "built-in" provider. That is, a provider under terraform.io/builtin/ which is included as part of the Terraform binary itself rather than one to be installed from elsewhere.

These are ignored by the provider installer because they are assumed to already be available without any further installation.

func (Provider) IsDefault

func (pt Provider) IsDefault() bool

IsDefault returns true if the provider is a default hashicorp provider

func (Provider) IsLegacy

func (pt Provider) IsLegacy() bool

IsLegacy returns true if the provider is a legacy-style provider

func (Provider) IsZero

func (pt Provider) IsZero() bool

IsZero returns true if the receiver is the zero value of addrs.Provider.

The zero value is not a valid addrs.Provider and calling other methods on such a value is likely to either panic or otherwise misbehave.

func (Provider) LegacyString

func (pt Provider) LegacyString() string

LegacyString returns the provider type, which is frequently used interchangeably with provider name. This function can and should be removed when provider type is fully integrated. As a safeguard for future refactoring, this function panics if the Provider is not a legacy provider.

func (Provider) String

func (pt Provider) String() string

String returns an FQN string, indended for use in machine-readable output.

type ProviderReferences

type ProviderReferences map[LocalProviderConfig]Provider

func (ProviderReferences) LocalNameByAddr

func (pr ProviderReferences) LocalNameByAddr(addr Provider) (LocalProviderConfig, bool)