bootstrap

Documentation

Overview

Package bootstrap provides the functionality to initialize certain aspects of an xDS client by reading a bootstrap file.

Index

• func NewContentsForTesting(opts ConfigOptionsForTesting) ([]byte, error)
• func PopulateResourceTemplate(template, target string) string
• func SetFallbackBootstrapConfig(cfgJSON []byte) error
• func UnsetFallbackBootstrapConfigForTesting()
• type Authority
  • func (a *Authority) Equal(other *Authority) bool
• type ChannelCreds
  • func (cc ChannelCreds) Equal(other ChannelCreds) bool
  • func (cc ChannelCreds) String() string
• type Config
  • func GetConfiguration() (*Config, error)
  • func NewConfigForTesting(contents []byte) (*Config, error)
  • func (c *Config) Authorities() map[string]*Authority
  • func (c *Config) CertProviderConfigs() map[string]*certprovider.BuildableConfig
  • func (c *Config) ClientDefaultListenerResourceNameTemplate() string
  • func (c *Config) Equal(other *Config) bool
  • func (c *Config) MarshalJSON() ([]byte, error)
  • func (c *Config) Node() *v3corepb.Node
  • func (c *Config) ServerListenerResourceNameTemplate() string
  • func (c *Config) String() string
  • func (c *Config) UnmarshalJSON(data []byte) error
  • func (c *Config) XDSServers() ServerConfigs
• type ConfigOptionsForTesting
• type ServerConfig
  • func ServerConfigForTesting(opts ServerConfigTestingOptions) (*ServerConfig, error)
  • func (sc *ServerConfig) ChannelCreds() []ChannelCreds
  • func (sc *ServerConfig) Cleanups() []func()
  • func (sc *ServerConfig) DialOptions() []grpc.DialOption
  • func (sc *ServerConfig) Equal(other *ServerConfig) bool
  • func (sc *ServerConfig) MarshalJSON() ([]byte, error)
  • func (sc *ServerConfig) ServerFeatures() []string
  • func (sc *ServerConfig) ServerFeaturesIgnoreResourceDeletion() bool
  • func (sc *ServerConfig) ServerURI() string
  • func (sc *ServerConfig) String() string
  • func (sc *ServerConfig) UnmarshalJSON(data []byte) error
• type ServerConfigTestingOptions
• type ServerConfigs
  • func (scs *ServerConfigs) Equal(other *ServerConfigs) bool
  • func (scs *ServerConfigs) String() string
  • func (scs *ServerConfigs) UnmarshalJSON(data []byte) error

Functions

func NewContentsForTesting

func NewContentsForTesting(opts ConfigOptionsForTesting) ([]byte, error)

NewContentsForTesting creates a new bootstrap configuration from the passed in options, for testing purposes.

Testing-Only

func PopulateResourceTemplate

func PopulateResourceTemplate(template, target string) string

PopulateResourceTemplate populates the given template using the target string. "%s", if exists in the template, will be replaced with target.

If the template starts with "xdstp:", the replaced string will be %-encoded. But note that "/" is not percent encoded.

func SetFallbackBootstrapConfig

func SetFallbackBootstrapConfig(cfgJSON []byte) error

SetFallbackBootstrapConfig sets the fallback bootstrap configuration to be used when the bootstrap environment variables are unset.

The provided configuration must be valid JSON. Returns a non-nil error if parsing the provided configuration fails.

func UnsetFallbackBootstrapConfigForTesting

func UnsetFallbackBootstrapConfigForTesting()

UnsetFallbackBootstrapConfigForTesting unsets the fallback bootstrap configuration to be used when the bootstrap environment variables are unset.

Testing-Only

Types

type Authority

type Authority struct {
	// ClientListenerResourceNameTemplate is template for the name of the
	// Listener resource to subscribe to for a gRPC client channel.  Used only
	// when the channel is created using an "xds:" URI with this authority name.
	//
	// The token "%s", if present in this string, will be replaced
	// with %-encoded service authority (i.e., the path part of the target
	// URI used to create the gRPC channel).
	//
	// Must start with "xdstp://<authority_name>/".  If it does not,
	// that is considered a bootstrap file parsing error.
	//
	// If not present in the bootstrap file, defaults to
	// "xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s".
	ClientListenerResourceNameTemplate string `json:"client_listener_resource_name_template,omitempty"`
	// XDSServers contains the list of server configurations for this authority.
	XDSServers ServerConfigs `json:"xds_servers,omitempty"`
}

Authority contains configuration for an xDS control plane authority.

This type does not implement custom JSON marshal/unmarshal logic because it is straightforward to accomplish the same with json struct tags.

func (*Authority) Equal

func (a *Authority) Equal(other *Authority) bool

Equal returns true if a equals other.

type ChannelCreds

type ChannelCreds struct {
	// Type contains a unique name identifying the credentials type. The only
	// supported types currently are "google_default" and "insecure".
	Type string `json:"type,omitempty"`
	// Config contains the JSON configuration associated with the credentials.
	Config json.RawMessage `json:"config,omitempty"`
}

ChannelCreds contains the credentials to be used while communicating with an xDS server. It is also used to dedup servers with the same server URI.

This type does not implement custom JSON marshal/unmarshal logic because it is straightforward to accomplish the same with json struct tags.

func (ChannelCreds) Equal

func (cc ChannelCreds) Equal(other ChannelCreds) bool

Equal reports whether cc and other are considered equal.

func (ChannelCreds) String

func (cc ChannelCreds) String() string

String returns a string representation of the credentials. It contains the type and the config (if non-nil) separated by a "-".

type Config

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

Config is the internal representation of the bootstrap configuration provided to the xDS client.

func GetConfiguration

func GetConfiguration() (*Config, error)

GetConfiguration returns the bootstrap configuration initialized by reading the bootstrap file found at ${GRPC_XDS_BOOTSTRAP} or bootstrap contents specified at ${GRPC_XDS_BOOTSTRAP_CONFIG}. If both env vars are set, the former is preferred.

If none of the env vars are set, this function returns the fallback configuration if it is not nil. Else, it returns an error.

This function tries to process as much of the bootstrap file as possible (in the presence of the errors) and may return a Config object with certain fields left unspecified, in which case the caller should use some sane defaults.

func NewConfigForTesting

func NewConfigForTesting(contents []byte) (*Config, error)

NewConfigForTesting creates a new bootstrap configuration from the provided contents, for testing purposes.

Testing-Only

func (*Config) Authorities

func (c *Config) Authorities() map[string]*Authority

Authorities returns a map of authority name to corresponding configuration. Callers must not modify the returned map.

This is used in the following cases:

• A gRPC client channel is created using an "xds:" URI that includes an authority.
• A gRPC client channel is created using an "xds:" URI with no authority, but the "client_default_listener_resource_name_template" field above turns it into an "xdstp:" URI.
• A gRPC server is created and the "server_listener_resource_name_template" field is an "xdstp:" URI.

In any of those cases, it is an error if the specified authority is not present in this map.

func (*Config) CertProviderConfigs

func (c *Config) CertProviderConfigs() map[string]*certprovider.BuildableConfig

CertProviderConfigs returns a map from certificate provider plugin instance name to their configuration. Callers must not modify the returned map.

func (*Config) ClientDefaultListenerResourceNameTemplate

func (c *Config) ClientDefaultListenerResourceNameTemplate() string

ClientDefaultListenerResourceNameTemplate returns a template for the name of the Listener resource to subscribe to for a gRPC client channel. Used only when the channel is created with an "xds:" URI with no authority.

If starts with "xdstp:", will be interpreted as a new-style name, in which case the authority of the URI will be used to select the relevant configuration in the "authorities" map.

The token "%s", if present in this string, will be replaced with the service authority (i.e., the path part of the target URI used to create the gRPC channel). If the template starts with "xdstp:", the replaced string will be %-encoded.

Defaults to "%s".

func (*Config) Equal

func (c *Config) Equal(other *Config) bool

Equal returns true if c equals other.

func (*Config) MarshalJSON

func (c *Config) MarshalJSON() ([]byte, error)

MarshalJSON returns marshaled JSON bytes corresponding to this config.

func (*Config) Node

func (c *Config) Node() *v3corepb.Node

Node returns xDS a v3 Node proto corresponding to the node field in the bootstrap configuration, which identifies a specific gRPC instance.

func (*Config) ServerListenerResourceNameTemplate

func (c *Config) ServerListenerResourceNameTemplate() string

ServerListenerResourceNameTemplate returns template for the name of the Listener resource to subscribe to for a gRPC server.

If starts with "xdstp:", will be interpreted as a new-style name, in which case the authority of the URI will be used to select the relevant configuration in the "authorities" map.

The token "%s", if present in this string, will be replaced with the IP and port on which the server is listening. (e.g., "0.0.0.0:8080", "[::]:8080"). For example, a value of "example/resource/%s" could become "example/resource/0.0.0.0:8080". If the template starts with "xdstp:", the replaced string will be %-encoded.

There is no default; if unset, xDS-based server creation fails.

func (*Config) String

func (c *Config) String() string

String returns a string representation of the Config.

func (*Config) UnmarshalJSON

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON takes the json data (the complete bootstrap configuration) and unmarshals it to the struct.

func (*Config) XDSServers

func (c *Config) XDSServers() ServerConfigs

XDSServers returns the top-level list of management servers to connect to, ordered by priority.

type ConfigOptionsForTesting

type ConfigOptionsForTesting struct {
	// Servers is the top-level xDS server configuration. It contains a list of
	// server configurations.
	Servers json.RawMessage
	// CertificateProviders is the certificate providers configuration.
	CertificateProviders map[string]json.RawMessage
	// ServerListenerResourceNameTemplate is the listener resource name template
	// to be used on the gRPC server.
	ServerListenerResourceNameTemplate string
	// ClientDefaultListenerResourceNameTemplate is the default listener
	// resource name template to be used on the gRPC client.
	ClientDefaultListenerResourceNameTemplate string
	// Authorities is a list of non-default authorities.
	Authorities map[string]json.RawMessage
	// Node identifies the gRPC client/server node in the
	// proxyless service mesh.
	Node json.RawMessage
}

ConfigOptionsForTesting specifies options for creating a new bootstrap configuration for testing purposes.

Testing-Only

type ServerConfig

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

ServerConfig contains the configuration to connect to a server.

func ServerConfigForTesting

func ServerConfigForTesting(opts ServerConfigTestingOptions) (*ServerConfig, error)

ServerConfigForTesting creates a new ServerConfig from the passed in options, for testing purposes.

Testing-Only

func (*ServerConfig) ChannelCreds

func (sc *ServerConfig) ChannelCreds() []ChannelCreds

ChannelCreds returns the credentials configuration to use when communicating with this server. Also used to dedup servers with the same server URI.

func (*ServerConfig) Cleanups

func (sc *ServerConfig) Cleanups() []func()

Cleanups returns a collection of functions to be called when the xDS client for this server is closed. Allows cleaning up resources created specifically for this server.

func (*ServerConfig) DialOptions

func (sc *ServerConfig) DialOptions() []grpc.DialOption

DialOptions returns a slice of all the configured dial options for this server.

func (*ServerConfig) Equal

func (sc *ServerConfig) Equal(other *ServerConfig) bool

Equal reports whether sc and other are considered equal.

func (*ServerConfig) MarshalJSON

func (sc *ServerConfig) MarshalJSON() ([]byte, error)

MarshalJSON returns marshaled JSON bytes corresponding to this server config.

func (*ServerConfig) ServerFeatures

func (sc *ServerConfig) ServerFeatures() []string

ServerFeatures returns the list of features supported by this server. Also used to dedup servers with the same server URI and channel creds.

func (*ServerConfig) ServerFeaturesIgnoreResourceDeletion

func (sc *ServerConfig) ServerFeaturesIgnoreResourceDeletion() bool

ServerFeaturesIgnoreResourceDeletion returns true if this server supports a feature where the xDS client can ignore resource deletions from this server, as described in gRFC A53.

This feature controls the behavior of the xDS client when the server deletes a previously sent Listener or Cluster resource. If set, the xDS client will not invoke the watchers' OnResourceDoesNotExist() method when a resource is deleted, nor will it remove the existing resource value from its cache.

func (*ServerConfig) ServerURI

func (sc *ServerConfig) ServerURI() string

ServerURI returns the URI of the management server to connect to.

func (*ServerConfig) String

func (sc *ServerConfig) String() string

String returns the string representation of the ServerConfig.

func (*ServerConfig) UnmarshalJSON

func (sc *ServerConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON takes the json data (a server) and unmarshals it to the struct.

type ServerConfigTestingOptions

type ServerConfigTestingOptions struct {
	// URI is the name of the server corresponding to this server config.
	URI string
	// ChannelCreds contains a list of channel credentials to use when talking
	// to this server. If unspecified, `insecure` credentials will be used.
	ChannelCreds []ChannelCreds
	// ServerFeatures represents the list of features supported by this server.
	ServerFeatures []string
}

ServerConfigTestingOptions specifies options for creating a new ServerConfig for testing purposes.

Testing-Only

type ServerConfigs

type ServerConfigs []*ServerConfig

ServerConfigs represents a collection of server configurations.

func (*ServerConfigs) Equal

func (scs *ServerConfigs) Equal(other *ServerConfigs) bool

Equal returns true if scs equals other.

func (*ServerConfigs) String

func (scs *ServerConfigs) String() string

String returns a string representation of the ServerConfigs, by concatenating the string representations of the underlying server configs.

func (*ServerConfigs) UnmarshalJSON

func (scs *ServerConfigs) UnmarshalJSON(data []byte) error

UnmarshalJSON takes the json data (a list of server configurations) and unmarshals it to the struct.