dataplane

Documentation

Overview

Package dataplane provides functionality for communicating with and providing configuration to backend dataplane APIs.

Index

• Constants
• type AddressFinder
  • func NewAddressFinder() *AddressFinder
  • func (a *AddressFinder) GetAddresses() ([]string, error)
  • func (a *AddressFinder) GetLoadBalancerAddresses() ([]corev1.LoadBalancerIngress, error)
  • func (a *AddressFinder) SetGetter(getter AddressGetter)
  • func (a *AddressFinder) SetOverrides(addrs []string)
• type AddressGetter
• type Client
• type KongClient
  • func NewKongClient(logger logrus.FieldLogger, timeout time.Duration, ingressClass string, ...) (*KongClient, error)
  • func (c *KongClient) AreCombinedServiceRoutesEnabled() bool
  • func (c *KongClient) AreKubernetesObjectReportsEnabled() bool
  • func (c *KongClient) DBMode() string
  • func (c *KongClient) DeleteObject(obj client.Object) error
  • func (c *KongClient) EnableCombinedServiceRoutes()
  • func (c *KongClient) EnableKubernetesObjectReports(q *status.Queue)
  • func (c *KongClient) KubernetesObjectIsConfigured(obj client.Object) bool
  • func (c *KongClient) Listeners(ctx context.Context) ([]kong.ProxyListener, []kong.StreamListener, error)
  • func (c *KongClient) ObjectExists(obj client.Object) (bool, error)
  • func (c *KongClient) RootWithTimeout() (map[string]interface{}, error)
  • func (c *KongClient) Update(ctx context.Context) error
  • func (c *KongClient) UpdateObject(obj client.Object) error
• type Synchronizer
  • func NewSynchronizer(logger logrus.FieldLogger, dataplaneClient Client) (*Synchronizer, error)
  • func NewSynchronizerWithStagger(logger logrus.FieldLogger, dataplaneClient Client, stagger time.Duration) (*Synchronizer, error)
  • func (p *Synchronizer) IsReady() bool
  • func (p *Synchronizer) IsRunning() bool
  • func (p *Synchronizer) NeedLeaderElection() bool
  • func (p *Synchronizer) Start(ctx context.Context) error

Constants

const (
	// DefaultSyncSeconds indicates the time.Duration (minimum) that will occur between
	// updates to the DataplaneClient.
	//
	// This 1s default was based on local testing wherein it appeared sub-second updates
	// to the Admin API could be problematic (or at least operate differently) based on
	// which storage backend was in use (i.e. "dbless", "postgres"). This is a workaround
	// for improvements we still need to investigate upstream.
	//
	// See Also: https://github.com/Kong/kubernetes-ingress-controller/issues/1398
	DefaultSyncSeconds float32 = 3.0
)

const (
	// DefaultTimeoutSeconds indicates the time.Duration allowed for responses to
	// come back from the backend data-plane API.
	//
	// NOTE: the current default is based on observed latency in a CI environment using
	// the GKE cloud provider with the Kong Admin API.
	DefaultTimeoutSeconds float32 = 30.0
)

Types

type AddressFinder

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

AddressFinder is a threadsafe metadata object which can provide the current live addresses in use by the dataplane at any point in time.

func NewAddressFinder

func NewAddressFinder() *AddressFinder

NewAddressFinder provides a new AddressFinder which can be used to find the current listening addresses of the data-plane for ingress network traffic.

func (*AddressFinder) GetAddresses

func (a *AddressFinder) GetAddresses() ([]string, error)

GetAddresses provides a list of the addresses which the data-plane is listening on for ingress network traffic. Addresses can either be IP addresses or hostnames.

func (*AddressFinder) GetLoadBalancerAddresses

func (a *AddressFinder) GetLoadBalancerAddresses() ([]corev1.LoadBalancerIngress, error)

GetLoadBalancerAddresses provides a list of the addresses which the data-plane is listening on for ingress network traffic, but provides the addresses in Kubernetes corev1.LoadBalancerIngress format. Addresses can be IP addresses or hostnames.

func (*AddressFinder) SetGetter

func (a *AddressFinder) SetGetter(getter AddressGetter)

SetGetter provides a callback function that the AddressFinder will use to dynamically retrieve the addresses of the data-plane.

func (*AddressFinder) SetOverrides

func (a *AddressFinder) SetOverrides(addrs []string)

SetOverrides hard codes a specific list of addresses to be the addresses that this finder produces for the data-plane. To disable overrides, call this method again with an empty list.

type AddressGetter

type AddressGetter func() ([]string, error)

AddressGetter is a function which can dynamically retrieve the list of IPs that the data-plane is listening on for ingress network traffic.

type Client

type Client interface {
	// DBMode informs the caller which DB mode the data-plane has employed
	// (e.g. "off" (dbless) or "postgres").
	DBMode() string

	// Update the data-plane by parsing the current configuring and applying
	// it to the backend API.
	Update(ctx context.Context) error
}

type KongClient

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

KongClient is a threadsafe high level API client for the Kong data-plane which parses Kubernetes object caches into Kong Admin configurations and sends them as updates to the data-plane (Kong Admin API).

func NewKongClient

func NewKongClient(
	logger logrus.FieldLogger,
	timeout time.Duration,
	ingressClass string,
	enableReverseSync bool,
	skipCACertificates bool,
	diagnostic util.ConfigDumpDiagnostic,
	kongConfig sendconfig.Kong,
) (*KongClient, error)

NewKongClient provides a new KongClient object after connecting to the data-plane API and verifying integrity.

func (*KongClient) AreCombinedServiceRoutesEnabled

func (c *KongClient) AreCombinedServiceRoutesEnabled() bool

AreCombinedServiceRoutesEnabled determines whether the combined service routes translation mode has been enabled, or if the legacy logic is being used. When enabled this changes the logic to try and combine multiple paths into single routes, but it also changes the names of existing routes and so it should be considered disruptive as it will temporarily drop routes when it's first enabled.

func (*KongClient) AreKubernetesObjectReportsEnabled

func (c *KongClient) AreKubernetesObjectReportsEnabled() bool

AreKubernetesObjectReportsEnabled returns true or false whether this client has been configured to report on Kubernetes objects which have been successfully configured for in the data-plane.

func (*KongClient) DBMode

func (c *KongClient) DBMode() string

DBMode indicates which database the Kong Gateway is using

func (*KongClient) DeleteObject

func (c *KongClient) DeleteObject(obj client.Object) error

DeleteObject accepts a Kubernetes controller-runtime client.Object and removes it from the configuration cache. The delete action will asynchronously be converted to Kong DSL and applied to the Kong Admin API. A status will later be added to the object whether the configuration update succeeds or fails.

under the hood the cache implementation will ignore deletions on objects that are not present in the cache, so in those cases this is a no-op.

func (*KongClient) EnableCombinedServiceRoutes

func (c *KongClient) EnableCombinedServiceRoutes()

EnableCombinedServiceRoutes turns on the combined service routes feature for the Kong Dataplane client.

func (*KongClient) EnableKubernetesObjectReports

func (c *KongClient) EnableKubernetesObjectReports(q *status.Queue)

EnableKubernetesObjectReports turns on reporting for Kubernetes objects which are configured as part of Update() operations. Enabling this makes it possible to use ObjectConfigured(obj) to determine whether an object has successfully been configured for on the data-plane.

func (*KongClient) KubernetesObjectIsConfigured

func (c *KongClient) KubernetesObjectIsConfigured(obj client.Object) bool

KubernetesObjectIsConfigured reports whether the provided object has active configuration for itself successfully applied to the data-plane.

func (*KongClient) Listeners

func (c *KongClient) Listeners(ctx context.Context) ([]kong.ProxyListener, []kong.StreamListener, error)

Listeners retrieves the currently configured listeners from the underlying proxy so that callers can gather this metadata to know which ports and protocols are in use by the proxy.

func (*KongClient) ObjectExists

func (c *KongClient) ObjectExists(obj client.Object) (bool, error)

ObjectExists indicates whether or not any version of the provided object is already present in the proxy.

func (*KongClient) RootWithTimeout

func (c *KongClient) RootWithTimeout() (map[string]interface{}, error)

RootWithTimeout provides the root configuration from Kong, but uses a configurable timeout to avoid long waits if the Admin API is not yet ready to respond. If a timeout error occurs, the caller is responsible for providing a retry mechanism.

func (*KongClient) Update

func (c *KongClient) Update(ctx context.Context) error

Update parses the Cache present in the client and converts current Kubernetes state into Kong objects and state, and then ships the resulting configuration to the data-plane (Kong Admin API).

func (*KongClient) UpdateObject

func (c *KongClient) UpdateObject(obj client.Object) error

UpdateObject accepts a Kubernetes controller-runtime client.Object and adds/updates that to the configuration cache. It will be asynchronously converted into the upstream Kong DSL and applied to the Kong Admin API. A status will later be added to the object whether the configuration update succeeds or fails.

type Synchronizer

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

Synchronizer is a threadsafe object which starts a goroutine to updates the data-plane at regular intervals.

func NewSynchronizer

func NewSynchronizer(logger logrus.FieldLogger, dataplaneClient Client) (*Synchronizer, error)

NewSynchronizer will provide a new Synchronizer object. Note that this starts some background goroutines and the caller is resonsible for marking the provided context.Context as "Done()" to shut down the background routines

func NewSynchronizerWithStagger

func NewSynchronizerWithStagger(logger logrus.FieldLogger, dataplaneClient Client, stagger time.Duration) (*Synchronizer, error)

NewSynchronizer will provide a new Synchronizer object with a specified stagger time for data-plane updates to occur. Note that this starts some background goroutines and the caller is resonsible for marking the provided context.Context as "Done()" to shut down the background routines

func (*Synchronizer) IsReady

func (p *Synchronizer) IsReady() bool

IsReady indicates whether the synchronizer is actively able to synchronize configuration to the dataplane. It's similar to IsRunning() but reports on whether configuration can actually be successful and is also used as part of a controller-runtime Runnable interface to wait for readiness before starting controllers.

func (*Synchronizer) IsRunning

func (p *Synchronizer) IsRunning() bool

IsRunning informs the caller whether the synchronization server is running.

func (*Synchronizer) NeedLeaderElection

func (p *Synchronizer) NeedLeaderElection() bool

NeedLeaderElection implements the controller-runtime Runnable interface to inform the controller manager whether leadership election is needed, which is always true in our case.

func (*Synchronizer) Start

func (p *Synchronizer) Start(ctx context.Context) error

Start starts the goroutine synchronization server that will perform an Update() on the provided dataplane.Client according to the provided stagger time, or using the DefaultSyncSeconds if not otherwise provided.

To stop the server, the provided context must be Done().