forked from openshift/openshift-docs
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Do not use deprecated asciidoctor footnote syntax
- Loading branch information
Showing
7 changed files
with
281 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
// Module included in the following assemblies: | ||
// | ||
// * operators/olm-restricted-networks.adoc | ||
// * migration/migrating_3_4/deploying-cam-3-4.adoc | ||
// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc | ||
// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc | ||
|
||
[id="olm-building-operator-catalog-image_{context}"] | ||
= Building an Operator catalog image | ||
|
||
Cluster administrators can build a custom Operator catalog image to be used by | ||
Operator Lifecycle Manager (OLM) and push the image to a container image | ||
registry that supports | ||
link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2]. For a | ||
cluster on a restricted network, this registry can be a registry that the cluster | ||
has network access to, such as the mirror registry created during the restricted | ||
network installation. | ||
|
||
[IMPORTANT] | ||
==== | ||
The {product-title} cluster's internal registry cannot be used as the target | ||
registry because it does not support pushing without a tag, which is required | ||
during the mirroring process. | ||
==== | ||
|
||
For this example, the procedure assumes use of the mirror registry created on | ||
the bastion host during a restricted network cluster installation. | ||
|
||
.Prerequisites | ||
|
||
|
||
* A Linux workstation with unrestricted network access | ||
ifeval::["{context}" == "olm-restricted-networks"] | ||
footnoteref:BZ1771329[The | ||
`oc adm catalog` command is currently only supported on Linux. | ||
(link:https://bugzilla.redhat.com/show_bug.cgi?id=1771329[*BZ#1771329*])] | ||
endif::[] | ||
* `oc` version 4.3.5+ | ||
* `podman` version 1.4.4+ | ||
* Access to mirror registry that supports | ||
link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] | ||
* If you are working with private registries, set the `REG_CREDS` environment | ||
variable to the file path of your registry credentials for use in later steps. | ||
For example, for the `podman` CLI: | ||
+ | ||
---- | ||
$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json | ||
---- | ||
|
||
.Procedure | ||
|
||
. On the workstation with unrestricted network access, authenticate with the | ||
target mirror registry: | ||
+ | ||
---- | ||
$ podman login <registry_host_name> | ||
---- | ||
+ | ||
Also authenticate with `registry.redhat.io` so that the base image can be pulled | ||
during the build: | ||
+ | ||
---- | ||
$ podman login registry.redhat.io | ||
---- | ||
|
||
. Build a catalog image based on the `redhat-operators` catalog from | ||
link:https://quay.io/[quay.io], tagging and pushing it to your mirror registry: | ||
+ | ||
---- | ||
$ oc adm catalog build \ | ||
--appregistry-org redhat-operators \//<1> | ||
--from=registry.redhat.io/openshift4/ose-operator-registry:v4.4 \//<2> | ||
--filter-by-os="linux/amd64" \//<3> | ||
--to=<registry_host_name>:<port>/olm/redhat-operators:v1 \//<4> | ||
[-a ${REG_CREDS}] \//<5> | ||
[--insecure] <6> | ||
INFO[0013] loading Bundles dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 | ||
... | ||
Pushed sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 to example_registry:5000/olm/redhat-operators:v1 | ||
---- | ||
<1> Organization (namespace) to pull from an App Registry instance. | ||
<2> Set `--from` to the `ose-operator-registry` base image using the tag that | ||
matches the target {product-title} cluster major and minor version. | ||
<3> Set `--filter-by-os` to the operating system and architecture to use for the | ||
base image, which must match the target {product-title} cluster. Valid values | ||
are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. | ||
<4> Name your catalog image and include a tag, for example, `v1`. | ||
<5> Optional: If required, specify the location of your registry credentials file. | ||
<6> Optional: If you do not want to configure trust for the target registry, add the | ||
`--insecure` flag. | ||
+ | ||
Sometimes invalid manifests are accidentally introduced into Red Hat's catalogs; | ||
when this happens, you might see some errors: | ||
+ | ||
---- | ||
... | ||
INFO[0014] directory dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=4.2 load=package | ||
W1114 19:42:37.876180 34665 builder.go:141] error building database: error loading package into db: fuse-camel-k-operator.v7.5.0 specifies replacement that couldn't be found | ||
Uploading ... 244.9kB/s | ||
---- | ||
+ | ||
These errors are usually non-fatal, and if the Operator package mentioned does | ||
not contain an Operator you plan to install or a dependency of one, then they | ||
can be ignored. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,154 @@ | ||
// Module included in the following assemblies: | ||
// | ||
// * operators/olm-restricted-networks.adoc | ||
|
||
[id="olm-updating-operator-catalog-image_{context}"] | ||
= Updating an Operator catalog image | ||
|
||
After a cluster administrator has configured OperatorHub to use custom Operator | ||
catalog images, administrators can keep their {product-title} cluster up to date | ||
with the latest Operators by capturing updates made to Red Hat’s App Registry | ||
catalogs. This is done by building and pushing a new Operator catalog image, | ||
then replacing the existing CatalogSource’s `spec.image` parameter with the new | ||
image digest. | ||
|
||
For this example, the procedure assumes a custom `redhat-operators` catalog | ||
image is already configured for use with OperatorHub. | ||
|
||
.Prerequisites | ||
|
||
* A Linux workstation with unrestricted network access | ||
ifeval::["{context}" == "olm-restricted-networks"] | ||
footnoteref:BZ1771329[] | ||
endif::[] | ||
* `oc` version 4.3.5+ | ||
* `podman` version 1.4.4+ | ||
* Access to mirror registry that supports | ||
link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] | ||
* OperatorHub configured to use custom catalog images | ||
* If you are working with private registries, set the `REG_CREDS` environment | ||
variable to the file path of your registry credentials for use in later steps. | ||
For example, for the `podman` CLI: | ||
+ | ||
---- | ||
$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json | ||
---- | ||
|
||
.Procedure | ||
|
||
. On the workstation with unrestricted network access, authenticate with the | ||
target mirror registry: | ||
+ | ||
---- | ||
$ podman login <registry_host_name> | ||
---- | ||
+ | ||
Also authenticate with `registry.redhat.io` so that the base image can be pulled | ||
during the build: | ||
+ | ||
---- | ||
$ podman login registry.redhat.io | ||
---- | ||
|
||
. Build a new catalog image based on the `redhat-operators` catalog from | ||
link:https://quay.io/[quay.io], tagging and pushing it to your mirror registry: | ||
+ | ||
---- | ||
$ oc adm catalog build \ | ||
--appregistry-org redhat-operators \//<1> | ||
--from=registry.redhat.io/openshift4/ose-operator-registry:v4.4 \//<2> | ||
--filter-by-os="linux/amd64" \//<3> | ||
--to=<registry_host_name>:<port>/olm/redhat-operators:v2 \//<4> | ||
[-a ${REG_CREDS}] \//<5> | ||
[--insecure] <6> | ||
INFO[0013] loading Bundles dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 | ||
... | ||
Pushed sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 to example_registry:5000/olm/redhat-operators:v2 | ||
---- | ||
<1> Organization (namespace) to pull from an App Registry instance. | ||
<2> Set `--from` to the `ose-operator-registry` base image using the tag that | ||
matches the target {product-title} cluster major and minor version. | ||
<3> Set `--filter-by-os` to the operating system and architecture to use for the | ||
base image, which must match the target {product-title} cluster. Valid values | ||
are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. | ||
<4> Name your catalog image and include a tag, for example, `v2` because it is the | ||
updated catalog. | ||
<5> Optional: If required, specify the location of your registry credentials file. | ||
<6> Optional: If you do not want to configure trust for the target registry, add the | ||
`--insecure` flag. | ||
|
||
. Mirror the contents of your catalog to your target registry. The following | ||
`oc adm catalog mirror` command extracts the contents of your custom Operator | ||
catalog image to generate the manifests required for mirroring and mirrors the | ||
images to your registry: | ||
+ | ||
---- | ||
$ oc adm catalog mirror \ | ||
<registry_host_name>:<port>/olm/redhat-operators:v2 \//<1> | ||
<registry_host_name>:<port> \ | ||
[-a ${REG_CREDS}] \//<2> | ||
[--insecure] \//<3> | ||
[--filter-by-os="<os>/<arch>"] <4> | ||
mirroring ... | ||
---- | ||
<1> Specify your new Operator catalog image. | ||
<2> Optional: If required, specify the location of your registry credentials | ||
file. | ||
<3> Optional: If you do not want to configure trust for the target registry, add | ||
the `--insecure` flag. | ||
<4> Optional: Because the catalog might reference images that support multiple | ||
architectures and operating systems, you can filter by architecture and | ||
operating system to mirror only the images that match. Valid values are | ||
`linux/amd64`, `linux/ppc64le`, and `linux/s390x`. | ||
|
||
. Apply the newly generated manifests: | ||
+ | ||
---- | ||
$ oc apply -f ./redhat-operators-manifests | ||
---- | ||
+ | ||
[IMPORTANT] | ||
==== | ||
It is possible that you do not need to apply the `imageContentSourcePolicy.yaml` | ||
manifest. Complete a `diff` of the files to determine if changes are necessary. | ||
==== | ||
|
||
. Update your CatalogSource object that references your catalog image. | ||
|
||
.. If you have your original `catalogsource.yaml` file for this CatalogSource: | ||
|
||
... Edit your `catalogsource.yaml` file to reference your new catalog image in the | ||
`spec.image` field: | ||
+ | ||
[source,yaml] | ||
---- | ||
apiVersion: operators.coreos.com/v1alpha1 | ||
kind: CatalogSource | ||
metadata: | ||
name: my-operator-catalog | ||
namespace: openshift-marketplace | ||
spec: | ||
sourceType: grpc | ||
image: <registry_host_name>:<port>/olm/redhat-operators:v2 <1> | ||
displayName: My Operator Catalog | ||
publisher: grpc | ||
---- | ||
<1> Specify your new Operator catalog image. | ||
|
||
... Use the updated file to replace the CatalogSource object: | ||
+ | ||
---- | ||
$ oc replace -f catalogsource.yaml | ||
---- | ||
|
||
.. Alternatively, edit the CatalogSource using the following command and reference | ||
your new catalog image in the `spec.image` parameter: | ||
+ | ||
---- | ||
$ oc edit catalogsource <catalog_source_name> -n openshift-marketplace | ||
---- | ||
|
||
Updated Operators should now be available from the *OperatorHub* page on your | ||
{product-title} cluster. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.