Skip to content
This repository was archived by the owner on Aug 2, 2021. It is now read-only.

Deprecate olm-book repo #44

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Deprecate olm-book repo #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 2 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!
32 changes: 2 additions & 30 deletions docs/discover-operator-presence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <operator name>`. 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
94 changes: 2 additions & 92 deletions docs/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
52 changes: 2 additions & 50 deletions docs/how-do-i-install-my-operator-with-olm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: <name-of-your-subscription>
namespace: <namespace-you-want-your-operator-installed-in>
spec:
channel: <channel-you-want-to-subscribe-to>
name: <name-of-your-operator>
source: <name-of-catalog-operator-is-part-of>
sourceNamespace: <namespace-that-has-catalog>
```
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 <name-of-your-subscription> -n <namespace>`.

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 <namespace-operator-was-installed-in>

NAME DISPLAY VERSION REPLACES PHASE
<name-of-csv> <operator-name> <version> <csv-of-previous-version> Succeeded
```
```
$ kubectl get deployments -n <namespace-operator-was-installed-in>
NAME READY UP-TO-DATE AVAILABLE AGE
<name-of-your-operator> 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.

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
57 changes: 2 additions & 55 deletions docs/install-olm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
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
1 change: 0 additions & 1 deletion docs/intro.md
View file
Open in desktop

This file was deleted.

25 changes: 2 additions & 23 deletions docs/list-available-operators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <namespace>
```

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
60 changes: 2 additions & 58 deletions docs/multiarch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.<GOARCH>: supported
operatorframework.io/os.<GOOS>: supported
```

Where `<GOARCH>` and `<GOOS>` 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
Loading