controlplane

package
v0.0.0-...-aec5def Latest Latest
Warning

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

 Go to latest Published: May 3, 2026 License: Apache-2.0, Apache-2.0 Imports: 53 Imported by: 0

Documentation

Overview

controlplane/bootstrap.go

internal/controlplane/ingress.go

controlplane/logger.go

internal/controlplane/plane.go

Package controlplane provides utilities for constructing Envoy xDS resources, including clusters, endpoints, routes, listeners, and TLS transport sockets. It facilitates dynamic configuration of Envoy proxies for service discovery, load balancing, routing, and secure communication.

Functions:

  • MakeCluster: Creates an Envoy Cluster resource with optional TLS configuration and endpoints.
  • makeUpstreamTLS: Generates an upstream TLS transport socket configuration for secure connections.
  • makeDownstreamTLS: Generates a downstream TLS transport socket configuration for secure client connections.
  • makeEndpoint: Constructs a ClusterLoadAssignment for load balancing across specified endpoints.
  • MakeRoute: Builds a RouteConfiguration with CORS policy and host header rewriting.
  • MakeHTTPListener: Configures an HTTP listener with filters for gRPC-Web, CORS, and routing, with optional TLS.
  • makeConfigSource: Creates a ConfigSource for xDS gRPC API configuration.

The package leverages Envoy's go-control-plane APIs and protobuf types to programmatically generate configuration resources for Envoy proxies.

Package controlplane provides an xDS management server implementation for Envoy, leveraging the go-control-plane library. It offers functionality to create, configure, and run a gRPC management server with custom keepalive and stream options to support high concurrency and robust connection management.

The Server type wraps the go-control-plane server implementation and exposes methods for registering xDS services and running the management server. Utility functions are provided for direct server registration and startup.

Key Features:

  • Customizable gRPC keepalive and stream settings for reliability and scalability.
  • Registration of all major xDS services (ADS, Cluster, Endpoint, Route, Listener, Secret, Runtime).
  • Simple API for server instantiation and execution.

Example usage: 

cache := ... // create a cache_v3.Cache implementation
callbacks := ... // create test_v3.Callbacks
srv := controlplane.NewServer(context.Background(), cache, callbacks)
go srv.Run(18000)

// Or using RunServer directly:
controlplane.RunServer(srv.xdsserver, 18000)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddSnapshot 

func AddSnapshot(id, version string, values []Snapshot) error

AddSnapshot supports both sidecars and a shared ingress listener.

func DefaultIngressHTTPPort 

func DefaultIngressHTTPPort(host string) uint32

DefaultIngressHTTPPort exposes the HTTP port selection logic for other packages.

func DefaultIngressPort 

func DefaultIngressPort(host string) uint32

DefaultIngressPort exposes the HTTPS port selection logic for other packages.

func GetSnapshot 

func GetSnapshot(nodeID string) (cache_v3.ResourceSnapshot, error)

GetSnapshot fetches the current snapshot for a node.

func HashSecret 

func HashSecret(secret *tls_v3.Secret) (string, error)

HashSecret computes a content hash of a Secret resource for version tracking. This enables change detection: same cert = same hash, different cert = different hash.

The hash is computed over the secret's serialized content, ensuring any change (cert rotation, key change, CA update) results in a new version.

func MakeCertificateValidationContext 

func MakeCertificateValidationContext(caPath string) (*tls_v3.CertificateValidationContext, error)

MakeCertificateValidationContext builds a validation context from a CA bundle. This is used for validating peer certificates (upstream TLS or mTLS).

func MakeCluster 

func MakeCluster(
	clusterName, certFilePath, keyFilePath, caFilePath, sni string,
	endPoints []EndPoint,
) *cluster_v3.Cluster

MakeCluster function constructs a cluster using the STRICT_DNS discovery type, sets a 5-second connection timeout, configures round-robin load balancing, and enables HTTP/2 protocol options. If a key file path is provided, it configures the cluster to use TLS for upstream connections by setting the transport socket.

Parameters:

  • clusterName: The name of the Envoy cluster.
  • certFilePath: Path to the TLS certificate file (optional; required for TLS).
  • keyFilePath: Path to the TLS private key file (optional; required for TLS).
  • caFilePath: Path to the CA certificate file (optional; required for TLS).
  • endPoints: Slice of EndPoint structs specifying the cluster's endpoints.

Returns:

  • *cluster_v3.Cluster: A pointer to the constructed Envoy Cluster resource.

MakeCluster builds an upstream cluster. If caFilePath != "" OR both cert/key are set, Envoy will use TLS (and HTTP/2) to the upstream. Pass SNI = the DNS name on the Globular 8181 certificate (e.g., "globular.io" or your host FQDN).

func MakeClusterWithSDS 

func MakeClusterWithSDS(
	clusterName, caSecretName, clientCertSecretName, sni string,
	endPoints []EndPoint,
) *cluster_v3.Cluster

MakeClusterWithSDS creates an Envoy Cluster using SDS for TLS certificate delivery. Instead of reading certificates from files, Envoy fetches them dynamically via SDS.

Parameters:

  • clusterName: Name of the cluster
  • caSecretName: SDS secret name for CA bundle (e.g., "internal-ca-bundle")
  • clientCertSecretName: SDS secret name for client cert (optional, for mTLS)
  • sni: Server Name Indication for TLS handshake
  • endPoints: List of upstream endpoints

Returns:

  • *cluster_v3.Cluster configured with SDS for TLS

func MakeHTTPHealthChecks 

func MakeHTTPHealthChecks(path string) []*core_v3.HealthCheck

MakeHTTPHealthChecks returns an HTTP health check for services that don't support gRPC health protocol (e.g. the gateway, which is HTTP-only).

func MakeHTTPListener 

func MakeHTTPListener(listenerHost string, listenerPort uint32, listenerName, routeName, certFilePath, keyFilePath, caFilePath string) *listener_v3.Listener

MakeHTTPListener creates and configures an Envoy HTTP listener with the specified parameters. It sets up HTTP filters for gRPC-Web, CORS, and routing, and optionally configures TLS if certificate and key file paths are provided.

Parameters: 

listenerHost   - The host address to bind the listener.
listenerPort   - The port number to bind the listener.
listenerName   - The name of the listener.
routeName      - The name of the route configuration.
certFilePath   - Path to the TLS certificate file (optional).
keyFilePath    - Path to the TLS key file (optional).
caFilePath     - Path to the CA certificate file (optional).

Returns: 

*listener.Listener - A pointer to the configured Envoy listener.

func MakeHTTPListenerWithSDS 

func MakeHTTPListenerWithSDS(listenerHost string, listenerPort uint32, listenerName, routeName, serverCertSecretName, caSecretName string) *listener_v3.Listener

MakeHTTPListenerWithSDS creates an HTTP listener using SDS for TLS certificate delivery. Instead of reading certificates from files, Envoy fetches them dynamically via SDS.

Parameters:

  • listenerHost: Bind address (e.g., "0.0.0.0")
  • listenerPort: Port to listen on (e.g., 443)
  • listenerName: Logical name for the listener
  • routeName: Name of the route configuration to use
  • serverCertSecretName: SDS secret name for server cert (e.g., "internal-server-cert")
  • caSecretName: SDS secret name for CA bundle (optional, for client validation)

Returns:

  • *listener_v3.Listener configured with SDS for TLS

func MakeHTTPListenerWithSDSFilterChains 

func MakeHTTPListenerWithSDSFilterChains(
	listenerHost string,
	listenerPort uint32,
	listenerName string,
	routeName string,
	defaultServerCertSecretName string,
	caSecretName string,
	extraFilterChains []*listener_v3.FilterChain,
) *listener_v3.Listener

MakeHTTPListenerWithSDSFilterChains creates an HTTP listener with custom SNI filter chains. This allows per-domain certificate routing by prepending SNI-matched chains before the default chain.

Parameters:

  • listenerHost: Bind address (e.g., "0.0.0.0")
  • listenerPort: Port to listen on (e.g., 443)
  • listenerName: Logical name for the listener
  • routeName: Name of the route configuration to use
  • defaultServerCertSecretName: SDS secret for default/fallback certificate
  • caSecretName: SDS secret name for CA bundle (optional)
  • extraFilterChains: SNI-matched filter chains to prepend (matched before default)

Returns:

  • *listener_v3.Listener with SNI chains + default fallback chain

func MakeRedirectRoutes 

func MakeRedirectRoutes(routeName string, httpsPort uint32, permanent bool) (types.Resource, error)

MakeRedirectRoutes builds a simple redirect configuration that sends all HTTP requests to HTTPS.

func MakeRoute 

func MakeRoute(routeName string, clusterName, host string) *route_v3.RouteConfiguration

MakeRoute creates an Envoy RouteConfiguration with a single virtual host and route. The route matches all paths ("/") and forwards requests to the specified cluster, rewriting the host header to the provided host value. CORS policy is configured to allow all origins, specific HTTP methods, and headers. The route has an infinite timeout.

Parameters:

  • routeName: Name of the route configuration.
  • clusterName: Name of the target cluster for routing.
  • host: Host value to rewrite in the request.

Returns:

  • *route_v3.RouteConfiguration: Pointer to the constructed RouteConfiguration.

func MakeRoutes 

func MakeRoutes(routeName string, rs []IngressRoute, allowedOrigins []string, corsPolicy ...*coreConfig.CorsPolicy) *route_v3.RouteConfiguration

MakeRoutes builds the shared ingress RouteConfiguration with per-route prefixes. IMPORTANT: Enables CORS (with credentials) for browser callers.

corsPolicy (optional) provides the structured CORS configuration from the gateway. When nil, falls back to allowedOrigins (legacy []string) and hardcoded defaults. When allowedOrigins is also empty, a permissive regex ("https?://.*") is used.

func MakeSNIHTTPFilterChainWithSDS 

func MakeSNIHTTPFilterChainWithSDS(
	routeName string,
	serverNames []string,
	serverCertSecretName string,
	caSecretName string,
) (*listener_v3.FilterChain, error)

MakeSNIHTTPFilterChainWithSDS creates a FilterChain with SNI matching and SDS-based TLS. This is used for per-domain certificate routing in Envoy listeners.

Parameters:

  • routeName: Name of the route configuration to use
  • serverNames: List of SNI hostnames to match (e.g., ["globule-ryzen.globular.cloud"])
  • serverCertSecretName: SDS secret name for this domain's certificate (e.g., "ext-cert/globule-ryzen.globular.cloud")
  • caSecretName: SDS secret name for CA bundle (optional, for client validation)

Returns:

  • *listener_v3.FilterChain configured with SNI matching and SDS TLS
  • error if configuration fails

func MakeSecret 

func MakeSecret(name string, certPath, keyPath, caPath string) (*tls_v3.Secret, error)

MakeSecret builds an xDS Secret resource from certificate files. This enables Envoy SDS (Secret Discovery Service) for dynamic TLS certificate delivery.

Parameters:

  • name: Logical secret name (e.g., "internal-server-cert", "internal-ca-bundle")
  • certPath: Path to certificate file (PEM format), empty string if CA-only secret
  • keyPath: Path to private key file (PEM format), empty string if CA-only secret
  • caPath: Path to CA bundle (PEM format), empty string if cert-only secret

Returns an xDS Secret resource ready to be included in snapshot cache.

func MakeTLSCertificate 

func MakeTLSCertificate(certPath, keyPath string) (*tls_v3.TlsCertificate, error)

MakeTLSCertificate builds a TlsCertificate from PEM-encoded certificate and key files. The certificate chain and private key are read from disk and embedded inline.

func MarshalBootstrap 

func MarshalBootstrap(opt BootstrapOptions) ([]byte, error)

MarshalBootstrap builds the Envoy bootstrap JSON bytes without writing to disk.

func RemoveSnapshot 

func RemoveSnapshot(nodeID string)

RemoveSnapshot clears cached resources for the given node.

func RunServer 

func RunServer(srv server_v3.Server, port uint)

RunServer starts a gRPC server for the provided Server implementation on the specified port. It configures gRPC server options including maximum concurrent streams and keepalive parameters to ensure robust connection management. The function listens on the given TCP port, registers the server implementation, and begins serving incoming gRPC requests. If the server fails to start or encounters an error, it logs the error and terminates the process.

Parameters: 

srv  - The server_v3.Server implementation to register and serve.
port - The TCP port number to listen on for incoming gRPC connections.

func SecretVersion 

func SecretVersion(secret *tls_v3.Secret) (string, error)

SecretVersion generates a version string for xDS snapshot versioning. Format: "sds-{hash[:16]}" (first 16 chars of hash for brevity)

func StartControlPlane 

func StartControlPlane(ctx context.Context, port uint, exit chan bool) error

StartControlPlane runs the ADS/xDS management server.

func StripH2ALPN 

func StripH2ALPN(ts *core_v3.TransportSocket)

StripH2ALPN removes the "h2" ALPN protocol from a transport socket's TLS context. Used for HTTP/1.1-only upstream services (like the gateway) where h2 ALPN causes the TLS handshake to fail.

func ValidateCertKeyPair 

func ValidateCertKeyPair(certPEM, keyPEM []byte) error

ValidateCertKeyPair performs validation that cert and key are valid PEM and parseable. This rejects garbage-but-readable renewals before pushing to Envoy/SDS.

func WriteBootstrap 

func WriteBootstrap(path string, opt BootstrapOptions) error

WriteBootstrap writes the generated Envoy bootstrap to disk.

Types

type BootstrapOptions 

type BootstrapOptions struct {
	NodeID    string
	Cluster   string
	XDSHost   string
	XDSPort   int
	AdminPort int
	// Optional runtime config dir for resolving canonical PKI paths.
	RuntimeConfigDir string
	// DevInsecure allows plaintext bootstrap generation when true (GLOBULAR_XDS_INSECURE=1).
	// Use only for local development; production must keep this false.
	DevInsecure bool

	// set a global cap on active downstream connections (0 = omit)
	MaxActiveDownstreamConns uint64

	// TLS configuration for xDS cluster (mTLS to xDS server).
	// These are resolved automatically when empty using canonical PKI paths.
	XDSClientCertPath string // Envoy client certificate
	XDSClientKeyPath  string // Envoy client private key
	XDSCACertPath     string // CA bundle for validating xDS server certificate
}

type EndPoint 

type EndPoint struct {
	Host     string
	Port     uint32
	Priority uint32
	Weight   uint32 // 0 = use default (equal), 1-100 = relative weight from AI Router
}

EndPoint represents an upstream endpoint.

type IngressRoute 

type IngressRoute struct {
	// Prefix is the path prefix to match (for gRPC use "/pkg.Service/").
	Prefix string
	// Cluster is the name of the upstream cluster to route to.
	Cluster string
	// HostRewrite (optional) sets :authority when forwarding upstream.
	HostRewrite string
	// Domains optionally restricts the route to these virtual host domains.
	Domains []string
	// Authority enables an exact :authority match within the route.
	Authority string
	// Timeout sets the route timeout in seconds (0 = disabled for streaming)
	Timeout int
}

IngressRoute describes one route entry for the shared ingress listener.

type Logger 

type Logger struct {
	Debug bool
	// contains filtered or unexported fields
}

func NewLogger 

func NewLogger(address, app string, echo io.Writer, debug bool) *Logger

func (Logger) Debugf 

func (l Logger) Debugf(format string, args ...interface{})

Debugf implements log.Logger.

func (Logger) Errorf 

func (l Logger) Errorf(format string, args ...interface{})

Errorf implements log.Logger.

func (Logger) Infof 

func (l Logger) Infof(format string, args ...interface{})

Infof implements log.Logger.

func (Logger) Warnf 

func (l Logger) Warnf(format string, args ...interface{})

Warnf implements log.Logger.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server represents an xDS management server for Envoy, wrapping the go-control-plane server implementation.

func NewServer 

func NewServer(ctx context.Context, cache cache_v3.Cache, cb *test_v3.Callbacks) Server

NewServer creates and returns a new Server instance using the provided context, cache, and callbacks. It wraps the underlying server_v3.Server with additional functionality as defined by the Server type.

Parameters: 

ctx   - The context for controlling cancellation and deadlines.
cache - The cache implementation to be used by the server.
cb    - The callbacks to handle server events.

Returns: 

A new Server instance.

func (*Server) Run 

func (s *Server) Run(port uint)

Run starts the gRPC management server on the specified port with custom keepalive and stream options. It configures the server to handle a high number of concurrent streams and sets keepalive parameters to ensure connection reliability, especially when requests are multiplexed over a single TCP connection. The server is registered and begins listening for incoming connections. If the server fails to start, the error is logged and the process is terminated.

Parameters: 

port - The TCP port number on which the server will listen.

The function logs the listening port and any errors encountered during startup or while serving.

type Snapshot 

type Snapshot struct {
	// Sidecar fields
	ClusterName        string
	RouteName          string
	ListenerName       string
	ListenerHost       string // used for host-rewrite toward upstream
	ListenerPort       uint32
	HTTPPort           uint32
	EnableHTTPRedirect bool
	GatewayPort        uint32
	EndPoints          []EndPoint

	// Upstream (Envoy → service) mTLS
	ServerCertPath string
	KeyFilePath    string
	CAFilePath     string
	SNI            string // Server Name Indication for upstream TLS

	// Downstream (client → Envoy) TLS
	CertFilePath   string
	IssuerFilePath string

	// Ingress: if non-empty, build one listener with many routes (clusters must exist).
	IngressRoutes []IngressRoute

	HostRewrite string // e.g., backend service host
}

Snapshot can describe either:

  • a per-service sidecar (Cluster + single Route + Listener), or
  • a shared ingress listener with multiple routes (no cluster/endpoints needed here).

Source Files

View all Source files

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.