github.com/dmvolod/operator-sdk@v0.8.2/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