diff --git a/_topic_map.yml b/_topic_map.yml index 3de638d7e89b..91baa15c5217 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -511,6 +511,9 @@ Topics: - Name: Creating policy for Operator installations and upgrades File: olm-creating-policy Distros: openshift-origin,openshift-enterprise + - Name: Configuring OLM in disconnected mode + File: olm-disconnected + Distros: openshift-origin,openshift-enterprise - Name: Application life cycle management Dir: application-life-cycle-management Topics: diff --git a/applications/operators/olm-disconnected.adoc b/applications/operators/olm-disconnected.adoc new file mode 100644 index 000000000000..626d1cef8101 --- /dev/null +++ b/applications/operators/olm-disconnected.adoc @@ -0,0 +1,27 @@ +[id="olm-disconnected"] += Using Operator Lifecycle Manager on disconnected clusters +include::modules/common-attributes.adoc[] +:context: olm-disconnected + +toc::[] + +When {product-title} is installed as a disconnected cluster, Operator Lifecycle +Manager (OLM) can no longer use the default OperatorHub sources as they require +Internet connectivity. Cluster administrators can disable those default sources +and create local mirrors so that OLM can install and manage Operators from the +local sources instead. + +//// +.Additional resources + +* Link to section about disconnected cluster installations. +//// + +include::modules/olm-disconnected-operatorhub-disconnected-mode.adoc[leveloffset=+1] +.Additional resources + +* For details on exposing your {product-title} cluster's internal registry to +off-cluster access, see +xref:../../registry/securing-exposing-registry.adoc#securing-exposing-registry[Exposing the registry]. +* For details on accessing the internal registry, see +xref:../../registry/accessing-the-registry.adoc#accessing-the-registry[Accessing the registry]. diff --git a/modules/olm-disconnected-operatorhub-disconnected-mode.adoc b/modules/olm-disconnected-operatorhub-disconnected-mode.adoc new file mode 100644 index 000000000000..95512a10ba23 --- /dev/null +++ b/modules/olm-disconnected-operatorhub-disconnected-mode.adoc @@ -0,0 +1,289 @@ +// Module included in the following assemblies: +// +// * applications/operators/olm-disconnected.adoc + +[id="olm-disconnected-operatohub-disconnected-mode_{context}"] += Configuring OperatorHub in disconnected mode + +Cluster administrators can configure OLM and OperatorHub to use local content in +a disconnected mode. + +.Prerequisites + +* Cluster administrator access to a connected or disconnected {product-title} cluster and its internal registry. +* Separate workstation with full Internet access. +* If pushing images to the {product-title} cluster's internal registry, the registry must be exposed with a route. +* `podman` version 1.5.1+ + +.Procedure + +. **Disable the default OperatorSources.** ++ +Add `disableAllDefaultSources: true` to the spec: ++ +---- +$ oc patch OperatorHub cluster --type json \ + -p '[{"op": "add", "path": "/spec/disableAllDefaultSources", "value": true}]' +---- ++ +This disables the default OperatorSources that are configured by default during +a {product-title} installation. + +. **Retrieve package lists.** ++ +To get the list of packages that are available for the default OperatorSources, +run the following `curl` commands from your workstation with Internet access: ++ +---- +$ curl https://quay.io/cnr/api/v1/packages?namespace=redhat-operators > packages.txt +$ curl https://quay.io/cnr/api/v1/packages?namespace=community-operators >> packages.txt +$ curl https://quay.io/cnr/api/v1/packages?namespace=certified-operators >> packages.txt +---- ++ +Each package in the new `packages.txt` is an Operator that you could add to your +disconnected catalog. From this list, you could either pull every Operator or a +subset that you would like to expose to users. + +. **Pull Operator content.** ++ +For a given Operator in the package list, you must pull its content: ++ +---- +$ curl https://quay.io/cnr/api/v1/packages/// +---- ++ +This example uses the etcd Operator: + +.. Retrieve the digest: ++ +---- +$ curl https://quay.io/cnr/api/v1/packages/community-operators/etcd/0.0.12 +---- + +.. From that JSON, take the digest and use it to pull the gzipped archive: ++ +---- +$ curl -XGET https://quay.io/cnr/api/v1/packages/community-operators/etcd/blobs/sha256/8108475ee5e83a0187d6d0a729451ef1ce6d34c44a868a200151c36f3232822b \ + -o etcd.tar.gz +---- + +.. To pull the information out, you must untar the archive into a +`manifests//` directory with all the other Operators that you +want. For example, to untar to an existing directory called `manifests/etcd/`: ++ +---- +$ mkdir -p manifests/etcd/ <1> +$ tar -xf etcd.tar.gz -C manifests/etcd/ +---- +<1> Create different subdirectories for each extracted archive so that files are not +overwritten by subsequent extractions for other Operators. + +. *Break apart `bundle.yaml` content, if necessary.* ++ +In your new `manifests/` directory, the goal is to get your bundle in the following directory structure: ++ +---- +manifests/ +└── etcd + ├── 0.0.12 + │   ├── clusterserviceversion.yaml + │   └── customresourcedefinition.yaml + └── package.yaml +---- ++ +If you see files already in this structure, you can skip this step. However, if +you instead see only a single file called `bundle.yaml`, you must first break +this file up to conform to the required structure. ++ +You must separate the CSV content under `data.clusterServiceVersion` (each file +in the list), the CRD content under `data.customResourceDefinition` (each file +in the list), and the package content under `data.Package` into their own files. + +.. For the CSV file creation, find the following lines in the `bundle.yaml` file: ++ +[source,yaml] +---- +data: + clusterServiceVersions: | +---- ++ +Omit those lines, but save a new file consisting of the full CSV resource +content beginning with the following lines, removing the prepended `-` +character: ++ +[source,yaml] +.Example `clusterserviceversion.yaml` file snippet +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: ClusterServiceVersion +[...] +---- + +.. For the CRD file creation, find the following line in the `bundle.yaml` file: ++ +[source,yaml] +---- + customResourceDefinitions: | +---- ++ +Omit this line, but save new files consisting of each, full CRD resource content +beginning with the following lines, removing the prepended `-` character: ++ +[source,yaml] +.Example `customresourcedefinition.yaml` file snippet +---- +apiVersion: apiextensions.k8s.io/v1beta1 +kind: CustomResourceDefinition +[...] +---- ++ +.. For the package file creation, find the following line in the `bundle.yaml` +file: ++ +[source,yaml] +---- + packages: | +---- ++ +Omit this line, but save a new file consisting of the package content beginning +with the following lines, removing the prepended `-` character, and ending with +a `packageName` entry: ++ +[source,yaml] +.Example `package.yaml` file +---- +channels: +- currentCSV: etcdoperator.v0.9.4 + name: singlenamespace-alpha +- currentCSV: etcdoperator.v0.9.4-clusterwide + name: clusterwide-alpha +defaultChannel: singlenamespace-alpha +packageName: etcd +---- + +. **Create an Operator catalog image.** + +.. Save the following to a Dockerfile, for example named +`custom-registry.Dockerfile`: ++ +[source,go] +---- +FROM registry.redhat.io/openshift4/ose-operator-registry:v4.2 AS builder + +COPY manifests manifests + +RUN /bin/initializer -o ./bundles.db + +FROM scratch + +COPY --from=builder /build/bundles.db /bundles.db +COPY --from=builder /build/bin/registry-server /registry-server +COPY --from=builder /bin/grpc_health_probe /bin/grpc_health_probe + +EXPOSE 50051 + +ENTRYPOINT ["/registry-server"] + +CMD ["--database", "bundles.db"] +---- + +.. Use the `podman` command to create and tag the container image from the +Dockerfile: ++ +---- +$ podman build -f custom-registry.Dockerfile \ + -t //custom-registry <1> +---- +<1> Tag the image for the internal registry of the disconnected {product-title} +cluster and any namespace. + +. **Push the Operator catalog image to a registry.** ++ +Your new Operator catalog image must be pushed to a registry that the +{product-title} can access. This can be the internal registry of the cluster +itself or another registry that the disconnected cluster has network access to, +such as an on-premise Quay Enterprise registry. ++ +For this example, login and push the image to the internal registry of the +disconnected {product-title} cluster ++ +---- +$ podman push //custom-registry +---- + +. **Create a CatalogSource pointing to the new Operator catalog image.** + +.. Save the following to a file, for example `my-operator-catalog.yaml`: ++ +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: my-operator-catalog + namespace: default +spec: + displayName: My Operator Catalog + sourceType: grpc + image: //custom-registry:latest +---- + +.. Create the CatalogSource resource: ++ +---- +$ oc create -f my-operator-catalog.yaml +---- + +.. Verify the CatalogSource and package manifest are created successfully: ++ +---- +# oc get pods -n openshift-marketplace +NAME READY STATUS RESTARTS AGE +my-operator-catalog-6njx6 1/1 Running 0 28s +marketplace-operator-d9f549946-96sgr 1/1 Running 0 26h + +# oc get catalogsource -n openshift-marketplace +NAME DISPLAY TYPE PUBLISHER AGE +my-operator-catalog My Operator Catalog grpc 5s + +# oc get packagemanifest -n openshift-marketplace +NAME CATALOG AGE +etcd My Operator Catalog 34s +---- ++ +You should also be able to view them from the *OperatorHub* page in the web +console. + +. **Mirror the images required by the Operators you want to use.** + +.. Determine the images defined by the Operator that you are expecting. This + example uses the etcd Operator, requiring the `quay.io/coreos/etcd-operator` + image. + +.. To use mirrored images, you must first create an ImageContentSourcePolicy for +each image to change the source location of the Operator catalog image. For +example: ++ +[source,yaml] +---- +apiVersion: operator.openshift.io/v1alpha1 +kind: ImageContentSourcePolicy +metadata: + name: etcd-operator +spec: + repositoryDigestMirrors: + - mirrors: + - :5000/coreos/etcd-operator + source: quay.io/coreos/etcd-operator +---- + +.. Use the `oc image mirror` command from your workstation with Internet access to +pull the image from the source registry and push to the internal registry +without being stored locally: ++ +---- +$ oc image mirror quay.io/coreos/etcd-operator \ + :5000/coreos/etcd-operator +---- + +You can now install the Operator from the OperatorHub in disconnected mode.