diff --git a/content/en/docs/Concepts/crds/installplan.md b/content/en/docs/Concepts/crds/installplan.md index 3d8195b9..f0e0e336 100644 --- a/content/en/docs/Concepts/crds/installplan.md +++ b/content/en/docs/Concepts/crds/installplan.md @@ -8,3 +8,19 @@ This section is under construction. {{% /alert %}} An 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. + + +InstallPlan can be created in two ways: +1. Users can also create an InstallPlan resource directly, containing the names of the desired ClusterServiceVersions and an approval strategy. +2. When the Catalog Operator find a new InstallPlan, even though it likely created it, it will create an "execution plan" and embed that into the InstallPlan to create all of the required resources. Once approved, whether manually or automatically, the Catalog Operator will implement its portion of the the execution plan, satisfying the underlying expectations of the OLM Operator. + +**_Table 1. Install plan phases_** + +| Phase | Description | +|--------------------|---------------------------------------------------------------------------------------------| +| None | initial phase, once seen by the Operator, it is immediately transitioned to `Planning` | +| Planning | dependencies between resources are being resolved, to be stored in the InstallPlan `Status` | +| RequiresApproval | occurs when using manual approval, will not transition phase until `approved` field is true | +| Installing | resolved resources in the InstallPlan `Status` block are being created | +| Complete | all resolved resources in the `Status` block exist | +--------------------- \ No newline at end of file diff --git a/content/en/docs/Tasks/Troubleshooting/clusterserviceversion.md b/content/en/docs/Tasks/Troubleshooting/clusterserviceversion.md index 0de6d600..0d1ba94b 100644 --- a/content/en/docs/Tasks/Troubleshooting/clusterserviceversion.md +++ b/content/en/docs/Tasks/Troubleshooting/clusterserviceversion.md @@ -11,7 +11,9 @@ description: > 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` +```shell script +$ 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. diff --git a/content/en/docs/Tasks/Troubleshooting/install-plan.md b/content/en/docs/Tasks/Troubleshooting/install-plan.md new file mode 100644 index 00000000..22fbeee3 --- /dev/null +++ b/content/en/docs/Tasks/Troubleshooting/install-plan.md @@ -0,0 +1,49 @@ +--- +title: "InstallPlan" +linkTitle: "InstallPlan" +date: 2020-03-25 +weight: 4 +description: > + Tips and tricks related to troubleshooting a `InstallPlan`. +--- + + +The primary way an InstallPlan can fail is by not resolving the resources needed to install a CSV. + +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: InstallPlan +metadata: + name: olm-testing +spec: + clusterServiceVersionNames: + - etcdoperator.v0.7.2 + approval: Automatic +``` + +This installPlan will fail because `etcdoperator.v0.7.2` is not in a catalog. We can see this in its status: + +```bash +$ kubectl get installplans olm-testing -o yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: InstallPlan +metadata: + ... +spec: + approval: Automatic + clusterServiceVersionNames: + - etcdoperator.v0.7.2 +status: + catalogSources: + - rh-operators + conditions: + - lastTransitionTime: 2018-01-22T16:05:09Z + lastUpdateTime: 2018-01-22T16:06:59Z + message: 'not found: ClusterServiceVersion etcdoperator.v0.7.2' + reason: DependenciesConflict + status: "False" + type: Resolved + phase: Planning +``` + +Error messages like this will displayed for any other inconsistency in the catalog. They can be resolved by either updating the catalog or choosing clusterservices that resolve correctly. \ No newline at end of file diff --git a/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md b/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md index c3d0dc43..fae35f7b 100644 --- a/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md +++ b/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md @@ -2,7 +2,7 @@ title: "Debugging OLM and Catalog Operator" linkTitle: "Debugging OLM/Catalog Operator" date: 2020-03-25 -weight: 4 +weight: 5 description: > Tips and tricks related to debugging the OLM or Catalog Operator. --- diff --git a/content/en/docs/Tasks/packaging-an-operator.md b/content/en/docs/Tasks/packaging-an-operator.md index d11d73dc..67ed50c4 100644 --- a/content/en/docs/Tasks/packaging-an-operator.md +++ b/content/en/docs/Tasks/packaging-an-operator.md @@ -235,17 +235,12 @@ TODO: example status ##### Extension apiservers and APIServices -Please see the document on [extension apiservers]() if your operator does not rely on CRDs to provide its API. +Please see the document on [extension apiservers](https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server/) if your operator does not rely on CRDs to provide its API. #### Operator SDK -TODO: link to SDK csv generation +ClusterServiceVersion (CSV) can be generated using operator-sdk. See [Generating a CSV](https://sdk.operatorframework.io/docs/olm-integration/generating-a-csv/) for more details. #### Advanced and Optional features -Please see the documentation for [advanced operator configuration]() which includes additional suggestions for further integration with OLM. - - -``` -This is the final element on the page and there should be no margin below this. -``` +Please see the documentation for [advanced operator configuration]() which includes additional suggestions for further integration with OLM. \ No newline at end of file diff --git a/content/en/docs/Tasks/validate-package.md b/content/en/docs/Tasks/validate-package.md index 041ae8e9..af699adf 100644 --- a/content/en/docs/Tasks/validate-package.md +++ b/content/en/docs/Tasks/validate-package.md @@ -11,15 +11,16 @@ description: > You can perform some basic static verification on your package by using [`operator-courier`](https://github.com/operator-framework/operator-courier). -``` +```shell script $ 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/). -``` +```shell script $ operator-courier verify --ui_validate_io manifests/my-operator-package +``` -Note: Your package can also be validated 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.). \ No newline at end of file +>Note: Your package can also be validated 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.). \ No newline at end of file diff --git a/content/en/docs/advanced-tasks/updating-an-operator.md b/content/en/docs/advanced-tasks/updating-an-operator.md index b36c619a..4d43ba2e 100644 --- a/content/en/docs/advanced-tasks/updating-an-operator.md +++ b/content/en/docs/advanced-tasks/updating-an-operator.md @@ -12,7 +12,7 @@ If the image used to build the `Catalogsource` uses a versioned tag, update the For example: -``` +```bash $ oc get catsrc operatorhubio-catalog -n olm -o yaml | grep image: image: quay.io/operator-framework/upstream-community-operators:0.0.1 @@ -25,7 +25,7 @@ If the image used to build the `Catalogsource` uses the `latest` tag, simply del For example: -``` +```bash $ kubectl delete pods -n olm -l olm.catalogSource=operatorhubio-catalog ``` diff --git a/content/en/docs/contribution-guidelines/local-docs.md b/content/en/docs/contribution-guidelines/local-docs.md index b5583603..441a08a4 100644 --- a/content/en/docs/contribution-guidelines/local-docs.md +++ b/content/en/docs/contribution-guidelines/local-docs.md @@ -7,7 +7,7 @@ linkTitle: Local Docs Clone the repository: -``` +```bash $ git clone https://github.com/operator-framework/olm-docs/ ``` @@ -18,7 +18,7 @@ guide](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installatio We use `git submodules` to install the docsy theme. From the root directory, update the submodules to install the theme. -``` +```bash $ git submodule update --init --recursive ``` @@ -26,8 +26,8 @@ $ git submodule update --init --recursive You can build and serve your docs to localhost:1313 with: -``` -hugo server +```bash +$ hugo server ``` Any changes will be included in real time.