bootstrap

package
v1.66.1 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: Apache-2.0 Imports: 19 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 NewContentsForTesting added in v1.66.0 

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

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

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

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

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

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

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

Equal returns true if c equals other.

func (*Config) MarshalJSON added in v1.66.0 

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

MarshalJSON returns marshaled JSON bytes corresponding to this config.

func (*Config) Node added in v1.66.0 

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

func (c *Config) String() string

String returns a string representation of the Config.

func (*Config) UnmarshalJSON added in v1.66.0 

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

func (c *Config) XDSServers() []*ServerConfig

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

type ConfigOptionsForTesting added in v1.66.0 

type ConfigOptionsForTesting struct {
	// Servers is the top-level xDS server configuration
	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 added in v1.66.0 

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

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

Testing-Only

func (*ServerConfig) ChannelCreds added in v1.66.0 

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) CredsDialOption 

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

CredsDialOption returns the first supported transport credentials from the configuration, as a 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 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 added in v1.66.0 

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.

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.

type ServerConfigTestingOptions added in v1.66.0 

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

type ServerConfigs []*ServerConfig

ServerConfigs represents a collection of server configurations.

func (*ServerConfigs) Equal added in v1.66.0 

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

Equal returns true if scs equals other.

func (*ServerConfigs) UnmarshalJSON added in v1.66.0 

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

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

Source Files

View all Source files

Directories

Path Synopsis
Package tlscreds implements mTLS Credentials in xDS Bootstrap File.
 Package tlscreds implements mTLS Credentials in xDS Bootstrap File.

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.