operatorkit

README

Kubernetes Operator Kit

A Kubernetes Operator is a controller for custom resources. The purpose of the operator kit is to provide a common library for implementing operators.

The library originated from the Rook operator. Much more thought needs to be put into API design, but at least provides the basis for the library with working code. With enough interest, this could become a Kubernetes incubator project.

Features

The operator kit is a simple collection of features that will be useful for operators.

• TPR handling: creating, retrieving, and watching TPRs
• Timing: helpers to timeout when taking too long or retry when when working with kubernetes resources

Roadmap

The operator kit is still in its infancy and needs plenty of work before it is considered stable.

• Community collaboration on the requirements and design
• Add support for CustomResourceDefinitions (CRDs) with Kubernetes 1.7
• Leader election for HA
• Tests

The conversation has been started here.

Sample Code

To help you get started, a simple operator with a single custom resource is provided here.

Contributing

Contributions are welcome! See Contributing to get started.

Report a Bug

For filing bugs, suggesting improvements, or requesting new features, help out by opening an issue.

Licensing

The operator kit is under the Apache 2.0 license. The appropriate license information can be found in the headers of the source files.

Documentation

Overview

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code below came from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code below came from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code was modified from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code below came from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code below came from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Package kit for Kubernetes operators

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some of the code was modified from https://github.com/coreos/etcd-operator which also has the apache 2.0 license.

Index

• Constants
• Variables
• func CreateCustomResource(context KubeContext, resource CustomResource) error
• func CreateCustomResources(context KubeContext, resources []CustomResource) error
• func GetRawList(clientset kubernetes.Interface, resource CustomResource) ([]byte, error)
• func GetRawListNamespaced(clientset kubernetes.Interface, resource CustomResource, namespace string) ([]byte, error)
• func NewHTTPClient(group string) (*rest.RESTClient, error)
• func Retry(context KubeContext, f ConditionFunc) error
• type ConditionFunc
• type CustomResource
• type KubeContext
• type RawEvent
• type ResourceWatcher
  • func NewWatcher(context KubeContext, resource CustomResource, namespace, watchVersion string, ...) *ResourceWatcher
  • func (w *ResourceWatcher) Watch() error

Constants

const (
	// V1Alpha1 version for kubernetes resources
	V1Alpha1 = "v1alpha1"

	// V1Beta1 version for kubernetes resources
	V1Beta1 = "v1beta1"

	// V1 version for kubernetes resources
	V1 = "v1"
)

Variables

var (
	// ErrVersionOutdated indicates that the custom resource is outdated and needs to be refreshed
	ErrVersionOutdated = errors.New("requested version is outdated in apiserver")
)

Functions

func CreateCustomResource

func CreateCustomResource(context KubeContext, resource CustomResource) error

CreateCustomResource creates a single custom resource, but does not wait for it to initialize

func CreateCustomResources

func CreateCustomResources(context KubeContext, resources []CustomResource) error

CreateCustomResources creates the given custom resources and waits for them to initialize

func GetRawList

func GetRawList(clientset kubernetes.Interface, resource CustomResource) ([]byte, error)

GetRawList retrieves a list of custom resources of the given type across all namespaces

func GetRawListNamespaced

func GetRawListNamespaced(clientset kubernetes.Interface, resource CustomResource, namespace string) ([]byte, error)

GetRawListNamespaced retrieves a list custom resources of the given type in a specific namespace

func NewHTTPClient

func NewHTTPClient(group string) (*rest.RESTClient, error)

NewHTTPClient creates a new http client for the operator to manage the Kubernetes cluster

func Retry

func Retry(context KubeContext, f ConditionFunc) error

Retry retries f every interval until after maxRetries. The interval won't be affected by how long f takes. For example, if interval is 3s, f takes 1s, another f will be called 2s later. However, if f takes longer than interval, it will be delayed.

Types

type ConditionFunc

type ConditionFunc func() (bool, error)

ConditionFunc returns true if a retry condition has been satisfied. If the condition returns false, the retry will try again.

type CustomResource

type CustomResource struct {
	// Name of the custom resource
	Name string

	// Group the custom resource belongs to
	Group string

	// Version which should be defined in a const above
	Version string

	// Description that is human readable
	Description string
}

CustomResource is for creating a Kubernetes TPR/CRD

type KubeContext

type KubeContext struct {
	// Clientset is a connection to the core kubernetes API
	Clientset kubernetes.Interface

	// RetryDelay is the number of seconds to delay between retrying of kubernetes API calls.
	// Only used by the Retry function.
	RetryDelay int

	// MaxRetries is the number of times that an operation will be attempted by the Retry function.
	MaxRetries int

	// The host where the Kubernetes master is found.
	MasterHost string

	// An http connection to the Kubernetes API
	KubeHTTPCli *http.Client
}

KubeContext provides the context for connecting to Kubernetes APIs

type RawEvent

type RawEvent struct {
	Type   kwatch.EventType
	Object json.RawMessage
}

RawEvent is the raw json message retrieved from the TPR/CRD update

type ResourceWatcher

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

ResourceWatcher watches a custom resource for desired state

func NewWatcher

func NewWatcher(context KubeContext, resource CustomResource, namespace, watchVersion string,
	callback func(event *RawEvent) error,
	checkStaleCache func() (string, error)) *ResourceWatcher

NewWatcher creates an instance of a custom resource watcher for the given resource

func (*ResourceWatcher) Watch

func (w *ResourceWatcher) Watch() error

Watch begins watching the custom resource (TPR/CRD). The call will block until an error is raised during the watch. When the watch has detected a create, update, or delete event, the raw event will be passed to the caller in the callback. After the callback returns, the watch loop will continue for the next event. If the callback returns an error, the error will be logged but will not abort the event loop.