Overview ▹

Overview ▾

The kates package is a library for writing kubernetes extensions. The library provides a number of capabilities:

Consistent bootstrap of multiple resources
Graceful Load Shedding via Coalesced Events
Read/write coherence
Grouping
Works well with typed (e.g. corev1.Pod) and untyped (e.g. map[string]interface{}) representations of k8s resources.

It does not provide codegen or admissions controllers, for those we should use kubebuilder.

Comparison to other libraries:

higher level, simpler, and more idiomatic than client-go
lower level (and more flexible) than operator-sdk or kubebuilder

Constructing a Client

The primary entrypoint for the kates library is the Client type. A Client is constructed by passing in the ClientConfig struct with a path to a kubeconfig file:

client, err := NewClient(ClientConfig{Kubeconfig: "path/to/kubeconfig"}) // or NewClient(ClientConfig{}) for defaults

Creating, Modifying, and Deleting Resources

A client can be used to Create, Update, and/or Delete any kubernetes resource. Each of the "CRUD" methods will, upon success, store an updated copy of the resource into the object referenced by the last argument. This will typically be different than the value you supplied if e.g. the server defaults fields, updates the resource version, assigns UIDs, etc.

var result kates.Pod
err = client.Create(ctx, &kates.Pod{...}, &result)
err = client.Update(ctx, result, &result)
err = client.UpdateStatus(ctx, result, &result)
err = client.Delete(ctx, result, &result)

You can pass both typed and untyped values into the APIs. The only requirement is that the values you pass will json.Marshal to and json.Unmarshal from something that looks like a kubernetes resource:

pod := kates.Pod{...}
err := client.Create(ctx, &pod, &pod)
// -or-
pod := map[string]interface{}{"kind": "Pod", ...}
err := client.Create(ctx, &pod, &pod)

Watching Resources

The client can be used to watch sets of multiple related resources. This is accomplished via the Accumulator type. An accumulator tracks events coming from the API server for the indicated resources, and merges those events with any locally initiated changes made via the client in order to maintain a snapshot that is coherent.

You can construct an Accumulator by invoking the Client's Watch method:

accumulator = client.Watch(ctx,
                           Query{Name: "Services", Kind: "svc"},
                           Query{Name: "Deployments", Kind: "deploy"})

The Accumulator will bootstrap a complete list of each supplied Query, and then provide continuing notifications if any of the resources change. Notifications that the initial bootstrap is complete as well as notifications of any subsequent changes are indicated by sending an empty struct down the Accumulator.Changed() channel:

<-accumulator.Changed() // Wait until all Queries have been initialized.

The Accumulator provides access to the values it tracks via the Accumulator.Update(&snapshot) method. The Update() method expects a pointer to a snapshot that is defined by the caller. The caller must supply a pointer to a struct with fields that match the names of the Query structs used to create the Accumulator. The types of the snapshot fields are free to be anything that will json.Unmarshal from a slice of kubernetes resources:

// initialize an empty snapshot
snapshot := struct {
    Services    []*kates.Service
    Deployments []*kates.Deployment
}{}

accumulator.Update(&snapshot)

The first call to update will populate the snapshot with the bootstrapped values. At this point any startup logic can be performed with confidence that the snapshot represents a complete and recent view of cluster state:

// perform any startup logic
...

The same APIs can then be used to watch for and reconcile subsequent changes:

// reconcile ongoing changes
for {
    select {
        case <-accumulator.Changed():
            wasChanged = accumulator.Update(&snapshot)
            if wasChanged {
                reconcile(snapshot)
            }
        case <-ctx.Done():
            break
    }
}

The Accumulator will provide read/write coherence for any changes made using the client from which the Accumulator was created. This means that any snapshot produced by the Accumulator is guaranteed to include all the Create, Update, UpdateStatus, and/or Delete operations that were performed using the client. (The underlying client-go CRUD and Watch operations do not provide this guarantee, so a straighforward reconcile operation will often end up creating duplicate objects and/or performing updates on stale versions.)

Event Coalescing for Graceful Load Shedding

The Accumulator automatically coalesces events behind the scenes in order to facilitate graceful load shedding for situations where the reconcile operation takes a long time relative to the number of incoming events. This allows the Accumulator.Update(&snapshot) method to provide a guarantee that when it returns the snapshot will contain the most recent view of cluster state regardless of how slowly and infrequently we read from the Accumulator.Changed() channel:

snapshot := Snapshot{}
for {
    <-accumulator.Changed()
    wasChanged := accumulator.Update(&snapshot) // Guaranteed to return the most recent view of cluster state.
    if wasChanged {
        slowReconcile(&snapshot)
    }
}

Name	Synopsis
..
k8s_resource_types

Package kates

Overview ▹

Overview ▾

Constructing a Client

Creating, Modifying, and Deleting Resources

Watching Resources

Event Coalescing for Graceful Load Shedding

Index ▹

Index ▾

Package files

Constants

Variables

func ConvertObject ¶

func HasOwnerReference ¶

func InCluster ¶

func MergeUpdate ¶

func NewClientFactory ¶

func NewRESTMapper ¶

func SetOwnerReferences ¶

type APIResource ¶

type Accumulator ¶

func (*Accumulator) Changed ¶

func (*Accumulator) FilteredUpdate ¶

func (*Accumulator) Listen ¶

func (*Accumulator) Update ¶

func (*Accumulator) UpdateWithDeltas ¶

type Client ¶

func NewClient ¶

func NewClientFromConfigFlags ¶

func (*Client) Create ¶

func (*Client) Delete ¶

func (*Client) DynamicInterface ¶

func (*Client) Get ¶

func (*Client) InvalidateCache ¶

func (*Client) List ¶

func (*Client) MaxAccumulatorInterval ¶

func (*Client) Patch ¶

func (*Client) PodLogs ¶

func (*Client) ServerPreferredResources ¶

func (*Client) ServerResources ¶

func (*Client) ServerVersion ¶

func (*Client) Update ¶

func (*Client) UpdateStatus ¶

func (*Client) Upsert ¶

func (*Client) WaitFor ¶

func (*Client) Watch ¶

type ClientConfig ¶

type ClusterRole ¶

type ClusterRoleBinding ¶

type ConfigFlags ¶

type ConfigMap ¶

type Container ¶

type ContainerMetrics ¶

type CreateOptions ¶

type CustomResourceDefinition ¶

type DeleteOptions ¶

type Delta ¶

func NewDelta ¶

func NewDeltaFromObject ¶

type DeltaType ¶

func (DeltaType) MarshalJSON ¶

func (*DeltaType) UnmarshalJSON ¶

type Deployment ¶

type EndpointAddress ¶

type EndpointPort ¶

type EndpointSubset ¶

type Endpoints ¶

type EnvVar ¶

type Event ¶

type GetOptions ¶

type IntOrString ¶

type LabelSelector ¶

type LabelSet ¶

type ListOptions ¶

type LocalObjectReference ¶

type LogEvent ¶

type Namespace ¶

type Node ¶

type NodeMetrics ¶

type Object ¶