kubernetes

Documentation

Overview

Package kubernetes provides some higher level Kubernetes abstractions to orchestrate Ingress resources.

Operations

The exported Adapter provides a limited set of operations that can be used to:

• List Ingress resources
• Update the Hostname attribute of Ingress load balancer objects

Usage

The Adapter can be created with the typical in-cluster configuration. This configuration depends on some specific Kubernetes environment variables and files, required to communicate with the API server:

• Environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT
• OAuth2 Bearer token contained in the file /var/run/secrets/kubernetes.io/serviceaccount/token
• The Root CA certificate contained in the file /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

This is the preferred way and should be as simples as:

config, err := InClusterConfig()
if err != nil {
    log.Fatal(err)
}
kubeAdapter, err := kubernetes.NewAdapter(config)
if err != nil {
    log.Fatal(err)
}
ingresses, err := kubeAdapter.ListIngress() // for ex.

For local development it is possible to create an Adapter using an insecure configuration.

For example:

config := kubernetes.InsecureConfig("http://localhost:8001")
kubeAdapter, err := kubernetes.NewAdapter(config)
if err != nil {
    log.Fatal(err)
}
ingresses, err := kubeAdapter.ListIngress() // for ex.

Index

• Constants
• Variables
• type Adapter
  • func NewAdapter(config *Config, ingressAPIVersion string, ingressClassFilters []string, ...) (*Adapter, error)
  • func (a *Adapter) GetConfigMap(namespace, name string) (*ConfigMap, error)
  • func (a *Adapter) IngressFiltersString() string
  • func (a *Adapter) ListIngress() ([]*Ingress, error)
  • func (a *Adapter) ListResources() ([]*Ingress, error)
  • func (a *Adapter) ListRoutegroups() ([]*Ingress, error)
  • func (a *Adapter) UpdateIngressLoadBalancer(ingress *Ingress, loadBalancerDNSName string) error
• type Config
  • func InClusterConfig() (*Config, error)
  • func InsecureConfig(apiServerBaseURL string) *Config
• type ConfigMap
  • func (c *ConfigMap) String() string
• type Ingress
  • func (i *Ingress) String() string
• type ResourceLocation
  • func ParseResourceLocation(s string) (*ResourceLocation, error)
  • func (r *ResourceLocation) String() string
• type TLSClientConfig

Constants

const (
	IngressAPIVersionExtensions   = "extensions/v1beta1"
	IngressAPIVersionNetworking   = "networking.k8s.io/v1beta1"
	IngressAPIVersionNetworkingV1 = "networking.k8s.io/v1"
)

const (
	DefaultClusterLocalDomain = ".cluster.local"
)

Variables

var (
	// ErrMissingKubernetesEnv is returned when the Kubernetes API server environment variables are not defined
	ErrMissingKubernetesEnv = errors.New("unable to load in-cluster configuration, KUBERNETES_SERVICE_HOST and " +
		"KUBERNETES_SERVICE_PORT are not defined")
	// ErrInvalidIngressUpdateParams is returned when a request to update ingress resources has an empty DNS name
	// or doesn't specify any ingress resources
	ErrInvalidIngressUpdateParams = errors.New("invalid ingress update parameters")
	// ErrInvalidIngressUpdateARNParams is returned when a request to update ingress resources has an empty ARN
	// or doesn't specify any ingress resources
	ErrInvalidIngressUpdateARNParams = errors.New("invalid ingress updateARN parameters")
	// ErrUpdateNotNeeded is returned when an ingress update call doesn't require an update due to already having
	// the desired hostname
	ErrUpdateNotNeeded = errors.New("update to ingress resource not needed")
	// ErrInvalidConfiguration is returned when the Kubernetes configuration is missing required attributes
	ErrInvalidConfiguration = errors.New("invalid Kubernetes Adapter configuration")
	// ErrInvalidCertificates is returned when the CA certificates required to communicate with the
	// API server are invalid
	ErrInvalidCertificates = errors.New("invalid CA certificates")
)

var ErrNoPermissionToAccessResource = errors.New("no permission to access resource")

var ErrResourceNotFound = errors.New("resource not found")

Types

type Adapter

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

func NewAdapter

func NewAdapter(config *Config, ingressAPIVersion string, ingressClassFilters []string, ingressDefaultSecurityGroup, ingressDefaultSSLPolicy, ingressDefaultLoadBalancerType, clusterLocalDomain string, disableInstrumentedHttpClient bool) (*Adapter, error)

NewAdapter creates an Adapter for Kubernetes using a given configuration.

func (*Adapter) GetConfigMap

func (a *Adapter) GetConfigMap(namespace, name string) (*ConfigMap, error)

GetConfigMap retrieves the ConfigMap with name from namespace.

func (*Adapter) IngressFiltersString

func (a *Adapter) IngressFiltersString() string

Get ingress class filters that are used to filter ingresses acted upon.

func (*Adapter) ListIngress

func (a *Adapter) ListIngress() ([]*Ingress, error)

ListIngress can be used to obtain the list of ingress resources for all namespaces filtered by class. It returns the Ingress business object, that for the controller does not matter to be routegroup or ingress..

func (*Adapter) ListResources

func (a *Adapter) ListResources() ([]*Ingress, error)

ListResources can be used to obtain the list of ingress and routegroup resources for all namespaces filtered by class. It returns the Ingress business object, that for the controller does not matter to be routegroup or ingress..

func (*Adapter) ListRoutegroups

func (a *Adapter) ListRoutegroups() ([]*Ingress, error)

ListRoutegroups can be used to obtain the list of Ingress resources for all namespaces filtered by class. It returns the Ingress business object, that for the controller does not matter to be routegroup or ingress.

func (*Adapter) UpdateIngressLoadBalancer

func (a *Adapter) UpdateIngressLoadBalancer(ingress *Ingress, loadBalancerDNSName string) error

UpdateIngressLoadBalancer can be used to update the loadBalancer object of an ingress resource. It will update the hostname property with the provided load balancer DNS name.

type Config

type Config struct {
	// BaseURL must be a URL to the base of the apiserver.
	BaseURL string

	// Server requires Bearer authentication. This client will not
	// attempt to use refresh tokens for an OAuth2 flow.
	// TODO: demonstrate an OAuth2 compatible client.
	BearerToken string

	// TLSClientConfig contains settings to enable transport layer
	// security
	TLSClientConfig

	// Server should be accessed without verifying the TLS
	// certificate. For testing only.
	Insecure bool

	// UserAgent is an optional field that specifies the caller of
	// this request.
	UserAgent string

	// The maximum length of time to wait before giving up on a
	// server request. A value of zero means no timeout.
	Timeout time.Duration
}

Config holds the common attributes that can be passed to a Kubernetes client on initialization.

Mostly copied from https://github.com/kubernetes/client-go/blob/master/rest/config.go

func InClusterConfig

func InClusterConfig() (*Config, error)

InClusterConfig creates a configuration for the Kubernetes Adapter that will communicate with the API server using TLS and authenticate with the cluster provide Bearer token. The environment should contain variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT. The CA certificate and Bearer token will also be taken from the Kubernetes environment.

func InsecureConfig

func InsecureConfig(apiServerBaseURL string) *Config

InsecureConfig creates a configuration for the Kubernetes Adapter that won't use any encryption or authentication mechanisms to communicate with the API Server. This should be used only for local development, as usually provided by the kubectl proxy

type ConfigMap

type ConfigMap struct {
	Namespace string
	Name      string
	Data      map[string]string
}

ConfigMap is the ingress-controller's representation of a Kubernetes ConfigMap

func (*ConfigMap) String

func (c *ConfigMap) String() string

String implements fmt.Stringer.

type Ingress

type Ingress struct {
	Shared           bool
	HTTP2            bool
	ClusterLocal     bool
	CertificateARN   string
	Namespace        string
	Name             string
	Hostname         string
	Scheme           string
	SecurityGroup    string
	SSLPolicy        string
	IPAddressType    string
	LoadBalancerType string
	WAFWebACLID      string
	Hostnames        []string
	// contains filtered or unexported fields
}

Ingress is the ingress-controller's business object. It is used to store Kubernetes ingress and routegroup resources.

func (*Ingress) String

func (i *Ingress) String() string

String returns a string representation of the Ingress instance containing the namespace and the resource name.

type ResourceLocation

type ResourceLocation struct {
	Name      string
	Namespace string
}

ResourceLocation defines the location of Kubernetes resource in a particular namespace.

func ParseResourceLocation

func ParseResourceLocation(s string) (*ResourceLocation, error)

ParseResourceLocation parses a Kubernetes resource location from string. Returns an error if the string does not match the expected format of `namespace/name`.

func (*ResourceLocation) String

func (r *ResourceLocation) String() string

String implements fmt.Stringer.

type TLSClientConfig

type TLSClientConfig struct {
	// Trusted root certificates for server
	CAFile string
}

TLSClientConfig contains settings to enable transport layer security