From c5e13f87b9ab242fc00ed974a30b46e57a7e4887 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 2 Oct 2020 12:51:28 -0400 Subject: [PATCH] Deprecate olm-book repo All the docs from this repo have been moved over to https://github.com/operator-framework/olm-docs This PR nukes this repo to drive both contributor and user traffic to the new doc site. --- README.md | 15 +- docs/discover-operator-presence.md | 32 +-- docs/glossary.md | 94 +------ docs/how-do-i-install-my-operator-with-olm.md | 52 +--- docs/install-olm.md | 57 +--- docs/intro.md | 1 - docs/list-available-operators.md | 25 +- docs/multiarch.md | 60 +---- .../operator-dependencies-and-requirements.md | 50 +--- docs/operator-scoping.md | 170 +----------- docs/packaging-an-operator.md | 243 +----------------- docs/snapshot-appr-registry.md | 153 ----------- docs/subscriptions.md | 74 +----- docs/troubleshooting.md | 153 +---------- docs/uninstall-an-operator.md | 45 +--- docs/uninstall-olm.md | 73 +----- docs/validate-package.md | 90 +------ docs/what-does-olm-enable.md | 3 - docs/what-is-an-operator.md | 2 - docs/when-to-update-my-operator.md | 28 +- docs/why-olm.md | 1 - index.md | 72 +----- 22 files changed, 34 insertions(+), 1459 deletions(-) delete mode 100644 docs/intro.md delete mode 100644 docs/snapshot-appr-registry.md delete mode 100644 docs/what-does-olm-enable.md delete mode 100644 docs/what-is-an-operator.md delete mode 100644 docs/why-olm.md diff --git a/README.md b/README.md index c579c15..28f0e9d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,3 @@ -# Operator Lifecycle Book +This repo is deprecated. Please checkout https://olm.operatorframework.io for the latest docs. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs -## Adding a new page - - - Clone this repo - - Make a new markdown doc in `docs` - - Example: `docs/what-does-olm-enable.md` - - Update or create a new link in `index.md` to point to the doc in `docs` - - The link should be `https://operator-framework.github.io/olm-book/docs/` + doc name (no `.md`) - - Example: `[What does OLM enable](https://operator-framework.github.io/olm-book/docs/what-does-olm-enable)`? - - Make a PR with both changes - - See the updated links in https://operator-framework.github.io/olm-book - -You can also use the in-browser editor to make PRs! diff --git a/docs/discover-operator-presence.md b/docs/discover-operator-presence.md index 59996e6..99dd434 100644 --- a/docs/discover-operator-presence.md +++ b/docs/discover-operator-presence.md @@ -1,30 +1,2 @@ -# How do I discover the presence/availability of an Operator? - -## Discovering installed operators -Checking the presence of custom installed operators in the cluster is simply a matter of checking all the -`ClusterServiceVersions` (CSV) that are available in the cluster. Every operator installed by OLM has a corresponding CSV -associated with it that that contains all the details of the operator. Running `kubectl get csvs -A` -would return all CSVs across all namespaces and provide a high-level view of all custom installed operators. - -If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](openshift/coming-soon.md) to debug your installation. - -## Finding available operators -Operators are available from a variety of sources, or catalogs. Some catalogs are bundled in the default installation of -OLM, and there are also online catalogs of operators available to install within the cluster. - -### Installing operators from within the cluster -A collection of operators come packaged with the default OLM installation and can be examined by querying the packageserver. -These operators come from the community as well as officially supported Red Hat operators. The package server is an - [apiserver extension](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) -that aggregates information on all operators available to install from catalog sources in the cluster. To see available -packages run `kubectl get packagemanifests`. - -To get more information about a particular operator installed within the cluster from a catalogsource, run -`kubectl describe packagemanifests `. This will provide some detailed information about the operator such as -its intended use, applicable CRDs, and resources for support with that particular operator. - -### Finding operators to install -A great resource to find all available operators is [OperatorHub](https://operatorhub.io/), an online catalog -of installable operators. There are over 80 available operators available to install, with details around the installation process, -the upgrade process, and operator support information. Installing operators from OperatorHub is seamless if OLM is installed. - +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/list-operators-available-to-install/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/glossary.md b/docs/glossary.md index 4b71cda..8d1e695 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,92 +1,2 @@ -# OLM Glossary - -A list of OLM terms, with definitions and common Aliases. - -## CustomResourceDefinitions (CRDs) - -The following [CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) are defined by the OLM. - -### ClusterServiceVersion - -**Definition**: The ClusterServiceVersion represents a particular version of a ClusterService and its operator. It includes metadata such as name, description, version, repository link, labels, icon, etc. It declares `owned`/`required` CRDs, cluster requirements, and install strategy that tells OLM how to create required resources and set up the operator as a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). - -**Aliases**: CSV(s) - -### CatalogSources - -**Definition**: The CatalogSource represents a repository of bundles, which are collections of resources that must contain [CSVs](#ClusterServiceVersion), [CRDs](#CustomResourceDefinitions), and package definitions. There are multiple implementations of a CatalogSource backend, the current recommendation is to use a [registry image](#Index). - -**Aliases**: CatSrc(s) - -### InstallPlans - -**Definition**: The InstallPlan defines a set of resources to be created in order to install or upgrade to a specific version of a ClusterService defined by a CSV. - -**Aliases**: IP(s) - -### OperatorGroups - -**Definition**: The OperatorGroup selects a set of target namespaces in which to generate required RBAC access for its member Operators. - -**Aliases**: OG(s) - -### OperatorSources - -**Definition**: The OperatorSources are a way of pointing to external app registry namespaces that contain a catalog of operators. Applying an OperatorSource to a cluster makes the operators in that OperatorSource available for installation in that cluster. - -**Aliases**: OpSrc(s) - -### Subscriptions - -**Definition**: The Subscription defines the channel and the source of Operator updates and is used to keep the CSV updated by binding with a channel in a package. - -**Aliases**: Subs(s) - -## OLM Concepts - -### Bundle - -**Definition**: A collection of Operator [CSV](#ClusterServiceVersion), manifests, and metadata which together form a unique version of an Operator that can be installed onto the cluster. - -### Bundle Image - -**Definition**: An image of a bundle is built from operator manifests and contains exactly one [bundle](#Bundle). The bundle images are stored and distributed by OCI spec container registries such as Quay.io or DockerHub. - -### Channel - -**Definition**: The channel defines a stream of updates for an operator and is used to roll out updates for subscribers. The head points at the latest version of that channel. For example, a stable channel would have all stable versions of an operator arranged from the earliest to the latest. An operator can have several channels, and a subscription binding to a certain channel would only look for updates in that channel. - -### Channel Head - -**Definition**: Head refers to the latest known update in a particular [channel](#Channel). - -### Catalog Image - -**Definition**: A catalog image is a containerized datastore that describes a set of operator and update metadata that can be installed onto a cluster via OLM. - -**Aliases**: OPM Index - -### Dependency - -**Definition**: An Operator may have a dependency on another Operator being present in the cluster. For example, the Vault Operator has a dependency on the Etcd Operator for its data persistence layer. OLM resolves these dependencies by ensuring all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a Catalog that satisfies the required CRD API, and not related to [packages](#Packages)/[bundles](#Bundles). - -**Aliases**: Operator Dependency, GVK Dependency, API Dependency, Required CRD - -### Index - -**Definition**: The Index refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs, CRDs, etc of all versions. This index can host a history of used operators on a cluster and be maintained by adding or removing operators. - -**Aliases**: Registry DB, Catalog DB, OPM registry - -### Package - -**Definition**: A package is a directory that encloses all released history of an Operator with each version contained - in the bundle format. A released version of an Operator is described in a ClusterServiceVersion manifest alongside the CustomResourceDefinitions. - -### Registry - -**Definition**: A database which stores [Bundle Images](#Bundle-Image) of Operators, each with all of its latest/historical versions in all [channels](#Channel). - -### Upgrade Graph - -**Definition**: An upgrade graph links versions of [CSV](#ClusterServiceVersions) together, similar to the upgrade graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added. This is automatically resolved as part of [index](#Index). +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/glossary/glossary/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/how-do-i-install-my-operator-with-olm.md b/docs/how-do-i-install-my-operator-with-olm.md index 96c38b5..7300d17 100644 --- a/docs/how-do-i-install-my-operator-with-olm.md +++ b/docs/how-do-i-install-my-operator-with-olm.md @@ -1,50 +1,2 @@ -# How do I install my operator with OLM? - -[Once you've made your operator available in a catalog](openshift/coming-soon.md), [or you've chosen an operator from an existing catalog](openshift/coming-soon.md), you can install your operator by creating a Subscription to a specific channel. -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: - namespace: -spec: - channel: - name: - source: - sourceNamespace: - ``` -For example, if you want to install an operator named `my-operator`, from a catalog named `my-catalog` that is in the namespace `olm`, and you want to subscribe to the channel `stable`, your subscription yaml would look like this: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: subs-to-my-operator - namespace: olm -spec: - channel: stable - name: my-operator - source: my-catalog - sourceNamespace: olm - ``` - -Once you have the subscription yaml, `kubectl apply -f Subscription.yaml` to install your operator. - -You can inspect your Subscription with `kubectl get subs -n `. - -To ensure the operator installed successfully, check for the ClusterServiceVersion and the operator deployment in the namespace it was installed in. - -``` -$ kubectl get csv -n - -NAME DISPLAY VERSION REPLACES PHASE - Succeeded -``` -``` -$ kubectl get deployments -n -NAME READY UP-TO-DATE AVAILABLE AGE - 1/1 1 1 9m48s -``` - -If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](openshift/coming-soon.md)) to debug your installation. - \ No newline at end of file +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/install-olm.md b/docs/install-olm.md index bb6ac74..3edad20 100644 --- a/docs/install-olm.md +++ b/docs/install-olm.md @@ -1,55 +1,2 @@ -# How do I install OLM? - -The OLM is installable on Kubernetes clusters. For the following instructions to work, you must have a Kubernetes cluster running and the `kubectl` is able to communicate with the API server of that cluster. For more information about configuring `kubectl`, please visit [here](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/). - -Note: The OLM can be tested locally with a [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) cluster, currently supporting version 1.16.0. For more information see [Makefile](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Makefile). - -## Install Released OLM -For installing release versions of OLM, for example version 0.12.0, you can use the following command: - -```bash -export olm_release=0.12.0 -kubectl apply -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/${olm_release}/crds.yaml -kubectl apply -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/${olm_release}/olm.yaml -``` - -Learn more about available releases [here](https://github.com/operator-framework/operator-lifecycle-manager/releases). - -## Install From Git Repository Master Branch - -You can install OLM from the master branch of the [operator-framework/operator-lifecycle-manager](https://github.com/operator-framework/operator-lifecycle-manager/) repository with the following: - -```bash -kubectl create -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/crds.yaml -kubectl create -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/olm.yaml -``` -You can also clone the entire git repository and use the [Makefile](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Makefile) for deploying OLM locally on [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) for development purposes. - -```bash -git clone https://github.com/operator-framework/operator-lifecycle-manager.git -cd operator-lifecycle-manager -make run-local -``` - -## Verify OLM Install - -You can verify the necessary CustomResourceDefinitions are created from applying the `crds.yaml` file with the following: - -```bash -$ kubectl get crd -NAME CREATED AT -catalogsources.operators.coreos.com 2019-10-21T18:15:27Z -clusterserviceversions.operators.coreos.com 2019-10-21T18:15:27Z -installplans.operators.coreos.com 2019-10-21T18:15:27Z -operatorgroups.operators.coreos.com 2019-10-21T18:15:27Z -subscriptions.operators.coreos.com 2019-10-21T18:15:27Z -``` -You can also visualize OLM deployments from applying `olm.yaml` file with the following: - -```bash -$ kubectl get deploy -n olm -NAME READY UP-TO-DATE AVAILABLE AGE -catalog-operator 1/1 1 1 5m52s -olm-operator 1/1 1 1 5m52s -packageserver 2/2 2 2 5m43s -``` \ No newline at end of file +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/getting-started/#installing-olm-in-your-cluster for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index 8b13789..0000000 --- a/docs/intro.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/list-available-operators.md b/docs/list-available-operators.md index 96a240a..99dd434 100644 --- a/docs/list-available-operators.md +++ b/docs/list-available-operators.md @@ -1,23 +1,2 @@ -# How do I list Operators available to install? - -There is an extension API in OLM named `PackageManifest` that contains information about existing `CatalogSources`, which is essentially a repository of CSVs, CRDs, and packages that define an operator in the cluster. By querying that API, you can see the list of available operators. - -There are two different types of `CatalogSource` in OLM: global and namespaced `CatalogSource`. The global `CatalogSource` contains operators that will be available for all namespaces while namespaced `CatalogSource` only contains operators that are only available for a specific namespace. - -## PackageManifest Commands - -You can use these example commands via kubectl CLI (kubectl) to list available operators in a specific namespace. `PackageManifest` will return the union of global, which are available globally, and namespaced operators in namespace you're requesting. -```bash -$ kubectl get packagemanifest -n -``` - -The list of available operators will be displayed as an output of those above commands: -```bash -$ kubectl get packagemanifest -NAME CATALOG AGE -cassandra-operator Community Operators 26m -etcd Community Operators 26m -postgres-operator Community Operators 26m -prometheus Community Operators 26m -wildfly Community Operators 26m -``` +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/list-operators-available-to-install/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/multiarch.md b/docs/multiarch.md index 612db39..a2d987d 100644 --- a/docs/multiarch.md +++ b/docs/multiarch.md @@ -1,58 +1,2 @@ -# How do I ship an operator that supports multiple node architectures? - -It is assumed that all operators run on linux hosts, but can be configured to manage workloads on other architectures if worker nodes are available. - -Which os/arches are supported by the operator can be indicated by adding labels to the ClusterServiceVersion providing the operator. - -## Supported Labels - -Labels indicating supported os and arch are defined by: - -```yaml -labels: - operatorframework.io/arch.: supported - operatorframework.io/os.: supported -``` - -Where `` and `` are one of the values [listed here](https://github.com/golang/go/blob/master/src/go/build/syslist.go). - -## Multiple Architectures - -Some operators may support multiple node architectures or oses. In this case, multiple labels can be added. For example, an operator that support both windows and linux workloads: - -```yaml -labels: - operatorframework.io/os.windows: supported - operatorframework.io/os.linux: supported -``` - -## Defaults - -If a ClusterServiceVersion does not include an `os` label, it is treated as if it has the following label: - -```yaml -labels: - operatorframework.io/os.linux: supported -``` - - -If a ClusterServiceVersion does not include an `arch` label, it is treated as if it has the following label: - -```yaml -labels: - operatorframework.io/arch.amd64: supported -``` - -## Filtering available operators by os or arch - -Only windows: - -```sh -$ kubectl get packagemanifests -l operatorframework.io/os.windows=supported -``` - -## Caveats - -Only the labels on the [HEAD of the default channel](glossary.md#channel-head) are considered for filtering PackageManifests by label. - -This means, for example, that providing an alternate architecture for an operator in the non-default channel is possible, but will not be available for filtering in the PackageManifest API. +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/advanced-tasks/ship-operator-supporting-multiarch/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/operator-dependencies-and-requirements.md b/docs/operator-dependencies-and-requirements.md index cd72a15..3b7a388 100644 --- a/docs/operator-dependencies-and-requirements.md +++ b/docs/operator-dependencies-and-requirements.md @@ -1,48 +1,2 @@ -# Operator Dependency and Requirement Resolution - -## Overview on Dependency Principles - -OLM manages the dependency resolution and upgrade lifecycle of running operators. - -Dependencies within OLM exist when an operator will not function as intended if a second operator is not present on cluster and are often introduced when installing or updating an operator. - -OLM does not allow an operator to define a dependency on a specific version (e.g. `etcd-operator v0.9.0`) or instance (e.g. `etcd v3.2.1`) of an operator. Instead, an operator may define a dependency on a specific (Group, Version, Kind) of an API provided by a seperate operator. This encourages operator authors to depend on the interface and not the implementation; thereby allowing operators to update on individual release cycles. - -If a dependency is ever discovered, OLM will attempt to resolve said dependency by searching through known `CatalogSources` for an operator that `owns` the API. If an operator is found that `owns`the `required` API, OLM will attempt to deploy the operator that `owns` the API. If no `owner` is found, OLM will fail to deploy the operator with the dependency. - -### Similarity with Package Managers - -OLM manages operator dependency resolution very similarily to OS package managers, such as apt/dkpg and yum/rpm. However, given that operators are always running, OLM attempts to ensure that it never deploys a combination of operators that do not work with each other. - -This means that OLM will never: - -* install a set of operators that require APIs that can't be provided -* update an operator in a way that breaks another that depends upon it - -### OLM Dependency Resolution Specifics - -Dependency resolution begins when a `Subscription` is reconciled by OLM. - -When resolving a `Subscription`, OLM will look at all `Subscription` in the namespace and identify the next offering of each operator based on the upgrade graph. By updating all `Subscriptions` in the namespace, OLM avoids version deadlock that could be introduced when two operators have dependencies on each other. - -Once OLM has identified the list of operator that should be installed in the namespace, OLM will attempt to resolve any required APIs that are missing from the cluster by querying known `CatalogSources`. - -Rather than returning the first `CatalogSource` that contains the missing API, OLM will attempt to identify a prioritized `CatalogSource` - one that provided an operator that depends on the missing API. If the prioritized `CatalogSource` does not contain the API, OLM will search through the remaining `CatalogSources` in the namespace for the API. If an operator is found that provides the API, OLM will create a `Subscription` for the operator using that `CatalogSource`. - -If the required API cannot be resolved, OLM will not install operators that rely on that API. - -## Defining a Dependency - -An operator can define dependencies within its `ClusterServiceVersion (CSV)``. An operator can specify: - -* A `required` CRD by adding it to the `spec.customresourcedefinitions.required` field. -* A `required` API Service by adding it to the `spec.apiservicedefinitions.required` field. - -> Note: If your operator defines a dependency, packaging it in the same `CatalogSource` as the operator that fulfills the dependency ensures that OLM will always resolve the dependency. - -## Defining Ownership over an API - -An operator can define which APIs it owns within its CSV. An operator can specify: - -* An `owned` CRD by adding it to the `spec.customresourcedefinitions.owned` field. -* An `owned` API Service by adding it to the `spec.apiservicedefinitions.owned` field. +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/concepts/olm-architecture/dependency-resolution/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/operator-scoping.md b/docs/operator-scoping.md index aa37f0a..884b31d 100644 --- a/docs/operator-scoping.md +++ b/docs/operator-scoping.md @@ -1,168 +1,2 @@ -# Operator Scoping - -OLM runs with cluster-admin privileges and is capable of granting permissions to operators that it deploys. By default, an operator can specify any set of permission(s) in the CSV and OLM will consequently grant it to the operator. In effect, an operator can achieve cluster-scoped privilege(s) which may not always be desired. - -OLM introduces the concept of `OperatorGroups` to enable cluster admins complete control over the permissions that OLM grants operators that it deploys. An admin may create a single `OperatorGroup` in a given namespace. Any CSV created in that namespace is said to be a member operator of that `OperatorGroup`. With `OperatorGroups`, a cluster admin can: - -* Define the set of permissions that OLM may grant to member operators -* Define the set of namespaces that OLM may grant namespaced permissions in. - -## Configuring OperatorGroups - -### Scoping Member Operators to Specific Namespaces - -Using an `OperatorGroup`, a cluster admin can scope member operators' namespaced permissions to specific namespaces in two ways: - -* Using a predefined list of namespaces -* Using a label selector. - -#### Defining a set of namespaces - -The set of namespaces can be hardcoded setting the `spec.targetNamespaces` of an `OperatorGroup` like so: - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: my-group - namespace: my-namespace -spec: - targetNamespaces: - - my-namespace - - my-other-namespace - - my-other-other-namespace -``` - -In the example above, member operator will be scoped to the following namespaces: - -* my-namespace -* my-other-namespace -* my-other-other-namespace - -#### Defining a set of namespaces with a label selector - -Cluster admins may not know in advance which namespaces member operators should be scoped to. In this case, it may make sense to use a label selector to identify which namespaces permissions should be granted in. A namespace selector can be defined for an `OpearatorGroup` like so: - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: my-group - namespace: my-namespace -spec: - selector: - cool.io/prod: "true" -``` - -In the example above, member operators will be scoped to any namespaces with the `cool.io/prod: true` label. If no namespaces exist with the `cool.io/prod: true` label, OLM will fail to install any member operators. - ->Note: In the case that both a selector and a list of namespaces are provided, the selector is ignored. - -#### TargetNamespaces and their realationship to InstallModes - -When creating `OperatorGroups` it is important to keep in mind that an operator may not support all namespace configurations. For example, an operator that is designed to run at the cluster level shouldn't be expected to work in an `OperatorGroup` that defines a single targetNamespace. - -Operator authors are responsible for defining which `InstallModes` their operator supports within its `ClusterServiceVersion (CSV)`. There are four `InstallModes` that an operator can support: - -* **OwnNamespace**: If supported, the operator can be configured to watch for events in the namespace it is deployed in. -* **SingleNamespace**: If supported, the operator can be configured to watch for events in a single namespace that the operator is not deployed in. -* **MultiNamespace**: If supported, the operator can be configured to watch for events in more than one namespace. -* **AllNamespaces**: If supported, the operator can be configured to watch for events in all namespaces. - ->Note: If a CSV's spec omits an entry of InstallModeType, that type is considered unsupported unless support can be inferred by an existing entry that implicitly supports it. - -Cluster admins cannot override which `InstallModes` an operator supports, and so should understand how to create an `OperatorGroup` that supports each `InstallMode`. Let's look at an example of an `OperatorGroup` implementing each type of installMode: - -##### OwnNamespace - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: own-namespace-operator-group - namespace: own-namespace -spec: - targetNamespaces: - - own-namespace -``` - -##### SingleNamespace - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: single-namespace-operator-group - namespace: own-namespace -spec: - targetNamespaces: - - some-other-namespace -``` - -##### MultiNamespace - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: multi-namespace-operator-group - namespace: own-namespace -spec: - targetNamespaces: - - own-namespace - - some-other-namespace -``` - -##### AllNamespaces - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: all-namespaces-operator-group - namespace: own-namespace -``` - -### Scoping Member Operator Permissions - -When creating an `OperatorGroup`, cluster admins may specify a `ServiceAccount` that defines the set of permissions that may be granted to all member operators. OLM will ensure that when an operator is installed its privileges are confined to that of the `ServiceAccount` specified. - -As a result a cluster-admin can limit an operator to a pre-defined set of RBAC rules. The Operator will not be able to do anything that is not explicitly permitted by these permissions. This enables self-sufficient installation of Operators by non-cluster-admin users with a limited scope. - -#### Defining a ServiceAccount for an OperatorGroup - -A `ServiceAccount` may be defined within an `OperatorGroup` like so: - -```yaml -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: scoped-permissions-operator-group - namespace: own-namespace -spec: - serviceAccountName: member-operator-servicee-account - targetNamespaces: - - own-namespace -``` - -Any operator tied to this `OperatorGroup` will now be confined to the permission(s) granted to the specified `ServiceAccount`. If the operator asks for permission(s) that are outside the scope of the `ServiceAccount` the install will fail with appropriate error(s). - -An example of scoping an operator can be found [here](openshift/coming-soon.md). - -### Configuring the End User Experience - -### Making Operators Available - -Once a cluster admin has successfully created an `OperatorGroup`, he or she then has the opportunity to decide which operators should be offered as a part of that group. This is an important phase in configuring the cluster, as most users may not have the ability to install an operator into an `OperatorGroup`. - -A cluster admin can add an operator to an `OperatorGroup` by creating a `Subscription` in the same namespace. An operator can be added and removed from an `OperatorGroup` at anytime. - -Keep in mind that this process can be repeated for any number of `OperatorGroups`. This means that a cluster admin can decide for a set of operator to watch for events in one set of namespaces while defining a seperate set of operators that watch for events in a seperate set of namespaces. - -### Enabling a User to use an Operator - -Once a cluster admin has decided which operators are available on a cluster, it is now time to decide which user(s) may take advantage of an available operator. - -Users interact with operators by creating a resource in a namespace that an operator is watching. As such, by tuning RBAC privileges a cluster admin has complete control over the set of users that may interact with an operator along with the set of APIs that user may take advantage of. - -For example, if an operator were available that offered two APIs, a cluster admin may provide a user with full RBAC privileges over one API but not grant the user any privileges with the second API. +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/advanced-tasks/operator-scoping-with-operatorgroups/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/packaging-an-operator.md b/docs/packaging-an-operator.md index 5ba1ce9..f2ead67 100644 --- a/docs/packaging-an-operator.md +++ b/docs/packaging-an-operator.md @@ -1,241 +1,2 @@ -# How do I package an Operator for OLM? - -OLM requires you to provide metadata about your operator in order to ensure that it can be kept running safely on a cluster, and to provide information about how updates should be applied as you publish new versions of your operator. - -This is very similar to packaging software for a traditional operating system - think of the packaging step for OLM as the stage at which you make your `rpm`, `dep`, or `apk` bundle. - -## Writing your Operator Manifests - -OLM uses an api called `ClusterServiceVersion` (CSV) to describe a single instance of a version of an operator. This is the main entrypoint for packaging an operator for OLM. - -There are two important ways to think about the CSV: - - 1. Like an `rpm` or `deb`, it collects metadata about the operator that is required to install it onto the cluster. - 2. Like a `Deployment` that can stamp out `Pod`s from a template, the `ClusterServiceVersion` describes a template for the operator `Deployment` and can stamp them out. - -This is all in service of ensuring that when a user installs an operator from OLM, they can understand what changes are happening to the cluster, and OLM can ensure that installing the operator is a safe operation. - -### Starting from an existing set of operator manifests - -For this example, we'll use the example manifests from [the example memcached operator](https://github.com/operator-framework/operator-sdk-samples/tree/master/go/memcached-operator/deploy). - -These manifests consist of: - -- **CRDs** that define the APIs your operator will manage -- **Operator** (`operator.yaml`), containing the`Deployment` that runs your operator pods -- **RBAC** (`role.yaml`, `role_binding.yaml`, `service_account.yaml`) that configures the service account permissions your operator requires. - -Building a minimal `ClusterServiceVersion` from these requires transplanting the contents of the Operator definition and the RBAC definitions into a CSV. Together, your CSV and CRDs will form the package that you give to OLM to install an operator. - -#### Basic Metadata (Optional) - -Let's start with a CSV that only contains some descriptive metadata: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - annotations: - name: memcached-operator.v0.10.0 -spec: - description: This is an operator for memcached. - displayName: Memcached Operator - keywords: - - memcached - - app - maintainers: - - email: corp@example.com - name: Some Corp - maturity: alpha - provider: - name: Example - url: www.example.com - version: 0.10.0 -``` - -Most of these fields are optional, but they provide an opportunity to describe your operator to potential or current users. - -#### Installation Metadata (Required) - -The next section to add to the CSV is the Install Strategy - this tells OLM about the runtime components of your operator and their requirements. - -Here is an example of the basic structure of an install strategy: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - annotations: - name: memcached-operator.v0.10.0 -spec: - install: - # strategy indicates what type of deployment artifacts are used - strategy: deployment - # spec for the deployment strategy is a list of deployment specs and required permissions - similar to a pod template used in a deployment - spec: - permissions: - - serviceAccountName: memcached-operator - rules: - - apiGroups: - - "" - resources: - - pods - verbs: - - '*' - # the rest of the rules - # permissions required at the cluster scope - clusterPermissions: - - serviceAccountName: memcached-operator - rules: - - apiGroups: - - "" - resources: - - serviceaccounts - verbs: - - '*' - # the rest of the rules - deployments: - - name: memcached-operator - spec: - replicas: 1 - # the rest of a deployment spec -``` - -`deployments` is an array - your operator may be composed of several seperate components that should all be deployed and versioned together. - -It's also important to tell OLM the ways in which your operator can be deployed, or its `installModes`. InstallModes indicate if your operator can be configured to watch, one, some, or all namespaces. Please see the [document on install modes]() and `OperatorGroups` for more information. - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: memcached-operator.v0.10.0 -spec: - # ... - installModes: - - supported: true - type: OwnNamespace - - supported: true - type: SingleNamespace - - supported: false - type: MultiNamespace - - supported: true - type: AllNamespaces -``` - -**Using `faq` to build an install strategy from an existing deployment and rbac** - -`faq` is a wrapper around `jq` that can handle multiple input and output formats, like the yaml we're working with now. The following example requires that [faq be installed](https://github.com/jzelinskie/faq#installation) and references [the example memcached operator](https://github.com/operator-framework/operator-sdk-samples/tree/master/go/memcached-operator/deploy). - -Here is a simple `faq` script that can generate an install strategy from a single deployment: - -```sh -$ faq -f yaml '{install: {strategy: "deployment", spec:{ deployments: [{name: .metadata.name, template: .spec }] }}}' operator.yaml -``` - -If you have an existing CSV `csv.yaml` (refer to the example from Basic Metadata) and you'd like to insert or update an install strategy from a deployment `operator.yaml`, a role `role.yaml`, and a service account `service_account.yaml`, that is also possible: - -```sh -$ faq -f yaml -o yaml --slurp '.[0].spec.install = {strategy: "deployment", spec:{ deployments: [{name: .[1].metadata.name, template: .[1].spec }], permissions: [{serviceAccountName: .[3].metadata.name, rules: .[2].rules }]}} | .[0]' csv.yaml operator.yaml role.yaml service_account.yaml -``` - -#### Defining APIs (Required) - -By definition, operators are programs that can talk to the Kubernetes API. Often, they are also programs that *extend* the Kubernetes API, by providing an interface via `CustomResourceDefinition`s or, less frequently, `APIService`s. - -##### Owned APIs - -Exactly which APIs are used and which APIs are watched or owned is important metadata for OLM. OLM uses this information to determine if dependencies are met and ensure that no two operators fight over the same resources in a cluster. - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: memcached-operator.v0.10.0 -spec: - # ... - customresourcedefinitions: - owned: - # a list of CRDs that this operator owns - # name is the metadata.name of the CRD - - name: cache.example.com - # version is the version of the CRD (one per entry) - version: v1alpha1 - # spec.names.kind from the CRD - kind: Memcached -``` - -##### Required APIs - -Similarly, there is a section `spec.customresourcedefinitions.required`, where dependencies can be specified. The operators that provide those APIs will be discovered and installed by OLM if they have not been installed. - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: other-operator.v1.0 -spec: - # ... - customresourcedefinitions: - required: - # a list of CRDs that this operator requires - - name: cache.example.com - version: v1alpha1 - kind: Memcached -``` - -Dependency resolution and ownership is discussed more in depth in our [registry documentation](). - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: memcached-operator.v0.10.0 -spec: - # ... - customresourcedefinitions: - owned: - # a list of CRDs that this operator owns - # name is the metadata.name of the CRD - - name: cache.example.com - # version is the version of the CRD (one per entry) - version: v1alpha1 - # spec.names.kind from the CRD - kind: Memcached -``` - -##### NativeAPIs (recommended) - -There are often cases where you wish to depend on an API that is either provided natively by the platform (i.e. `Pod`) or sometimes by another operator that is outside the control of OLM. - -In those cases, those dependencies can be described in the CSV as well, via `nativeAPIs` - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: other-operator.v1.0 -spec: - nativeAPIs: - - group: "" - version: v1 - kind: Pod -``` - -The absence of any required `nativeAPIs` from a cluster will pause the installation of the operator, and `OLM` will write a status into the `CSV` indicating the missing APIs. - -TODO: example status - -`nativeAPIs` is an optional field, but the more information you give OLM about the context in which your operator should be run, the more informed decisions OLM can make. - -##### Extension apiservers and APIServices - -Please see the document on [extension apiservers]() if your operator does not rely on CRDs to provide its API. - -#### Operator SDK - -TODO: link to SDK csv generation - -#### Advanced and Optional features - -Please see the documentation for [advanced operator configuration]() which includes additional suggestions for further integration with OLM. +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/packaging-an-operator/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/snapshot-appr-registry.md b/docs/snapshot-appr-registry.md deleted file mode 100644 index 2e6e62f..0000000 --- a/docs/snapshot-appr-registry.md +++ /dev/null @@ -1,153 +0,0 @@ -# How do I snapshot a Quay Appregistry operator catalog? - -## What in tarnation is a _snapshot_? - -For the purposes of this document, a _snapshot_ is: - -- a point-in-time export of an Appregistry (appr) type catalog's content -- the result of converting an appr catalog to a container image type catalog -- an immutable artifact - -## When/Why would I need a snapshot? - -OLM always installs from the latest version of an appr catalog. As appr catalogs are updated, the latest versions of operators change, and older versions may be removed or altered. This behavior can cause problems maintaining reproducible installs over time. - -As of OCP 4.3, Red Hat provided operators are distributed via appr catalogs. Creating a snapshot provides a simple way to use this content without incurring the aforementioned issues. - -## Prerequisites - -- Linux -- A version `oc` that has the `oc catalog build`, such as [this one for OCP `4.3`](https://openshift-release-artifacts.svc.ci.openshift.org/4.3/) -- A container image registry that supports [Docker v2-2](https://docs.docker.com/registry/spec/manifest-v2-2/) -- [grpcurl](https://github.com/fullstorydev/grpcurl) (optional, for testing) - -## Setup - -Users should authenticate with the target image registry. By default, `oc adm catalog build` uses `~/.docker/config.json` to determine credentials. - -## Taking a snapshot - -Snapshot `redhat-operators` as `quay.io/my/redhat-operators:snapshot-0`. - -```sh -$ oc adm catalog build --appregistry-endpoint https://quay.io/cnr --appregistry-org redhat-operators --to=quay.io/my/redhat-operators:snapshot-0 -INFO[0013] loading Bundles dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 -INFO[0013] directory dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=manifests-829192605 load=bundles -INFO[0013] directory dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=3scale-operator load=bundles -INFO[0013] found csv, loading bundle dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=3scale-operator.v0.3.0.clusterserviceversion.yaml load=bundles -INFO[0013] loading bundle file dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605/3scale-operator file=3scale-operator.package.yaml load=bundle -INFO[0013] loading bundle file dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605/3scale-operator file=3scale-operator.v0.3.0.clusterserviceversion.yaml load=bundle -... -Uploading ... 244.9kB/s -Pushed sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 to quay.io/my/redhat-operators:snapshot-0 -``` - -Sometimes invalid manifests are accidentally introduced into Red Hat's catalogs, when this happens you may see some errors. - -```sh -... -INFO[0014] directory dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=4.2 load=package -W1114 19:42:37.876180 34665 builder.go:141] error building database: error loading package into db: fuse-camel-k-operator.v7.5.0 specifies replacement that couldn't be found -Uploading ... 244.9kB/s -... -``` - -These errors are usually non-fatal, and if the operator package mentioned doesn't contain an operator you plan to install or a dependency of one, then they can be ignored. - -## Testing a snapshot - -You can validate snapshot content by running it as a container and querying its gRPC API: - -Pull a snapshot image. - -```sh -$ docker pull quay.io/my/redhat-operators:snapshot-0 -... -``` - -Run the snapshot image. - -```sh -$ docker run -p -p 50051:50051 -it quay.io/my/redhat-operators:snapshot-0 -... -``` - -Query the running snapshot for available packages using `grpcurl`. - -```sh -$ grpcurl -plaintext localhost:50051 api.Registry/ListPackages -{ - "name": "3scale-operator" -} -{ - "name": "amq-broker" -} -{ - "name": "amq-online" -} -... -``` - -Get the latest bundle in a channel. - -```sh -$ grpcurl -plaintext -d '{"pkgName":"kiali-ossm","channelName":"stable"}' localhost:50051 api.Registry/GetBundleForChannel -{ - "csvName": "kiali-operator.v1.0.7", - "packageName": "kiali-ossm", - "channelName": "stable", -... -``` - -## Using a snapshot - -You can resolve OLM `Subscriptions` with a snapshot image by referencing it in a `CatalogSource`: - -Pull a snapshot image. - -```sh -$ docker pull quay.io/my/redhat-operators:snapshot-0 -... -``` - -Get the digest of the snapshot image. - -```sh -$ docker inspect --format='{{index .RepoDigests 0}}' quay.io/my/redhat-operators:snapshot-0 -quay.io/my/redhat-operators@sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 -``` - -Assuming an `OperatorGroup` exists in namespace `my-ns` that supports your operator and its dependencies, create a `CatalogSource` using the snapshot digest. - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: redhat-operators-snapshot - namespace: my-ns -spec: - sourceType: grpc - image: quay.io/my/redhat-operators@sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 - displayName: Red Hat Operators Snapshot -``` - -Create a `Subscription` that resolves the latest available `servicemeshoperator` and its dependencies from the snapshot. - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: servicemeshoperator - namespace: my-ns -spec: - source: redhat-operators-snapshot - sourceNamespace: my-ns - name: servicemeshoperator - channel: 1.0 -``` - -Updates to Red Hat's appr catalog's can be captured by a new snapshot, tested, and introduced to existing clusters by swapping out the `CatalogSource's` `spec.image` field with the new snapshot digest. - -## My snapshot build succeeded, but the final image doesn't contain any operators!? - -This can occur if the image repository specified by `--to` does not have Docker v2-2 enabled. As of November 2019, only select Quay namespaces have v2-2 enabled. The OLM team keeps a [redhat-operators snapshot repo](https://quay.io/repository/operator-framework/redhat-operators) available and manually adds snapshots upon request. If you need a new snapshot taken and do not have access to a v2-2 enabled repo, please reach out to `@olm-dev` in [#forum-operator-fw](https://coreos.slack.com/archives/C3VS0LV41). diff --git a/docs/subscriptions.md b/docs/subscriptions.md index 89c5d5c..b85e8f7 100644 --- a/docs/subscriptions.md +++ b/docs/subscriptions.md @@ -1,72 +1,2 @@ -# Subscriptions - -Subscriptions are Custom Resources that relate an operator to a CatalogSource. Subscriptions describe which channel of an operator package to subscribe to and whether to perform updates automatically or manually. If set to automatic, the Subscription ensures OLM will manage and upgrade the operator to ensure the latest version is always running in the cluster. - -Here's an example of a Subscription definition: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: my-operator - namespace: openshift-operators -spec: - channel: stable - name: my-operator - source: redhat-operators - sourceNamespace: openshift-marketplace -``` - -This Subscription object defines the name and namespace of the operator, as well as the catalog from which the operator data can be found. The channel (such as alpha, beta, or stable) helps determine which stream of the operator should be installed from the CatalogSource. - -## Manually Approving Upgrades via Subscriptions - -By default, OLM will automatically approve updates to an operator as new versions become available via a CatalogSource. When creating a subscription, it is possible to disable automatic updates by setting the `approval` field to `Manual` like so: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: my-operator - namespace: openshift-operators -spec: - channel: stable - name: my-operator - source: redhat-operators - sourceNamespace: openshift-marketplace - approval: Manual -``` - -Setting the `approval` field to manual will prevent OLM from automatically installing the operator. As such, you will need to approve the installPlan which can be done with the following commands: - -```bash -kubectl -n openshift-operators get installplans -NAME CSV APPROVAL APPROVED -install-bfmxd my-operator.v0.1.0 Manual false - -$ kubectl -n default patch installplan install-bfmxd -p '{"spec":{"approved":true}}' --type merge -installplan.operators.coreos.com/install-bfmxd patched - -$ kubectl -n openshift-operators get installplans -NAME CSV APPROVAL APPROVED -install-bfmxd my-operator.v0.1.0 Manual true -``` - -Now that the `install-bfmxd` installPlan is in the approved state, OLM will install the operator defined by the `my-operator.v0.1.0` CSV. - -When the CatalogSource is updated with a newer version of that operator in the channel you selected, a new installPlan will be created in the namespace that you installed the operator to, as shown below: - -```bash -$ kubectl -n openshift-operators get installplans -NAME CSV APPROVAL APPROVED -install-bfmxd my-operator.v0.1.0 Manual true -install-svojy my-operator.v0.2.0 Manual false -``` - -From here, you can approve `install-svojy` using the patch command shown earlier. - -With the new installPlan in the approve state, the `my-operator.v0.2.0` CSV will be deployed to the cluster and if the CSV reaches the `Succeeded` state the old CSV will be deleted. If the new CSV fails to reach the `Succeeded` state, both CSVs will continue to exist and it is up to the user to resolve the failure. In either case, OLM will not delete old installPlans as they act as a record of CSVs that were installed on your cluster. - -## How do I know when an update is available for an operator - -It is possible to identify when there is a newer version of an operator available by inspecting the status of the operator's subscription. The value associated with the `currentCSV` field is the newest version that is known to OLM, and `installedCSV` is the version that is installed on the cluster. \ No newline at end of file +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/concepts/crds/subscription/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 861fed6..be0743c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,151 +1,2 @@ -# Troubleshooting - -This document focuses on troubleshooting unexpected behavior when installing and managing operators with OLM. This document contains 3 sections where we highlight how to troubleshoot specific OLM components: - -* [Troubleshooting the `CatalogSource`](#catalogsource-troubleshooting) -* [Troubleshooting the `Subscription`](#subscription-troubleshooting) -* [Troubleshooting the `ClusterServiceVersion (CSV)`](#clusterserviceversion-troubleshooting) - -## Prereqs - -Some of the commands listed below assume that you have [yq](https://github.com/mikefarah/yq) installed on your system. While `yq` is not required, it is a useful tool when parsing yaml. You can install `yq` by following the [official installation steps](https://github.com/mikefarah/yq#install). - -## CatalogSource Troubleshooting - -### How to debug a failing CatalogSource - -The Catalog operator will constantly update the `Status` of `CatalogSources` to reflect its current state. You can check the `Status` of your `CatalogSource` with the following command: - -`$ kubectl -n my-namespace get catsrc my-catalog -o yaml | yq r - status` - ->Note: It is possible that the `Status` is missing, which suggests that the Catalog operator is encountering an issue when processing the `CatalogSource` in a very early stage. - -If the `Status` block does not provide enough information, check the [Catalog operator's logs](#how-to-view-the-catalog-operator-logs). - -If you are still unable to identify the cause of the failure, check if a pod was created for the `CatalogSource`. If a pod exists, review the pod's yaml and logs: - -```bash -$ kubectl -n my-namespace get pods -NAME READY STATUS RESTARTS AGE -my-catalog-ltdlp 1/1 Running 0 8m31s - -$ kubectl -n my-namespace get pod my-catalog-ltdlp -o yaml -... - -$ kubectl -n my-namespace logs my-catalog-ltdlp -... -``` - -### I'm not sure if a specific version of an operator is available in a CatalogSource - -First verify that the `CatalogSource` contains the operator that you want to install: - -```bash -$ kubectl -n my-namespace get packagemanifests -NAME CATALOG AGE -... -portworx My Catalog Source 14m -postgres-operator My Catalog Source 14m -postgresql My Catalog Source 14m -postgresql-operator-dev4devs-com My Catalog Source 14m -prometheus My Catalog Source 14m -... -``` - -If the operator is present, check if the version you want is available: - -`$ kubectl -n my-namespace get packagemanifests my-operator -o yaml` - -### My CatalogSource cannot pull images from a private registry - -If you are attempting to pull images from a private registry, make sure to specify a secret key in the `CatalogSource.Spec.Secrets` field. - -## Subscription Troubleshooting - -This section assumes that you have a working `CatalogSource`. - -### How to debug a failing Subscription - -The Catalog operator will constantly update the `Status` of `Subscription` to reflect its current state. You can check the `Status` of your `Subscription` with the following command: - -`$ kubectl -n my-namespace get subscriptions my-subscription -o yaml | yq r - status` - ->Note: It is possible that the `Status` is missing, which suggests that the Catalog operator is encountering an issue when processing the `Subscription` in a very early stage. - -If the `Status` block does not provide enough information, check the [Catalog operator's logs](#how-to-view-the-catalog-operator-logs). - -### A subscription in namespace X can't install operators from a CatalogSource in namespace Y - -`Subscriptions` cannot install operators provided by `CatalogSources` that are not in the same namespace unless the `CatalogSource` is created in the `olm` namespace. - -### Why does a single failing subscription cause all subscriptions in a namespace to fail? - -Each Subscription in a namespace acts as a part of a set of operators for the namespace - think of a Subscription as an entry in a python `requirements.txt`. If OLM is unable to resolve part of the set, it knows that resolving the entire set will fail, so it will bail out of the installation of operators for that particular namespace. Subscriptions are separate objects but within a namespace they are all synced and resolved together. - -## ClusterServiceVersion Troubleshooting - -### How to debug a failing CSV - -If the OLM operator encounters an unrecoverable error when attempting to install the operator the `CSV` will be placed in the `failed` phase. The OLM operator will constantly update the `Status` with useful information regarding the state of the `CSV`. You can check the `Status` of your `CSV` with the following command: - -`$ kubectl -n my-catalogsource-namespace get csv prometheusoperator.0.32.0 -o yaml | yq r - status` - ->Note: It is possible that the Status is missing, which suggests that the OLM operator is encountering an issue when processing the `CSV` in a very early stage. You should respond by reviewing the logs of the OLM operator. - -You should typically pay special attention to the information within the `status.reason` and `status.message` fields. Please look in the [failed CSV reasons](#failed-csv-reasons) - -If the `Status` block does not provide enough information, check the [OLM operator's logs](#how-to-view-the-olm-operator-logs). - -### Failed CSV Reasons - -#### Reason: NoOperatorGroup - -The `CSV` failed to install because it has been deployed in a namespace that does not include an `OperatorGroup`. For more information about `OperatorGroups` see [operator-scoping.md](operator-scoping.md). - -#### Reason: UnsupportedOperatorGroup - -The `CSV` is failing to install because it does not support he `OperatorGroup` defined in the namespace. For more information about `OperatorGroups` see [operator-scoping.md](operator-scoping.md). - -### Failed CSV Messages - -#### Messages Ending with "field is immutable" - -The `CSV` is failing because its install strategy changes some immutable field of an existing `Deployment`. This usually happens on upgrade, after an operator author publishes a new version of the operator containing such a change. In this case, the issue can be resolved by publishing a new version of the operator that uses a different `Deployment` name, which will cause OLM to generate a completely new `Deployment` instead of attempting to patch any existing one. - -## Debugging the OLM or Catalog operators - -### How to enable verbose logging on the OLM and Catalog operators - -Both the OLM and Catalog operators have `-debug` flags available that display much more useful information when diagnosing a problem. If necessary, add this flag to their deployments and perform the action that is showing undersired behavior. - -### How to view the Catalog operator logs - -To view the Catalog Operator logs, use the following commands: - -```bash -$ kubectl -n olm get pods -NAME READY STATUS RESTARTS AGE -catalog-operator-5bdc79c56b-zbqbl 1/1 Running 0 5m30s -olm-operator-6999db5767-5r5zs 1/1 Running 0 5m31s -operatorhubio-catalog-ltdlp 1/1 Running 0 5m28s -packageserver-5c76df75bb-mq4qd 1/1 Running 0 5m26s - -$ kubectl -n olm logs catalog-operator-5bdc79c56b-zbqbl -... -``` - -### How to view the OLM operator logs - -To view the OLM Operator logs, use the following commands: - -```bash -$ kubectl -n olm get pods -NAME READY STATUS RESTARTS AGE -catalog-operator-5bdc79c56b-zbqbl 1/1 Running 0 5m30s -olm-operator-6999db5767-5r5zs 1/1 Running 0 5m31s -operatorhubio-catalog-ltdlp 1/1 Running 0 5m28s -packageserver-5c76df75bb-mq4qd 1/1 Running 0 5m26s - -$ kubectl -n olm logs olm-operator-6999db5767-5r5zs -... -``` +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/troubleshooting/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/uninstall-an-operator.md b/docs/uninstall-an-operator.md index 10ce0bf..3be4470 100644 --- a/docs/uninstall-an-operator.md +++ b/docs/uninstall-an-operator.md @@ -1,43 +1,2 @@ -# How to uninstall an Operator? - -In order to uninstall an operator, you need to delete the following resources: - -- Subscription -- ClusterServiceVersion (CSV) - -Both `Subscription` and `CSV` are namespaced objects meaning you need to delete a `Subscription` and a `CSV` in a specific namespace where you install the operator into. - -## Delete a Subscription - -If you wish to look up a list of `Subscription` in a specific namespace to see which `Subscription` you want to delete, you can use the following `kubectl` command: -```bash -$ kubectl get subscription -n -``` - -You can delete the `Subscription` in the namespace that the operator was installed into using this command: -```bash -$ kubectl delete subscription -n -``` - -## Delete a ClusterServiceVersion (CSV) - -If you wish to look up a list of `ClusterServiceVersion` in a specific namespace to see which `ClusterServiceVersion` you need to delete, you can use the example `kubectl` command: - -```bash -$ kubectl get clusterserviceversion -n -``` - -You can delete the `ClusterServiceVersion` in the namespace that the operator was installed into using this command: - -```bash -$ kubectl delete clusterserviceversion -n -``` - -By deleting `ClusterServiceVersion`, it will delete the operator's resources that OLM created for the operator such as deployment, pod(s), RBAC, and others. However, `CustomResourceDefinition` (CRD), that is installed by the operator, won't get deleted during uninstalling process. Deleting `CRD` will resolve into deleting all instances of that `CRD` which may be used by other operators. `CRD` can be deleted manually if needed. Furthermore, deleting a `CSV` also deletes any corresponding CSVs that OLM "Copied" into other namespaces watched by the operator. - -Alternatively, you can delete both `Subscription` and its `CSV` using a sequence of commands: -```bash -$ CSV=kubectl delete subscription -n -o json | jq '.status.installedCSV' -$ kubectl delete subscription -n -$ kubectl delete csv $CSV -n -``` +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/uninstall-operator/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/uninstall-olm.md b/docs/uninstall-olm.md index 9ae0b8a..5abb4d1 100644 --- a/docs/uninstall-olm.md +++ b/docs/uninstall-olm.md @@ -1,71 +1,2 @@ -# How do I uninstall OLM? - -You can symmetrically uninstall OLM as you did to install it. Specifically all OLM resources in [crds.yaml](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/deploy/upstream/quickstart/crds.yaml) and [olm.yaml](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/deploy/upstream/quickstart/olm.yaml) should be deleted. The `apiservices` should be removed as the first step, preventing it from becoming a dangling resource. - -Uninstalling OLM does not necessarily clean up the operators it maintained. Please clean up installed operator resources before uninstalling OLM, especially for resources that do not have an owner reference. - -## Uninstall Released OLM - -For uninstalling release versions of OLM, you can use the following commands: - -```bash -export OLM_RELEASE= -kubectl delete apiservices.apiregistration.k8s.io v1.packages.operators.coreos.com -kubectl delete -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/${OLM_RELEASE}/crds.yaml -kubectl delete -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/${OLM_RELEASE}/olm.yaml -``` - -> NOTE: You can identify which version of OLM you are using by inspecting the version of the packageserver CSV. - -> ```bash -> export OLM_NAMESPACE= -> kubectl -n $OLM_NAMESPACE get csvs -> NAME DISPLAY VERSION REPLACES PHASE -> packageserver Package Server 0.13.0 Succeeded -> ``` - -## Uninstall From Git Repository Master Branch - -You can also uninstall OLM from the master branch of the [operator-framework/operator-lifecycle-manager](https://github.com/operator-framework/operator-lifecycle-manager/) repository with the following: - -```bash -kubectl delete apiservices.apiregistration.k8s.io v1.packages.operators.coreos.com -kubectl delete -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/crds.yaml -kubectl delete -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/olm.yaml -``` - -## Verify OLM Uninstall - -Primarily, you can check that OLM has been uninstalled by checking the OLM namespace. - -```bash -kubectl get namespace $OLM_NAMESPACE -Error from server (NotFound): namespaces "$OLM_NAMESPACE" not found -``` - -More specifically, you can verify that OLM has been uninstalled successfully by making sure that OLM **owned** `CustomResourceDefinitions` are removed: - -```bash -kubectl get crd | grep operators.coreos.com -``` - -You can also check that the OLM `deployments` are terminated: - -```bash -kubectl get deploy -n $OLM_NAMESPACE -No resources found. -``` - -The `role` and `rolebinding` in the OLM namespace are removed: - -```bash -kubectl get role -n $OLM_NAMESPACE -No resources found. -``` - -```bash -kubectl get rolebinding -n $OLM_NAMESPACE -No resources found. -``` - -At last, the OLM namespace should also be terminated. +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/uninstall-olm/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/validate-package.md b/docs/validate-package.md index 0811ee7..872fb4b 100644 --- a/docs/validate-package.md +++ b/docs/validate-package.md @@ -1,88 +1,2 @@ -# How do I validate the package? - -Once you've [created your operator's package manifests](packaging-an-operator.md), you will want to ensure that your package is valid and in the correct format. To ensure this, you should take several steps to ensure that your package can be used to install your operator in OLM. We will publish the package into a catalog, install that catalog onto a Kube cluster, and then install the operator onto that cluster. If all of that succeeds and your operator is behaving as expected, your package is valid. - -## Linting - -You can perform some basic static verification on your package by using [`operator-courier`](https://github.com/operator-framework/operator-courier). - -``` -$ pip3 install operator-courier -$ operator-courier verify manifests/my-operator-package -``` - -You can also use `operator-courier` to verify that your operator will be displayed properly on [OperatorHub.io](https://operatorhub.io/). - -``` -$ operator-courier verify --ui_validate_io manifests/my-operator-package -``` - -## Add your package to a catalog - -The [operator-registry project](https://github.com/operator-framework/operator-registry) defines a format for storing sets of operators and exposing them to make them available on a cluster. As part of adding your package to an operator-registry catalog, the operator-registry tools will verify that your operator is packaged properly ("Does it have a valid CSV of the correct format?", "Does my CRD properly reference my CSVs?", etc.). The simplest way to test that your package can be added to a catalog is by actually attempting to create a catalog that includes your operator. - -To create a catalog that includes your package, simply build a container image that uses the operator-registry command line tools to generate a registry and serve it. For example, create a file in the root of your project called `registry.Dockerfile` - -```Dockerfile -FROM quay.io/operator-framework/upstream-registry-builder as builder - -COPY manifests manifests -RUN ./bin/initializer -o ./bundles.db - -FROM scratch -COPY --from=builder /build/bundles.db /bundles.db -COPY --from=builder /build/bin/registry-server /registry-server -COPY --from=builder /bin/grpc_health_probe /bin/grpc_health_probe -EXPOSE 50051 -ENTRYPOINT ["/registry-server"] -CMD ["--database", "bundles.db"] -``` - -This Dockerfile assumes that your package is in a directory called `./manifests/` similar to [this example](https://github.com/operator-framework/operator-registry/tree/master/manifests). It copies your manifests into the builder image, runs `initializer`, then copies the output into the final scratch image and defines the run command to serve the operator-registry. - -Then just use your favorite container tooling to build the container image and push it to a registry: - -``` -docker build -t example-registry:latest -f registry-Dockerfile . -docker push example-registry:latest -``` - -Your catalog is published and we are ready to use it on your cluster. - -## Install your operator - -Now that you have created an operator-registry image that hosts your operator's package, add that catalog to your cluster: - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: example-manifests - namespace: your-namespace -spec: - sourceType: grpc - image: example-registry:latest -``` - -This will cause OLM to pull your image and create a pod in the designated namespace (`your-namespace`) that hosts your package. Your Catalog is now installed onto your cluster and your package is available! - -Once the catalog has been loaded, your Operators package definitions are read by the `package-server`, a component of OLM. Watch your Operator packages become available: - -``` -$ kubectl get packagemanifests -n your-namespace - -NAME AGE -your-operator 13m -``` - -Once loaded, you can query a particular package for its Operators that it serves across multiple channels. To obtain the default channel run: - -``` -$ kubectl get packagemanifests your-operator -o jsonpath='{.status.defaultChannel}' -n your-namespace - -alpha -``` - -With this information, the operators package name, the channel and the name and namespace of your catalog you can now [install your operator with OLM](how-do-i-install-my-operator-with-olm.md) - -Now that your operator is installed from your package, poke around and ensure that it is working as you expect. If so, your package is valid! +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/validate-package/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/what-does-olm-enable.md b/docs/what-does-olm-enable.md deleted file mode 100644 index b68df56..0000000 --- a/docs/what-does-olm-enable.md +++ /dev/null @@ -1,3 +0,0 @@ -# What does OLM enable me to do? - -OLM enables management of operators in a cluster. diff --git a/docs/what-is-an-operator.md b/docs/what-is-an-operator.md deleted file mode 100644 index ddda53b..0000000 --- a/docs/what-is-an-operator.md +++ /dev/null @@ -1,2 +0,0 @@ -# What is an Operator? - diff --git a/docs/when-to-update-my-operator.md b/docs/when-to-update-my-operator.md index 61ecc96..4c17386 100644 --- a/docs/when-to-update-my-operator.md +++ b/docs/when-to-update-my-operator.md @@ -1,26 +1,2 @@ -# When do I need to update my operator - -When you install an operator from a catalog such as [quay.io/operator-framework/upstream-community-operator](https://quay.io/repository/operator-framework/upstream-community-operators), updated versions of one of more operators are pushed to the container image by rebuilding the catalog. If you have an older image of the catalog in your cluster, you can get the updates to your operators by fetching the latest release of the catalog's container image. - -If the image used to build the `Catalogsource` uses a versioned tag, update the tag version of the image to fetch updates to operators in the `Catalogsource`. - -For example: - -``` -$ oc get catsrc operatorhubio-catalog -n olm -o yaml | grep image: - - image: quay.io/operator-framework/upstream-community-operators:0.0.1 - -$ kubectl patch catsrc operatorhubio-catalog -n olm --type=merge -p '{"spec": {"image": "quay.io/operator-framework/upstream-community-operators:0.0.2"}}' - -``` - -If the image used to build the `Catalogsource` uses the `latest` tag, simply delete the pod corresponding to the `CatalogSource`. When the pod is recreated, it will be recreated with the latest image of the catalog, which will contain updates to the operators in that catalog. - -For example: - -``` -$ kubectl delete pods -n olm -l olm.catalogSource=operatorhubio-catalog - -``` -The operators that were installed from the catalog will be updated automatically or manually, depending on the value of `installPlanApproval` in the Subscription for the operator. For more information on approving manual updates to operators, please see [How do I approve an update?](openshift/coming-soon.md) \ No newline at end of file +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/tasks/update-your-operator/ for the latest on this doc. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs diff --git a/docs/why-olm.md b/docs/why-olm.md deleted file mode 100644 index a39b425..0000000 --- a/docs/why-olm.md +++ /dev/null @@ -1 +0,0 @@ -# Why would I use OLM? \ No newline at end of file diff --git a/index.md b/index.md index d79cb97..9f15250 100644 --- a/index.md +++ b/index.md @@ -1,70 +1,2 @@ -# Operator Lifecycle Book - -- [Introduction](docs/intro.md) - -- [Glossary](docs/glossary.md) - -## Foundational Concepts - -- [What is an Operator?](docs/what-is-an-operator.md) -- [Why would I use OLM?](docs/openshift/coming-soon.md) -- [What does OLM enable?](docs/what-does-olm-enable.md) -- [Operators on cluster](docs/openshift/coming-soon.md) - -## Under the hood - -- [Operands](docs/openshift/coming-soon.md) -- [Operator bundles](docs/openshift/coming-soon.md) -- [Operator catalogs](docs/openshift/coming-soon.md) -- [Subscriptions](docs/subscriptions.md) -- [Operator dependencies and requirements](docs/operator-dependencies-and-requirements.md) -- [Operator update graphs and channels](docs/openshift/coming-soon.md) -- [Operator versioning and release strategies](docs/openshift/coming-soon.md) -- [Operand support matrices](docs/openshift/coming-soon.md) -- [Operator install modes](docs/openshift/coming-soon.md) -- [Operator scoping](docs/operator-scoping.md) - -## Basic Use Cases - -- [How do I install OLM?](docs/install-olm.md) -- [How do I package my Operator for OLM?](docs/packaging-an-operator.md) -- [How do I validate the package?](docs/validate-package.md) -- [How do I make my Operator part of a catalog?](docs/openshift/coming-soon.md) -- [How do I install my Operator with OLM?](docs/how-do-i-install-my-operator-with-olm.md) -- [How do I list Operators available to install?](docs/list-available-operators.md) -- [How do I uninstall an Operator?](docs/uninstall-an-operator.md) -- [How do I discover the presence/availability of an Operator?](docs/discover-operator-presence.md) -- [How do I uninstall OLM?](docs/uninstall-olm.md) - -## Advanced Use Cases - -- [When do I need to update my Operator?](docs/when-to-update-my-operator.md) -- [How do I create an updated version of my Operator?](docs/openshift/coming-soon.md) -- [How do I test an update before shipping?](docs/openshift/coming-soon.md) -- [How do I ship an updated version of my Operator?](docs/openshift/coming-soon.md) -- [How do I approve an update?](docs/openshift/coming-soon.md) -- [How do I scope down an Operator?](docs/openshift/coming-soon.md) -- [How can I install an Operator when I am not cluster admin?](docs/openshift/coming-soon.md) -- [How do I rely on other Operators with my Operator?](docs/openshift/coming-soon.md) -- [How can I configure / customize my Operator deployment?](docs/openshift/coming-soon.md) -- [How can I set / override defaults to amend runtime behavior of my Operator?](docs/openshift/coming-soon.md) -- [What annotations can I use to drive UIs?](docs/openshift/coming-soon.md) -- [How do I change which users are able to use an Operator?](docs/openshift/coming-soon.md) -- [How do I “hide” particular CRDs not intended for consumption by an end-user?](docs/openshift/coming-soon.md) -- [How do I ship webhooks?](docs/openshift/coming-soon.md) -- [When and how should a running Operator express that it is not upgradeable?](docs/openshift/coming-soon.md) -- [When should an Operator upgrade its Operands?](docs/openshift/coming-soon.md) -- [How should an Operator Author create and package an Operator for a singleton operand?](docs/openshift/coming-soon.md) -- [How do I snapshot a Quay Appregistry operator catalog?](docs/snapshot-appr-registry.md) -- [How do I ship an operator that supports multiple node architectures?](docs/multiarch.md) - -## Troubleshooting - -- [Troubleshoot OLM installation](docs/openshift/coming-soon.md) -- [Troubleshoot operator installation with OLM](docs/troubleshooting.md) - -## OLM on OCP (OpenShift Container Platform) - -- [FAQ](docs/openshift/faq.md) -- [Important changes by OCP release](docs/openshift/important-changes-by-release.md) -- [Operator Marketplace](docs/openshift/operator-marketplace.md) +This repo is deprecated. Please checkout https://olm.operatorframework.io/docs/ for the latest docs. +To contribute new docs, please checkout https://github.com/operator-framework/olm-docs