diff --git a/_topic_map.yml b/_topic_map.yml index c1fc7b798f..cec9078e1f 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -44,6 +44,27 @@ Topics: File: deployment-strategies - Name: Using route-based deployment strategies File: route-based-deployment-strategies +- Name: Operators + Dir: operators + Topics: + - Name: What Operators are + File: olm-what-operators-are + - Name: Adding Operators to a cluster + File: olm-adding-operators-to-cluster + Distros: openshift-enterprise,openshift-origin + - 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: Creating Helm-based Operators + File: osdk-helm + - Name: Operator SDK CLI reference + File: osdk-cli-reference + - Name: Migrating to Operator SDK v0.1.0 + File: migrating-to-osdk-v0-1-0 + Distros: openshift-origin + - Name: Appendices + File: operators-appendices - Name: Managing resources from CRDs File: crd-managing-resources-from-crds --- @@ -188,7 +209,7 @@ Topics: File: idling-applications - Name: Extending the Kubernetes API with CRDs File: crd-extending-api-with-crds -- Name: Pruning objects +- Name: Pruning objects to reclaim resources File: pruning-objects --- Name: Control Plane management @@ -242,28 +263,6 @@ Topics: - Name: Optimizing storage File: optimizing-storage --- -Name: Operators -Dir: operators -Distros: openshift-* -Topics: -- Name: What are Operators? - File: olm-what-are-operators -- Name: Adding Operators to a cluster - File: olm-adding-operators-to-cluster - Distros: openshift-enterprise,openshift-origin -- 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 - File: osdk-helm -- Name: Operator SDK CLI reference - File: osdk-cli-reference -- Name: Migrating to Operator SDK v0.1.0 - File: migrating-to-osdk-v0-1-0 -- Name: Appendices - File: operators-appendices ---- Name: Nodes Dir: nodes Distros: openshift-* diff --git a/applications_and_projects/operators/images b/applications_and_projects/operators/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/applications_and_projects/operators/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/operators/migrating-to-osdk-v0-1-0.adoc b/applications_and_projects/operators/migrating-to-osdk-v0-1-0.adoc similarity index 92% rename from operators/migrating-to-osdk-v0-1-0.adoc rename to applications_and_projects/operators/migrating-to-osdk-v0-1-0.adoc index 9a2cf4b235..d38f0c46b0 100644 --- a/operators/migrating-to-osdk-v0-1-0.adoc +++ b/applications_and_projects/operators/migrating-to-osdk-v0-1-0.adoc @@ -1,13 +1,7 @@ +:relfileprefix: ../ [id='osdk-migrating-to-osdk-v0-1-0'] = Migrating to Operator SDK v0.1.0 -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: +include::modules/common-attributes.adoc[] :context: osdk-migrating-to-osdk-v0-1-0 toc::[] diff --git a/applications_and_projects/operators/modules b/applications_and_projects/operators/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/applications_and_projects/operators/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/operators/olm-adding-operators-to-cluster.adoc b/applications_and_projects/operators/olm-adding-operators-to-cluster.adoc similarity index 68% rename from operators/olm-adding-operators-to-cluster.adoc rename to applications_and_projects/operators/olm-adding-operators-to-cluster.adoc index 2a8051b3b0..fad7e2c5c6 100644 --- a/operators/olm-adding-operators-to-cluster.adoc +++ b/applications_and_projects/operators/olm-adding-operators-to-cluster.adoc @@ -1,21 +1,15 @@ +:relfileprefix: ../ [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!: +include::modules/common-attributes.adoc[] :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. +cluster administrators 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] diff --git a/operators/olm-creating-apps-from-installed-operators.adoc b/applications_and_projects/operators/olm-creating-apps-from-installed-operators.adoc similarity index 51% rename from operators/olm-creating-apps-from-installed-operators.adoc rename to applications_and_projects/operators/olm-creating-apps-from-installed-operators.adoc index 1a45c2274e..e2a5e4498c 100644 --- a/operators/olm-creating-apps-from-installed-operators.adoc +++ b/applications_and_projects/operators/olm-creating-apps-from-installed-operators.adoc @@ -1,19 +1,13 @@ +:relfileprefix: ../ [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!: +include::modules/common-attributes.adoc[] :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. +This guide walks developers 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/applications_and_projects/operators/olm-what-operators-are.adoc similarity index 86% rename from operators/olm-what-are-operators.adoc rename to applications_and_projects/operators/olm-what-operators-are.adoc index ea3ee3e45f..3ea4a18fd9 100644 --- a/operators/olm-what-are-operators.adoc +++ b/applications_and_projects/operators/olm-what-operators-are.adoc @@ -1,14 +1,8 @@ -[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 +:relfileprefix: ../ +[id='olm-what-operators-are'] += What Operators are +include::modules/common-attributes.adoc[] +:context: olm-what-operators-are toc::[] diff --git a/operators/operators-appendices.adoc b/applications_and_projects/operators/operators-appendices.adoc similarity index 54% rename from operators/operators-appendices.adoc rename to applications_and_projects/operators/operators-appendices.adoc index 9230325d7c..0cd84de6a9 100644 --- a/operators/operators-appendices.adoc +++ b/applications_and_projects/operators/operators-appendices.adoc @@ -1,15 +1,9 @@ +:relfileprefix: ../ [id='operator-appendices'] = Appendices -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: +include::modules/common-attributes.adoc[] :context: operator-appendices toc::[] -include::modules/olm-operator-project-staffolding-layout.adoc[leveloffset=+2] +include::modules/olm-operator-project-staffolding-layout.adoc[leveloffset=+1] diff --git a/operators/osdk-cli-reference.adoc b/applications_and_projects/operators/osdk-cli-reference.adoc similarity index 87% rename from operators/osdk-cli-reference.adoc rename to applications_and_projects/operators/osdk-cli-reference.adoc index b2e3dcebbc..b56a9a7e40 100644 --- a/operators/osdk-cli-reference.adoc +++ b/applications_and_projects/operators/osdk-cli-reference.adoc @@ -1,13 +1,7 @@ +:relfileprefix: ../ [id='osdk-cli-reference'] = Operator SDK CLI reference -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: +include::modules/common-attributes.adoc[] :context: osdk-cli-reference toc::[] diff --git a/operators/osdk-getting-started.adoc b/applications_and_projects/operators/osdk-getting-started.adoc similarity index 56% rename from operators/osdk-getting-started.adoc rename to applications_and_projects/operators/osdk-getting-started.adoc index bfe1ab4a67..872d886527 100644 --- a/operators/osdk-getting-started.adoc +++ b/applications_and_projects/operators/osdk-getting-started.adoc @@ -1,27 +1,27 @@ +:relfileprefix: ../ [id='getting-started-osdk'] = Getting started with the Operator SDK -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: +include::modules/common-attributes.adoc[] :context: osdk-getting-started toc::[] {nbsp} + -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). +This guide walks Operator authors through an example of building a simple +Go-based 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). 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] +.Additional resources +- See +xref:../applications_and_projects/operators/operators-appendices.adoc#olm-operator-project-scaffolding-layout_operator-appendices[Appendices] +to learn about the project directory structures created by the Operator SDK. + include::modules/managing-memcached-operator-using-olm.adoc[leveloffset=+1] ifdef::openshift-origin[] @@ -36,6 +36,5 @@ link:https://github.com/operator-framework[*github.com/operator-framework*] If you want to discuss your experience, have questions, or want to get involved, join the -link:https://groups.google.com/forum/#!forum/operator-framework[Operator -Framework mailing list]. +link:https://groups.google.com/forum/#!forum/operator-framework[Operator Framework mailing list]. endif::[] diff --git a/operators/osdk-helm.adoc b/applications_and_projects/operators/osdk-helm.adoc similarity index 62% rename from operators/osdk-helm.adoc rename to applications_and_projects/operators/osdk-helm.adoc index e508ec6daa..5e20f42785 100644 --- a/operators/osdk-helm.adoc +++ b/applications_and_projects/operators/osdk-helm.adoc @@ -1,21 +1,15 @@ +:relfileprefix: ../ [id='osdk-helm'] -= Operators based on Helm charts -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: += Creating Helm-based Operators +include::modules/common-attributes.adoc[] :context: osdk-helm toc::[] {nbsp} + -This guide outlines Helm chart support in the Operator SDK and walks through an -example of building and running an Nginx Operator with the `operator-sdk` CLI -tool that uses an existing Helm chart. +This guide outlines Helm chart support in the Operator SDK and walks Operator +authors through an example of building and running an Nginx Operator with the +`operator-sdk` CLI tool that uses an existing Helm chart. include::modules/osdk-helm-chart-support.adoc[leveloffset=+1] diff --git a/masters/pruning-objects.adoc b/masters/pruning-objects.adoc index de7468e2f8..d21edf07da 100644 --- a/masters/pruning-objects.adoc +++ b/masters/pruning-objects.adoc @@ -1,5 +1,5 @@ [id='pruning-objects'] -= Pruning objects += Pruning objects to reclaim resources include::modules/common-attributes.adoc[] :context: pruning-objects diff --git a/modules/building-memcached-operator-using-osdk.adoc b/modules/building-memcached-operator-using-osdk.adoc index 00040372f9..606c5356e8 100644 --- a/modules/building-memcached-operator-using-osdk.adoc +++ b/modules/building-memcached-operator-using-osdk.adoc @@ -3,7 +3,7 @@ // * operators/osdk-getting-started.adoc [id='building-memcached-operator-using-osdk_{context}'] -= Building a Memcached Operator using the Operator SDK += Building a Go-based Memcached Operator using the Operator SDK The Operator SDK makes it easier to build Kubernetes native applications, a process that can require deep, application-specific operational knowledge. The @@ -34,12 +34,6 @@ $ cd $GOPATH/src/github.com/example-inc/ $ operator-sdk new memcached-operator $ cd memcached-operator ---- -+ -[TIP] -==== -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. -==== . *Add a new Custom Resource Definition (CRD).* @@ -49,7 +43,7 @@ learn about the project directory structure created by the previous commands. ---- $ operator-sdk add api \ --api-version=cache.example.com/v1alpha1 \ - --kind=Memcached + --kind=Memcached ---- + This scaffolds the Memcached resource API under `pkg/apis/cache/v1alpha1/`. @@ -83,7 +77,7 @@ resource: ---- $ operator-sdk add controller \ --api-version=cache.example.com/v1alpha1 \ - --kind=Memcached + --kind=Memcached ---- + This scaffolds a new Controller implementation under diff --git a/modules/building-operator-with-helm-using-osdk.adoc b/modules/building-operator-with-helm-using-osdk.adoc index 3303a68c08..ecb7f6a235 100644 --- a/modules/building-operator-with-helm-using-osdk.adoc +++ b/modules/building-operator-with-helm-using-osdk.adoc @@ -3,7 +3,7 @@ // * operators/osdk-helm.adoc [id='building-operator-with-helm-using-osdk_{context}'] -= Building an Operator with Helm charts using the Operator SDK += Building a Helm-based Operator using the Operator SDK This procedure walks through an example of building a simple Nginx Operator powered by a Helm chart using tools and libraries provided by the Operator SDK. diff --git a/modules/olm-operator-framework.adoc b/modules/olm-operator-framework.adoc index 25a3e4c221..dde0d48928 100644 --- a/modules/olm-operator-framework.adoc +++ b/modules/olm-operator-framework.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * operators/what-are-operators.adoc +// * operators/what-operators-are.adoc [id='olm-operator-framework-{context}'] = Operator Framework diff --git a/modules/olm-operator-project-staffolding-layout.adoc b/modules/olm-operator-project-staffolding-layout.adoc index 0248faf0cb..0d493a5c20 100644 --- a/modules/olm-operator-project-staffolding-layout.adoc +++ b/modules/olm-operator-project-staffolding-layout.adoc @@ -9,6 +9,7 @@ The `operator-sdk` CLI generates a number of packages for each Operator project. The following sections describes a basic rundown of each generated file and directory. +[id='olm-operator-project-scaffolding-layout-go_{context}'] == Go-based projects Go-based Operator projects (the default type) generated using the `operator-sdk new` @@ -17,7 +18,7 @@ command contain the following directories and files: [options="header",cols="1,2"] |=== -|File/Folders |Purpose +|File/folders |Purpose |`cmd/` |Contains `manager/main.go` file, which is the main program of the Operator. This @@ -57,6 +58,7 @@ vendor directly. |=== +[id='olm-operator-project-scaffolding-layout-helm_{context}'] == Helm-based projects Helm-based Operator projects generated using the `operator-sdk new --type helm` @@ -65,7 +67,7 @@ command contain the following directories and files: [options="header",cols="1,2"] |=== -|File/Folders |Purpose +|File/folders |Purpose |`deploy/` |Contains various YAML manifests for registering CRDs, setting up RBAC, diff --git a/modules/olm-why-use-operators.adoc b/modules/olm-why-use-operators.adoc index 3cc122b231..3e260b62ac 100644 --- a/modules/olm-why-use-operators.adoc +++ b/modules/olm-why-use-operators.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * operators/what-are-operators.adoc +// * operators/what-operators-are.adoc [id='olm-why-use-operators-{context}'] = Why use Operators? diff --git a/modules/osdk-operator-sdk.adoc b/modules/osdk-operator-sdk.adoc index 6afdc0d12a..d3aea57fa2 100644 --- a/modules/osdk-operator-sdk.adoc +++ b/modules/osdk-operator-sdk.adoc @@ -3,7 +3,7 @@ // * operators/osdk-getting-started.adoc [id='osdk-operator-sdk-{context}'] -= Understanding the Operator SDK += Architecture of the Operator SDK The link:https://coreos.com/operators/[Operator Framework] is an open source toolkit to manage Kubernetes native applications, called _Operators_, in an @@ -17,17 +17,17 @@ 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. -The Operator SDK is a framework designed to make writing operators easier by +The Operator SDK is a framework designed to make writing Operators easier by providing: - High-level APIs and abstractions to write the operational logic more intuitively - Tools for scaffolding and code generation to quickly bootstrap a new project -- Extensions to cover common operator use cases +- Extensions to cover common Operator use cases [discrete] -=== Operator SDK Workflow +=== Operator SDK workflow -The SDK provides the following workflow to develop a new operator: +The SDK provides the following workflow to develop a new Operator: . Create a new Operator project using the SDK command line interface (CLI). . Define new resource APIs by adding Custom Resource Definitions (CRDs).