getproviders

package
v0.12.31 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2021 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package getproviders is the lowest-level provider automatic installation functionality. It can answer questions about what providers and provider versions are available in a registry, and it can retrieve the URL for the distribution archive for a specific version of a specific provider targeting a particular platform.

This package is not responsible for choosing the best version to install from a set of available versions, or for any signature verification of the archives it fetches. Callers will use this package in conjunction with other logic elsewhere in order to construct a full provider installer.

Index

Constants

View Source 
const Wildcard string = "*"

Wildcard is a string value representing a wildcard element in the Include and Exclude patterns used with MultiSource. It is not valid to use Wildcard anywhere else.

Variables

View Source 
var CurrentPlatform = Platform{
	OS:   runtime.GOOS,
	Arch: runtime.GOARCH,
}

CurrentPlatform is the platform where the current program is running.

If attempting to install providers for use on the same system where the installation process is running, this is the right platform to use.

Functions

func LookupLegacyProvider 

func LookupLegacyProvider(addr addrs.Provider, source Source) (addrs.Provider, error)

LookupLegacyProvider attempts to resolve a legacy provider address (whose registry host and namespace are implied, rather than explicit) into a fully-qualified provider address, by asking the main Terraform registry to resolve it.

If the given address is not a legacy provider address then it will just be returned verbatim without making any outgoing requests.

Legacy provider lookup is possible only if the given source is either a *RegistrySource directly or if it is a MultiSource containing a *RegistrySource whose selector matching patterns include the public registry hostname registry.terraform.io.

This is a backward-compatibility mechanism for compatibility with existing configurations that don't include explicit provider source addresses. New configurations should not rely on it, and this fallback mechanism is likely to be removed altogether in a future Terraform version.

Types

type ErrHostNoProviders 

type ErrHostNoProviders struct {
	Hostname svchost.Hostname

	// HasOtherVersionis set to true if the discovery process detected
	// declarations of services named "providers" whose version numbers did not
	// match any version supported by the current version of Terraform.
	//
	// If this is set, it's helpful to hint to the user in an error message
	// that the provider host may be expecting an older or a newer version
	// of Terraform, rather than that it isn't a provider registry host at all.
	HasOtherVersion bool
}

ErrHostNoProviders is an error type used to indicate that a hostname given in a provider address does not support the provider registry protocol.

func (ErrHostNoProviders) Error 

func (err ErrHostNoProviders) Error() string

type ErrHostUnreachable 

type ErrHostUnreachable struct {
	Hostname svchost.Hostname
	Wrapped  error
}

ErrHostUnreachable is an error type used to indicate that a hostname given in a provider address did not resolve in DNS, did not respond to an HTTPS request for service discovery, or otherwise failed to correctly speak the service discovery protocol.

func (ErrHostUnreachable) Error 

func (err ErrHostUnreachable) Error() string

func (ErrHostUnreachable) Unwrap 

func (err ErrHostUnreachable) Unwrap() error

Unwrap returns the underlying error that occurred when trying to reach the indicated host.

type ErrPlatformNotSupported 

type ErrPlatformNotSupported struct {
	Provider addrs.Provider
	Version  Version
	Platform Platform
}

ErrPlatformNotSupported is an error type used to indicate that a particular version of a provider isn't available for a particular target platform.

This is returned when DownloadLocation encounters a 404 Not Found response from the underlying registry, because it presumes that a caller will only ask for the DownloadLocation for a version it already found the existence of via AvailableVersions.

func (ErrPlatformNotSupported) Error 

func (err ErrPlatformNotSupported) Error() string

type ErrProviderNotKnown 

type ErrProviderNotKnown struct {
	Provider addrs.Provider
}

ErrProviderNotKnown is an error type used to indicate that the hostname given in a provider address does appear to be a provider registry but that registry does not know about the given provider namespace or type.

A caller serving requests from an end-user should recognize this error type and use it to produce user-friendly hints for common errors such as failing to specify an explicit source for a provider not in the default namespace (one not under registry.terraform.io/hashicorp/). The default error message for this type is a direct description of the problem with no such hints, because we expect that the caller will have better context to decide what hints are appropriate, e.g. by looking at the configuration given by the user.

func (ErrProviderNotKnown) Error 

func (err ErrProviderNotKnown) Error() string

type ErrQueryFailed 

type ErrQueryFailed struct {
	Provider addrs.Provider
	Wrapped  error
}

ErrQueryFailed is an error type used to indicate that the hostname given in a provider address does appear to be a provider registry but that when we queried it for metadata for the given provider the server returned an unexpected error.

This is used for any error responses other than "Not Found", which would indicate the absense of a provider and is thus reported using ErrProviderNotKnown instead.

func (ErrQueryFailed) Error 

func (err ErrQueryFailed) Error() string

func (ErrQueryFailed) Unwrap 

func (err ErrQueryFailed) Unwrap() error

Unwrap returns the underlying error that occurred when trying to reach the indicated host.

type ErrUnauthorized 

type ErrUnauthorized struct {
	Hostname svchost.Hostname

	// HaveCredentials is true when the request that failed included some
	// credentials, and thus it seems that those credentials were invalid.
	// Conversely, HaveCredentials is false if the request did not include
	// credentials at all, in which case it seems that credentials must be
	// provided.
	HaveCredentials bool
}

ErrUnauthorized is an error type used to indicate that a hostname given in a provider address returned a "401 Unauthorized" or "403 Forbidden" error response when we tried to access it.

func (ErrUnauthorized) Error 

func (err ErrUnauthorized) Error() string

type FilesystemMirrorSource 

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

FilesystemMirrorSource is a source that reads providers and their metadata from a directory prefix in the local filesystem.

func NewFilesystemMirrorSource 

func NewFilesystemMirrorSource(baseDir string) *FilesystemMirrorSource

NewFilesystemMirrorSource constructs and returns a new filesystem-based mirror source with the given base directory.

func (*FilesystemMirrorSource) AvailableVersions 

func (s *FilesystemMirrorSource) AvailableVersions(provider addrs.Provider) (VersionList, error)

AvailableVersions scans the directory structure under the source's base directory for locally-mirrored packages for the given provider, returning a list of version numbers for the providers it found.

func (*FilesystemMirrorSource) PackageMeta 

func (s *FilesystemMirrorSource) PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)

PackageMeta checks to see if the source's base directory contains a local copy of the distribution package for the given provider version on the given target, and returns the metadata about it if so.

type HTTPMirrorSource 

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

HTTPMirrorSource is a source that reads provider metadata from a provider mirror that is accessible over the HTTP provider mirror protocol.

func NewHTTPMirrorSource 

func NewHTTPMirrorSource(baseURL *url.URL) *HTTPMirrorSource

NewHTTPMirrorSource constructs and returns a new network mirror source with the given base URL. The relative URL offsets defined by the HTTP mirror protocol will be resolve relative to the given URL.

func (*HTTPMirrorSource) AvailableVersions 

func (s *HTTPMirrorSource) AvailableVersions(provider addrs.Provider) (VersionList, error)

AvailableVersions retrieves the available versions for the given provider from the object's underlying HTTP mirror service.

func (*HTTPMirrorSource) PackageMeta 

func (s *HTTPMirrorSource) PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)

PackageMeta retrieves metadata for the requested provider package from the object's underlying HTTP mirror service.

type MemoizeSource 

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

MemoizeSource is a Source that wraps another Source and remembers its results so that they can be returned more quickly on future calls to the same object.

Each MemoizeSource maintains a cache of response it has seen as part of its body. All responses are retained for the remaining lifetime of the object. Errors from the underlying source are also cached, and so subsequent calls with the same arguments will always produce the same errors.

A MemoizeSource can be called concurrently, with incoming requests processed sequentially.

func NewMemoizeSource 

func NewMemoizeSource(underlying Source) *MemoizeSource

NewMemoizeSource constructs and returns a new MemoizeSource that wraps the given underlying source and memoizes its results.

func (*MemoizeSource) AvailableVersions 

func (s *MemoizeSource) AvailableVersions(provider addrs.Provider) (VersionList, error)

AvailableVersions requests the available versions from the underlying source and caches them before returning them, or on subsequent calls returns the result directly from the cache.

func (*MemoizeSource) PackageMeta 

func (s *MemoizeSource) PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)

PackageMeta requests package metadata from the underlying source and caches the result before returning it, or on subsequent calls returns the result directly from the cache.

type MultiSource 

type MultiSource []MultiSourceSelector

MultiSource is a Source that wraps a series of other sources and combines their sets of available providers and provider versions.

A MultiSource consists of a sequence of selectors that each specify an underlying source to query and a set of matching patterns to decide which providers can be retrieved from which sources. If multiple selectors find a given provider version then the earliest one in the sequence takes priority for deciding the package metadata for the provider.

For underlying sources that make network requests, consider wrapping each one in a MemoizeSource so that availability information retrieved in AvailableVersions can be reused in PackageMeta.

func (MultiSource) AvailableVersions 

func (s MultiSource) AvailableVersions(provider addrs.Provider) (VersionList, error)

AvailableVersions retrieves all of the versions of the given provider that are available across all of the underlying selectors, while respecting each selector's matching patterns.

func (MultiSource) PackageMeta 

func (s MultiSource) PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)

PackageMeta retrieves the package metadata for the given provider from the first selector that indicates support for it.

type MultiSourceMatchingPatterns 

type MultiSourceMatchingPatterns []addrs.Provider

MultiSourceMatchingPatterns is a set of patterns that together define a set of providers by matching on the segments of the provider FQNs.

The Provider address values in a MultiSourceMatchingPatterns are special in that any of Hostname, Namespace, or Type can be getproviders.Wildcard to indicate that any concrete value is permitted for that segment.

func ParseMultiSourceMatchingPatterns 

func ParseMultiSourceMatchingPatterns(strs []string) (MultiSourceMatchingPatterns, error)

ParseMultiSourceMatchingPatterns parses a slice of strings containing the string form of provider matching patterns and, if all the given strings are valid, returns the corresponding MultiSourceMatchingPatterns value.

func (MultiSourceMatchingPatterns) MatchesProvider 

func (ps MultiSourceMatchingPatterns) MatchesProvider(addr addrs.Provider) bool

MatchesProvider tests whether the receiving matching patterns match with the given concrete provider address.

type MultiSourceSelector 

type MultiSourceSelector struct {
	// Source is the underlying source that this selector applies to.
	Source Source

	// Include and Exclude are sets of provider matching patterns that
	// together define which providers are eligible to be potentially
	// installed from the corresponding Source.
	Include, Exclude MultiSourceMatchingPatterns
}

MultiSourceSelector is an element of the source selection configuration on MultiSource. A MultiSource has zero or more of these to configure which underlying sources it should consult for a given provider.

func (MultiSourceSelector) CanHandleProvider 

func (s MultiSourceSelector) CanHandleProvider(addr addrs.Provider) bool

CanHandleProvider returns true if and only if the given provider address is both included by the selector's include patterns and _not_ excluded by its exclude patterns.

The absense of any include patterns is treated the same as a pattern that matches all addresses. Exclusions take priority over inclusions.

type PackageHTTPURL 

type PackageHTTPURL string

PackageHTTPURL is a provider package location accessible via HTTP. Its value is a URL string using either the http: scheme or the https: scheme.

type PackageLocalArchive 

type PackageLocalArchive string

PackageLocalArchive is the location of a provider distribution archive file in the local filesystem. Its value is a local filesystem path using the syntax understood by Go's standard path/filepath package on the operating system where Terraform is running.

type PackageLocalDir 

type PackageLocalDir string

PackageLocalDir is the location of a directory containing an unpacked provider distribution archive in the local filesystem. Its value is a local filesystem path using the syntax understood by Go's standard path/filepath package on the operating system where Terraform is running.

type PackageLocation 

type PackageLocation interface {
	// contains filtered or unexported methods
}

PackageLocation represents a location where a provider distribution package can be obtained. A value of this type contains one of the following concrete types: PackageLocalArchive, PackageLocalDir, or PackageHTTPURL.

type PackageMeta 

type PackageMeta struct {
	ProtocolVersions VersionList
	TargetPlatform   Platform

	Filename  string
	Location  PackageLocation
	SHA256Sum [sha256.Size]byte
}

PackageMeta represents the metadata related to a particular downloadable provider package targeting a single platform.

Package findproviders does no signature verification or protocol version compatibility checking of its own. A caller receving a PackageMeta must verify that it has a correct signature and supports a protocol version accepted by the current version of Terraform before trying to use the described package.

type Platform 

type Platform struct {
	OS, Arch string
}

Platform represents a target platform that a provider is or might be available for.

func (Platform) String 

func (p Platform) String() string

type RegistrySource 

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

RegistrySource is a Source that knows how to find and install providers from their originating provider registries.

func NewRegistrySource 

func NewRegistrySource(services *disco.Disco) *RegistrySource

NewRegistrySource creates and returns a new source that will install providers from their originating provider registries.

func (*RegistrySource) AvailableVersions 

func (s *RegistrySource) AvailableVersions(provider addrs.Provider) (VersionList, error)

AvailableVersions returns all of the versions available for the provider with the given address, or an error if that result cannot be determined.

If the request fails, the returned error might be an value of ErrHostNoProviders, ErrHostUnreachable, ErrUnauthenticated, ErrProviderNotKnown, or ErrQueryFailed. Callers must be defensive and expect errors of other types too, to allow for future expansion.

func (*RegistrySource) LookupLegacyProviderNamespace 

func (s *RegistrySource) LookupLegacyProviderNamespace(hostname svchost.Hostname, typeName string) (string, error)

LookupLegacyProviderNamespace is a special method available only on RegistrySource which can deal with legacy provider addresses that contain only a type and leave the namespace implied.

It asks the registry at the given hostname to provide a default namespace for the given provider type, which can be combined with the given hostname and type name to produce a fully-qualified provider address.

Not all unqualified type names can be resolved to a default namespace. If the request fails, this method returns an error describing the failure.

This method exists only to allow compatibility with unqualified names in older configurations. New configurations should be written so as not to depend on it, and this fallback mechanism will likely be removed altogether in a future Terraform version.

func (*RegistrySource) PackageMeta 

func (s *RegistrySource) PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)

PackageMeta returns metadata about the location and capabilities of a distribution package for a particular provider at a particular version targeting a particular platform.

Callers of PackageMeta should first call AvailableVersions and pass one of the resulting versions to this function. This function cannot distinguish between a version that is not available and an unsupported target platform, so if it encounters either case it will return an error suggesting that the target platform isn't supported under the assumption that the caller already checked that the version is available at all.

To find a package suitable for the platform where the provider installation process is running, set the "target" argument to getproviders.CurrentPlatform.

If the request fails, the returned error might be an value of ErrHostNoProviders, ErrHostUnreachable, ErrUnauthenticated, ErrPlatformNotSupported, or ErrQueryFailed. Callers must be defensive and expect errors of other types too, to allow for future expansion.

type Source 

type Source interface {
	AvailableVersions(provider addrs.Provider) (VersionList, error)
	PackageMeta(provider addrs.Provider, version Version, target Platform) (PackageMeta, error)
}

A Source can query a particular source for information about providers that are available to install.

type Version 

type Version = versions.Version

Version represents a particular single version of a provider.

func ParseVersion 

func ParseVersion(str string) (Version, error)

ParseVersion parses a "semver"-style version string into a Version value, which is the version syntax we use for provider versions.

type VersionList 

type VersionList = versions.List

VersionList represents a list of versions. It is a []Version with some extra methods for convenient filtering.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.