Skip to content
This repository was archived by the owner on Sep 21, 2020. It is now read-only.

Fix OLM Steps for Getting Started #57

Merged
merged 3 commits into from
Nov 5, 2019
Merged

Fix OLM Steps for Getting Started #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de70e62
update OLM steps to help users
camilamacedo86 Oct 27, 2019
2e7c789
Update README.md
camilamacedo86 Nov 1, 2019
dd2345a
Update README.md
camilamacedo86 Nov 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 27 additions & 93 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
# Getting Started

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -->

- [Overview](#overview)
- [Build an operator using the Operator SDK](#build-an-operator-using-the-operator-sdk)
- [Create a new project](#create-a-new-project)
Expand All @@ -22,13 +18,10 @@
- [Reference implementation](#reference-implementation)
- [Manage the operator using the Operator Lifecycle Manager](#manage-the-operator-using-the-operator-lifecycle-manager)
- [Generate an operator manifest](#generate-an-operator-manifest)
- [Deploy the Operator](#deploy-the-operator)
- [Create an application instance](#create-an-application-instance)
- [Update an application](#update-an-application)
- [Testing locally](#testing-locally)
- [Promoting operator standards](#promoting-operator-standards)
- [Conclusion](#conclusion)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Overview

The [Operator Framework][org_operator_framework] ([intro blog post][site_blog_post]) is an open source toolkit to manage Kubernetes native applications, called operators, in an effective, automated, and scalable way. Operators take advantage of Kubernetes's extensibility to deliver the automation advantages of cloud services like provisioning, scaling, and backup/restore while being able to run anywhere that Kubernetes can run.
Expand Down Expand Up @@ -416,107 +409,42 @@ The above walkthrough follows the actual implementation process used to produce

## Manage the operator using the Operator Lifecycle Manager

> NOTE: This section of the Getting Started Guide is out-of-date.
> We're working on some improvements to Operator SDK to streamline
> the experience of using OLM. For further information see, for example, this enhancement [proposal][sdk-integration-with-olm-doc].
> In the meantime, you might find the following documentation helpful:

The previous section has covered manually running an operator. In the next sections, we will explore using the [Operator Lifecycle Manager][operator_lifecycle_manager] (OLM) which is what enables a more robust deployment model for operators being run in production environments.

OLM helps you to install, update, and generally manage the lifecycle of all of the operators (and their associated services) on a Kubernetes cluster. It runs as an Kubernetes extension and lets you use `kubectl` for all the lifecycle management functions without any additional tools.

**NOTE:** Various public, OLM-ready operator projects are available at [operatorhub.io][operator-hub-io].

### Generate an operator manifest

The first step to leveraging OLM is to create a [Cluster Service Version][csv_design_doc] (CSV) manifest. An operator manifest describes how to display, create and manage the application, in this case memcached, as a whole. It is required for OLM to function.

The Operator SDK CLI can generate CSV manifests via the following command:
```console
$ operator-sdk olm-catalog gen-csv --csv-version 0.0.1
```
For more details see the SDK's [CSV generation doc][csv_generation_doc].

For the purpose of this guide, we will continue with this [predefined manifest][manifest_v1] file for the next steps. If you’d like, you can alter the image field within this manifest to reflect the image you built in previous steps, but it is unnecessary.

### Deploy the Operator

Deploying an operator is as simple as applying the operator’s CSV manifest to the desired namespace in the cluster.

First we need to create an [OperatorGroup][operator_group_doc] that specifies the namespaces that the operator will be targeting. Create the following OperatorGroup in the namespace where you will create the CSV. In this example the `default` namespace is used.

```YAML
apiVersion: operators.coreos.com/v1alpha2
kind: OperatorGroup
metadata:
name: memcached-operator-group
namespace: default
spec:
targetNamespaces:
- default
```

Next create the CSV.

```sh
$ curl -Lo memcachedoperator.0.0.1.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.1.csv.yaml
$ kubectl apply -f memcachedoperator.0.0.1.csv.yaml
$ kubectl get ClusterServiceVersion memcachedoperator.v0.0.1 -o json | jq '.status'
```

After applying this manifest, nothing has happened yet, because the cluster does not meet the requirements specified in our manifest. Create the CustomResourceDefinition and RBAC rules for the `Memcached` type managed by the operator:

```sh
$ kubectl create -f deploy/crds/cache_v1alpha1_memcached_crd.yaml
$ kubectl create -f deploy/service_account.yaml
$ kubectl create -f deploy/role.yaml
$ kubectl create -f deploy/role_binding.yaml
```console
$ operator-sdk olm-catalog gen-csv --csv-version 0.0.1 --update-crds
```

Because OLM creates operators in a particular namespace when a manifest has been applied, administrators can leverage the native Kubernetes RBAC permission model to restrict which users are allowed to install operators.
Several fields must be updated after generating the CSV. See the CSV generation doc for a list of [required fields][csv-fields], and the memcached-operator [CSV][memcached_csv] for an example of a complete CSV.

### Create an application instance
**NOTE:** You are able to preview and validate your CSV manifest syntax in the [operatorhub.io CSV Preview][operator-hub-io-preview] tool.

The memcached operator is now running in the `memcached` namespace. Users interact with operators via instances of CustomResources; in this case, the resource has the Kind `Memcached`. Native Kubernetes RBAC also applies to CustomResources, providing administrators control over who can interact with each operator.
### Testing locally

Creating instances of memcached in this namespace will now trigger the memcached operator to instantiate pods running the memcached server that are managed by the operator. The more CustomResources you create, the more unique instances of memcached will be managed by the memcached operator running in this namespace.

```sh
$ cat <<EOF | kubectl apply -f -
apiVersion: "cache.example.com/v1alpha1"
kind: "Memcached"
metadata:
name: "memcached-for-wordpress"
spec:
size: 1
EOF
$ cat <<EOF | kubectl apply -f -
apiVersion: "cache.example.com/v1alpha1"
kind: "Memcached"
metadata:
name: "memcached-for-drupal"
spec:
size: 1
EOF
$ kubectl get Memcached
NAME AGE
memcached-for-drupal 22s
memcached-for-wordpress 27s
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
memcached-app-operator-66b5777b79-pnsfj 1/1 Running 0 14m
memcached-for-drupal-5476487c46-qbd66 1/1 Running 0 3s
memcached-for-wordpress-65b75fd8c9-7b9x7 1/1 Running 0 8s
```
The next step is to ensure your project deploys correctly with OLM and runs as expected. Follow this [testing guide][testing-operators] to deploy and test your operator.

### Update an application
**NOTE:** Also, check out operatorhub.io's [bundle build tool][operator-hub-io-bundle] as an alternative to using `operator-sdk olm-catalog gen-csv`.

Manually applying an update to the operator is as simple as creating a new operator manifest with a `replaces` field that references the old operator manifest. OLM will ensure that all resources being managed by the old operator have their ownership moved to the new operator without fear of any programs stopping execution. It is up to the operators themselves to execute any data migrations required to upgrade resources to run under a new version of the operator.
### Promoting operator standards

The following command demonstrates applying a new [operator manifest][manifest_v2] using a new version of the operator and shows that the pods remain executing:
We recommend running `operator-sdk scorecard` against your operator to see whether your operator's OLM integration follows best practices. For further information on running the scorecard and results, see the [scorecard documentation][scorecard-doc].

```sh
$ curl -Lo memcachedoperator.0.0.2.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.2.csv.yaml
$ kubectl apply -f memcachedoperator.0.0.2.csv.yaml
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
memcached-app-operator-66b5777b79-pnsfj 1/1 Running 0 3s
memcached-for-drupal-5476487c46-qbd66 1/1 Running 0 14m
memcached-for-wordpress-65b75fd8c9-7b9x7 1/1 Running 0 14m
```
**NOTE:** the scorecard is undergoing changes to give informative and helpful feedback. The original scorecard functionality will still be available while and after changes are made.

## Conclusion

Expand All @@ -543,6 +471,12 @@ Hopefully, this guide was an effective demonstration of the value of the Operato
[result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result
[doc_client_api]: https://github.com/operator-framework/operator-sdk/blob/master/doc/user/client.md
[repo_sdk_samples_memcached]: https://github.com/operator-framework/operator-sdk-samples/tree/master/memcached-operator/
[manifest_v1]: memcachedoperator.0.0.1.csv.yaml
[manifest_v2]: memcachedoperator.0.0.2.csv.yaml
[mailing_list]: https://groups.google.com/forum/#!forum/operator-framework
[memcached_csv]: https://github.com/operator-framework/operator-sdk/blob/master/test/test-framework/deploy/olm-catalog/memcached-operator/0.0.3/memcached-operator.v0.0.3.clusterserviceversion.yaml
[testing-operators]: https://github.com/operator-framework/community-operators/blob/master/docs/testing-operators.md
[sdk-integration-with-olm-doc]: https://github.com/operator-framework/operator-sdk/blob/master/doc/proposals/sdk-integration-with-olm.md
[operator-hub-io]: https://operatorhub.io/
[operator-hub-io-preview]: https://operatorhub.io/preview
[operator-hub-io-bundle]: https://operatorhub.io/bundle
[scorecard-doc]: https://github.com/operator-framework/operator-sdk/blob/master/doc/test-framework/scorecard.md
[csv-fields]: https://github.com/operator-framework/operator-sdk/blob/master/doc/user/olm-catalog/generating-a-csv.md#csv-fields
144 changes: 0 additions & 144 deletions memcachedoperator.0.0.1.csv.yaml
View file
Open in desktop

This file was deleted.

Loading