bootstrap

package
v1.61.0 Latest Latest
Warning

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

Go to latest
Published: Jan 23, 2024 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PopulateResourceTemplate added in v1.43.0

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 added in v1.43.0

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 added in v1.43.0

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

UnmarshalJSON implement json unmarshaller.

type ChannelCreds added in v1.54.0

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 added in v1.54.0

func (cc ChannelCreds) Equal(other ChannelCreds) bool

Equal reports whether cc and other are considered equal.

func (ChannelCreds) String added in v1.54.0

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.

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 added in v1.45.0

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 added in v1.43.0

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 added in v1.54.0

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 added in v1.54.0

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

CredsDialOption returns the configured credentials as a grpc dial option.

func (*ServerConfig) Equal added in v1.54.0

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

Equal reports whether sc and other are considered equal.

func (ServerConfig) MarshalJSON added in v1.45.0

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

MarshalJSON marshals the ServerConfig to json.

func (*ServerConfig) String added in v1.43.0

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 added in v1.43.0

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

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL