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 ChannelCreds
  • func (cc ChannelCreds) Equal(other ChannelCreds) bool
  • func (cc ChannelCreds) String() string
• type Config
  • func NewConfig() (*Config, error)
  • func NewConfigFromContents(data []byte) (*Config, error)
• type ServerConfig
  • func ServerConfigFromJSON(data []byte) (*ServerConfig, error)
  • func (sc *ServerConfig) CredsDialOption() grpc.DialOption
  • func (sc *ServerConfig) Equal(other *ServerConfig) bool
  • 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 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
	// Config contains the JSON configuration associated with the credentials.
	Config json.RawMessage
}

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.

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 {
	// 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
	// NodeProto contains the Node proto to be used in xDS requests. This will be
	// of type *v3corepb.Node.
	NodeProto *v3corepb.Node
}

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.

Users must use one of the NewConfigXxx() functions to create a Config instance, and not initialize it manually.

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 NewConfigFromContents

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

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

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 communicationg with this
	// xDS server. It is also used to dedup servers with the same server URI.
	Creds ChannelCreds
	// ServerFeatures contains a list of features supported by this xDS server.
	// It is also used to dedup servers with the same server URI and creds.
	ServerFeatures []string

	// IgnoreResourceDeletion 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.
	IgnoreResourceDeletion bool

	// Cleanups are called when the xDS client for this server is closed. Allows
	// cleaning up resources created specifically for this ServerConfig.
	Cleanups []func()
	// contains filtered or unexported fields
}

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

It contains unexported fields that are initialized when unmarshaled from JSON using either the UnmarshalJSON() method or the ServerConfigFromJSON() function. Hence users are strongly encouraged not to use a literal struct initialization to create an instance of this type, but instead unmarshal from JSON using one of the two available options.

func ServerConfigFromJSON

func ServerConfigFromJSON(data []byte) (*ServerConfig, error)

ServerConfigFromJSON creates a new ServerConfig from the given JSON configuration. This is the preferred way of creating a ServerConfig when hand-crafting the JSON configuration.

func (*ServerConfig) CredsDialOption

func (sc *ServerConfig) CredsDialOption() grpc.DialOption

CredsDialOption returns the configured credentials as a grpc dial option.

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 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.