SDK for building Kubernetes applications. Provides high level APIs, useful abstractions, and project scaffolding.
Clone or download
madorn and hasbro17 doc/user-guide: Update 3rd Party Resources User-Guide Info (#761)
Document Core Kubernetes resources that are automatically registered and update 3rd Party Resource example to reflect a scheme that is not registered "out-of-the-box".
Latest commit 1ea16af Nov 19, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Use marker for markdown link verification (#708) Nov 5, 2018
commands/operator-sdk commands/.../new.go;pkg/scaffold: adding support for ClusterRole and … Nov 15, 2018
doc doc/user-guide: Update 3rd Party Resources User-Guide Info (#761) Nov 19, 2018
example/memcached-operator doc/dev/logging.md: discuss how to use logging in SDK operators Nov 14, 2018
hack hack/check_error_case.sh: check against Error/Fatal Nov 14, 2018
internal/util *: use logrus instead of std log Nov 14, 2018
pkg pkg/scaffold: fixing main printVersion (#752) Nov 16, 2018
test *: use logrus instead of std log Nov 14, 2018
version pkg/scaffold,version,changelog: bump to v0.1.1-git (#706) Nov 5, 2018
.gitignore pkg/ansible: fail early if we are unable to find role or playbook (#677) Oct 31, 2018
.travis.yml Use marker for markdown link verification (#708) Nov 5, 2018
CHANGELOG.md pkg/scaffold,version,changelog: bump to v0.1.1-git (#706) Nov 5, 2018
CONTRIBUTING.MD contributing.md: require documentation for new features Jun 25, 2018
Gopkg.lock Gopkg.lock: dep ensure Nov 14, 2018
Gopkg.toml Refactor file generation using abstractions (#581) Oct 16, 2018
LICENSE Initial commit Feb 7, 2018
MAINTAINERS MAINTAINERS: update MAINTAINERS file (#507) Sep 20, 2018
Makefile doc/release-versioning.md: document signing process for binaries Nov 2, 2018
README.md Fix sed issue on OSX (#699) Nov 8, 2018
bill-of-materials.json *: update import paths from coreos to operator-framework Apr 27, 2018
bill-of-materials.override.json pom: add bill-of-materials.override.json Mar 16, 2018
code-of-conduct.md operator-sdk: add code-of-conduct.md Apr 26, 2018
release.sh Release versioning (#684) Nov 1, 2018

README.md

Build Status

Project Status: alpha

The project is currently alpha which means that there are still new features and APIs planned that will be added in the future. Due to this breaking changes may still happen.

Note: The core APIs provided by the controller-runtime will most likely stay unchanged however the expectation is that any breaking changes should be relatively minor and easier to handle than the changes from SDK v0.0.7 to v0.1.0.

See the proposal docs and issues for ongoing or planned work.

Overview

This project is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. Read more in the introduction blog post.

Operators make it easy to manage complex stateful applications on top of Kubernetes. However writing an operator today can be difficult because of challenges such as using low level APIs, writing boilerplate, and a lack of modularity which leads to duplication.

The Operator SDK is a framework that uses the controller-runtime library to make writing operators easier by providing:

  • High level APIs and abstractions to write the operational logic more intuitively
  • Tools for scaffolding and code generation to bootstrap a new project fast
  • Extensions to cover common operator use cases

Workflow

The SDK provides workflows to develop operators in Go or Ansible.

The following workflow is for a new Go operator:

  1. Create a new operator project using the SDK Command Line Interface(CLI)
  2. Define new resource APIs by adding Custom Resource Definitions(CRD)
  3. Define Controllers to watch and reconcile resources
  4. Write the reconciling logic for your Controller using the SDK and controller-runtime APIs
  5. Use the SDK CLI to build and generate the operator deployment manifests

The following workflow is for a new Ansible operator:

  1. Create a new operator project using the SDK Command Line Interface(CLI)
  2. Write the reconciling logic for your object using ansible playbooks and roles
  3. Use the SDK CLI to build and generate the operator deployment manifests
  4. Optionally add additional CRD's using the SDK CLI and repeat steps 2 and 3

Prerequisites

  • dep version v0.5.0+.
  • git
  • go version v1.10+.
  • docker version 17.03+.
  • kubectl version v1.11.0+.
  • Access to a kubernetes v.1.11.0+ cluster.

Quick Start

First, checkout and install the operator-sdk CLI:

$ mkdir -p $GOPATH/src/github.com/operator-framework
$ cd $GOPATH/src/github.com/operator-framework
$ git clone https://github.com/operator-framework/operator-sdk
$ cd operator-sdk
$ git checkout master
$ make dep
$ make install

Create and deploy an app-operator using the SDK CLI:

# Create an app-operator project that defines the App CR.
$ mkdir -p $GOPATH/src/github.com/example-inc/
# Create a new app-operator project
$ cd $GOPATH/src/github.com/example-inc/
$ operator-sdk new app-operator
$ cd app-operator

# Add a new API for the custom resource AppService
$ operator-sdk add api --api-version=app.example.com/v1alpha1 --kind=AppService

# Add a new controller that watches for AppService
$ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService

# Build and push the app-operator image to a public registry such as quay.io
$ operator-sdk build quay.io/example/app-operator
$ docker push quay.io/example/app-operator

# Update the operator manifest to use the built image name (if you are performing these steps on OSX, see note below)
$ sed -i 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml
# On OSX use:
$ sed -i "" 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml

# Setup Service Account
$ kubectl create -f deploy/service_account.yaml
# Setup RBAC
$ kubectl create -f deploy/role.yaml
$ kubectl create -f deploy/role_binding.yaml
# Setup the CRD
$ kubectl create -f deploy/crds/app_v1alpha1_appservice_crd.yaml
# Deploy the app-operator
$ kubectl create -f deploy/operator.yaml

# Create an AppService CR
# The default controller will watch for AppService objects and create a pod for each CR
$ kubectl create -f deploy/crds/app_v1alpha1_appservice_cr.yaml

# Verify that a pod is created
$ kubectl get pod -l app=example-appservice
NAME                     READY     STATUS    RESTARTS   AGE
example-appservice-pod   1/1       Running   0          1m

# Cleanup
$ kubectl delete -f deploy/crds/app_v1alpha1_appservice_cr.yaml
$ kubectl delete -f deploy/operator.yaml
$ kubectl delete -f deploy/role.yaml
$ kubectl delete -f deploy/role_binding.yaml
$ kubectl delete -f deploy/service_account.yaml
$ kubectl delete -f deploy/crds/app_v1alpha1_appservice_crd.yaml

User Guides

To learn more about the writing an operator in Go, see the user guide.

The SDK also supports developing an operator using Ansible. See the Ansible operator user guide.

Samples

To explore any operator samples built using the operator-sdk, see the operator-sdk-samples.

Contributing

See CONTRIBUTING for details on submitting patches and the contribution workflow.

Reporting bugs

See reporting bugs for details about reporting any issues.

License

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