github.com/fabianvf/ocp-release-operator-sdk@v0.0.0-20190426141702-57620ee2f090/README.md (about) 1 <img src="doc/images/operator_logo_sdk_color.svg" height="125px"></img> 2 3 [](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.10+. 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 First, checkout and install the operator-sdk CLI: 51 52 ```sh 53 $ mkdir -p $GOPATH/src/github.com/operator-framework 54 $ cd $GOPATH/src/github.com/operator-framework 55 $ git clone https://github.com/operator-framework/operator-sdk 56 $ cd operator-sdk 57 $ git checkout master 58 $ make dep 59 $ make install 60 ``` 61 62 Alternatively, if you are using [Homebrew][homebrew_tool], you can install the SDK CLI tool with the following command: 63 64 ```sh 65 $ brew install operator-sdk 66 ``` 67 68 Create and deploy an app-operator using the SDK CLI: 69 70 ```sh 71 # Create an app-operator project that defines the App CR. 72 $ mkdir -p $GOPATH/src/github.com/example-inc/ 73 # Create a new app-operator project 74 $ cd $GOPATH/src/github.com/example-inc/ 75 $ operator-sdk new app-operator 76 $ cd app-operator 77 78 # Add a new API for the custom resource AppService 79 $ operator-sdk add api --api-version=app.example.com/v1alpha1 --kind=AppService 80 81 # Add a new controller that watches for AppService 82 $ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService 83 84 # Build and push the app-operator image to a public registry such as quay.io 85 $ operator-sdk build quay.io/example/app-operator 86 $ docker push quay.io/example/app-operator 87 88 # Update the operator manifest to use the built image name (if you are performing these steps on OSX, see note below) 89 $ sed -i 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml 90 # On OSX use: 91 $ sed -i "" 's|REPLACE_IMAGE|quay.io/example/app-operator|g' deploy/operator.yaml 92 93 # Setup Service Account 94 $ kubectl create -f deploy/service_account.yaml 95 # Setup RBAC 96 $ kubectl create -f deploy/role.yaml 97 $ kubectl create -f deploy/role_binding.yaml 98 # Setup the CRD 99 $ kubectl create -f deploy/crds/app_v1alpha1_appservice_crd.yaml 100 # Deploy the app-operator 101 $ kubectl create -f deploy/operator.yaml 102 103 # Create an AppService CR 104 # The default controller will watch for AppService objects and create a pod for each CR 105 $ kubectl create -f deploy/crds/app_v1alpha1_appservice_cr.yaml 106 107 # Verify that a pod is created 108 $ kubectl get pod -l app=example-appservice 109 NAME READY STATUS RESTARTS AGE 110 example-appservice-pod 1/1 Running 0 1m 111 112 # Test the new Resource Type 113 $ kubectl describe appservice example-appservice 114 Name: example-appservice 115 Namespace: myproject 116 Labels: <none> 117 Annotations: <none> 118 API Version: app.example.com/v1alpha1 119 Kind: AppService 120 Metadata: 121 Cluster Name: 122 Creation Timestamp: 2018-12-17T21:18:43Z 123 Generation: 1 124 Resource Version: 248412 125 Self Link: /apis/app.example.com/v1alpha1/namespaces/myproject/appservices/example-appservice 126 UID: 554f301f-0241-11e9-b551-080027c7d133 127 Spec: 128 Size: 3 129 130 # Cleanup 131 $ kubectl delete -f deploy/crds/app_v1alpha1_appservice_cr.yaml 132 $ kubectl delete -f deploy/operator.yaml 133 $ kubectl delete -f deploy/role.yaml 134 $ kubectl delete -f deploy/role_binding.yaml 135 $ kubectl delete -f deploy/service_account.yaml 136 $ kubectl delete -f deploy/crds/app_v1alpha1_appservice_crd.yaml 137 ``` 138 ## Command Line Interface 139 140 To learn more about the SDK CLI, see the [SDK CLI Reference][sdk_cli_ref], or run `operator-sdk [command] -h`. 141 142 ## User Guides 143 144 To learn more about the writing an operator in Go, see the [user guide][guide]. 145 146 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. 147 148 ## Samples 149 150 To explore any operator samples built using the operator-sdk, see the [operator-sdk-samples][samples]. 151 152 ## Contributing 153 154 See [CONTRIBUTING][contrib] for details on submitting patches and the contribution workflow. 155 156 See the [proposal docs][proposals_docs] and issues for ongoing or planned work. 157 158 ## Reporting bugs 159 160 See [reporting bugs][bug_guide] for details about reporting any issues. 161 162 ## License 163 164 Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file for details. 165 166 [operator_link]: https://coreos.com/operators/ 167 [proposals_docs]: ./doc/proposals 168 [sdk_cli_ref]: ./doc/sdk-cli-reference.md 169 [guide]: ./doc/user-guide.md 170 [samples]: https://github.com/operator-framework/operator-sdk-samples 171 [of-home]: https://github.com/operator-framework 172 [of-blog]: https://coreos.com/blog/introducing-operator-framework 173 [contrib]: ./CONTRIBUTING.MD 174 [bug_guide]:./doc/dev/reporting_bugs.md 175 [license_file]:./LICENSE 176 [homebrew_tool]:https://brew.sh/ 177 [dep_tool]:https://golang.github.io/dep/docs/installation.html 178 [git_tool]:https://git-scm.com/downloads 179 [go_tool]:https://golang.org/dl/ 180 [docker_tool]:https://docs.docker.com/install/ 181 [kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ 182 [controller_runtime]: https://github.com/kubernetes-sigs/controller-runtime 183 [ansible_user_guide]:./doc/ansible/user-guide.md 184 [helm_user_guide]:./doc/helm/user-guide.md