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

refine install and dependency docs #21

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

refine install and dependency docs #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1149a32
refine install and dependency docs
dmesser Dec 2, 2019
06a8d68
fix broken links
dmesser Dec 2, 2019
1113a86
Merge branch 'master' into doc-improvements
ecordell Jan 23, 2020
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
2 changes: 1 addition & 1 deletion docs/discover-operator-presence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Checking the presence of custom installed operators in the cluster is simply a m
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](https://) to debug your installation.
If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](troubleshooting.md) to debug your installation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could link to (troubleshooting.md#clusterserviceversion-troubleshooting) to link to the more relevant section instead of the entire doc.


## Finding available operators
Operators are available from a variety of sources, or catalogs. Some catalogs are bundled in the default installation of
Expand Down
167 changes: 152 additions & 15 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,6 +1,17 @@
# How do I install my operator with OLM?
# How do I install my operator with OLM?

[Once you've made your packaged operator available in a catalog](packaging-an-operator.md) it will appear in the `packagemanifest` list from which the Operators to install are selected. See [How do I list available Operators](list-available-operators.md#information-relevant-for-installation) how to retrieve the required information from the `PackageServer` in order start an installation of an Operator.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following sentence does not read well:

See [How do I list available Operators] how to retrieve...


## Install with automatic updates enabled

First, retrieve the package name, channel and catalog name and catalog source namespace from the `packagemanifest` of the desired Operator to install.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: package name, channel, CatalogSource name, and CatalogSource namespace from the packagemanifest...


```bash
$ kubectl describe packagemanifest my-operator
```

With this information a `Subscription` object can be created. This represents the intent to install an Operator from a particular catalog and keep it updated throughout the life cycle of the Operator via newly released version that got subsequently added to the referenced catalog.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend changing

This represents the intent to install an Operator from a particular catalog and keep it updated throughout the life cycle of the Operator via newly released version that got subsequently added to the referenced catalog.

to

A subscription represents the desire to install an Operator from a particular catalog and keep it updated as new versions are subsequently added to the referenced catalog.

or somethings along those lines.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe even

With this information, a Subscription to an operator can be created.

instead of

With this information a Subscription object can be created.

And in @awgreene 's suggestion:

A subscription represents the desire to install an Operator from a particular catalog and keep it updated as new versions are subsequently added to the referenced catalog.

if we tweak it to

A subscription represents the desire to install an Operator from a particular catalog, and subscribe to updated version of the operators as they are subsequently added to the catalog.

then if could read like more of a user facing doc than dev facing doc.


[Once you've made your operator available in a catalog](https://), [or you've chosen an operator from an existing catalog](https:// ), you can install your operator by creating a Subscription to a specific channel.
```yaml
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
Expand All @@ -12,8 +23,11 @@ spec:
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:
```

The `spec.channel` property can also be omitted in which case the default channel will be picked. Optionally you can also define `spec.startingCSV` to denote that you want to install a specific version of your Operator and not the latest.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we highlight behavior when specifying spec.startingCSV with automatic approval? My concern is that users will set a startingCSV expecting that the specified version will persist on cluster and be surprised when it is updated.


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
Expand All @@ -28,23 +42,146 @@ spec:
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>`.
Once you have the YAML, `kubectl apply -f subscription.yaml` to install your operator.

To ensure the operator installed successfully, check for the ClusterServiceVersion and the operator deployment in the namespace it was installed in.
You can inspect your `Subscription` with `kubectl describe subs <name-of-your-subscription> -n <namespace>`.

```yaml
k describe subs subs-to-my-operator -n olm
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we want to say $ kubectl instead of k?

Name: subs-to-my-operator
Namespace: olm
Labels: <none>
Annotations: <none>
API Version: operators.coreos.com/v1alpha1
Kind: Subscription
Metadata:
Creation Timestamp: 2019-11-19T13:54:51Z
Generation: 1
Resource Version: 1787
Self Link: /apis/operators.coreos.com/v1alpha1/namespaces/operators/subscriptions/subs-to-my-operator
UID: 2864cc19-0ad4-11ea-8c0e-aa8cc6bce8d3
Spec:
Channel: stable
Name: my-operator
Source: my-catalog
Source Namespace: olm
Status:
Catalog Health:
Catalog Source Ref:
API Version: operators.coreos.com/v1alpha1
Kind: CatalogSource
Name: my-catalog
Namespace: olm
Resource Version: 787
UID: 674c52e3-0ad2-11ea-8c0e-aa8cc6bce8d3
Healthy: true
Last Updated: 2019-11-19T13:54:51Z
Conditions:
Last Transition Time: 2019-11-19T13:54:51Z
Message: all available catalogsources are healthy
Reason: AllCatalogSourcesHealthy
Status: False
Type: CatalogSourcesUnhealthy
Current CSV: my-operator.v1.15.0
Install Plan Ref:
API Version: operators.coreos.com/v1alpha1
Kind: InstallPlan
Name: install-4xhbl
Namespace: operators
Resource Version: 1744
UID: 286e5546-0ad4-11ea-8c0e-aa8cc6bce8d3
Installed CSV: my-operator.v1.15.0
Installplan:
API Version: operators.coreos.com/v1alpha1
Kind: InstallPlan
Name: install-4xhbl
Uuid: 286e5546-0ad4-11ea-8c0e-aa8cc6bce8d3
Last Updated: 2019-11-19T13:54:55Z
State: AtLatestKnown
Events: <none>
```
$ kubectl get csv -n <namespace-operator-was-installed-in>

The `Subscription` has successfully deployed the Operator when the `status.state` property reaches `AtLatestKnown`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this always true? If the CSV reaches a Failed state, will the Subscription not reach AtLatestKnow?


You can verify that the Operator is deployed by checking the `ClusterServiceVersion` (CSV) object in the same namespace where the `Subscription` was placed in. The name of the CSV is referenced in `status.installedCSV` of the `Subscription`:

```bash
$ kubectl get csv my-operator.v1.15.0 -n olm

NAME DISPLAY VERSION REPLACES PHASE
<name-of-csv> <operator-name> <version> <csv-of-previous-version> Succeeded
my-operator.v1.15.0 My Operator 1.15.0 my-operator.v1.14.0 Succeeded
```

If the the CSV has transitioned to the _Succeeded_ phase the Operator deployment was successful. You inspect it manually like so:

```bash
$ kubectl get deployments -n olm

NAME READY UP-TO-DATE AVAILABLE AGE
my-operator 1/1 1 1 9m48s
```
$ 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](troubleshooting.md) to debug your installation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above about the (troubleshooting.md#clusterserviceversion-troubleshooting).


## Install with manual updates

It is also possible to create a `Subscription` that will not automatically install updates as soon as they appear in the catalog. For this the `spec.installPlanApproval` property can be set to `Manual` instead of the default `Automatic`:

```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
installPlanApproval: Manual
```

If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](https://) to debug your installation.

The `Subscription` will not immediately cause the Operator to be deploy by creating a CSV this time. Instead it will remain in a pending state:

```bash
$ kubectl get subscriptions subs-to-my-operator -n operators -o custom-columns=NAME:.metadata.name,NAMESPACE:.metadata.namespace,STATUS:.status.state,INSTALLPLAN:.status.installPlanRef.name

NAME NAMESPACE STATUS INSTALLPLAN
my-operator olm UpgradePending install-q4fmf
```

An `InstallPlan` object has been created as a result of the `Subscription` getting processed. This also happens when no approval method is selected but it now presents an opportunity to manually approve the Operator installation.

```bash
$ kubectl get installplan install-q4fmf -n olm

NAME CSV APPROVAL APPROVED
install-q4fmf my-operator.v1.15.0 Manual false
```

You can also inspect this objects `status.plan` section to get a preview of the resources that will be deloyed as part of this Operator.

You can then either interactively set the `spec.approved` property of the `InstallPlan` to `true` or _patch_ the object like so:

```bash
kubectl patch installplan install-q4fmf -n olm --type merge -p '{"spec":{"approved":true}}'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we get rid of the "What do I approve an update?" doc too if we're putting this information here?

installplan.operators.coreos.com/install-q4fmf patched
```

Now the `InstallPlan` will be processed by OLM, creating the objects that ship as part of the Operator and eventually create the `ClusterServiceVersion` to represent the deployed Operator:

```bash
$ kubectl get csv -n olm

NAME DISPLAY VERSION REPLACES PHASE
my-operator.v1.15.0 My Operator 1.15.0 my-operator.v1.14.0 Succeeded
```

If the the CSV has transitioned to the _Succeeded_ phase the Operator deployment was successful. You inspect it manually like so:

```bash
$ kubectl get deployments -n olm

NAME READY UP-TO-DATE AVAILABLE AGE
my-operator 1/1 1 1 9m48s
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we highlight that a new installPlan for the next available version will be created when available? This will give users an idea how to perform a manual update.

30 changes: 29 additions & 1 deletion docs/install-olm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,32 @@ 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
```
```

## Verify The Default Catalog

OLM ships with a default catalog of packaged Operatrs. To verify that it loaded correctly run

```bash
$ kubectl get catalogsource -n olm
NAME DISPLAY TYPE PUBLISHER AGE
operatorhubio-catalog Community Operators grpc OperatorHub.io 13s
```

You inspect the catalog contents by listing all the `packagemanifests` that ship with it:

```bash
kubectl get packagemanifests
NAME CATALOG AGE
akka-cluster-operator Community Operators 84s
anchore-engine Community Operators 84s
appsody-operator Community Operators 84s
aqua Community Operators 84s
atlasmap-operator Community Operators 84s
aws-service Community Operators 84s
awss3-operator-registry Community Operators 84s
banzaicloud-kafka-operator Community Operators 84s
[...]
```

You can now proceed to either [install an Operator](./how-do-i-install-my-operator-with-olm.md) or add your own catalog.
65 changes: 59 additions & 6 deletions docs/list-available-operators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
# 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 is an extension API in OLM named `PackageManifest` that contains information about the content served by `CatalogSources`, which is essentially a repository of CSVs, CRDs, and packages that define a operator in the cluster. By querying that API, you can see the list of available operators.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a operator

This should be:

an operator


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.
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. Therefore the list of `packagemanifests` can differ depending on from which namespace it has been executed.

## PackageManifest Commands
By default, OLM ships with the namespace `olm` configured the place where global catalogs are stored. The content of these catalogs are visible in all namespaces of the cluster:

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>
$ kubectl get catalogsources -n olm

NAME DISPLAY TYPE PUBLISHER AGE
operatorhubio-catalog Community Operators grpc OperatorHub.io 11m
```

The list of available operators will be displayed as an output of those above commands:
## PackageManifest Commands

You can use these example commands via kubectl CLI (kubectl) to list operators available to install. `PackageManifest` will return the union of global, which are available globally, and namespaced operators in namespace you're requesting.

The list of available operators will be displayed as an output:

```bash
$ kubectl get packagemanifest
NAME CATALOG AGE
Expand All @@ -21,3 +28,49 @@ postgres-operator Community Operators 26m
prometheus Community Operators 26m
wildfly Community Operators 26m
```

If there are no `CatalogSource` objects present in the current namespace of the command above the list will contain all Operators found in global catalogs. To include Operators available to install from namespace catalogs simply supply it with the `kubectl` command:

```bash
$ kubectl get packagemanifests

NAME CATALOG AGE
...
my-operator My Catalog 31m
...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You used [...] above to imply that additional output existed. Please chose a single format.

```
Comment on lines +32 to +41
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As someone that has worked with OLM before this is clear, but it may not be clear to users unfamiliar with OLM.


## Information relevant for installation

From the `packagemanifest` of an Operator you can discover available update channels and latest version like so:

```bash
$ kubectl describe packagemanifest my-operator

Name: my-operator
Namespace: default
Labels: catalog=operatorhubio-catalog
catalog-namespace=olm
provider=CNCF
provider-url=
Annotations: <none>
API Version: packages.operators.coreos.com/v1
Kind: PackageManifest
Metadata:
Creation Timestamp: 2019-11-19T13:42:18Z
Self Link: /apis/packages.operators.coreos.com/v1/namespaces/default/packagemanifests/my-operator
Spec:
Status:
Catalog Source: operatorhubio-catalog
Catalog Source Display Name: Community Operators
Catalog Source Namespace: olm
Catalog Source Publisher: OperatorHub.io
Channels:
Current CSV: my-operator.v1.15.0
[...]
Name: stable
Default Channel: stable
Package Name: jaeger
```

This will also show you information about the catalog object from which this Operator is served. Note that only the latest version in `status.channels.currentCSV` will be shown.
15 changes: 8 additions & 7 deletions docs/operator-dependencies-and-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Dependencies within OLM exist when an operator will not function as intended if

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

Expand All @@ -23,20 +23,21 @@ This means that OLM will never:

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.
When resolving a `Subscription`, OLM will look at the Operator metadata (specified in its `ClusterServiceVersion`) in order to determine required APIs either from the cluster itself or other Operators (via CRDs or APIServices). Once OLM has identified the list of Operators that should be installed it will create `Subscriptions` for those in the same namespace.

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`.
Throughout the existence of a `Subscription`, OLM will look at all `Subscription` objects in the namespace and detect available updates of each operators. By looking at all `Subscriptions` in the namespace at once, OLM avoids version deadlock that could be introduced when two operators have dependencies on each other.

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`.
In case multiple Operators serve a required API, rather than using the first match, OLM searches `CatalogSources` in a specific order. First is the same catalog that contains the Operator stating the dependency, followed by other catalogs in the same namespace as the required `Subscription` and then finally all remaining `CatalogSources` objects in other namespaces of the cluster.

If the required API cannot be resolved, OLM will not install operators that rely on that API.
If are required API cannot be resolved or found, OLM will not install operators that rely on that API.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I don't understand why we changed the to are...


## 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.
* A `required` CRD by adding it to the `spec.customresourcedefinitions.required` list.
* A `required` API Service by adding it to the `spec.apiservicedefinitions.required` list.
* A `required` Cluster-provided API by adding it to the `spec.nativeapis` 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.

Expand Down
Loading