kubernetes

package
v0.21.57 Latest Latest
Warning

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

Go to latest
Published: Apr 19, 2024 License: Apache-2.0, MIT Imports: 28 Imported by: 5

Documentation

Overview

Package kubernetes implements Kubernetes Ingress support for Skipper.

See: http://kubernetes.io/docs/user-guide/ingress/

The package provides a Skipper DataClient implementation that can be used to access the Kubernetes API for ingress resources and generate routes based on them. The client polls for the ingress settings, and there is no need for a separate controller. On the other hand, it doesn't provide a full Ingress solution alone, because it doesn't do any load balancer configuration or DNS updates. For a full Ingress solution, it is possible to use Skipper together with Kube-ingress-aws-controller, which targets AWS and takes care of the load balancer setup for Kubernetes Ingress.

See: https://github.com/zalando-incubator/kube-ingress-aws-controller

Both Kube-ingress-aws-controller and Skipper Kubernetes are part of the larger project, Kubernetes On AWS:

https://github.com/zalando-incubator/kubernetes-on-aws/

Ingress shutdown by healthcheck

The Kubernetes ingress client catches TERM signals when the ProvideHealthcheck option is enabled, and reports failing healthcheck after the signal was received. This means that, when the Ingress client is responsible for the healthcheck of the cluster, and the Skipper process receives the TERM signal, it won't exit by itself immediately, but will start reporting failures on healthcheck requests. Until it gets killed by the kubelet, Skipper keeps serving the requests in this case.

Example - Ingress

Please check https://opensource.zalando.com/skipper/kubernetes/ingress-usage/ for more information and examples.

Index

Constants

View Source
const (
	IngressesV1ClusterURI      = "/apis/networking.k8s.io/v1/ingresses"
	ZalandoResourcesClusterURI = "/apis/zalando.org/v1"
	RouteGroupsName            = "routegroups"
	RouteGroupsClusterURI      = "/apis/zalando.org/v1/routegroups"

	ServicesClusterURI       = "/api/v1/services"
	EndpointsClusterURI      = "/api/v1/endpoints"
	EndpointSlicesClusterURI = "/apis/discovery.k8s.io/v1/endpointslices"
	SecretsClusterURI        = "/api/v1/secrets"

	IngressesV1NamespaceFmt    = "/apis/networking.k8s.io/v1/namespaces/%s/ingresses"
	RouteGroupsNamespaceFmt    = "/apis/zalando.org/v1/namespaces/%s/routegroups"
	ServicesNamespaceFmt       = "/api/v1/namespaces/%s/services"
	EndpointsNamespaceFmt      = "/api/v1/namespaces/%s/endpoints"
	EndpointSlicesNamespaceFmt = "/apis/discovery.k8s.io/v1/namespaces/%s/endpointslices"
	SecretsNamespaceFmt        = "/api/v1/namespaces/%s/secrets"
)
View Source
const DefaultLoadBalancerAlgorithm = "roundRobin"
View Source
const RouteGroupsNotInstalledMessage = `` /* 129-byte string literal not displayed */

Variables

This section is empty.

Functions

This section is empty.

Types

type BackendTrafficAlgorithm added in v0.16.110

type BackendTrafficAlgorithm int

BackendTrafficAlgorithm specifies the algorithm for backend traffic calculation

const (
	// TrafficPredicateAlgorithm is the default algorithm for backend traffic calculation.
	// It uses Traffic and True predicates to distribute traffic between backends.
	TrafficPredicateAlgorithm BackendTrafficAlgorithm = iota

	// TrafficSegmentPredicateAlgorithm uses TrafficSegment predicate to distribute traffic between backends
	TrafficSegmentPredicateAlgorithm
)

func ParseBackendTrafficAlgorithm added in v0.16.110

func ParseBackendTrafficAlgorithm(name string) (BackendTrafficAlgorithm, error)

ParseBackendTrafficAlgorithm parses a string into a BackendTrafficAlgorithm

func (BackendTrafficAlgorithm) String added in v0.16.110

func (a BackendTrafficAlgorithm) String() string

type Client

type Client struct {
	ClusterClient *clusterClient
	// contains filtered or unexported fields
}

Client is a Skipper DataClient implementation used to create routes based on Kubernetes Ingress settings.

func New

func New(o Options) (*Client, error)

New creates and initializes a Kubernetes DataClient.

func (*Client) Close added in v0.10.16

func (c *Client) Close()

func (*Client) GetEndpointAddresses added in v0.13.232

func (c *Client) GetEndpointAddresses(ns, name string) []string

GetEndpointAddresses returns the list of all addresses for the given service loaded by previous call to LoadAll or LoadUpdate.

func (*Client) LoadAll

func (c *Client) LoadAll() ([]*eskip.Route, error)

func (*Client) LoadEndpointAddresses added in v0.20.7

func (c *Client) LoadEndpointAddresses(namespace, name string) ([]string, error)

LoadEndpointAddresses returns the list of all addresses for the given service.

func (*Client) LoadUpdate

func (c *Client) LoadUpdate() ([]*eskip.Route, []string, error)

LoadUpdate returns all known eskip.Route, a list of route IDs scheduled for delete and an error.

TODO: implement a force reset after some time.

type ClusterResource added in v0.11.130

type ClusterResource struct {
	Name string `json:"name"`
}

type ClusterResourceList added in v0.11.130

type ClusterResourceList struct {
	// Items, aka "resources".
	Items []*ClusterResource `json:"resources"`
}

type EndpointSliceEndpoints added in v0.18.0

type EndpointSliceEndpoints struct {
	// Addresses [1..100] of the same AddressType, see also https://github.com/kubernetes/kubernetes/issues/106267
	// Basically it always has only one in our case and likely makes no sense to use more than one.
	// Pick first or one at random are possible, but skipper will pick the first.
	// If you need something else please create an issue https://github.com/zalando/skipper/issues/new/choose
	Addresses []string `json:"addresses"` // [ "10.2.13.9" ]
	// Conditions are used for deciding to drop out of load balancer or fade into the load balancer.
	Conditions *endpointsliceCondition `json:"conditions"`
	// Zone is used for zone aware traffic routing, please see also
	// https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/#constraints
	// https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/#safeguards
	// Zone aware routing will be available if https://github.com/zalando/skipper/issues/1446 is closed.
	Zone string `json:"zone"` // "eu-central-1c"
}

EndpointSliceEndpoints is the single endpoint definition

type Options

type Options struct {
	// KubernetesInCluster defines if skipper is deployed and running in the kubernetes cluster
	// this would make authentication with API server happen through the service account, rather than
	// running along side kubectl proxy
	KubernetesInCluster bool

	// KubernetesURL is used as the base URL for Kubernetes API requests. Defaults to http://localhost:8001.
	// (TBD: support in-cluster operation by taking the address and certificate from the standard Kubernetes
	// environment variables.)
	KubernetesURL string

	// TokenFile configures path to the token file.
	// Defaults to /var/run/secrets/kubernetes.io/serviceaccount/token when running in-cluster.
	TokenFile string

	// KubernetesNamespace is used to switch between finding ingresses in the cluster-scope or limit
	// the ingresses to only those in the specified namespace. Defaults to "" which means monitor ingresses
	// in the cluster-scope.
	KubernetesNamespace string

	// KubernetesEnableEndpointslices if set skipper will fetch
	// endpointslices instead of endpoints to scale more than 1000 pods within a service
	KubernetesEnableEndpointslices bool

	// *DEPRECATED* KubernetesEnableEastWest if set adds automatically routes
	// with "%s.%s.skipper.cluster.local" domain pattern
	KubernetesEnableEastWest bool

	// ProvideHealthcheck, when set, tells the data client to append a healthcheck route to the ingress
	// routes in case of successfully receiving the ingress items from the API (even if individual ingress
	// items may be invalid), or a failing healthcheck route when the API communication fails. The
	// healthcheck endpoint can be accessed from internal IPs on any hostname, with the path
	// /kube-system/healthz.
	//
	// When used in a custom configuration, the current filter registry needs to include the status()
	// filter, and the available predicates need to include the Source() predicate.
	ProvideHealthcheck bool

	// ProvideHTTPSRedirect, when set, tells the data client to append an HTTPS redirect route to the
	// ingress routes. This route will detect the X-Forwarded-Proto=http and respond with a 301 message
	// to the HTTPS equivalent of the same request (using the redirectTo(301, "https:") filter). The
	// X-Forwarded-Proto and X-Forwarded-Port is expected to be set by the load balancer.
	//
	// (See also https://github.com/zalando-incubator/kube-ingress-aws-controller as part of the
	// https://github.com/zalando-incubator/kubernetes-on-aws project.)
	ProvideHTTPSRedirect bool

	// HTTPSRedirectCode, when set defines which redirect code to use for redirecting from HTTP to HTTPS.
	// By default, 308 StatusPermanentRedirect is used.
	HTTPSRedirectCode int

	// DisableCatchAllRoutes, when set, tells the data client to not create catchall routes.
	DisableCatchAllRoutes bool

	// IngressClass is a regular expression to filter only those ingresses that match. If an ingress does
	// not have a class annotation or the annotation is an empty string, skipper will load it. The default
	// value for the ingress class is 'skipper'.
	//
	// For further information see:
	//		https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/multiple-ingress-controllers
	IngressClass string

	// RouteGroupClass is a regular expression to filter only those RouteGroups that match. If a RouteGroup
	// does not have the required annotation (zalando.org/routegroup.class) or the annotation is an empty string,
	// skipper will load it. The default value for the RouteGroup class is 'skipper'.
	RouteGroupClass string

	// IngressLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. A label and its value on an Ingress must be match exactly to be loaded by Skipper.
	// If the value is irrelevant for a given configuration, it can be left empty. The default
	// value is no labels required.
	// Examples:
	//  Config [] will load all Ingresses.
	// 	Config ["skipper-enabled": ""] will load only Ingresses with a label "skipper-enabled", no matter the value.
	// 	Config ["skipper-enabled": "true"] will load only Ingresses with a label "skipper-enabled: true"
	// 	Config ["skipper-enabled": "", "foo": "bar"] will load only Ingresses with both labels while label "foo" must have a value "bar".
	IngressLabelSelectors map[string]string

	// ServicesLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. Read documentation for IngressLabelSelectors for examples and more details.
	// The default value is no labels required.
	ServicesLabelSelectors map[string]string

	// EndpointsLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. Read documentation for IngressLabelSelectors for examples and more details.
	// The default value is no labels required.
	EndpointsLabelSelectors map[string]string

	// EndpointSlicesLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. Read documentation for IngressLabelSelectors for examples and more details.
	// The default value is no labels required.
	EndpointSlicesLabelSelectors map[string]string

	// SecretsLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. Read documentation for IngressLabelSelectors for examples and more details.
	// The default value is no labels required.
	SecretsLabelSelectors map[string]string

	// RouteGroupsLabelSelectors is a map of kubernetes labels to their values that must be present on a resource to be loaded
	// by the client. Read documentation for IngressLabelSelectors for examples and more details.
	// The default value is no labels required.
	RouteGroupsLabelSelectors map[string]string

	// ReverseSourcePredicate set to true will do the Source IP
	// whitelisting for the heartbeat endpoint correctly in AWS.
	// Amazon's ALB writes the client IP to the last item of the
	// string list of the X-Forwarded-For header, in this case you
	// want to set this to true.
	ReverseSourcePredicate bool

	// Noop, WIP.
	ForceFullUpdatePeriod time.Duration

	// WhitelistedHealthcheckCIDR to be appended to the default iprange
	WhitelistedHealthCheckCIDR []string

	// PathMode controls the default interpretation of ingress paths in cases when the ingress doesn't
	// specify it with an annotation.
	PathMode PathMode

	// *DEPRECATED *KubernetesEastWestDomain sets the DNS domain to be
	// used for east west traffic, defaults to "skipper.cluster.local"
	KubernetesEastWestDomain string

	// KubernetesEastWestRangeDomains set the the cluster internal domains for
	// east west traffic. Identified routes to such domains will include
	// the KubernetesEastWestRangePredicates.
	KubernetesEastWestRangeDomains []string

	// KubernetesEastWestRangePredicates set the Predicates that will be
	// appended to routes identified as to KubernetesEastWestRangeDomains.
	KubernetesEastWestRangePredicates []*eskip.Predicate

	// DefaultFiltersDir enables default filters mechanism and sets the location of the default filters.
	// The provided filters are then applied to all routes.
	DefaultFiltersDir string

	// OriginMarker is *deprecated* and not used anymore. It will be deleted in v1.
	OriginMarker bool

	// If the OpenTracing tag containing RouteGroup backend name
	// (using tracingTag filter) should be added to all routes
	BackendNameTracingTag bool

	// OnlyAllowedExternalNames will enable validation of ingress external names and route groups network
	// backend addresses, explicit LB endpoints validation against the list of patterns in
	// AllowedExternalNames.
	OnlyAllowedExternalNames bool

	// AllowedExternalNames contains regexp patterns of those domain names that are allowed to be
	// used with external name services (type=ExternalName).
	AllowedExternalNames []*regexp.Regexp

	CertificateRegistry *certregistry.CertRegistry

	// ForceKubernetesService overrides the default Skipper functionality to route traffic using
	// Kubernetes Endpoint, instead using Kubernetes Services.
	ForceKubernetesService bool

	// BackendTrafficAlgorithm specifies the algorithm to calculate the backend traffic.
	BackendTrafficAlgorithm BackendTrafficAlgorithm

	// DefaultLoadBalancerAlgorithm sets the default algorithm to be used for load balancing between backend endpoints,
	// available options: roundRobin, consistentHash, random, powerOfRandomNChoices
	DefaultLoadBalancerAlgorithm string
}

Options is used to initialize the Kubernetes DataClient.

type PathMode added in v0.10.23

type PathMode int

PathMode values are used to control the ingress path interpretation. The path mode can be set globally for all ingress paths, and it can be overruled by the individual ingress rules using the zalando.org/skipper-ingress-path-mode annotation. When path mode is not set, the Kubernetes ingress specification is used, accepting regular expressions with a mandatory leading "/", automatically prepended by the "^" control character.

When PathPrefix is used, the path matching becomes deterministic when a request could match more than one ingress routes otherwise.

const (
	// KubernetesIngressMode is the default path mode. Expects regular expressions
	// with a mandatory leading "/". The expressions are automatically prepended by
	// the "^" control character.
	KubernetesIngressMode PathMode = iota

	// PathRegexp is like KubernetesIngressMode but is not prepended by the "^"
	// control character.
	PathRegexp

	// PathPrefix is like the PathSubtree predicate. E.g. "/foo/bar" will match
	// "/foo/bar" or "/foo/bar/baz", but won't match "/foo/barooz".
	//
	// In this mode, when a Path or a PathSubtree predicate is set in an annotation,
	// the value from the annotation has precedence over the standard ingress path.
	PathPrefix
)

func ParsePathMode added in v0.10.23

func ParsePathMode(s string) (PathMode, error)

ParsePathMode parses the string representations of the different path modes.

func (PathMode) String added in v0.10.23

func (m PathMode) String() string

String returns the string representation of the path mode, the same values that are used in the path mode annotation.

Directories

Path Synopsis
Package definitions provides type definitions, parsing, marshaling and validation for Kubernetes resources used by Skipper.
Package definitions provides type definitions, parsing, marshaling and validation for Kubernetes resources used by Skipper.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL