github.com/michaelhenkel/operator-sdk@v0.8.1/README.md (about) 1 <img src="doc/images/operator_logo_sdk_color.svg" height="125px"></img> 2 3 [![Build Status](https://travis-ci.org/operator-framework/operator-sdk.svg?branch=master)](https://travis-ci.org/operator-framework/operator-sdk) 4 5 ## Overview 6 7 This project is a component of the [Operator Framework][of-home], 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][of-blog]. 8 9 [Operators][operator_link] 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. 10 11 The Operator SDK is a framework that uses the [controller-runtime][controller_runtime] library to make writing operators easier by providing: 12 - High level APIs and abstractions to write the operational logic more intuitively 13 - Tools for scaffolding and code generation to bootstrap a new project fast 14 - Extensions to cover common operator use cases 15 16 ## Workflow 17 18 The SDK provides workflows to develop operators in Go, Ansible, or Helm. 19 20 The following workflow is for a new **Go** operator: 21 1. Create a new operator project using the SDK Command Line Interface(CLI) 22 2. Define new resource APIs by adding Custom Resource Definitions(CRD) 23 3. Define Controllers to watch and reconcile resources 24 4. Write the reconciling logic for your Controller using the SDK and controller-runtime APIs 25 5. Use the SDK CLI to build and generate the operator deployment manifests 26 27 The following workflow is for a new **Ansible** operator: 28 1. Create a new operator project using the SDK Command Line Interface(CLI) 29 2. Write the reconciling logic for your object using ansible playbooks and roles 30 3. Use the SDK CLI to build and generate the operator deployment manifests 31 4. Optionally add additional CRD's using the SDK CLI and repeat steps 2 and 3 32 33 The following workflow is for a new **Helm** operator: 34 1. Create a new operator project using the SDK Command Line Interface(CLI) 35 2. Create a new (or add your existing) Helm chart for use by the operator's reconciling logic 36 3. Use the SDK CLI to build and generate the operator deployment manifests 37 4. Optionally add additional CRD's using the SDK CLI and repeat steps 2 and 3 38 39 ## Prerequisites 40 41 - [dep][dep_tool] version v0.5.0+. 42 - [git][git_tool] 43 - [go][go_tool] version v1.12+. 44 - [docker][docker_tool] version 17.03+. 45 - [kubectl][kubectl_tool] version v1.11.3+. 46 - Access to a Kubernetes v1.11.3+ cluster. 47 48 ## Quick Start 49 50 ### Install the Operator SDK CLI 51 52 Follow the steps in the [installation guide][install_guide] to learn how to install the Operator SDK CLI tool. 53 54 ### Create and deploy an app-operator 55 56 ```sh 57 # Create an app-operator project that defines the App CR. 58 $ mkdir -p $GOPATH/src/github.com/example-inc/ 59 # Create a new app-operator project 60 $ cd $GOPATH/src/github.com/example-inc/ 61 $ export GO111MODULE=on 62 $ operator-sdk new app-operator 63 $ cd app-operator 64 65 # Add a new API for the custom resource AppService 66 $ operator-sdk add api --api-version=app.example.com/v1alpha1 --kind=AppService 67 68 # Add a new controller that watches for AppService 69 $ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService 70 71 # Build and push the app-operator image to a public registry such as quay.io 72 $ go mod vendor 73 $ operator-sdk build quay.io/example/app-operator 74 $ docker push quay.io/example/app-operator 75 76 # Update the operator manifest to use the built image name (if you are performing these steps on OSX, see note below) 77 $ sed -i 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml 78 # On OSX use: 79 $ sed -i "" 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml 80 81 # Setup Service Account 82 $ kubectl create -f deploy/service_account.yaml 83 # Setup RBAC 84 $ kubectl create -f deploy/role.yaml 85 $ kubectl create -f deploy/role_binding.yaml 86 # Setup the CRD 87 $ kubectl create -f deploy/crds/app_v1alpha1_appservice_crd.yaml 88 # Deploy the app-operator 89 $ kubectl create -f deploy/operator.yaml 90 91 # Create an AppService CR 92 # The default controller will watch for AppService objects and create a pod for each CR 93 $ kubectl create -f deploy/crds/app_v1alpha1_appservice_cr.yaml 94 95 # Verify that a pod is created 96 $ kubectl get pod -l app=example-appservice 97 NAME READY STATUS RESTARTS AGE 98 example-appservice-pod 1/1 Running 0 1m 99 100 # Test the new Resource Type 101 $ kubectl describe appservice example-appservice 102 Name: example-appservice 103 Namespace: myproject 104 Labels: <none> 105 Annotations: <none> 106 API Version: app.example.com/v1alpha1 107 Kind: AppService 108 Metadata: 109 Cluster Name: 110 Creation Timestamp: 2018-12-17T21:18:43Z 111 Generation: 1 112 Resource Version: 248412 113 Self Link: /apis/app.example.com/v1alpha1/namespaces/myproject/appservices/example-appservice 114 UID: 554f301f-0241-11e9-b551-080027c7d133 115 Spec: 116 Size: 3 117 118 # Cleanup 119 $ kubectl delete -f deploy/crds/app_v1alpha1_appservice_cr.yaml 120 $ kubectl delete -f deploy/operator.yaml 121 $ kubectl delete -f deploy/role.yaml 122 $ kubectl delete -f deploy/role_binding.yaml 123 $ kubectl delete -f deploy/service_account.yaml 124 $ kubectl delete -f deploy/crds/app_v1alpha1_appservice_crd.yaml 125 ``` 126 ## Command Line Interface 127 128 To learn more about the SDK CLI, see the [SDK CLI Reference][sdk_cli_ref], or run `operator-sdk [command] -h`. 129 130 ## User Guides 131 132 To learn more about the writing an operator in Go, see the [user guide][guide]. 133 134 The SDK also supports developing an operator using Ansible or Helm. See the [Ansible][ansible_user_guide] and [Helm][helm_user_guide] operator user guides. 135 136 ## Samples 137 138 To explore any operator samples built using the operator-sdk, see the [operator-sdk-samples][samples]. 139 140 ## Contributing 141 142 See [CONTRIBUTING][contrib] for details on submitting patches and the contribution workflow. 143 144 See the [proposal docs][proposals_docs] and issues for ongoing or planned work. 145 146 ## Reporting bugs 147 148 See [reporting bugs][bug_guide] for details about reporting any issues. 149 150 ## License 151 152 Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file for details. 153 154 [install_guide]: ./doc/user/install-operator-sdk.md 155 [operator_link]: https://coreos.com/operators/ 156 [proposals_docs]: ./doc/proposals 157 [sdk_cli_ref]: ./doc/sdk-cli-reference.md 158 [guide]: ./doc/user-guide.md 159 [samples]: https://github.com/operator-framework/operator-sdk-samples 160 [of-home]: https://github.com/operator-framework 161 [of-blog]: https://coreos.com/blog/introducing-operator-framework 162 [contrib]: ./CONTRIBUTING.MD 163 [bug_guide]:./doc/dev/reporting_bugs.md 164 [license_file]:./LICENSE 165 [dep_tool]:https://golang.github.io/dep/docs/installation.html 166 [git_tool]:https://git-scm.com/downloads 167 [go_tool]:https://golang.org/dl/ 168 [docker_tool]:https://docs.docker.com/install/ 169 [kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ 170 [controller_runtime]: https://github.com/kubernetes-sigs/controller-runtime 171 [ansible_user_guide]:./doc/ansible/user-guide.md 172 [helm_user_guide]:./doc/helm/user-guide.md