diff --git a/docs/discover-operator-presence.md b/docs/discover-operator-presence.md index 1978ac4..53c0d10 100644 --- a/docs/discover-operator-presence.md +++ b/docs/discover-operator-presence.md @@ -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. ## Finding available operators Operators are available from a variety of sources, or catalogs. Some catalogs are bundled in the default installation of 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 a664543..1774688 100644 --- a/docs/how-do-i-install-my-operator-with-olm.md +++ b/docs/how-do-i-install-my-operator-with-olm.md @@ -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. + +## 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. + +```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. -[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 @@ -12,8 +23,11 @@ spec: 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: + ``` + +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. + +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 @@ -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 -n `. +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 -n `. +```yaml +k describe subs subs-to-my-operator -n olm +Name: subs-to-my-operator +Namespace: olm +Labels: +Annotations: +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: ``` -$ kubectl get csv -n + +The `Subscription` has successfully deployed the Operator when the `status.state` property reaches `AtLatestKnown`. + +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 - 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 -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](troubleshooting.md) to debug your installation. + +## 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. - \ No newline at end of file +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}}' +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 +``` \ No newline at end of file diff --git a/docs/install-olm.md b/docs/install-olm.md index bb6ac74..dc25e5f 100644 --- a/docs/install-olm.md +++ b/docs/install-olm.md @@ -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 -``` \ No newline at end of file +``` + +## 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. \ No newline at end of file diff --git a/docs/list-available-operators.md b/docs/list-available-operators.md index 96a240a..36b5c3e 100644 --- a/docs/list-available-operators.md +++ b/docs/list-available-operators.md @@ -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. -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 +$ 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 @@ -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 +... +``` + +## 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: +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. \ No newline at end of file diff --git a/docs/operator-dependencies-and-requirements.md b/docs/operator-dependencies-and-requirements.md index cd72a15..d8068c9 100644 --- a/docs/operator-dependencies-and-requirements.md +++ b/docs/operator-dependencies-and-requirements.md @@ -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 @@ -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. ## 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. diff --git a/docs/operator-scoping.md b/docs/operator-scoping.md index ba6a825..af14f76 100644 --- a/docs/operator-scoping.md +++ b/docs/operator-scoping.md @@ -147,7 +147,7 @@ spec: 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]("https://operator-framework.github.io/olm-book/docs/how-do-i-scope-down-an-operator). +An example of scoping an operator can be found [here](./). ### Configuring the End User Experience