operatorkit

README

operatorkit

Package operatorkit implements an opinionated framework for developing Kubernetes operators. It emerged as we extracted common functionality from a number of the operators we developed at Giant Swarm. The goal of this library is to provide a common structure for operator projects and to encapsulate best practices we learned while running operators in production.

Features

• CRD primitives to reliably create, watch and delete custom resources, as well as any Kubernetes runtime object.
• Managing finalizers on reconciled objects, making sure the code is executed at least once for each create/delete/update event.
• Guarantees to perform only one successful deletion event reconciliation to avoid unnecessary, possibly expensive interactions with third party systems.
• A deterministic informer implementation that guarantees the expected behaviour of configured resync periods and rate waits.
• Convenient client library helpers for simpler client creation.
• Resource wrapping to gain ability of composing resources like middlewares.
• Control flow primitives that allow cancellation and repetition of resource implementations.
• Independent packages. It is possible to use only certain parts of the library without being bound to all primitives it provides.
• Ability to change behaviour that is often specific to an organization like logging and error handling.
• Minimal set of dependencies.

Docs

• Control Flow Primitives
• File Structure
• Keeping Reconciliation Loops Short
• Managing CR Status Sub Resources
• Metrics Provider
• Troubleshooting
• Using Finalizers

Current Scope

The project is split into independent packages providing complementary functionality, making it easier to create production grade Kubernetes operators.

• client: provides a unified way of creating Kubernetes clients required by other packages.
• informer: provides well defined watching functionality for virtually any Kubernetes resource. The informer is deterministic, meaning it does not dispatch events twice after the resync period, which saves some cycles. It also features rate limiting of the event dispatching. It also provides functionality for decoding custom objects, reducing error prone boilerplate code.
• controller: provides a framework aiming to help writing reliable, robust controllers performing reconciliation loops. The heart of the controller is a Resource interface. The reconciliation primitive allows splitting the reconciliation into smaller parts. Controller manages finalizers on reconciled objects, making sure all resources are executed at least once during the deletion.

Projects using operatorkit

Giant Swarm operators using operatorkit.

Integration Tests

You can simply create a kind cluster to run the integration tests.

kind create cluster

The tests need to figure out how to connect to the Kubernetes cluster. Therefore we need to set an environment variable pointing to your local kube config.

export E2E_KUBECONFIG=~/.kube/config

Now you can easily run the integration tests.

go test -v -tags=k8srequired ./integration/test/<test-name>

Once you did your testing you may want to delete your local test cluster again.

kind delete cluster

Example

For the detailed implementation in the state of art, please see giantswarm/aws-operator.

Contact

• Mailing list: giantswarm
• IRC: #giantswarm on freenode.org
• Bugs: issues

Contributing & Reporting Bugs

See CONTRIBUTING for details on submitting patches, the contribution workflow as well as reporting bugs.

License

operatorkit is under the Apache 2.0 license. See the LICENSE file for details.