github.com/cilium/cilium@v1.16.2/pkg/envoy/xds/doc.go (about)

     1  // SPDX-License-Identifier: Apache-2.0
     2  // Copyright Authors of Cilium
     3  
     4  // Package xds is an implementation of Envoy's xDS (Discovery Service)
     5  // protocol.
     6  //
     7  // Server is the base implementation of any gRPC server which supports the xDS
     8  // protocol. All xDS bi-directional gRPC streams from Stream* calls must be
     9  // handled by calling Server.HandleRequestStream.
    10  // For example, to implement the ADS protocol:
    11  //
    12  //	func (s *myGRPCServer) StreamAggregatedResources(stream api.AggregatedDiscoveryService_StreamAggregatedResourcesServer) error {
    13  //	    return s.xdsServer.HandleRequestStream(stream.Context(), stream, xds.AnyTypeURL)
    14  //	}
    15  //
    16  // Server is parameterized by a map of supported resource type URLs to resource
    17  // sets, e.g. to support the LDS and RDS protocols:
    18  //
    19  //	ldsCache := xds.NewCache()
    20  //	lds := xds.NewAckingResourceMutatorWrapper(ldsCache)
    21  //	rdsCache := xds.NewCache()
    22  //	rds := xds.NewAckingResourceMutatorWrapper(rdsCache)
    23  //
    24  //	resTypes := map[string]xds.ResourceTypeConfiguration{
    25  //	    "type.googleapis.com/envoy.config.listener.v3.Listener": {ldsCache, lds},
    26  //	    "type.googleapis.com/envoy.config.route.v3.RouteConfiguration": {rdsCache, rds},
    27  //	}
    28  //
    29  //	server := xds.NewServer(resTypes, 5*time.Seconds)
    30  //
    31  // It is recommended to use a distinct resource set for each resource type to
    32  // minimize the volume of messages sent and received by xDS clients.
    33  //
    34  // Resource sets must implement the ResourceSource interface to provide read
    35  // access to resources of one or multiple resource types:
    36  //
    37  //	type ResourceSource interface {
    38  //	    GetResources(ctx context.Context, typeURL string, lastVersion *uint64,
    39  //	        nodeIP string, resourceNames []string) (*VersionedResources, error)
    40  //	}
    41  //
    42  // Resource sets should implement the ResourceSet interface to provide
    43  // read-write access. It provides an API to atomically update the resources in
    44  // the set: Upsert inserts or updates a single resource in the set, and
    45  // Delete deletes a single resource from the set.
    46  //
    47  // Cache is an efficient, ready-to-use implementation of ResourceSet:
    48  //
    49  //	typeURL := "type.googleapis.com/envoy.config.listener.v3.Listener"
    50  //	ldsCache := xds.NewCache()
    51  //	ldsCache.Upsert(typeURL, "listener123", listenerA, false)
    52  //	ldsCache.Delete(typeURL, "listener456", false)
    53  //
    54  // In order to wait for acknowledgements of updates by Envoy nodes,
    55  // each resource set should be wrapped into an AckingResourceMutatorWrapper,
    56  // which should then be passed to NewServer().
    57  // AckingResourceMutatorWrapper provides an extended API which accepts
    58  // Completions to notify of ACKs.
    59  //
    60  //	typeURL := "type.googleapis.com/envoy.config.listener.v3.Listener"
    61  //	ldsCache := xds.NewCache()
    62  //	lds := xds.NewAckingResourceMutatorWrapper(ldsCache)
    63  //
    64  //	ctx, cancel := context.WithTimeout(..., 5*time.Second)
    65  //	wg := completion.NewWaitGroup(ctx)
    66  //	nodes := []string{"10.0.0.1"} // Nodes to wait an ACK from.
    67  //	lds.Upsert(typeURL, "listener123", listenerA, nodes, wg.AddCompletion())
    68  //	lds.Delete(typeURL, "listener456", nodes, wg.AddCompletion())
    69  //	wg.Wait()
    70  //	cancel()
    71  package xds