client

package
v0.1.11 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2019 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package client contains functionality for interacting with Kubernetes API servers.

Clients

Clients are split into two interfaces -- Readers and Writers. Readers get and list, while writers create, update, and delete.

The New function can be used to create a new client that talks directly to the API server.

A common pattern in Kubernetes to read from a cache and write to the API server. This pattern is covered by the DelegatingClient type, which can be used to have a client whose Reader is different from the Writer.

Options

Many client operations in Kubernetes support options. These options are represented as variadic arguments at the end of a given method call. For instance, to use a label selector on list, you can call 

err := someReader.List(context.Background(), &podList, client.MatchingLabels(someLabelMap))

Indexing

Indexes may be added to caches using a FieldIndexer. This allows you to easily and efficiently look up objects with certain properties. You can then make use of the index by specifying a field selector on calls to List on the Reader corresponding to the given Cache.

For instance, a Secret controller might have an index on the `.spec.volumes.secret.secretName` field in Pod objects, so that it could easily look up all pods that reference a given secret.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client interface {
	Reader
	Writer
	StatusClient
}

Client knows how to perform CRUD operations on Kubernetes objects.

Example (Create)

This example shows how to use the client with typed and unstrucurted objects to create objects. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var c client.Client

func main() {
	// Using a typed object.
	pod := &corev1.Pod{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: "namespace",
			Name:      "name",
		},
		Spec: corev1.PodSpec{
			Containers: []corev1.Container{
				corev1.Container{
					Image: "nginx",
					Name:  "nginx",
				},
			},
		},
	}
	// c is a created client.
	_ = c.Create(context.Background(), pod)

	// Using a unstructured object.
	u := &unstructured.Unstructured{}
	u.Object = map[string]interface{}{
		"name":      "name",
		"namespace": "namespace",
		"spec": map[string]interface{}{
			"replicas": 2,
			"selector": map[string]interface{}{
				"matchLabels": map[string]interface{}{
					"foo": "bar",
				},
			},
			"template": map[string]interface{}{
				"labels": map[string]interface{}{
					"foo": "bar",
				},
				"spec": map[string]interface{}{
					"containers": []map[string]interface{}{
						{
							"name":  "nginx",
							"image": "nginx",
						},
					},
				},
			},
		},
	}
	u.SetGroupVersionKind(schema.GroupVersionKind{
		Group:   "apps",
		Kind:    "Deployment",
		Version: "v1",
	})
	_ = c.Create(context.Background(), u)
}

Output:
Example (Delete)

This example shows how to use the client with typed and unstrucurted objects to delete objects. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var c client.Client

func main() {
	// Using a typed object.
	pod := &corev1.Pod{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: "namespace",
			Name:      "name",
		},
	}
	// c is a created client.
	_ = c.Delete(context.Background(), pod)

	// Using a unstructured object.
	u := &unstructured.Unstructured{}
	u.Object = map[string]interface{}{
		"name":      "name",
		"namespace": "namespace",
	}
	u.SetGroupVersionKind(schema.GroupVersionKind{
		Group:   "apps",
		Kind:    "Deployment",
		Version: "v1",
	})
	_ = c.Delete(context.Background(), u)
}

Output:
Example (Get)

This example shows how to use the client with typed and unstructured objects to retrieve a objects. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var c client.Client

func main() {
	// Using a typed object.
	pod := &corev1.Pod{}
	// c is a created client.
	_ = c.Get(context.Background(), client.ObjectKey{
		Namespace: "namespace",
		Name:      "name",
	}, pod)

	// Using a unstructured object.
	u := &unstructured.Unstructured{}
	u.SetGroupVersionKind(schema.GroupVersionKind{
		Group:   "apps",
		Kind:    "Deployment",
		Version: "v1",
	})
	_ = c.Get(context.Background(), client.ObjectKey{
		Namespace: "namespace",
		Name:      "name",
	}, u)
}

Output:
Example (List)

This example shows how to use the client with typed and unstrucurted objects to list objects. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var c client.Client

func main() {
	// Using a typed object.
	pod := &corev1.PodList{}
	// c is a created client.
	_ = c.List(context.Background(), pod)

	// Using a unstructured object.
	u := &unstructured.UnstructuredList{}
	u.SetGroupVersionKind(schema.GroupVersionKind{
		Group:   "apps",
		Kind:    "DeploymentList",
		Version: "v1",
	})
	_ = c.List(context.Background(), u)
}

Output:
Example (Update)

This example shows how to use the client with typed and unstrucurted objects to update objects. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var c client.Client

func main() {
	// Using a typed object.
	pod := &corev1.Pod{}
	// c is a created client.
	_ = c.Get(context.Background(), client.ObjectKey{
		Namespace: "namespace",
		Name:      "name",
	}, pod)
	pod.SetFinalizers(append(pod.GetFinalizers(), "new-finalizer"))
	_ = c.Update(context.Background(), pod)

	// Using a unstructured object.
	u := &unstructured.Unstructured{}
	u.SetGroupVersionKind(schema.GroupVersionKind{
		Group:   "apps",
		Kind:    "Deployment",
		Version: "v1",
	})
	_ = c.Get(context.Background(), client.ObjectKey{
		Namespace: "namespace",
		Name:      "name",
	}, u)
	u.SetFinalizers(append(u.GetFinalizers(), "new-finalizer"))
	_ = c.Update(context.Background(), u)
}

Output:

func New 

func New(config *rest.Config, options Options) (Client, error)

New returns a new Client using the provided config and Options. The returned client reads *and* writes directly from the server (it doesn't use object caches). It understands how to work with normal types (both custom resources and aggregated/built-in resources), as well as unstructured types.

In the case of normal types, the scheme will be used to look up the corresponding group, version, and kind for the given type. In the case of unstrctured types, the group, version, and kind will be extracted from the corresponding fields on the object.

Example 
package main

import (
	"context"
	"fmt"
	"os"

	corev1 "k8s.io/api/core/v1"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/client/config"
)

func main() {
	cl, err := client.New(config.GetConfigOrDie(), client.Options{})
	if err != nil {
		fmt.Println("failed to create client")
		os.Exit(1)
	}

	podList := &corev1.PodList{}

	err = cl.List(context.Background(), podList, client.InNamespace("default"))
	if err != nil {
		fmt.Printf("failed to list pods in namespace default: %v\n", err)
		os.Exit(1)
	}
}

Output:

type DelegatingClient 

type DelegatingClient struct {
	Reader
	Writer
	StatusClient
}

DelegatingClient forms a Client by composing separate reader, writer and statusclient interfaces. This way, you can have an Client that reads from a cache and writes to the API server.

type DelegatingReader added in v0.1.4 

type DelegatingReader struct {
	CacheReader  Reader
	ClientReader Reader
}

DelegatingReader forms a Reader that will cause Get and List requests for unstructured types to use the ClientReader while requests for any other type of object with use the CacheReader. This avoids accidentally caching the entire cluster in the common case of loading arbitrary unstructured objects (e.g. from OwnerReferences).

func (*DelegatingReader) Get added in v0.1.4 

func (d *DelegatingReader) Get(ctx context.Context, key ObjectKey, obj runtime.Object) error

Get retrieves an obj for a given object key from the Kubernetes Cluster.

func (*DelegatingReader) List added in v0.1.4 

func (d *DelegatingReader) List(ctx context.Context, list runtime.Object, opts ...ListOptionFunc) error

List retrieves list of objects for a given namespace and list options.

type DeleteOptionFunc added in v0.1.3 

type DeleteOptionFunc func(*DeleteOptions)

DeleteOptionFunc is a function that mutates a DeleteOptions struct. It implements the functional options pattern. See https://github.com/tmrts/go-patterns/blob/master/idiom/functional-options.md.

func GracePeriodSeconds added in v0.1.3 

func GracePeriodSeconds(gp int64) DeleteOptionFunc

GracePeriodSeconds is a functional option that sets the GracePeriodSeconds field of a DeleteOptions struct.

func Preconditions added in v0.1.3 

func Preconditions(p *metav1.Preconditions) DeleteOptionFunc

Preconditions is a functional option that sets the Preconditions field of a DeleteOptions struct.

func PropagationPolicy added in v0.1.3 

func PropagationPolicy(p metav1.DeletionPropagation) DeleteOptionFunc

PropagationPolicy is a functional option that sets the PropagationPolicy field of a DeleteOptions struct.

type DeleteOptions added in v0.1.3 

type DeleteOptions struct {
	// GracePeriodSeconds is the duration in seconds before the object should be
	// deleted. Value must be non-negative integer. The value zero indicates
	// delete immediately. If this value is nil, the default grace period for the
	// specified type will be used.
	GracePeriodSeconds *int64

	// Preconditions must be fulfilled before a deletion is carried out. If not
	// possible, a 409 Conflict status will be returned.
	Preconditions *metav1.Preconditions

	// PropagationPolicy determined whether and how garbage collection will be
	// performed. Either this field or OrphanDependents may be set, but not both.
	// The default policy is decided by the existing finalizer set in the
	// metadata.finalizers and the resource-specific default policy.
	// Acceptable values are: 'Orphan' - orphan the dependents; 'Background' -
	// allow the garbage collector to delete the dependents in the background;
	// 'Foreground' - a cascading policy that deletes all dependents in the
	// foreground.
	PropagationPolicy *metav1.DeletionPropagation

	// Raw represents raw DeleteOptions, as passed to the API server.
	Raw *metav1.DeleteOptions
}

DeleteOptions contains options for delete requests. It's generally a subset of metav1.DeleteOptions.

func (*DeleteOptions) ApplyOptions added in v0.1.3 

func (o *DeleteOptions) ApplyOptions(optFuncs []DeleteOptionFunc) *DeleteOptions

ApplyOptions executes the given DeleteOptionFuncs and returns the mutated DeleteOptions.

func (*DeleteOptions) AsDeleteOptions added in v0.1.3 

func (o *DeleteOptions) AsDeleteOptions() *metav1.DeleteOptions

AsDeleteOptions returns these options as a metav1.DeleteOptions. This may mutate the Raw field.

type FieldIndexer 

type FieldIndexer interface {
	// IndexFields adds an index with the given field name on the given object type
	// by using the given function to extract the value for that field.  If you want
	// compatibility with the Kubernetes API server, only return one key, and only use
	// fields that the API server supports.  Otherwise, you can return multiple keys,
	// and "equality" in the field selector means that at least one key matches the value.
	// The FieldIndexer will automatically take care of indexing over namespace
	// and supporting efficient all-namespace queries.
	IndexField(obj runtime.Object, field string, extractValue IndexerFunc) error
}

FieldIndexer knows how to index over a particular "field" such that it can later be used by a field selector.

Example (SecretName)

This example shows how to set up and consume a field selector over a pod's volumes' secretName field. 

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var (
	c           client.Client
	someIndexer client.FieldIndexer
)

func main() {
	// someIndexer is a FieldIndexer over a Cache
	_ = someIndexer.IndexField(&corev1.Pod{}, "spec.volumes.secret.secretName", func(o runtime.Object) []string {
		var res []string
		for _, vol := range o.(*corev1.Pod).Spec.Volumes {
			if vol.Secret == nil {
				continue
			}
			// just return the raw field value -- the indexer will take care of dealing with namespaces for us
			res = append(res, vol.Secret.SecretName)
		}
		return res
	})

	// elsewhere (e.g. in your reconciler)
	mySecretName := "someSecret" // derived from the reconcile.Request, for instance
	var podsWithSecrets corev1.PodList
	_ = c.List(context.Background(), &podsWithSecrets, client.MatchingField("spec.volumes.secret.secretName", mySecretName))
}

Output:

type IndexerFunc 

type IndexerFunc func(runtime.Object) []string

IndexerFunc knows how to take an object and turn it into a series of non-namespaced keys. Namespaced objects are automatically given namespaced and non-spaced variants, so keys do not need to include namespace.

type ListOptionFunc added in v0.1.11 

type ListOptionFunc func(*ListOptions)

ListOptionFunc is a function that mutates a ListOptions struct. It implements the functional options pattern. See https://github.com/tmrts/go-patterns/blob/master/idiom/functional-options.md.

func InNamespace 

func InNamespace(ns string) ListOptionFunc

InNamespace is a functional option that sets the Namespace field of a ListOptions struct.

func MatchingField 

func MatchingField(name, val string) ListOptionFunc

MatchingField is a functional option that sets the FieldSelector field of a ListOptions struct.

func MatchingLabels 

func MatchingLabels(lbls map[string]string) ListOptionFunc

MatchingLabels is a functional option that sets the LabelSelector field of a ListOptions struct.

func UseListOptions added in v0.1.11 

func UseListOptions(newOpts *ListOptions) ListOptionFunc

UseListOptions is a functional option that replaces the fields of a ListOptions struct with those of a different ListOptions struct.

Example: cl.List(ctx, list, client.UseListOptions(lo.InNamespace(ns).MatchingLabels(labels)))

type ListOptions 

type ListOptions struct {
	// LabelSelector filters results by label.  Use SetLabelSelector to
	// set from raw string form.
	LabelSelector labels.Selector
	// FieldSelector filters results by a particular field.  In order
	// to use this with cache-based implementations, restrict usage to
	// a single field-value pair that's been added to the indexers.
	FieldSelector fields.Selector

	// Namespace represents the namespace to list for, or empty for
	// non-namespaced objects, or to list across all namespaces.
	Namespace string

	// Raw represents raw ListOptions, as passed to the API server.  Note
	// that these may not be respected by all implementations of interface,
	// and the LabelSelector and FieldSelector fields are ignored.
	Raw *metav1.ListOptions
}

ListOptions contains options for limiting or filtering results. It's generally a subset of metav1.ListOptions, with support for pre-parsed selectors (since generally, selectors will be executed against the cache).

func (*ListOptions) ApplyOptions added in v0.1.11 

func (o *ListOptions) ApplyOptions(optFuncs []ListOptionFunc) *ListOptions

ApplyOptions executes the given ListOptionFuncs and returns the mutated ListOptions.

func (*ListOptions) AsListOptions 

func (o *ListOptions) AsListOptions() *metav1.ListOptions

AsListOptions returns these options as a flattened metav1.ListOptions. This may mutate the Raw field.

func (*ListOptions) InNamespace 

func (o *ListOptions) InNamespace(ns string) *ListOptions

InNamespace is a convenience function that sets the namespace, and then returns the options. It mutates the list options.

func (*ListOptions) MatchingField 

func (o *ListOptions) MatchingField(name, val string) *ListOptions

MatchingField is a convenience function that sets the field selector to match the given field, and then returns the options. It mutates the list options.

func (*ListOptions) MatchingLabels 

func (o *ListOptions) MatchingLabels(lbls map[string]string) *ListOptions

MatchingLabels is a convenience function that sets the label selector to match the given labels, and then returns the options. It mutates the list options.

func (*ListOptions) SetFieldSelector 

func (o *ListOptions) SetFieldSelector(selRaw string) error

SetFieldSelector sets this the label selector of these options from a string form of the selector.

func (*ListOptions) SetLabelSelector 

func (o *ListOptions) SetLabelSelector(selRaw string) error

SetLabelSelector sets this the label selector of these options from a string form of the selector.

type ObjectKey 

type ObjectKey = types.NamespacedName

ObjectKey identifies a Kubernetes Object.

func ObjectKeyFromObject added in v0.1.3 

func ObjectKeyFromObject(obj runtime.Object) (ObjectKey, error)

ObjectKeyFromObject returns the ObjectKey given a runtime.Object

type Options 

type Options struct {
	// Scheme, if provided, will be used to map go structs to GroupVersionKinds
	Scheme *runtime.Scheme

	// Mapper, if provided, will be used to map GroupVersionKinds to Resources
	Mapper meta.RESTMapper
}

Options are creation options for a Client

type Reader 

type Reader interface {
	// Get retrieves an obj for the given object key from the Kubernetes Cluster.
	// obj must be a struct pointer so that obj can be updated with the response
	// returned by the Server.
	Get(ctx context.Context, key ObjectKey, obj runtime.Object) error

	// List retrieves list of objects for a given namespace and list options. On a
	// successful call, Items field in the list will be populated with the
	// result returned from the server.
	List(ctx context.Context, list runtime.Object, opts ...ListOptionFunc) error
}

Reader knows how to read and list Kubernetes objects.

type StatusClient 

type StatusClient interface {
	Status() StatusWriter
}

StatusClient knows how to create a client which can update status subresource for kubernetes objects.

type StatusWriter 

type StatusWriter interface {
	// Update updates the fields corresponding to the status subresource for the
	// given obj. obj must be a struct pointer so that obj can be updated
	// with the content returned by the Server.
	Update(ctx context.Context, obj runtime.Object) error
}

StatusWriter knows how to update status subresource of a Kubernetes object.

type Writer 

type Writer interface {
	// Create saves the object obj in the Kubernetes cluster.
	Create(ctx context.Context, obj runtime.Object) error

	// Delete deletes the given obj from Kubernetes cluster.
	Delete(ctx context.Context, obj runtime.Object, opts ...DeleteOptionFunc) error

	// Update updates the given obj in the Kubernetes cluster. obj must be a
	// struct pointer so that obj can be updated with the content returned by the Server.
	Update(ctx context.Context, obj runtime.Object) error
}

Writer knows how to create, delete, and update Kubernetes objects.

Source Files

View all Source files

Directories

Path Synopsis
Package apiutil contains utilities for working with raw Kubernetes API machinery, such as creating RESTMappers and raw REST clients, and extracting the GVK of an object.
 Package apiutil contains utilities for working with raw Kubernetes API machinery, such as creating RESTMappers and raw REST clients, and extracting the GVK of an object.
Package config contains libraries for initializing REST configs for talking to the Kubernetes API
 Package config contains libraries for initializing REST configs for talking to the Kubernetes API
Package fake provides a fake client for testing.
 Package fake provides a fake client for testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.