bootstrap

Documentation

Overview

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

Index

• func PopulateResourceTemplate(template, target string) string
• type Authority
  • func (a *Authority) UnmarshalJSON(data []byte) error
• type Config
  • func NewConfig() (*Config, error)
  • func NewConfigFromContentsForTesting(data []byte) (*Config, error)
• type ServerConfig
  • func (sc ServerConfig) MarshalJSON() ([]byte, error)
  • func (sc *ServerConfig) String() string
  • func (sc *ServerConfig) UnmarshalJSON(data []byte) error

Functions

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.

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
	// XDSServer contains the management server and config to connect to for
	// this authority.
	XDSServer *ServerConfig
}

Authority contains configuration for an Authority for an xDS control plane server. See the Authorities field in the Config struct for how it's used.

func (*Authority) UnmarshalJSON

func (a *Authority) UnmarshalJSON(data []byte) error

UnmarshalJSON implement json unmarshaller.

type Config

type Config struct {
	// XDSServer is the management server to connect to.
	//
	// The bootstrap file contains a list of servers (with name+creds), but we
	// pick the first one.
	XDSServer *ServerConfig
	// CertProviderConfigs contains a mapping from certificate provider plugin
	// instance names to parsed buildable configs.
	CertProviderConfigs map[string]*certprovider.BuildableConfig
	// ServerListenerResourceNameTemplate is a 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.
	ServerListenerResourceNameTemplate string
	// 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".
	ClientDefaultListenerResourceNameTemplate string

	// Authorities is a map of authority name to corresponding configuration.
	//
	// 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.
	Authorities map[string]*Authority
}

Config provides the xDS client with several key bits of information that it requires in its interaction with the management server. The Config is initialized from the bootstrap file.

func NewConfig

func NewConfig() (*Config, error)

NewConfig returns a new instance of Config 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.

We support a credential registration mechanism and only credentials registered through that mechanism will be accepted here. See package `xds/bootstrap` for details.

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 NewConfigFromContentsForTesting

func NewConfigFromContentsForTesting(data []byte) (*Config, error)

NewConfigFromContentsForTesting returns a new Config using the specified bootstrap file contents instead of reading the environment variable.

This is only suitable for testing purposes.

type ServerConfig

type ServerConfig struct {
	// ServerURI is the management server to connect to.
	//
	// The bootstrap file contains an ordered list of xDS servers to contact for
	// this authority. The first one is picked.
	ServerURI string
	// Creds contains the credentials to be used while talking to the xDS
	// server, as a grpc.DialOption.
	Creds grpc.DialOption
	// CredsType is the type of the creds. It will be used to dedup servers.
	CredsType string
	// TransportAPI indicates the API version of xDS transport protocol to use.
	// This describes the xDS gRPC endpoint and version of
	// DiscoveryRequest/Response used on the wire.
	TransportAPI version.TransportAPI
	// NodeProto contains the Node proto to be used in xDS requests. The actual
	// type depends on the transport protocol version used.
	//
	// Note that it's specified in the bootstrap globally for all the servers,
	// but we keep it in each server config so that its type (e.g. *v2pb.Node or
	// *v3pb.Node) is consistent with the transport API version.
	NodeProto proto.Message
}

ServerConfig contains the configuration to connect to a server, including URI, creds, and transport API version (e.g. v2 or v3).

func (ServerConfig) MarshalJSON

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

MarshalJSON marshals the ServerConfig to json.

func (*ServerConfig) String

func (sc *ServerConfig) String() string

String returns the string representation of the ServerConfig.

This string representation will be used as map keys in federation (`map[ServerConfig]authority`), so that the xDS ClientConn and stream will be shared by authorities with different names but the same server config.

It covers (almost) all the fields so the string can represent the config content. It doesn't cover NodeProto because NodeProto isn't used by federation.

func (*ServerConfig) UnmarshalJSON

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

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