dataplane

Documentation

Overview

Package dataplane translates Graph representation of the cluster state into an intermediate representation of data plane configuration. We can think of it as an intermediate state between the cluster resources and NGINX configuration files.

The package includes: - The types to hold the intermediate representation. - The functions to translate the Graph into the representation.

Index

• func CreateRatioVarName(ratio int32) string
• type Backend
• type BackendGroup
  • func (bg *BackendGroup) Name() string
• type BaseHTTPConfig
• type CertBundle
• type CertBundleID
• type Configuration
  • func BuildConfiguration(ctx context.Context, g *graph.Graph, serviceResolver resolver.ServiceResolver, ...) Configuration
• type HTTPFilters
• type HTTPHeader
• type HTTPHeaderFilter
• type HTTPHeaderMatch
• type HTTPPathModifier
• type HTTPQueryParamMatch
• type HTTPRequestRedirectFilter
• type HTTPURLRewriteFilter
• type IPFamilyType
• type InvalidHTTPFilter
• type Layer4VirtualServer
• type Match
• type MatchRule
• type PathModifierType
• type PathRule
• type PathType
• type Ratio
• type SSL
• type SSLKeyPair
• type SSLKeyPairID
• type SpanAttribute
• type Telemetry
• type Upstream
• type VerifyTLS
• type VirtualServer

Functions

func CreateRatioVarName

func CreateRatioVarName(ratio int32) string

CreateRatioVarName builds a variable name for an ObservabilityPolicy to be used with ratio-based trace sampling.

Types

type Backend

type Backend struct {
	// VerifyTLS holds the backend TLS verification configuration.
	VerifyTLS *VerifyTLS
	// UpstreamName is the name of the upstream for this backend.
	UpstreamName string
	// Weight is the weight of the BackendRef.
	// The possible values of weight are 0-1,000,000.
	// If weight is 0, no traffic should be forwarded for this entry.
	Weight int32
	// Valid indicates whether the Backend is valid.
	Valid bool
}

Backend represents a Backend for a routing rule.

type BackendGroup

type BackendGroup struct {
	// Source is the NamespacedName of the HTTPRoute the group belongs to.
	Source types.NamespacedName
	// Backends is a list of Backends in the Group.
	Backends []Backend
	// RuleIdx is the index of the corresponding rule in the HTTPRoute.
	RuleIdx int
}

BackendGroup represents a group of Backends for a routing rule in an HTTPRoute.

func (*BackendGroup) Name

func (bg *BackendGroup) Name() string

Name returns the name of the backend group. This name must be unique across all HTTPRoutes and all rules within the same HTTPRoute. The RuleIdx is used to make the name unique across all rules within the same HTTPRoute. The RuleIdx may change for a given rule if an update is made to the HTTPRoute, but it will always match the index of the rule in the stored HTTPRoute.

type BaseHTTPConfig

type BaseHTTPConfig struct {
	// IPFamily specifies the IP family for all servers.
	IPFamily IPFamilyType
	// HTTP2 specifies whether http2 should be enabled for all servers.
	HTTP2 bool
}

BaseHTTPConfig holds the configuration options at the http context.

type CertBundle

type CertBundle []byte

CertBundle is a Certificate bundle.

type CertBundleID

type CertBundleID string

CertBundleID is a unique identifier for a Certificate bundle. The ID is safe to use as a file name.

type Configuration

type Configuration struct {
	// SSLKeyPairs holds all unique SSLKeyPairs.
	SSLKeyPairs map[SSLKeyPairID]SSLKeyPair
	// CertBundles holds all unique Certificate Bundles.
	CertBundles map[CertBundleID]CertBundle
	// HTTPServers holds all HTTPServers.
	HTTPServers []VirtualServer
	// SSLServers holds all SSLServers.
	SSLServers []VirtualServer
	// TLSPassthroughServers hold all TLSPassthroughServers
	TLSPassthroughServers []Layer4VirtualServer
	// Upstreams holds all unique http Upstreams.
	Upstreams []Upstream
	// StreamUpstreams holds all unique stream Upstreams
	StreamUpstreams []Upstream
	// BackendGroups holds all unique BackendGroups.
	BackendGroups []BackendGroup
	// BaseHTTPConfig holds the configuration options at the http context.
	BaseHTTPConfig BaseHTTPConfig
	// Telemetry holds the Otel configuration.
	Telemetry Telemetry
	// Version represents the version of the generated configuration.
	Version int
}

Configuration is an intermediate representation of dataplane configuration.

func BuildConfiguration

func BuildConfiguration(
	ctx context.Context,
	g *graph.Graph,
	serviceResolver resolver.ServiceResolver,
	configVersion int,
) Configuration

BuildConfiguration builds the Configuration from the Graph.

type HTTPFilters

type HTTPFilters struct {
	// InvalidFilter is a special filter that indicates whether the filters are invalid. If this is the case,
	// the data plane must return 500 error, and all other filters are nil.
	InvalidFilter *InvalidHTTPFilter
	// RequestRedirect holds the HTTPRequestRedirectFilter.
	RequestRedirect *HTTPRequestRedirectFilter
	// RequestURLRewrite holds the HTTPURLRewriteFilter.
	RequestURLRewrite *HTTPURLRewriteFilter
	// RequestHeaderModifiers holds the HTTPHeaderFilter.
	RequestHeaderModifiers *HTTPHeaderFilter
	// ResponseHeaderModifiers holds the HTTPHeaderFilter.
	ResponseHeaderModifiers *HTTPHeaderFilter
}

HTTPFilters hold the filters for a MatchRule.

type HTTPHeader

type HTTPHeader struct {
	// Name is the name of the header.
	Name string
	// Value is the value of the header.
	Value string
}

HTTPHeader represents an HTTP header.

type HTTPHeaderFilter

type HTTPHeaderFilter struct {
	// Set adds or replaces headers.
	Set []HTTPHeader
	// Add adds headers. It appends to any existing values associated with a header name.
	Add []HTTPHeader
	// Remove removes headers.
	Remove []string
}

HTTPHeaderFilter manipulates HTTP headers.

type HTTPHeaderMatch

type HTTPHeaderMatch struct {
	// Name is the name of the header to match.
	Name string
	// Value is the value of the header to match.
	Value string
}

HTTPHeaderMatch matches an HTTP header.

type HTTPPathModifier

type HTTPPathModifier struct {
	// Replacement specifies the value with which to replace the full path or prefix match of a request during
	// a rewrite or redirect.
	Replacement string
	// Type indicates the type of path modifier.
	Type PathModifierType
}

HTTPPathModifier defines configuration for path modifiers.

type HTTPQueryParamMatch

type HTTPQueryParamMatch struct {
	// Name is the name of the query parameter to match.
	Name string
	// Value is the value of the query parameter to match.
	Value string
}

HTTPQueryParamMatch matches an HTTP query parameter.

type HTTPRequestRedirectFilter

type HTTPRequestRedirectFilter struct {
	// Scheme is the scheme of the redirect.
	Scheme *string
	// Hostname is the hostname of the redirect.
	Hostname *string
	// Port is the port of the redirect.
	Port *int32
	// StatusCode is the HTTP status code of the redirect.
	StatusCode *int
}

HTTPRequestRedirectFilter redirects HTTP requests.

type HTTPURLRewriteFilter

type HTTPURLRewriteFilter struct {
	// Hostname is the hostname of the rewrite.
	Hostname *string
	// Path is the path of the rewrite.
	Path *HTTPPathModifier
}

HTTPURLRewriteFilter rewrites HTTP requests.

type IPFamilyType

type IPFamilyType string

IPFamilyType specifies the IP family to be used by NGINX.

const (
	// Dual specifies that the server will use both IPv4 and IPv6.
	Dual IPFamilyType = "dual"
	// IPv4 specifies that the server will use only IPv4.
	IPv4 IPFamilyType = "ipv4"
	// IPv6 specifies that the server will use only IPv6.
	IPv6 IPFamilyType = "ipv6"
)

type InvalidHTTPFilter

type InvalidHTTPFilter struct{}

InvalidHTTPFilter is a special filter for handling the case when configured filters are invalid.

type Layer4VirtualServer

type Layer4VirtualServer struct {
	// Hostname is the hostname of the server.
	Hostname string
	// UpstreamName refers to the name of the upstream that is used.
	UpstreamName string
	// Port is the port of the server.
	Port int32
	// IsDefault refers to whether this server is created for the default listener hostname.
	IsDefault bool
}

Layer4VirtualServer is a virtual server for Layer 4 traffic.

type Match

type Match struct {
	// Method matches against the HTTP method.
	Method *string
	// Headers matches against the HTTP headers.
	Headers []HTTPHeaderMatch
	// QueryParams matches against the HTTP query parameters.
	QueryParams []HTTPQueryParamMatch
}

Match represents a match for a routing rule which consist of matches against various HTTP request attributes.

type MatchRule

type MatchRule struct {
	// Filters holds the filters for the MatchRule.
	Filters HTTPFilters
	// Source is the ObjectMeta of the resource that includes the rule.
	Source *metav1.ObjectMeta
	// Match holds the match for the rule.
	Match Match
	// BackendGroup is the group of Backends that the rule routes to.
	BackendGroup BackendGroup
}

MatchRule represents a routing rule. It corresponds directly to a Match in the HTTPRoute resource. An HTTPRoute is guaranteed to have at least one rule with one match. If no rule or match is specified by the user, the default rule {{path:{ type: "PathPrefix", value: "/"}}} is set by the schema.

type PathModifierType

type PathModifierType string

PathModifierType is the type of the PathModifier in a redirect or rewrite rule.

const (
	// ReplaceFullPath indicates that we replace the full path.
	ReplaceFullPath PathModifierType = "ReplaceFullPath"
	// ReplacePrefixMatch indicates that we replace a prefix match.
	ReplacePrefixMatch PathModifierType = "ReplacePrefixMatch"
)

type PathRule

type PathRule struct {
	// Path is a path. For example, '/hello'.
	Path string
	// PathType is the type of the path.
	PathType PathType
	// MatchRules holds routing rules.
	MatchRules []MatchRule
	// Policies contains the list of policies that are applied to this PathRule.
	Policies []policies.Policy
	// GRPC indicates if this is a gRPC rule
	GRPC bool
}

PathRule represents routing rules that share a common path.

type PathType

type PathType string

PathType is the type of the path in a PathRule.

const (
	// PathTypePrefix indicates that the path is a prefix.
	PathTypePrefix PathType = "prefix"
	// PathTypeExact indicates that the path is exact.
	PathTypeExact PathType = "exact"
)

type Ratio

type Ratio struct {
	// Name is based on the associated ObservabilityPolicy's NamespacedName,
	// and is used as the nginx variable name for this ratio.
	Name string
	// Value is the value of the ratio.
	Value int32
}

Ratio represents a tracing sampling ratio used in an nginx config with the otel_module.

type SSL

type SSL struct {
	// KeyPairID is the ID of the corresponding SSLKeyPair for the server.
	KeyPairID SSLKeyPairID
}

SSL is the SSL configuration for a server.

type SSLKeyPair

type SSLKeyPair struct {
	// Cert is the certificate.
	Cert []byte
	// Key is the private key.
	Key []byte
}

SSLKeyPair is an SSL private/public key pair.

type SSLKeyPairID

type SSLKeyPairID string

SSLKeyPairID is a unique identifier for a SSLKeyPair. The ID is safe to use as a file name.

type SpanAttribute

type SpanAttribute struct {
	// Key is the key for a span attribute.
	Key string
	// Value is the value for a span attribute.
	Value string
}

SpanAttribute is a key value pair to be added to a tracing span.

type Telemetry

type Telemetry struct {
	// Endpoint specifies the address of OTLP/gRPC endpoint that will accept telemetry data.
	Endpoint string
	// ServiceName is the “service.name” attribute of the OTel resource.
	ServiceName string
	// Interval specifies the export interval.
	Interval string
	// Ratios is a list of tracing sampling ratios.
	Ratios []Ratio
	// SpanAttributes are global custom key/value attributes that are added to each span.
	SpanAttributes []SpanAttribute
	// BatchSize specifies the maximum number of spans to be sent in one batch per worker.
	BatchSize int32
	// BatchCount specifies the number of pending batches per worker, spans exceeding the limit are dropped.
	BatchCount int32
}

Telemetry represents global Otel configuration for the dataplane.

type Upstream

type Upstream struct {
	// Name is the name of the Upstream. Will be unique for each service/port combination.
	Name string
	// ErrorMsg contains the error message if the Upstream is invalid.
	ErrorMsg string
	// Endpoints are the endpoints of the Upstream.
	Endpoints []resolver.Endpoint
}

Upstream is a pool of endpoints to be load balanced.

type VerifyTLS

type VerifyTLS struct {
	CertBundleID CertBundleID
	Hostname     string
	RootCAPath   string
}

VerifyTLS holds the backend TLS verification configuration.

type VirtualServer

type VirtualServer struct {
	// SSL holds the SSL configuration for the server.
	SSL *SSL
	// Hostname is the hostname of the server.
	Hostname string
	// PathRules is a collection of routing rules.
	PathRules []PathRule
	// Policies is a list of Policies that apply to the server.
	Policies []policies.Policy
	// Port is the port of the server.
	Port int32
	// IsDefault indicates whether the server is the default server.
	IsDefault bool
}

VirtualServer is a virtual server.