diff --git a/_topic_map.yml b/_topic_map.yml index 5529896b58..171e1d2305 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -190,6 +190,12 @@ Name: Operators Dir: operators Distros: openshift-* Topics: +- Name: What are Operators? + File: olm-what-are-operators +- Name: Adding Operators to your cluster + File: olm-adding-operators-to-cluster +- Name: Creating applications from installed Operators + File: olm-creating-apps-from-installed-operators - Name: Getting started with the Operator SDK File: osdk-getting-started - Name: Operators based on Helm charts diff --git a/images/etcd-operator-overview.png b/images/etcd-operator-overview.png new file mode 100644 index 0000000000..72ae3f7901 Binary files /dev/null and b/images/etcd-operator-overview.png differ diff --git a/images/etcd-operator-resources.png b/images/etcd-operator-resources.png new file mode 100644 index 0000000000..dce86b5e8e Binary files /dev/null and b/images/etcd-operator-resources.png differ diff --git a/images/olm-catalog-sources.png b/images/olm-catalog-sources.png new file mode 100644 index 0000000000..2a8e7dbbc0 Binary files /dev/null and b/images/olm-catalog-sources.png differ diff --git a/images/olm-workflow.png b/images/olm-workflow.png new file mode 100644 index 0000000000..f78f5f68ff Binary files /dev/null and b/images/olm-workflow.png differ diff --git a/images/osdk-workflow.png b/images/osdk-workflow.png new file mode 100644 index 0000000000..2fb5236bce Binary files /dev/null and b/images/osdk-workflow.png differ diff --git a/modules/building-memcached-operator-using-osdk.adoc b/modules/building-memcached-operator-using-osdk.adoc index fa5ce8ffa9..00040372f9 100644 --- a/modules/building-memcached-operator-using-osdk.adoc +++ b/modules/building-memcached-operator-using-osdk.adoc @@ -37,7 +37,7 @@ $ cd memcached-operator + [TIP] ==== -See xref:operators-appendices.adoc#operator-project-scaffolding-layout_operator-appendices[Appendices] to +See xref:operators-appendices.adoc#olm-operator-project-scaffolding-layout_operator-appendices[Appendices] to learn about the project directory structure created by the previous commands. ==== diff --git a/modules/building-operator-with-helm-using-osdk.adoc b/modules/building-operator-with-helm-using-osdk.adoc index 5c9ccbf643..3303a68c08 100644 --- a/modules/building-operator-with-helm-using-osdk.adoc +++ b/modules/building-operator-with-helm-using-osdk.adoc @@ -11,9 +11,9 @@ powered by a Helm chart using tools and libraries provided by the Operator SDK. [TIP] ==== It is best practice to build a new Operator for each chart. This can allow for -more native-behaving Kubernetes APIs (e.g., `oc get Nginx`) and flexibility if -you ever want to write a fully-fledged Operator in Go, migrating away from a -Helm-based Operator. +more native-behaving Kubernetes APIs (for example, `oc get Nginx`) and +flexibility if you ever want to write a fully-fledged Operator in Go, migrating +away from a Helm-based Operator. ==== .Prerequisites @@ -40,7 +40,7 @@ $ cd nginx-operator [TIP] ==== See -xref:operators-appendices.adoc#operator-project-scaffolding-layout_operator-appendices[Appendices] +xref:operators-appendices.adoc#olm-operator-project-scaffolding-layout_operator-appendices[Appendices] to learn about the project directory structure created by the previous commands. ==== + @@ -92,8 +92,8 @@ logic for each Nginx Custom Resource (CR): * Create a Nginx Service if it does not exist. * Create a Nginx Ingress if it is enabled and does not exist. * Ensure that the Deployment, Service, and optional Ingress match the desired -configuration (e.g., replica count, image, service type) as specified by the -Nginx CR. +configuration (for example, replica count, image, service type) as specified by +the Nginx CR. -- + By default, the `nginx-operator` watches `Nginx` resource events as shown in the diff --git a/modules/olm-creating-etcd-cluster-from-operator.adoc b/modules/olm-creating-etcd-cluster-from-operator.adoc new file mode 100644 index 0000000000..da34b0d2f1 --- /dev/null +++ b/modules/olm-creating-etcd-cluster-from-operator.adoc @@ -0,0 +1,77 @@ +// Module included in the following assemblies: +// +// * operators/olm-creating-apps-from-installed-operators.adoc + +[id='olm-creating-etcd-cluster-from-operator_{context}'] += Creating an etcd cluster using an Operator + +This procedure walks through creating a new etcd cluster using the etcd +Operator, managed by the Operator Lifecycle Manager (OLM). + +.Prerequisites + +- Access to a {product-title} 4.0 cluster +- etcd Operator already installed to the cluster by an administrator + +.Procedure + +. Create a new project in the {product-title} web console for this procedure. This +example uses a project called *my-etcd*. + +. Navigate to the *Catalogs -> Installed Operators* page. The Operators that have +been installed to the cluster by the cluster administrator and are available for +use are shown here as a list of ClusterServiceVersions (CSVs). CSVs are used to +launch and manage the software provided by the Operator. ++ +[TIP] +==== +You can get this list from the CLI using: + +---- +$ oc get csv +---- +==== + +. On the *Installed Operators* page, click on the etcd Operator to view more +details and available actions: ++ +.etcd Operator overview +image::etcd-operator-overview.png[] ++ +As shown under *Provided APIs*, this Operator makes available three new resource +types, including one for an *etcd Cluster* (the `EtcdCluster` resource). These +objects work similar to the built-in native Kubernetes ones, such as +`Deployments` or `ReplicaSets`, but contain logic specific to managing etcd. + +. Create a new etcd cluster: + +.. In the *etcd Cluster* API box, click *Create New*. + +.. The next screen allows you to make any modifications to the minimal starting +template of an `EtcdCluster` object, such as the size of the cluster. For now, +click *Create* to finalize. This triggers the Operator to start up the Pods, +Services, and other components of the new etcd cluster. + +. Click the *Resources* tab to see that your project now contains a number of +resources created and configured automatically by the Operator. ++ +.etcd Operator resources +image::etcd-operator-resources.png[] ++ +Verify that a Kubernetes service has been created that allows you to access the +database from other Pods in your project. + +. All users with the `edit` role in a given project can create, manage, and delete +application instances (an etcd cluster, in this example) managed by Operators +that have already been created in the project, in a self-service manner, just +like a cloud service. If you want to enable additional users with this ability, +project administrators can add the role using the following command: ++ +---- +$ oc policy add-role-to-user edit -n +---- + +You now have an etcd cluster that will react to failures and rebalance data as +Pods become unhealthy or are migrated between nodes in the cluster. Most +importantly, cluster administrators or developers with proper access can now +easily use the database with their applications. diff --git a/modules/olm-installing-operator-using-operatorhub.adoc b/modules/olm-installing-operator-using-operatorhub.adoc new file mode 100644 index 0000000000..cd9e788542 --- /dev/null +++ b/modules/olm-installing-operator-using-operatorhub.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * operators/olm-adding-operators-to-cluster.adoc + +[id='olm-installing-operator-using-operatorhub_{context}'] += Installing an Operator using the OperatorHub + +As a cluster administrator, you can install an Operator using the OperatorHub in +the {product-title} web console to make it available for all developers using +your cluster. This procedure uses the etcd Operator as an example. + +.Prerequisites + +- Access to an {product-title} v4 cluster using an account with `cluster-admin` +permissions. + +.Procedure + +. Navigate in the web console to the *Catalog → Operator Hub* page. + +. Click *Show Community Operators*. ++ +[NOTE] +==== +This Operator will be available under the *Red Hat* category in the GA release. +==== + +. Choose *etcd* from the list of available Operators, and click *Install*. + +. On the *Create Operator Subscription* page, change the *Target* to the +*global-operators* Operator Group. This makes the Operator available to all +users and projects that use this {product-title} cluster. + +. On the *Catalog → Installed Operators* page, verify that the *etcd* +ClusterServiceVersion (CSV) eventually shows up and its *Status* ultimately +resolves to *InstallSucceeded*. ++ +If it does not, switch to the *Catalog → Operator Management* page and inspect +the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors +under *Status*. Then, check the logs in any Pods in the *openshift-operators* +project (on the *Workloads → Pods* page) that are reporting issues to +troubleshoot further. diff --git a/modules/olm-operator-framework.adoc b/modules/olm-operator-framework.adoc new file mode 100644 index 0000000000..7a0d3d69c8 --- /dev/null +++ b/modules/olm-operator-framework.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * operators/what-are-operators.adoc + +[id='olm-operator-framework-{context}'] += Operator Framework + +The Operator Framework is a family of tools and capabilities to deliver on the +customer experience describe above. It is not just about writing code; testing, +delivering, and updating Operators is just as important. The Operator Framework +components consiss of open source tools to tackle these problems: + +Operator SDK:: +Assists Operator authors in bootstrapping, building, testing, and packaging +their own Operator based on their expertise without requiring knowledge of +Kubernetes API complexities. + +Operator Lifecycle Manager:: +Controls the installation, upgrade, and RBAC of Operators in a cluster. Deployed +by default in {product-title} 4. + +Operator Metering:: +Collects operational metrics about Operators on the cluster for Day 2 management +and aggregating usage metrics. + +Operator Hub:: +Web console for discovering and installing Operators on your cluster. Deployed +by default in {product-title} 4. + +These tools are designed to be composable, so you can use any that are useful to +you. diff --git a/modules/olm-operator-lifecycle-manager.adoc b/modules/olm-operator-lifecycle-manager.adoc new file mode 100644 index 0000000000..f4963acf32 --- /dev/null +++ b/modules/olm-operator-lifecycle-manager.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operators/olm-adding-operators-to-cluster.adoc + +[id='olm-operator-lifecycle-manager-{context}'] += Understanding the Operator Lifecycle Manager + +In {product-title} 4.0, the _Operator Lifecycle Manager_ (OLM) helps users +install, update, and manage the lifecycle of all Operators and their associated +services running across their clusters. It is part of the +link:https://coreos.com/blog/introducing-operator-framework[Operator Framework], +an open source toolkit designed to manage Kubernetes native applications +(Operators) in an effective, automated, and scalable way. + +.Operator Lifecycle Manager workflow +image::olm-workflow.png[] + +The OLM runs by default in {product-title} 4.0, which aids cluster +administrators in installing, upgrading, and granting access to Operators +running on their cluster. The {product-title} web console provides management +screens for cluster administrators to install Operators, as well as grant +specific projects access to use the catalog of Operators available on the +cluster. + +For developers, a self-service experience allows provisioning and configuring +instances of databases, monitoring, and big data services without having to be +subject matter experts, because the Operator has that knowledge baked into it. diff --git a/modules/operator-project-staffolding-layout.adoc b/modules/olm-operator-project-staffolding-layout.adoc similarity index 97% rename from modules/operator-project-staffolding-layout.adoc rename to modules/olm-operator-project-staffolding-layout.adoc index 18dbcdb1ec..0248faf0cb 100644 --- a/modules/operator-project-staffolding-layout.adoc +++ b/modules/olm-operator-project-staffolding-layout.adoc @@ -2,7 +2,7 @@ // // * operators/operators-appendices.adoc -[id='operator-project-scaffolding-layout_{context}'] +[id='olm-operator-project-scaffolding-layout_{context}'] = Operator project scaffolding layout The `operator-sdk` CLI generates a number of packages for each Operator project. diff --git a/modules/olm-operatorhub.adoc b/modules/olm-operatorhub.adoc new file mode 100644 index 0000000000..e272f312e4 --- /dev/null +++ b/modules/olm-operatorhub.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operators/olm-adding-operators-to-cluster.adoc + +[id='olm-operatorhub-{context}'] += Understanding the OperatorHub + +The _OperatorHub_ is available via the {product-title} web console and is the +interface that cluster administrators use to discover and install Operators. +With one click, an Operator can be pulled from their off-cluster source, +installed and subscribed on the cluster, and made ready for engineering teams to +self-service manage the product across deployment environments using the +Operator Lifecycle Manager (OLM). + +Cluster administrators can choose from catalog sources of Operators grouped into +the following categories: + +Red Hat Operators:: +Red Hat products packaged and shipped by Red Hat. Supported by Red Hat. + +Certified Operators:: +Products from leading independent software vendors (ISVs). Red Hat partners with +ISVs to package and ship. Supported by the ISV. + +Community Operators:: +Optionally-visible software maintained by relevant representatives in the +link:https://github.com/operator-framework/community-operators[operator-framework/community-operators] +GitHub repository. No official support. diff --git a/modules/olm-why-use-operators.adoc b/modules/olm-why-use-operators.adoc new file mode 100644 index 0000000000..3cc122b231 --- /dev/null +++ b/modules/olm-why-use-operators.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * operators/what-are-operators.adoc + +[id='olm-why-use-operators-{context}'] += Why use Operators? + +Operators provide: + +-- +- Repeatability of installation and upgrade. +- Constant health checks of every system component. +- Over-the-air (OTA) updates for OpenShift components and ISV content. +- A place to encapsulate knowledge from field engineers and spread it to all +users, not just one or two. +-- + +Why deploy on Kubernetes?:: +Kubernetes (and by extension, {product-title}) contains all of the primitives +needed to build complex distributed systems – secret handling, load balancing, +service discovery, autoscaling – that work across on-premise and cloud +providers. + +Why manage your app with Kubernetes APIs and `kubectl` tooling?:: +These APIs are feature rich, have clients for all platforms and plug into the +cluster’s access control/auditing. An Operator uses the Kubernetes' extension +mechanism, Custom Resource Definitions (CRDs), so your custom object, for +example `MongoDB`, looks and acts just like the built-in, native Kubernetes +objects. + +How do Operators compare with Service Brokers?:: +A Service Broker is a step towards programmatic discovery and deployment of an +app. However, because it is not a long running process, it cannot execute Day 2 +operations like upgrade, failover, or scaling. Customizations and +parameterization of tunables are provided at install time, versus an Operator +that is constantly watching your cluster's current state. Off-cluster services +continue to be a good match for a Service Broker, although Operators exist for +these as well. diff --git a/modules/osdk-cli-reference-test.adoc b/modules/osdk-cli-reference-test.adoc index 88245964be..d3f2760143 100644 --- a/modules/osdk-cli-reference-test.adoc +++ b/modules/osdk-cli-reference-test.adoc @@ -87,7 +87,7 @@ the Operator SDK as a Pod in the cluster. |Location of `kubeconfig` for a cluster. Default: `~/.kube/config`. |`--image-pull-policy` (string) -|Set test pod image pull policy. Allowed values: `Always` (default), `Never`. +|Set test Pod image pull policy. Allowed values: `Always` (default), `Never`. |`--namespace` (string) |Namespace to run tests in. Default: `default`. diff --git a/modules/osdk-helm-chart-support.adoc b/modules/osdk-helm-chart-support.adoc index 60280e09b8..267790d43d 100644 --- a/modules/osdk-helm-chart-support.adoc +++ b/modules/osdk-helm-chart-support.adoc @@ -24,10 +24,10 @@ The main function of an Operator is to read from a custom object that represents your application instance and have its desired state match what is running. In the case of a Helm-based Operator, the object's spec field is a list of configuration options that are typically described in Helm's `values.yaml` file. -Instead of setting these values with flags using the Helm CLI (e.g., `helm -install -f values.yaml`), you can express them within a Custom Resource (CR), -which, as a native Kubernetes object, enables the benefits of RBAC applied to it -and an audit trail. +Instead of setting these values with flags using the Helm CLI (for example, `helm install -f values.yaml`), +you can express them within a Custom Resource (CR), which, as a native +Kubernetes object, enables the benefits of RBAC applied to it and an audit +trail. For an example of a simple CR called `Tomcat`: diff --git a/modules/about-operator-sdk.adoc b/modules/osdk-operator-sdk.adoc similarity index 96% rename from modules/about-operator-sdk.adoc rename to modules/osdk-operator-sdk.adoc index d9e8ebb0f3..6afdc0d12a 100644 --- a/modules/about-operator-sdk.adoc +++ b/modules/osdk-operator-sdk.adoc @@ -2,7 +2,7 @@ // // * operators/osdk-getting-started.adoc -[id='about-opreator-sdk-{context}'] +[id='osdk-operator-sdk-{context}'] = Understanding the Operator SDK The link:https://coreos.com/operators/[Operator Framework] is an open source @@ -35,6 +35,9 @@ The SDK provides the following workflow to develop a new operator: . Define the Operator reconciling logic in a designated handler and use the SDK API to interact with resources. . Use the SDK CLI to build and generate the Operator deployment manifests. +.Operator SDK workflow +image::osdk-workflow.png[] + At a high level, an Operator using the SDK processes events for watched resources in a user-defined handler and takes actions to reconcile the state of the application. diff --git a/operators/olm-adding-operators-to-cluster.adoc b/operators/olm-adding-operators-to-cluster.adoc new file mode 100644 index 0000000000..2a8051b3b0 --- /dev/null +++ b/operators/olm-adding-operators-to-cluster.adoc @@ -0,0 +1,22 @@ +[id='olm-adding-operators-to-a-cluster'] += Adding Operators to a cluster +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: +:context: olm-adding-operators-to-a-cluster + +toc::[] + +{nbsp} + +This guide outlines the basics of the Operator Lifecycle Manager (OLM) and walks +through an example of installing and subscribing a cluster to Operators from the +OperatorHub. + +include::modules/olm-operator-lifecycle-manager.adoc[leveloffset=+1] +include::modules/olm-operatorhub.adoc[leveloffset=+1] +include::modules/olm-installing-operator-using-operatorhub.adoc[leveloffset=+1] diff --git a/operators/olm-creating-apps-from-installed-operators.adoc b/operators/olm-creating-apps-from-installed-operators.adoc new file mode 100644 index 0000000000..1a45c2274e --- /dev/null +++ b/operators/olm-creating-apps-from-installed-operators.adoc @@ -0,0 +1,19 @@ +[id='olm-creating-apps-from-installed-operators'] += Creating applications from installed Operators +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: +:context: olm-creating-apps-from-installed-operators + +toc::[] + +{nbsp} + +This guide walks through an example of creating applications from an installed +Operator using the {product-title} 4.0 web console. + +include::modules/olm-creating-etcd-cluster-from-operator.adoc[leveloffset=+1] diff --git a/operators/olm-what-are-operators.adoc b/operators/olm-what-are-operators.adoc new file mode 100644 index 0000000000..ea3ee3e45f --- /dev/null +++ b/operators/olm-what-are-operators.adoc @@ -0,0 +1,39 @@ +[id='olm-what-are-operators'] += What are Operators? +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: +:context: olm-what-are-operators + +toc::[] + +{nbsp} + +[.lead] +Conceptually, _Operators_ take human operational knowledge and encode it into +software that is more easily shared with consumers. + +Operators are pieces of software that ease the operational complexity of running +another piece of software. They act like an extension of the software vendor's +engineering team, watching over a Kubernetes environment (such as +{product-title}) and using its current state to make decisions in real time. +Advanced Operators are designed to handle upgrades seamlessly, react to failures +automatically, and not take shortcuts, like skipping a software backup process +to save time. + +[.lead] +More technically, _Operators_ are a method of packaging, deploying, and managing a +Kubernetes application. + +A Kubernetes application is an app that is both deployed on Kubernetes and +managed using the Kubernetes APIs and `kubectl` or `oc` tooling. To be able to +make the most of Kubernetes, you need a set of cohesive APIs to extend in order +to service and manage your apps that run on Kubernetes. Think of +Operators as the runtime that manages this type of app on Kubernetes. + +include::modules/olm-why-use-operators.adoc[leveloffset=+1] +include::modules/olm-operator-framework.adoc[leveloffset=+1] diff --git a/operators/operators-appendices.adoc b/operators/operators-appendices.adoc index 93a04c2b57..9230325d7c 100644 --- a/operators/operators-appendices.adoc +++ b/operators/operators-appendices.adoc @@ -12,4 +12,4 @@ toc::[] -include::modules/operator-project-staffolding-layout.adoc[leveloffset=+2] +include::modules/olm-operator-project-staffolding-layout.adoc[leveloffset=+2] diff --git a/operators/osdk-getting-started.adoc b/operators/osdk-getting-started.adoc index 4eb51002da..bfe1ab4a67 100644 --- a/operators/osdk-getting-started.adoc +++ b/operators/osdk-getting-started.adoc @@ -13,23 +13,13 @@ toc::[] {nbsp} + -This guide walks through an example of building a simple Memcached Operator -(`memcached-operator`) using the `operator-sdk` CLI tool and -`controller-runtime` library API. It also shows how to manage the new Operator's -lifecycle from installation through updating to a new version. +This guide walks through an example of building a simple Memcached Operator and +managing its lifecycle on a Kubernetes-based cluster (such as {product-title}) +from installation to upgrade. This is accomplished using two centerpieces of the +Operator Framework: the Operator SDK (the `operator-sdk` CLI tool and +`controller-runtime` library API) and the Operator Lifecycle Manager (OLM). -As an administrator of a Kubernetes-based cluster, you can accomplish this using -two centerpieces of the Operator Framework: - -Operator SDK:: Assists developers in bootstrapping and building an Operator -based on their expertise without requiring knowledge of Kubernetes API -complexities. - -Operator Lifecycle Manager (OLM):: Helps Operator users install, update, and -generally manage the lifecycle of all Operators and their associated services -running across their clusters. - -include::modules/about-operator-sdk.adoc[leveloffset=+1] +include::modules/osdk-operator-sdk.adoc[leveloffset=+1] include::modules/installing-operator-sdk-cli.adoc[leveloffset=+1] include::modules/building-memcached-operator-using-osdk.adoc[leveloffset=+1] include::modules/managing-memcached-operator-using-olm.adoc[leveloffset=+1]