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