diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..e2d08409 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,5 @@ +services: + - docker + +script: + ./hack/ci/link-check.sh diff --git a/README.md b/README.md new file mode 100644 index 00000000..6d597100 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# OLM Documentation + +We use [Hugo](https://gohugo.io/) to format and generate our website, the +[Docsy](https://github.com/google/docsy) theme for styling and site structure, +and [Netlify](https://www.netlify.com/) to manage the deployment of the site. +Hugo is an open-source static site generator that provides us with templates, +content organisation in a standard directory structure, and a website generation +engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website. + +All submissions, including submissions by project members, require review. We +use GitHub pull requests for this purpose. Consult +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more +information on using pull requests. + +## Quick start with Netlify + +Here's a quick guide to updating the docs. It assumes you're familiar with the +GitHub workflow and you're happy to use the automated preview of your doc +updates: + +1. Fork [olm-docs](https://github.com/operator-framework/olm-docs) on GitHub. +1. Make your changes and send a pull request (PR). +1. If you're not yet ready for a review, add "WIP" to the PR name to indicate + it's a work in progress. (**Don't** add the Hugo property + "draft = true" to the page front matter, because that prevents the + auto-deployment of the content preview described in the next point.) +1. Wait for the automated PR workflow to do some checks. When it's ready, + you should see a comment like this: **deploy/netlify — Deploy preview ready!** +1. Click **Details** to the right of "Deploy preview ready" to see a preview + of your updates. +1. Continue updating your doc and pushing your changes until you're happy with + the content. +1. When you're ready for a review, add a comment to the PR, and remove any + "WIP" markers. + +## Updating a single page + +If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you: + +1. Click **Edit this page** in the top right hand corner of the page. +1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode. +1. Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make, preview, and propose your changes. + +## Previewing your changes locally + +If you want to run your own local Hugo server to preview your changes as you work: + +1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS. +1. Fork [olm-docs](https://github.com/operator-framework/olm-docs), then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site. + + ```sh + git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git + ``` + +1. Run `hugo server` in the site root directory. By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. +1. Continue with the usual GitHub workflow to edit files, commit them, push the + changes up to your fork, and create a pull request. + +## Creating an issue + +If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [olm-docs repo](https://github.com/operator-framework/olm-docs). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page. + +## Local Development + +Clone the repository: + +```sh +$ git clone https://github.com/operator-framework/olm-docs/ +``` + +The docs are built with [Hugo](https://gohugo.io/) which can be installed along with the +required extensions by following the [docsy install +guide](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation). + +We use `git submodules` to install the docsy theme. From the +root directory, update the submodules to install the theme. + +```sh +$ git submodule update --init --recursive +``` + +## Build and Serve + +You can build and serve your docs to localhost:1313 with: + +```sh +$ hugo server +``` + +Any changes will be included in real time. + +## Useful resources + +* [Docsy user guide](wherever it goes): All about Docsy, including how it manages navigation, look and feel, and multi-language support. +* [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo. \ No newline at end of file diff --git a/assets/scss/_docs.scss b/assets/scss/_docs.scss index 34a12765..45268cb7 100644 --- a/assets/scss/_docs.scss +++ b/assets/scss/_docs.scss @@ -4,12 +4,12 @@ } .of-docs__wrapper { + pre, p, ol, ul { + margin-bottom: var(--of--spacer--md); + } ul { list-style: disc; - margin-left: 1rem; - } - p { - margin-bottom: var(--of--spacer--md); + margin-left: 2rem; } .td-sidebar-nav .td-sidebar-link__page { font-weight: normal; @@ -19,6 +19,10 @@ font-weight: 800; letter-spacing: 2px; margin: var(--of--spacer--md) 0 var(--of--spacer--sm); + + a:hover { + text-decoration: none; + } } h5, h6 { @@ -39,13 +43,13 @@ @media (min-width: $ov--breakpoint--lg) { h6 { - font-size: var(--of--FontSize--sm); + font-size: var(--of--FontSize--xs); } h5 { - font-size: var(--of--FontSize--sm); + font-size: var(--of--FontSize--xs); } h4 { - font-size: var(--of--FontSize--md); + font-size: var(--of--FontSize--sm); } h3 { font-size: var(--of--FontSize--md); diff --git a/config.toml b/config.toml index ba787fbd..f464c44c 100644 --- a/config.toml +++ b/config.toml @@ -70,14 +70,20 @@ copyright = "The Operator Lifecycle Manager Authors" # Menu title if your navbar has a versions selector to access old versions of your site. # This menu appears only if you have at least one [params.versions] set. -# version_menu = "Releases" -# [[params.versions]] -# version = "master" -# url = "/docs" - -# [[params.versions]] -# version = "v0.16" -# url = "https://github.com/operator-framework/operator-sdk/tree/v0.16.x/doc" + version_menu = "legacy" + +[[params.versions]] + version = "master" + url = "https://olm.operatorframework.io" + primary = true + +[[params.versions]] + version = "v0.16.z" + url = "https://v0-16-z.olm.operatorframework.io/" + +[[params.versions]] + version = "legacy" + url = "https://legacy.olm.operatorframework.io/" # Flag used in the "version-banner" partial to decide whether to display a # banner on every page indicating that this is an archived version of the docs. diff --git a/content/en/docs/Concepts/crds/CatalogSource.md b/content/en/docs/Concepts/crds/CatalogSource.md index 23f179b1..964f67ef 100644 --- a/content/en/docs/Concepts/crds/CatalogSource.md +++ b/content/en/docs/Concepts/crds/CatalogSource.md @@ -5,7 +5,7 @@ weight: 3 A CatalogSource represents a store of metadata that OLM can query to discover and install operators and their dependencies. -The `.spec` of a CatalogSource indicates to how to construct a pod or how to talk to a service that serves the [operator-registry grpc api](/docs/operator-registry). +The `.spec` of a CatalogSource indicates to how to construct a pod or how to talk to a service that serves the [operator-registry grpc api](/docs/concepts/olm-architecture/operator-registry/using-catalog-locally). There are three primary types: diff --git a/content/en/docs/Concepts/crds/operatorgroup.md b/content/en/docs/Concepts/crds/operatorgroup.md index dcd4b416..41f0961a 100644 --- a/content/en/docs/Concepts/crds/operatorgroup.md +++ b/content/en/docs/Concepts/crds/operatorgroup.md @@ -9,7 +9,7 @@ An OperatorGroup is an OLM resource that provides rudimentary multitenant config * An `OperatorGroup` selects a set of target namespaces in which to generate required RBAC access for its member operators. * The set of target namespaces is provided via a comma-delimited string stored in the `olm.targetNamespaces` annotation. This annotation is applied to member operator's `ClusterServiceVersion` (CSV) instances and is projected into their deployments. It is accessible to operator containers using [The Downward API](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#the-downward-api) -* An operator is said to be a [member of an `OperatorGroup`](#operatorgroup-membership) if its CSV exists in the same namespace as the `OperatorGroup` and its CSV's [`InstallModes` support the set of namespaces targeted by the `OperatorGroup`](#installmodes-and-supported-operatorgroups) +* An operator is said to be a [member of an `OperatorGroup`](#membership) if its CSV exists in the same namespace as the `OperatorGroup` and its CSV's [`InstallModes` support the set of namespaces targeted by the `OperatorGroup`](#installmodes-and-supported-operatorgroups) * In order to transition, a CSV must be an active member of an `OperatorGroup` that has no [provided API conflicts with intersecting `OperatorGroups`](#operatorgroup-intersection) ## Membership @@ -157,7 +157,7 @@ OLM will create copies of all active member CSVs of an `OperatorGroup` in each o ## Static OperatorGroups -An `OperatorGroup` is _static_ if it's `spec.staticProvidedAPIs` field is set to __true__. As a result, OLM does not modify the OperatorGroups's `olm.providedAPIs` annotation, which means that it can be set in advance. This is useful when a user wishes to use an `OperatorGroup` to prevent [resource contention](#what-can-go-wrong?) in a set of namespaces, but does not have active member CSVs that provide the APIs for those resources. +An `OperatorGroup` is _static_ if it's `spec.staticProvidedAPIs` field is set to __true__. As a result, OLM does not modify the OperatorGroups's `olm.providedAPIs` annotation, which means that it can be set in advance. This is useful when a user wishes to use an `OperatorGroup` to prevent resource contention in a set of namespaces, but does not have active member CSVs that provide the APIs for those resources. Here's an example of an `OperatorGroup` that "protects" prometheus resources in all namespaces with the `something.cool.io/cluster-monitoring: "true"` annotation: diff --git a/content/en/docs/Concepts/crds/subscription.md b/content/en/docs/Concepts/crds/subscription.md index 5010953f..55fdd1f2 100644 --- a/content/en/docs/Concepts/crds/subscription.md +++ b/content/en/docs/Concepts/crds/subscription.md @@ -4,7 +4,7 @@ weight: 4 --- -A Subscription represents an intention to install an operator. It is the CustomResource that relate an operator to a CatalogSource. Subscriptions describe which [channel](/docs/concepts/glossary/#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. +A Subscription represents an intention to install an operator. It is the CustomResource that relate an operator to a CatalogSource. Subscriptions describe which [channel](/docs/glossary/glossary/#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: diff --git a/content/en/docs/Concepts/olm-architecture/operator-registry/using-catalog-with-olm/_index.md b/content/en/docs/Concepts/olm-architecture/operator-registry/using-catalog-with-olm/_index.md index cd1532d5..4be433a5 100644 --- a/content/en/docs/Concepts/olm-architecture/operator-registry/using-catalog-with-olm/_index.md +++ b/content/en/docs/Concepts/olm-architecture/operator-registry/using-catalog-with-olm/_index.md @@ -8,7 +8,7 @@ description: > --- -To add a [catalog image](/operator-registry/tasks/building-catalog/#building-a-catalog-image-of-operators-using-operator-registry) to your cluster for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager) (OLM), create a [CatalogSource](/docs/Concepts/crds/CatalogSource) referencing the image you created and pushed to your favourite container registry: +To add a [catalog image](/docs/tasks/make-operator-part-of-catalog) to your cluster for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager) (OLM), create a [CatalogSource](/docs/concepts/crds/catalogsource) referencing the image you created and pushed to your favourite container registry: ```yaml apiVersion: operators.coreos.com/v1alpha1 diff --git a/content/en/docs/Glossary/Glossary.md b/content/en/docs/Glossary/Glossary.md index 40da9ef9..bd321b25 100644 --- a/content/en/docs/Glossary/Glossary.md +++ b/content/en/docs/Glossary/Glossary.md @@ -18,7 +18,7 @@ These pages are under construction. ### 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. +**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 @@ -26,7 +26,7 @@ These pages are under construction. ### Channel Head -**Definition**: Head refers to the latest known update in a particular [channel](#Channel). +**Definition**: Head refers to the latest known update in a particular [channel](#channel). ### Catalog Image @@ -53,7 +53,7 @@ These pages are under construction. ### Registry -**Definition**: A database which stores [Bundle Images](#Bundle-Image) of Operators, each with all of its latest/historical versions in all [channels](#Channel). +**Definition**: A database which stores [Bundle Images](#bundle-image) of Operators, each with all of its latest/historical versions in all [channels](#channel). ### Update Graph diff --git a/content/en/docs/Tasks/Troubleshooting/subscription.md b/content/en/docs/Tasks/Troubleshooting/subscription.md index aefcf032..406316e2 100644 --- a/content/en/docs/Tasks/Troubleshooting/subscription.md +++ b/content/en/docs/Tasks/Troubleshooting/subscription.md @@ -19,7 +19,7 @@ The Catalog operator will constantly update the `Status` of `Subscription` to re >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). +If the `Status` block does not provide enough information, check the [Catalog operator's logs](/docs/tasks/troubleshooting/olm-and-catalog-operators/#how-to-view-the-catalog-operator-logs). ### A subscription in namespace X can't install operators from a CatalogSource in namespace Y diff --git a/content/en/docs/Tasks/install-operator-with-olm.md b/content/en/docs/Tasks/install-operator-with-olm.md index 8d72d094..8a660320 100644 --- a/content/en/docs/Tasks/install-operator-with-olm.md +++ b/content/en/docs/Tasks/install-operator-with-olm.md @@ -3,23 +3,27 @@ title: "Install your operator with OLM" date: 2020-03-25 weight: 6 description: > - [Once you've made your operator available in a catalog](/docs/tasks/make-operator-part-of-catalog/), or you've chosen an operator from the [list of operators available to be installed in the cluster](/docs/tasks/list-operators-available-to-install/), you can install your operator by creating a [`Subscription`](/docs/concepts/customresourcedefinitions/subscription/) to a specific [channel](/docs/concepts/glossary/#channel). + [Once you've made your operator available in a catalog](/docs/tasks/make-operator-part-of-catalog/), or you've chosen an operator from the [list of operators available to be installed in the cluster](/docs/tasks/list-operators-available-to-install/), you can install your operator by creating a [`Subscription`](/docs/concepts/crds/subscription/) to a specific [channel](/docs/glossary/glossary/#channel). --- -Before installing an operator into a namespace, you will need to create an [OperatorGroup resource](/docs/concepts/crds/operatorgroup) in that namespace. The OperatorGroup must target namespaces such that it matches the operator's `installModes`. +## Prerequisites -For example, to install a cluster scoped operator into the `foo` namespace create an OperatorGroup like: +Before installing an operator into a namespace, you will need to create an `OperatorGroup` that targets the namespaces your operator is planning to watch, to generate the required RBACs for your operator in those namespaces. You can read more about `OperatorGroup` [here](/docs/concepts/crds/operatorgroup). +NOTE: The namespaces targeted by the OperatorGroup must align with the `installModes` specified in the `ClusterServiceVersion` of the operator's package. -```yaml -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: my-group - namespace: foo +To know the `installModes` of an operator, inspect the packagemanifest: + +```bash +$ kubectl get packagemanifest -o jsonpath="{.status.channels[0].currentCSVDesc.installModes}" + ``` -After creating this resource you can create Subscriptions to install cluster scoped operators. +You can read more about target namespace selection for your `OperatorGroup` [here](/docs/concepts/crds/operatorgroup#target-namespace-selection) + +## Subscribe to your operator + +To install an Operator, simply create a `Subscription` for your operator. ```yaml apiVersion: operators.coreos.com/v1alpha1 @@ -32,26 +36,67 @@ spec: name: source: sourceNamespace: - ``` + approval: + ``` -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: +You can read more about the `Subscription` object and what the different fields mean [here](/docs/concepts/crds/subscription). + +The `Subscription` object creates an [InstallPlan](/docs/concepts/crds/installplan), which is either automatically approved (if `sub.spec.approval: Automatic`), or needs to be approved (if `sub.spec.approval: Manual`), following which the operator is installed in the namespace you want. + +## Example + +If you want to install an operator named `my-operator` in the namespace `foo` that is cluster scoped (i.e `installModes:AllNamespaces`), from a catalog named `my-catalog` that is in the namespace `olm`, and you want to subscribe to the channel `stable`, + +create a _global_ `OperatorGroup` (which selects all namespaces): + +```bash +$ cat og.yaml + + apiVersion: operators.coreos.com/v1 + kind: OperatorGroup + metadata: + name: my-group + namespace: foo + +$ kubectl apply og.yaml + operatorgroup.operators.coreos.com/my-group created +``` + +Then, create a subscription for the operator: + +```bash + +$ cat sub.yaml -```yaml apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: - name: subs-to-my-operator - namespace: olm + name: sub-to-my-operator + namespace: foo spec: channel: stable name: my-operator source: my-catalog sourceNamespace: olm + approval: Manual + +$ kubectl apply -f sub.yaml +subscription.operators.coreos.com/sub-to-my-operator created ``` -Once you have the subscription yaml, `kubectl apply -f Subscription.yaml` to install your operator. +Since the `approval` is `Manual`, we need to manually go in and approve the `InstallPlan` + +```bash +$ kubectl get ip -n foo + +NAME CSV APPROVAL APPROVED +install-nlwcw my-operator.v0.9.2 Automatic false + +$ kubectl edit ip install-nlwcw -n foo +``` +And then change the `spec.approved` from `false` to `true` -You can inspect your Subscription with `kubectl get subs -n `. +This should spin up the `ClusterServiceVersion` of the operator in the `foo` namespace`, following which the operator pod will spin up. To ensure the operator installed successfully, check for the ClusterServiceVersion and the operator deployment in the namespace it was installed in. diff --git a/content/en/docs/Tasks/list-operators-available-to-install.md b/content/en/docs/Tasks/list-operators-available-to-install.md index a382005b..9a411d92 100644 --- a/content/en/docs/Tasks/list-operators-available-to-install.md +++ b/content/en/docs/Tasks/list-operators-available-to-install.md @@ -3,10 +3,10 @@ title: "List operators available to install" date: 2017-01-05 weight: 5 description: > - Once you've packaged your operator and made it part of catalog, you can see it among the list of operators that are available to install in the cluster. There is an extension API in OLM named `PackageManifest` that contains information about existing [CatalogSources](/docs/concepts/#catalogsources), which is essentially a collection of bundles that each define an operator in the cluster. By querying that API, you can see the list of available operators. + Once you've packaged your operator and made it part of catalog, you can see it among the list of operators that are available to install in the cluster. There is an extension API in OLM named `PackageManifest` that contains information about existing [CatalogSources](/docs/concepts/crds/catalogsource), which is essentially a collection of bundles that each define an operator in the cluster. By querying that API, you can see the list of available operators. --- -[CatalogSources](/docs/concepts/#catalogsources) in OLM are either global or namespaced. Global CatalogSources contain operators that will be available for installing in all namespaces, while namespaced CatalogSources only contains operators that are available to be installed in a specific namespace. +[CatalogSources](/docs/concepts/crds/catalogsource) in OLM are either global or namespaced. Global CatalogSources contain operators that will be available for installing in all namespaces, while namespaced CatalogSources only contains operators that are available to be installed in a specific namespace. ## Using the PackageManifest API diff --git a/content/en/docs/Tasks/packaging-an-operator.md b/content/en/docs/Tasks/packaging-an-operator.md index d11d73dc..3e50f9e6 100644 --- a/content/en/docs/Tasks/packaging-an-operator.md +++ b/content/en/docs/Tasks/packaging-an-operator.md @@ -22,7 +22,7 @@ This is all in service of ensuring that when a user installs an operator from OL ### 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). +For this example, we'll use the example manifests from [the example memcached operator](https://github.com/operator-framework/operator-sdk-samples/tree/v0.19.2/go/memcached-operator/deploy). These manifests consist of: @@ -130,7 +130,7 @@ spec: **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). +`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/v0.19.2/go/memcached-operator/deploy). Here is a simple `faq` script that can generate an install strategy from a single deployment: diff --git a/content/en/docs/Tasks/uninstall-operator.md b/content/en/docs/Tasks/uninstall-operator.md index 11fe591a..0ab2b9bb 100644 --- a/content/en/docs/Tasks/uninstall-operator.md +++ b/content/en/docs/Tasks/uninstall-operator.md @@ -3,32 +3,45 @@ title: "Uninstall your operator" date: 2020-03-25 weight: 7 description: > - In order to uninstall an operator, you need to delete the following resources: + When uninstalling an operator managed by OLM, a Cluster Admin must decide whether or not to remove the CustomResourceDefinitions (CRD), APIServices, and resources related to these types owned by the operator. By design, when OLM uninstalls an operator it does not remove any of the operator's owned CRDs, APIServices, or CRs in order to prevent data loss. Instead, it is left to the Cluster Admin to remove any unwanted types and resources from the cluster. This document will discuss the steps a Cluster Admin should take when uninstalling an operator. +--- - - Subscription - - ClusterServiceVersion (CSV) +## Step 1: Identifying Resources to Remove - 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. ---- +The cluster admin should first understand which types (CRDs and APIServices) are owned by the operator, which is available in the operator's ClusterServiceVersion (CSV) under the `spec.customresourcedefinitions.owned` and `spec.apiservicedefinitions.owned` arrays. It is likely that users have created resources for these types since the operator was installed. The cluster admin should should decide which of these resources to delete on a case-by-case basis. If the resource is not required, delete it. The Cluster Admin should delete all unwanted resources before moving to the next step. + +> Note: Although deleting the CRD or APIService removes all resource of the type from the cluster, this action may lead to unintended consequences. Operators often use [finalizers](https://book.kubebuilder.io/reference/using-finalizers.html) to execute application specific cleanup routines before removing the CR. If the API is removed, the operator will be unable to properly remove the resource, and the cluster may appear to be "stuck" as defined in this [Kubernetes issue](https://github.com/kubernetes/kubernetes/issues/60807). -## Delete a Subscription +## Step 2: Unsubscribe from the Operator -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: +OLM uses the subscription resource to convey a user's intent to subscribe to the latest version of an operator. If the operator was installed with Automatic Updates (spec.Approval: `Automatic`), OLM will reinstall a new version of the operator even if the operator's CSV was deleted earlier. In effect, you must tell OLM that you do not want new versions of the operator to be installed by deleting the subscription associated with the operator. + +You can list existing `Subscription` in a specific namespace with the following `kubectl` command: ```bash $ kubectl get subscription -n +# Example output +NAME PACKAGE SOURCE CHANNEL +foo-sub foo foo-catalog alpha ``` -You can delete the `Subscription` in the namespace that the operator was installed into using this command: +> Note: The name of the operator installed by the subscription is available under the `Package` column. + +The `Subscription` can be deleted by running this command: ```bash $ kubectl delete subscription -n ``` -## Delete a ClusterServiceVersion (CSV) +## Step 3: Delete the Operator's ClusterServiceVersion (CSV) + +The CSV contains all the information that OLM needs to manage an operator, and it effectively represents an operator that is installed on cluster. By deleting a `ClusterServiceVersion`, OLM will delete the resources it created for the operator such as the deployment, RBAC, and any corresponding CSVs that OLM "Copied" into other namespaces watched by the operator. 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 +# Example output +NAME DISPLAY VERSION REPLACES PHASE +foo Foo Operator 1.0.0 Succeeded ``` You can delete the `ClusterServiceVersion` in the namespace that the operator was installed into using this command: @@ -37,11 +50,15 @@ You can delete the `ClusterServiceVersion` in the namespace that the operator wa $ 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. +### Combine steps 2 and 3 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 -``` \ No newline at end of file +``` + +## Step 4: Deciding whether or not to delete the CRDs and APIServices + +The final step consists of deciding whether or not to delete the CRDs and APIServices that were introduced to the cluster by the operator. Assuming you have already deleted all unwanted resources on cluster as enumerated in Step 1, if no resources remain it is safe to remove the CRD or APISerivces. Otherwise, you should not delete the type as the wanted resources will be deleted automatically when the CRD or APISerivce is deleted. diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 53169d69..00bf8098 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -9,6 +9,6 @@ weight: 20 {{% alert title="Warning" color="warning" %}} These pages are under construction. Please continue to use the [docs in -tree](https://github.com/operator-framework/operator-sdk/tree/master/doc) +tree](https://github.com/operator-framework/operator-lifecycle-manager/tree/master/doc/) for now. {{% /alert %}} diff --git a/content/en/docs/advanced-tasks/adding-an-admission-webhook.md b/content/en/docs/advanced-tasks/adding-an-admission-webhook.md index 385512a6..2fb2247e 100644 --- a/content/en/docs/advanced-tasks/adding-an-admission-webhook.md +++ b/content/en/docs/advanced-tasks/adding-an-admission-webhook.md @@ -6,7 +6,7 @@ weight: 3 ## Defining your Webhook in the ClusterServiceVersion -OLM is capable of managing the lifecycle of [validating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) and [mutating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) admission webhooks that are shipped alongside your operator. To this end, the [ClusterServiceVersion resource](/docs/Concepts/crds/clusterserviceversion) includes a [WebhookDefinition object](https://github.com/operator-framework/api/blob/7856a40f92893fe94d19d223f5277d1d116ffc67/pkg/operators/v1alpha1/clusterserviceversion_types.go#L164-L180) which can be used to define validating and mutating admission webhooks that will be shipped with the operator. For your convenience, an example of a Validating WebhookDefinition can be seen below: +OLM is capable of managing the lifecycle of [validating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) and [mutating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) admission webhooks that are shipped alongside your operator. To this end, the [ClusterServiceVersion resource](/docs/concepts/crds/clusterserviceversion) includes a [WebhookDefinition object](https://github.com/operator-framework/api/blob/7856a40f92893fe94d19d223f5277d1d116ffc67/pkg/operators/v1alpha1/clusterserviceversion_types.go#L164-L180) which can be used to define validating and mutating admission webhooks that will be shipped with the operator. For your convenience, an example of a Validating WebhookDefinition can be seen below: ```yaml apiVersion: operators.coreos.com/v1alpha1 @@ -45,7 +45,7 @@ spec: ... ``` -The `WebhookDescription` object contains a union of the fields defined in the AdmissionWebhook and ValidatingWebhook Kubernetes objects with the exception of the NamespaceSelector, which is generated by OLM to match namespaces scoped by the [OperatorGroup](./operator-scoping.md) that the operator is deployed in. +The `WebhookDescription` object contains a union of the fields defined in the AdmissionWebhook and ValidatingWebhook Kubernetes objects with the exception of the NamespaceSelector, which is generated by OLM to match namespaces scoped by the [OperatorGroup](/docs/advanced-tasks/operator-scoping-with-operatorgroups) that the operator is deployed in. OLM requires that you define the following: diff --git a/content/en/docs/advanced-tasks/operator-scoping-with-operatorgroups.md b/content/en/docs/advanced-tasks/operator-scoping-with-operatorgroups.md new file mode 100644 index 00000000..ba5f0501 --- /dev/null +++ b/content/en/docs/advanced-tasks/operator-scoping-with-operatorgroups.md @@ -0,0 +1,172 @@ +--- +title: "Operator scoping with OperatorGroups" +linkTitle: "Operator scoping with OperatorGroups" +weight: 4 +description: > + 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`](/docs/concepts/crds/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). + +### 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. \ No newline at end of file diff --git a/content/en/docs/advanced-tasks/ship-operator-supporting-multiarch.md b/content/en/docs/advanced-tasks/ship-operator-supporting-multiarch.md index 153ae13f..b2b74919 100644 --- a/content/en/docs/advanced-tasks/ship-operator-supporting-multiarch.md +++ b/content/en/docs/advanced-tasks/ship-operator-supporting-multiarch.md @@ -55,6 +55,6 @@ $ kubectl get packagemanifests -l operatorframework.io/os.windows=supported ## Caveats -Only the labels on the [HEAD of the default channel](/docs/concepts/glossary/#channel-head) are considered for filtering PackageManifests by label. +Only the labels on the [HEAD of the default channel](/docs/glossary/glossary/#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. diff --git a/content/en/docs/getting-started/_index.md b/content/en/docs/getting-started/_index.md index 22fef3fe..65a8dec1 100644 --- a/content/en/docs/getting-started/_index.md +++ b/content/en/docs/getting-started/_index.md @@ -137,4 +137,4 @@ NAME READY UP-TO-DATE AVAILABLE AGE etcd-operator 1/1 1 1 3m29s ``` -To learn more about packaging your operator for OLM, installing/uninstalling an operator etc, visit the [Core Tasks](/docs/Tasks/) and the [Advanced Tasks](/docs/advanced-Tasks/) section of this site. \ No newline at end of file +To learn more about packaging your operator for OLM, installing/uninstalling an operator etc, visit the [Core Tasks](/docs/tasks/) and the [Advanced Tasks](/docs/advanced-tasks/) section of this site. diff --git a/hack/ci/link-check.sh b/hack/ci/link-check.sh new file mode 100755 index 00000000..de8f865c --- /dev/null +++ b/hack/ci/link-check.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -ev + +docker volume create olm-html +docker run --rm -v "$(pwd):/src" -v olm-html:/src/public klakegg/hugo:0.73.0-ext-ubuntu +docker run --rm -v olm-html:/target mtlynch/htmlproofer /target --empty-alt-ignore --http-status-ignore 429 --allow_hash_href +docker volume rm olm-html diff --git a/layouts/partials/navbar-version-selector.html b/layouts/partials/navbar-version-selector.html new file mode 100644 index 00000000..5a20b862 --- /dev/null +++ b/layouts/partials/navbar-version-selector.html @@ -0,0 +1,8 @@ + +
+ {{ range .Site.Params.versions }} + {{ .version }} + {{ end }} +
diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html new file mode 100644 index 00000000..e1f18d5b --- /dev/null +++ b/layouts/partials/navbar.html @@ -0,0 +1,25 @@ +
+ + + + + + + +
+ {{ partial "search-input.html" . }} +
+