bootstrap.go

Documentation: google.golang.org/grpc/internal/xds/bootstrap

     1  /*
     2   *
     3   * Copyright 2019 gRPC authors.
     4   *
     5   * Licensed under the Apache License, Version 2.0 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   *
     9   *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   *
    17   */
    18  
    19  // Package bootstrap provides the functionality to initialize certain aspects
    20  // of an xDS client by reading a bootstrap file.
    21  package bootstrap
    22  
    23  import (
    24  	"bytes"
    25  	"encoding/json"
    26  	"fmt"
    27  	"net/url"
    28  	"os"
    29  	"strings"
    30  
    31  	"google.golang.org/grpc"
    32  	"google.golang.org/grpc/credentials/tls/certprovider"
    33  	"google.golang.org/grpc/internal"
    34  	"google.golang.org/grpc/internal/envconfig"
    35  	"google.golang.org/grpc/internal/pretty"
    36  	"google.golang.org/grpc/xds/bootstrap"
    37  	"google.golang.org/protobuf/encoding/protojson"
    38  
    39  	v3corepb "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
    40  )
    41  
    42  const (
    43  	// The "server_features" field in the bootstrap file contains a list of
    44  	// features supported by the server:
    45  	// - A value of "xds_v3" indicates that the server supports the v3 version of
    46  	//   the xDS transport protocol.
    47  	// - A value of "ignore_resource_deletion" indicates that the client should
    48  	//   ignore deletion of Listener and Cluster resources in updates from the
    49  	//   server.
    50  	serverFeaturesV3                     = "xds_v3"
    51  	serverFeaturesIgnoreResourceDeletion = "ignore_resource_deletion"
    52  
    53  	gRPCUserAgentName               = "gRPC Go"
    54  	clientFeatureNoOverprovisioning = "envoy.lb.does_not_support_overprovisioning"
    55  	clientFeatureResourceWrapper    = "xds.config.resource-in-sotw"
    56  )
    57  
    58  // For overriding in unit tests.
    59  var bootstrapFileReadFunc = os.ReadFile
    60  
    61  // ChannelCreds contains the credentials to be used while communicating with an
    62  // xDS server. It is also used to dedup servers with the same server URI.
    63  type ChannelCreds struct {
    64  	// Type contains a unique name identifying the credentials type. The only
    65  	// supported types currently are "google_default" and "insecure".
    66  	Type string
    67  	// Config contains the JSON configuration associated with the credentials.
    68  	Config json.RawMessage
    69  }
    70  
    71  // Equal reports whether cc and other are considered equal.
    72  func (cc ChannelCreds) Equal(other ChannelCreds) bool {
    73  	return cc.Type == other.Type && bytes.Equal(cc.Config, other.Config)
    74  }
    75  
    76  // String returns a string representation of the credentials. It contains the
    77  // type and the config (if non-nil) separated by a "-".
    78  func (cc ChannelCreds) String() string {
    79  	if cc.Config == nil {
    80  		return cc.Type
    81  	}
    82  
    83  	// We do not expect the Marshal call to fail since we wrote to cc.Config
    84  	// after a successful unmarshalling from JSON configuration. Therefore,
    85  	// it is safe to ignore the error here.
    86  	b, _ := json.Marshal(cc.Config)
    87  	return cc.Type + "-" + string(b)
    88  }
    89  
    90  // ServerConfig contains the configuration to connect to a server, including
    91  // URI, creds, and transport API version (e.g. v2 or v3).
    92  //
    93  // It contains unexported fields that are initialized when unmarshaled from JSON
    94  // using either the UnmarshalJSON() method or the ServerConfigFromJSON()
    95  // function. Hence users are strongly encouraged not to use a literal struct
    96  // initialization to create an instance of this type, but instead unmarshal from
    97  // JSON using one of the two available options.
    98  type ServerConfig struct {
    99  	// ServerURI is the management server to connect to.
   100  	//
   101  	// The bootstrap file contains an ordered list of xDS servers to contact for
   102  	// this authority. The first one is picked.
   103  	ServerURI string
   104  	// Creds contains the credentials to be used while communicationg with this
   105  	// xDS server. It is also used to dedup servers with the same server URI.
   106  	Creds ChannelCreds
   107  	// ServerFeatures contains a list of features supported by this xDS server.
   108  	// It is also used to dedup servers with the same server URI and creds.
   109  	ServerFeatures []string
   110  
   111  	// As part of unmarshalling the JSON config into this struct, we ensure that
   112  	// the credentials config is valid by building an instance of the specified
   113  	// credentials and store it here as a grpc.DialOption for easy access when
   114  	// dialing this xDS server.
   115  	credsDialOption grpc.DialOption
   116  
   117  	// IgnoreResourceDeletion controls the behavior of the xDS client when the
   118  	// server deletes a previously sent Listener or Cluster resource. If set, the
   119  	// xDS client will not invoke the watchers' OnResourceDoesNotExist() method
   120  	// when a resource is deleted, nor will it remove the existing resource value
   121  	// from its cache.
   122  	IgnoreResourceDeletion bool
   123  
   124  	// Cleanups are called when the xDS client for this server is closed. Allows
   125  	// cleaning up resources created specifically for this ServerConfig.
   126  	Cleanups []func()
   127  }
   128  
   129  // CredsDialOption returns the configured credentials as a grpc dial option.
   130  func (sc *ServerConfig) CredsDialOption() grpc.DialOption {
   131  	return sc.credsDialOption
   132  }
   133  
   134  // String returns the string representation of the ServerConfig.
   135  //
   136  // This string representation will be used as map keys in federation
   137  // (`map[ServerConfig]authority`), so that the xDS ClientConn and stream will be
   138  // shared by authorities with different names but the same server config.
   139  //
   140  // It covers (almost) all the fields so the string can represent the config
   141  // content. It doesn't cover NodeProto because NodeProto isn't used by
   142  // federation.
   143  func (sc *ServerConfig) String() string {
   144  	features := strings.Join(sc.ServerFeatures, "-")
   145  	return strings.Join([]string{sc.ServerURI, sc.Creds.String(), features}, "-")
   146  }
   147  
   148  // MarshalJSON marshals the ServerConfig to json.
   149  func (sc ServerConfig) MarshalJSON() ([]byte, error) {
   150  	server := xdsServer{
   151  		ServerURI:      sc.ServerURI,
   152  		ChannelCreds:   []channelCreds{{Type: sc.Creds.Type, Config: sc.Creds.Config}},
   153  		ServerFeatures: sc.ServerFeatures,
   154  	}
   155  	server.ServerFeatures = []string{serverFeaturesV3}
   156  	if sc.IgnoreResourceDeletion {
   157  		server.ServerFeatures = append(server.ServerFeatures, serverFeaturesIgnoreResourceDeletion)
   158  	}
   159  	return json.Marshal(server)
   160  }
   161  
   162  // UnmarshalJSON takes the json data (a server) and unmarshals it to the struct.
   163  func (sc *ServerConfig) UnmarshalJSON(data []byte) error {
   164  	var server xdsServer
   165  	if err := json.Unmarshal(data, &server); err != nil {
   166  		return fmt.Errorf("xds: json.Unmarshal(data) for field ServerConfig failed during bootstrap: %v", err)
   167  	}
   168  
   169  	sc.ServerURI = server.ServerURI
   170  	sc.ServerFeatures = server.ServerFeatures
   171  	for _, f := range server.ServerFeatures {
   172  		if f == serverFeaturesIgnoreResourceDeletion {
   173  			sc.IgnoreResourceDeletion = true
   174  		}
   175  	}
   176  	for _, cc := range server.ChannelCreds {
   177  		// We stop at the first credential type that we support.
   178  		c := bootstrap.GetCredentials(cc.Type)
   179  		if c == nil {
   180  			continue
   181  		}
   182  		bundle, cancel, err := c.Build(cc.Config)
   183  		if err != nil {
   184  			return fmt.Errorf("failed to build credentials bundle from bootstrap for %q: %v", cc.Type, err)
   185  		}
   186  		sc.Creds = ChannelCreds(cc)
   187  		sc.credsDialOption = grpc.WithCredentialsBundle(bundle)
   188  		sc.Cleanups = append(sc.Cleanups, cancel)
   189  		break
   190  	}
   191  	return nil
   192  }
   193  
   194  // ServerConfigFromJSON creates a new ServerConfig from the given JSON
   195  // configuration. This is the preferred way of creating a ServerConfig when
   196  // hand-crafting the JSON configuration.
   197  func ServerConfigFromJSON(data []byte) (*ServerConfig, error) {
   198  	sc := new(ServerConfig)
   199  	if err := sc.UnmarshalJSON(data); err != nil {
   200  		return nil, err
   201  	}
   202  	return sc, nil
   203  }
   204  
   205  // Equal reports whether sc and other are considered equal.
   206  func (sc *ServerConfig) Equal(other *ServerConfig) bool {
   207  	switch {
   208  	case sc == nil && other == nil:
   209  		return true
   210  	case (sc != nil) != (other != nil):
   211  		return false
   212  	case sc.ServerURI != other.ServerURI:
   213  		return false
   214  	case !sc.Creds.Equal(other.Creds):
   215  		return false
   216  	case !equalStringSlice(sc.ServerFeatures, other.ServerFeatures):
   217  		return false
   218  	}
   219  	return true
   220  }
   221  
   222  func equalStringSlice(a, b []string) bool {
   223  	if len(a) != len(b) {
   224  		return false
   225  	}
   226  	for i := range a {
   227  		if a[i] != b[i] {
   228  			return false
   229  		}
   230  	}
   231  	return true
   232  }
   233  
   234  // unmarshalJSONServerConfigSlice unmarshals JSON to a slice.
   235  func unmarshalJSONServerConfigSlice(data []byte) ([]*ServerConfig, error) {
   236  	var servers []*ServerConfig
   237  	if err := json.Unmarshal(data, &servers); err != nil {
   238  		return nil, fmt.Errorf("failed to unmarshal JSON to []*ServerConfig: %v", err)
   239  	}
   240  	if len(servers) < 1 {
   241  		return nil, fmt.Errorf("no management server found in JSON")
   242  	}
   243  	return servers, nil
   244  }
   245  
   246  // Authority contains configuration for an Authority for an xDS control plane
   247  // server. See the Authorities field in the Config struct for how it's used.
   248  type Authority struct {
   249  	// ClientListenerResourceNameTemplate is template for the name of the
   250  	// Listener resource to subscribe to for a gRPC client channel.  Used only
   251  	// when the channel is created using an "xds:" URI with this authority name.
   252  	//
   253  	// The token "%s", if present in this string, will be replaced
   254  	// with %-encoded service authority (i.e., the path part of the target
   255  	// URI used to create the gRPC channel).
   256  	//
   257  	// Must start with "xdstp://<authority_name>/".  If it does not,
   258  	// that is considered a bootstrap file parsing error.
   259  	//
   260  	// If not present in the bootstrap file, defaults to
   261  	// "xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s".
   262  	ClientListenerResourceNameTemplate string
   263  	// XDSServer contains the management server and config to connect to for
   264  	// this authority.
   265  	XDSServer *ServerConfig
   266  }
   267  
   268  // UnmarshalJSON implement json unmarshaller.
   269  func (a *Authority) UnmarshalJSON(data []byte) error {
   270  	var jsonData map[string]json.RawMessage
   271  	if err := json.Unmarshal(data, &jsonData); err != nil {
   272  		return fmt.Errorf("xds: failed to parse authority: %v", err)
   273  	}
   274  
   275  	for k, v := range jsonData {
   276  		switch k {
   277  		case "xds_servers":
   278  			servers, err := unmarshalJSONServerConfigSlice(v)
   279  			if err != nil {
   280  				return fmt.Errorf("xds: json.Unmarshal(data) for field %q failed during bootstrap: %v", k, err)
   281  			}
   282  			a.XDSServer = servers[0]
   283  		case "client_listener_resource_name_template":
   284  			if err := json.Unmarshal(v, &a.ClientListenerResourceNameTemplate); err != nil {
   285  				return fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   286  			}
   287  		}
   288  	}
   289  	return nil
   290  }
   291  
   292  // Config provides the xDS client with several key bits of information that it
   293  // requires in its interaction with the management server. The Config is
   294  // initialized from the bootstrap file.
   295  type Config struct {
   296  	// XDSServer is the management server to connect to.
   297  	//
   298  	// The bootstrap file contains a list of servers (with name+creds), but we
   299  	// pick the first one.
   300  	XDSServer *ServerConfig
   301  	// CertProviderConfigs contains a mapping from certificate provider plugin
   302  	// instance names to parsed buildable configs.
   303  	CertProviderConfigs map[string]*certprovider.BuildableConfig
   304  	// ServerListenerResourceNameTemplate is a template for the name of the
   305  	// Listener resource to subscribe to for a gRPC server.
   306  	//
   307  	// If starts with "xdstp:", will be interpreted as a new-style name,
   308  	// in which case the authority of the URI will be used to select the
   309  	// relevant configuration in the "authorities" map.
   310  	//
   311  	// The token "%s", if present in this string, will be replaced with the IP
   312  	// and port on which the server is listening.  (e.g., "0.0.0.0:8080",
   313  	// "[::]:8080"). For example, a value of "example/resource/%s" could become
   314  	// "example/resource/0.0.0.0:8080". If the template starts with "xdstp:",
   315  	// the replaced string will be %-encoded.
   316  	//
   317  	// There is no default; if unset, xDS-based server creation fails.
   318  	ServerListenerResourceNameTemplate string
   319  	// A template for the name of the Listener resource to subscribe to
   320  	// for a gRPC client channel.  Used only when the channel is created
   321  	// with an "xds:" URI with no authority.
   322  	//
   323  	// If starts with "xdstp:", will be interpreted as a new-style name,
   324  	// in which case the authority of the URI will be used to select the
   325  	// relevant configuration in the "authorities" map.
   326  	//
   327  	// The token "%s", if present in this string, will be replaced with
   328  	// the service authority (i.e., the path part of the target URI
   329  	// used to create the gRPC channel).  If the template starts with
   330  	// "xdstp:", the replaced string will be %-encoded.
   331  	//
   332  	// Defaults to "%s".
   333  	ClientDefaultListenerResourceNameTemplate string
   334  	// Authorities is a map of authority name to corresponding configuration.
   335  	//
   336  	// This is used in the following cases:
   337  	// - A gRPC client channel is created using an "xds:" URI that includes
   338  	//   an authority.
   339  	// - A gRPC client channel is created using an "xds:" URI with no
   340  	//   authority, but the "client_default_listener_resource_name_template"
   341  	//   field above turns it into an "xdstp:" URI.
   342  	// - A gRPC server is created and the
   343  	//   "server_listener_resource_name_template" field is an "xdstp:" URI.
   344  	//
   345  	// In any of those cases, it is an error if the specified authority is
   346  	// not present in this map.
   347  	Authorities map[string]*Authority
   348  	// NodeProto contains the Node proto to be used in xDS requests. This will be
   349  	// of type *v3corepb.Node.
   350  	NodeProto *v3corepb.Node
   351  }
   352  
   353  type channelCreds struct {
   354  	Type   string          `json:"type"`
   355  	Config json.RawMessage `json:"config,omitempty"`
   356  }
   357  
   358  type xdsServer struct {
   359  	ServerURI      string         `json:"server_uri"`
   360  	ChannelCreds   []channelCreds `json:"channel_creds"`
   361  	ServerFeatures []string       `json:"server_features"`
   362  }
   363  
   364  func bootstrapConfigFromEnvVariable() ([]byte, error) {
   365  	fName := envconfig.XDSBootstrapFileName
   366  	fContent := envconfig.XDSBootstrapFileContent
   367  
   368  	// Bootstrap file name has higher priority than bootstrap content.
   369  	if fName != "" {
   370  		// If file name is set
   371  		// - If file not found (or other errors), fail
   372  		// - Otherwise, use the content.
   373  		//
   374  		// Note that even if the content is invalid, we don't failover to the
   375  		// file content env variable.
   376  		logger.Debugf("Using bootstrap file with name %q", fName)
   377  		return bootstrapFileReadFunc(fName)
   378  	}
   379  
   380  	if fContent != "" {
   381  		return []byte(fContent), nil
   382  	}
   383  
   384  	return nil, fmt.Errorf("none of the bootstrap environment variables (%q or %q) defined",
   385  		envconfig.XDSBootstrapFileNameEnv, envconfig.XDSBootstrapFileContentEnv)
   386  }
   387  
   388  // NewConfig returns a new instance of Config initialized by reading the
   389  // bootstrap file found at ${GRPC_XDS_BOOTSTRAP} or bootstrap contents specified
   390  // at ${GRPC_XDS_BOOTSTRAP_CONFIG}. If both env vars are set, the former is
   391  // preferred.
   392  //
   393  // We support a credential registration mechanism and only credentials
   394  // registered through that mechanism will be accepted here. See package
   395  // `xds/bootstrap` for details.
   396  //
   397  // This function tries to process as much of the bootstrap file as possible (in
   398  // the presence of the errors) and may return a Config object with certain
   399  // fields left unspecified, in which case the caller should use some sane
   400  // defaults.
   401  func NewConfig() (*Config, error) {
   402  	// Examples of the bootstrap json can be found in the generator tests
   403  	// https://github.com/GoogleCloudPlatform/traffic-director-grpc-bootstrap/blob/master/main_test.go.
   404  	data, err := bootstrapConfigFromEnvVariable()
   405  	if err != nil {
   406  		return nil, fmt.Errorf("xds: Failed to read bootstrap config: %v", err)
   407  	}
   408  	return newConfigFromContents(data)
   409  }
   410  
   411  // NewConfigFromContents returns a new Config using the specified
   412  // bootstrap file contents instead of reading the environment variable.
   413  func NewConfigFromContents(data []byte) (*Config, error) {
   414  	return newConfigFromContents(data)
   415  }
   416  
   417  func newConfigFromContents(data []byte) (*Config, error) {
   418  	config := &Config{}
   419  
   420  	var jsonData map[string]json.RawMessage
   421  	if err := json.Unmarshal(data, &jsonData); err != nil {
   422  		return nil, fmt.Errorf("xds: failed to parse bootstrap config: %v", err)
   423  	}
   424  
   425  	var node *v3corepb.Node
   426  	opts := protojson.UnmarshalOptions{DiscardUnknown: true}
   427  	for k, v := range jsonData {
   428  		switch k {
   429  		case "node":
   430  			node = &v3corepb.Node{}
   431  			if err := opts.Unmarshal(v, node); err != nil {
   432  				return nil, fmt.Errorf("xds: protojson.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   433  			}
   434  		case "xds_servers":
   435  			servers, err := unmarshalJSONServerConfigSlice(v)
   436  			if err != nil {
   437  				return nil, fmt.Errorf("xds: json.Unmarshal(data) for field %q failed during bootstrap: %v", k, err)
   438  			}
   439  			config.XDSServer = servers[0]
   440  		case "certificate_providers":
   441  			var providerInstances map[string]json.RawMessage
   442  			if err := json.Unmarshal(v, &providerInstances); err != nil {
   443  				return nil, fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   444  			}
   445  			configs := make(map[string]*certprovider.BuildableConfig)
   446  			getBuilder := internal.GetCertificateProviderBuilder.(func(string) certprovider.Builder)
   447  			for instance, data := range providerInstances {
   448  				var nameAndConfig struct {
   449  					PluginName string          `json:"plugin_name"`
   450  					Config     json.RawMessage `json:"config"`
   451  				}
   452  				if err := json.Unmarshal(data, &nameAndConfig); err != nil {
   453  					return nil, fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), instance, err)
   454  				}
   455  
   456  				name := nameAndConfig.PluginName
   457  				parser := getBuilder(nameAndConfig.PluginName)
   458  				if parser == nil {
   459  					// We ignore plugins that we do not know about.
   460  					continue
   461  				}
   462  				bc, err := parser.ParseConfig(nameAndConfig.Config)
   463  				if err != nil {
   464  					return nil, fmt.Errorf("xds: config parsing for plugin %q failed: %v", name, err)
   465  				}
   466  				configs[instance] = bc
   467  			}
   468  			config.CertProviderConfigs = configs
   469  		case "server_listener_resource_name_template":
   470  			if err := json.Unmarshal(v, &config.ServerListenerResourceNameTemplate); err != nil {
   471  				return nil, fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   472  			}
   473  		case "client_default_listener_resource_name_template":
   474  			if err := json.Unmarshal(v, &config.ClientDefaultListenerResourceNameTemplate); err != nil {
   475  				return nil, fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   476  			}
   477  		case "authorities":
   478  			if err := json.Unmarshal(v, &config.Authorities); err != nil {
   479  				return nil, fmt.Errorf("xds: json.Unmarshal(%v) for field %q failed during bootstrap: %v", string(v), k, err)
   480  			}
   481  		default:
   482  			logger.Warningf("Bootstrap content has unknown field: %s", k)
   483  		}
   484  		// Do not fail the xDS bootstrap when an unknown field is seen. This can
   485  		// happen when an older version client reads a newer version bootstrap
   486  		// file with new fields.
   487  	}
   488  
   489  	if config.ClientDefaultListenerResourceNameTemplate == "" {
   490  		// Default value of the default client listener name template is "%s".
   491  		config.ClientDefaultListenerResourceNameTemplate = "%s"
   492  	}
   493  	if config.XDSServer == nil {
   494  		return nil, fmt.Errorf("xds: required field %q not found in bootstrap %s", "xds_servers", jsonData["xds_servers"])
   495  	}
   496  	if config.XDSServer.ServerURI == "" {
   497  		return nil, fmt.Errorf("xds: required field %q not found in bootstrap %s", "xds_servers.server_uri", jsonData["xds_servers"])
   498  	}
   499  	if config.XDSServer.CredsDialOption() == nil {
   500  		return nil, fmt.Errorf("xds: required field %q doesn't contain valid value in bootstrap %s", "xds_servers.channel_creds", jsonData["xds_servers"])
   501  	}
   502  	// Post-process the authorities' client listener resource template field:
   503  	// - if set, it must start with "xdstp://<authority_name>/"
   504  	// - if not set, it defaults to "xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s"
   505  	for name, authority := range config.Authorities {
   506  		prefix := fmt.Sprintf("xdstp://%s", url.PathEscape(name))
   507  		if authority.ClientListenerResourceNameTemplate == "" {
   508  			authority.ClientListenerResourceNameTemplate = prefix + "/envoy.config.listener.v3.Listener/%s"
   509  			continue
   510  		}
   511  		if !strings.HasPrefix(authority.ClientListenerResourceNameTemplate, prefix) {
   512  			return nil, fmt.Errorf("xds: field ClientListenerResourceNameTemplate %q of authority %q doesn't start with prefix %q", authority.ClientListenerResourceNameTemplate, name, prefix)
   513  		}
   514  	}
   515  
   516  	// Performing post-production on the node information. Some additional fields
   517  	// which are not expected to be set in the bootstrap file are populated here.
   518  	if node == nil {
   519  		node = &v3corepb.Node{}
   520  	}
   521  	node.UserAgentName = gRPCUserAgentName
   522  	node.UserAgentVersionType = &v3corepb.Node_UserAgentVersion{UserAgentVersion: grpc.Version}
   523  	node.ClientFeatures = append(node.ClientFeatures, clientFeatureNoOverprovisioning, clientFeatureResourceWrapper)
   524  	config.NodeProto = node
   525  
   526  	if logger.V(2) {
   527  		logger.Infof("Bootstrap config for creating xds-client: %v", pretty.ToJSON(config))
   528  	}
   529  	return config, nil
   530  }
   531
View as plain text