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

Commit cbca033

Browse files
camilamacedo86camilamacedo86
authored
Merge pull request #57 from camilamacedo86/update-fix
Fix OLM Steps for Getting Started
2 parents a0da593 + dd2345a commit cbca033

File tree

3 files changed

+27
-382
lines changed

3 files changed

+27
-382
lines changed

‎README.md

Lines changed: 27 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
# Getting Started
22

3-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5-
<!-- **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -->
6-
73
- [Overview](#overview)
84
- [Build an operator using the Operator SDK](#build-an-operator-using-the-operator-sdk)
95
- [Create a new project](#create-a-new-project)
@@ -22,13 +18,10 @@
2218
- [Reference implementation](#reference-implementation)
2319
- [Manage the operator using the Operator Lifecycle Manager](#manage-the-operator-using-the-operator-lifecycle-manager)
2420
- [Generate an operator manifest](#generate-an-operator-manifest)
25-
- [Deploy the Operator](#deploy-the-operator)
26-
- [Create an application instance](#create-an-application-instance)
27-
- [Update an application](#update-an-application)
21+
- [Testing locally](#testing-locally)
22+
- [Promoting operator standards](#promoting-operator-standards)
2823
- [Conclusion](#conclusion)
2924

30-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
31-
3225
## Overview
3326

3427
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.
@@ -416,107 +409,42 @@ The above walkthrough follows the actual implementation process used to produce
416409

417410
## Manage the operator using the Operator Lifecycle Manager
418411

412+
> NOTE: This section of the Getting Started Guide is out-of-date.
413+
> We're working on some improvements to Operator SDK to streamline
414+
> the experience of using OLM. For further information see, for example, this enhancement [proposal][sdk-integration-with-olm-doc].
415+
> In the meantime, you might find the following documentation helpful:
416+
419417
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.
420418

421419
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.
422420

421+
**NOTE:** Various public, OLM-ready operator projects are available at [operatorhub.io][operator-hub-io].
422+
423423
### Generate an operator manifest
424424

425425
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.
426426

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

433-
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.
434-
435-
### Deploy the Operator
436-
437-
Deploying an operator is as simple as applying the operator’s CSV manifest to the desired namespace in the cluster.
438-
439-
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.
440-
441-
```YAML
442-
apiVersion: operators.coreos.com/v1alpha2
443-
kind: OperatorGroup
444-
metadata:
445-
name: memcached-operator-group
446-
namespace: default
447-
spec:
448-
targetNamespaces:
449-
- default
450-
```
451-
452-
Next create the CSV.
453-
454-
```sh
455-
$ curl -Lo memcachedoperator.0.0.1.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.1.csv.yaml
456-
$ kubectl apply -f memcachedoperator.0.0.1.csv.yaml
457-
$ kubectl get ClusterServiceVersion memcachedoperator.v0.0.1 -o json | jq '.status'
458-
```
459-
460-
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:
461-
462-
```sh
463-
$ kubectl create -f deploy/crds/cache_v1alpha1_memcached_crd.yaml
464-
$ kubectl create -f deploy/service_account.yaml
465-
$ kubectl create -f deploy/role.yaml
466-
$ kubectl create -f deploy/role_binding.yaml
429+
```console
430+
$ operator-sdk olm-catalog gen-csv --csv-version 0.0.1 --update-crds
467431
```
468432

469-
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.
433+
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.
470434

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

473-
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.
437+
### Testing locally
474438

475-
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.
476-
477-
```sh
478-
$ cat <<EOF | kubectl apply -f -
479-
apiVersion: "cache.example.com/v1alpha1"
480-
kind: "Memcached"
481-
metadata:
482-
name: "memcached-for-wordpress"
483-
spec:
484-
size: 1
485-
EOF
486-
$ cat <<EOF | kubectl apply -f -
487-
apiVersion: "cache.example.com/v1alpha1"
488-
kind: "Memcached"
489-
metadata:
490-
name: "memcached-for-drupal"
491-
spec:
492-
size: 1
493-
EOF
494-
$ kubectl get Memcached
495-
NAME AGE
496-
memcached-for-drupal 22s
497-
memcached-for-wordpress 27s
498-
$ kubectl get pods
499-
NAME READY STATUS RESTARTS AGE
500-
memcached-app-operator-66b5777b79-pnsfj 1/1 Running 0 14m
501-
memcached-for-drupal-5476487c46-qbd66 1/1 Running 0 3s
502-
memcached-for-wordpress-65b75fd8c9-7b9x7 1/1 Running 0 8s
503-
```
439+
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.
504440

505-
### Update an application
441+
**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`.
506442

507-
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.
443+
### Promoting operator standards
508444

509-
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:
445+
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].
510446

511-
```sh
512-
$ curl -Lo memcachedoperator.0.0.2.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.2.csv.yaml
513-
$ kubectl apply -f memcachedoperator.0.0.2.csv.yaml
514-
$ kubectl get pods
515-
NAME READY STATUS RESTARTS AGE
516-
memcached-app-operator-66b5777b79-pnsfj 1/1 Running 0 3s
517-
memcached-for-drupal-5476487c46-qbd66 1/1 Running 0 14m
518-
memcached-for-wordpress-65b75fd8c9-7b9x7 1/1 Running 0 14m
519-
```
447+
**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.
520448

521449
## Conclusion
522450

@@ -543,6 +471,12 @@ Hopefully, this guide was an effective demonstration of the value of the Operato
543471
[result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result
544472
[doc_client_api]: https://github.com/operator-framework/operator-sdk/blob/master/doc/user/client.md
545473
[repo_sdk_samples_memcached]: https://github.com/operator-framework/operator-sdk-samples/tree/master/memcached-operator/
546-
[manifest_v1]: memcachedoperator.0.0.1.csv.yaml
547-
[manifest_v2]: memcachedoperator.0.0.2.csv.yaml
548474
[mailing_list]: https://groups.google.com/forum/#!forum/operator-framework
475+
[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
476+
[testing-operators]: https://github.com/operator-framework/community-operators/blob/master/docs/testing-operators.md
477+
[sdk-integration-with-olm-doc]: https://github.com/operator-framework/operator-sdk/blob/master/doc/proposals/sdk-integration-with-olm.md
478+
[operator-hub-io]: https://operatorhub.io/
479+
[operator-hub-io-preview]: https://operatorhub.io/preview
480+
[operator-hub-io-bundle]: https://operatorhub.io/bundle
481+
[scorecard-doc]: https://github.com/operator-framework/operator-sdk/blob/master/doc/test-framework/scorecard.md
482+
[csv-fields]: https://github.com/operator-framework/operator-sdk/blob/master/doc/user/olm-catalog/generating-a-csv.md#csv-fields

‎memcachedoperator.0.0.1.csv.yaml

Lines changed: 0 additions & 144 deletions
This file was deleted.

0 commit comments

Comments
 (0)