diff --git a/disconnected/about.adoc b/disconnected/about.adoc index 9fc8abe1e85a..dfdb28428e8f 100644 --- a/disconnected/about.adoc +++ b/disconnected/about.adoc @@ -6,56 +6,23 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] A disconnected environment is an environment that does not have full access to the internet. {product-title} is designed to perform many automatic functions that depend on an internet connection, such as retrieving release images from a registry or retrieving update paths and recommendations for the cluster. Without a direct internet connection, you must perform additional setup and configuration for your cluster to maintain full functionality in the disconnected environment. -[id="glossary-disconnected_{context}"] -== Glossary of disconnected environment terms +//Glossary of disconnected environment terms +include::modules/glossary-discc-env-terms.adoc[leveloffset=+1] -Although it is used throughout the {product-title} documentation, _disconnected environment_ is a broad term that can refer to environments with various levels of internet connectivity. -Other terms are sometimes used to refer to a specific level of internet connectivity, and these environments might require additional unique configurations. +//Preferred methods for working with disconnected environments +include::modules/pref-methods-working-discc-env.adoc[leveloffset=+1] -The following table describes the different terms used to refer to environments without a full internet connection: +[role='_additional-resources'] +[id="about-additional-resources_{context}"] +== Additional resources +* xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[Mirroring images for a disconnected installation by using the oc-mirror plugin v2] -.Disconnected environment terms -[cols=".^2,.^4",options="header"] -|==== -|Term |Description +* xref:../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#installing-with-agent-based-installer[Installing a cluster with customizations] -|Air-gapped network -|An environment or network that is completely isolated from an external network. - -This isolation depends on a physical separation, or an "air gap", between machines on the internal network and any other part of an external network. -Air-gapped environments are often used in industries with strict security or regulatory requirements. - -|Disconnected environment -|An environment or network that has some level of isolation from an external network. - -This isolation could be enabled by physical or logical separation between machines on the internal network and an external network. -Regardless of the level of isolation from the external network, a cluster in a disconnected environment does not have access to public services hosted by Red{nbsp}Hat and requires additional setup to maintain full cluster functionality. - -|Restricted Network -|An environment or network with limited connection to an external network. - -A physical connection may exist between machines on the internal network and an external network, but network traffic is limited by additional configurations, such as with firewalls and proxies. -|==== - -[id="preferred-methods_{context}"] -== Preferred methods for working with disconnected environments - -// Not sure about the heading above, I'm trying to find some phrasing that basically says "You should probably use these things if you don't have a strong reason to go with other options". - -You can choose between multiple options for most aspects of managing a cluster in a disconnected environment. -For example, when mirroring images you can choose between using the oc-mirror {oc-first} plugin or using the `oc adm` command. - -However, some options provide a simpler and more convenient user experience for disconnected environments, and are the preferred method over their alternatives. - -Unless your organizational needs require you to choose another option, use the following methods for mirroring images, installing your cluster, and updating your cluster: - -* Mirror your images using the xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[oc-mirror plugin v2]. - -* Install your cluster using the xref:../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#installing-with-agent-based-installer[Agent-based Installer]. - -* Update your cluster using a xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[local OpenShift Update Service instance]. \ No newline at end of file +* xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service] \ No newline at end of file diff --git a/disconnected/using-olm.adoc b/disconnected/using-olm.adoc index d662520048a3..73bad6d82d6a 100644 --- a/disconnected/using-olm.adoc +++ b/disconnected/using-olm.adoc @@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] For {product-title} clusters in disconnected environments, Operator Lifecycle Manager (OLM) by default cannot access the Red{nbsp}Hat-provided software catalog sources hosted on remote registries because those remote sources require full internet connectivity. However, as a cluster administrator you can still enable your cluster to use OLM in a disconnected environment if you have a workstation that has full internet access. The workstation, which requires full internet access to pull the remote software catalog content, is used to prepare local mirrors of the remote sources, and push the content to a mirror registry. @@ -27,52 +28,45 @@ While OLM can manage Operators from local sources, the ability for a given Opera * List any related images, or other container images that the Operator might require to perform their functions, in the `relatedImages` parameter of its `ClusterServiceVersion` (CSV) object. * Reference all specified images by a digest (SHA) and not by a tag. -You can search software on the link:https://catalog.redhat.com/software/search?p=1&deployed_as=Operator&type=Containerized%20application&badges_and_features=Disconnected[Red{nbsp}Hat Ecosystem Catalog] for a list of Red{nbsp}Hat Operators that support running in disconnected mode by filtering with the following selections: +You can search software on the Red{nbsp}Hat Ecosystem Catalog for a list of Red{nbsp}Hat Operators that support running in disconnected mode by filtering with the following selections: [horizontal] Type:: Containerized application Deployment method:: Operator Infrastructure features:: Disconnected + +For more information, see "Red{nbsp}Hat Ecosystem Catalog". ==== [role="_additional-resources"] .Additional resources +* link:https://catalog.redhat.com/software/search?p=1&deployed_as=Operator&type=Containerized%20application&badges_and_features=Disconnected[Red{nbsp}Hat Ecosystem Catalog] -* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red{nbsp}Hat-provided Operator catalogs] - -[id="olm-restricted-network-prereqs"] -== Prerequisites - -* You are logged in to your {product-title} cluster as a user with `cluster-admin` privileges. - -* If you are using OLM in a disconnected environment on {ibm-z-name}, you must have at least 12 GB allocated to the directory where you place your registry. +//Prerequisites +include::modules/prereq-olm.adoc[leveloffset=+1] +//Disabling the default software catalog sources include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+1] -[id="olm-mirror-catalog_olm-restricted-networks"] -== Mirroring an Operator catalog - -For instructions about mirroring Operator catalogs for use with disconnected clusters, see xref:../disconnected/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters]. - -[IMPORTANT] -==== -As of {product-title} 4.11, the default Red{nbsp}Hat-provided Operator catalog releases in the file-based catalog format. The default Red{nbsp}Hat-provided Operator catalogs for {product-title} 4.6 through 4.10 released in the deprecated SQLite database format. +//Mirroring an Operator catalog +include::modules/mirroring-operator-catalog.adoc[leveloffset=+1] -The `opm` subcommands, flags, and functionality related to the SQLite database format are also deprecated and will be removed in a future release. The features are still supported and must be used for catalogs that use the deprecated SQLite database format. - -Many of the `opm` subcommands and flags for working with the SQLite database format, such as `opm index prune`, do not work with the file-based catalog format. For more information about working with file-based catalogs, see xref:../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[Operator Framework packaging format], xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[Managing custom catalogs], and xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[Mirroring images for a disconnected installation by using the oc-mirror plugin v2]. -==== +[role="_additional-resources"] +.Additional resources +* xref:../disconnected/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters] +* xref:../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[Operator Framework packaging format] +* xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[Managing custom catalogs] +* xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[Mirroring images for a disconnected installation by using the oc-mirror plugin v2] +//Adding a catalog source to a cluster include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +[id="using-olm-additional-resources_{context}"] +== Additional resources +* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red{nbsp}Hat-provided Operator catalogs] * xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries] * xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource-image-template_olm-understanding-olm[Image template for custom catalog sources] * xref:../openshift_images/managing_images/image-pull-policy.adoc#image-pull-policy[Image pull policy] - -[id="next-steps_olm-restricted-networks"] -== Next steps - -* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] +* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Update installed Operators] \ No newline at end of file diff --git a/modules/glossary-discc-env-terms.adoc b/modules/glossary-discc-env-terms.adoc new file mode 100644 index 000000000000..fd1d154034bd --- /dev/null +++ b/modules/glossary-discc-env-terms.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * disconnected/mirroring/about.adoc + +:_mod-docs-content-type: REFERENCE +[id="glossary-disconnected_{context}"] += Glossary of disconnected environment terms + +[role="_abstract"] +Although it is used throughout the {product-title} documentation, _disconnected environment_ is a broad term that can refer to environments with various levels of internet connectivity. +Other terms are sometimes used to refer to a specific level of internet connectivity, and these environments might require additional unique configurations. + +The following table describes the different terms used to refer to environments without a full internet connection: + +.Disconnected environment terms +[cols=".^2,.^4",options="header"] +|==== +|Term |Description + +|Air-gapped network +|An environment or network that is completely isolated from an external network. + +This isolation depends on a physical separation, or an "air gap", between machines on the internal network and any other part of an external network. +Air-gapped environments are often used in industries with strict security or regulatory requirements. + +|Disconnected environment +|An environment or network that has some level of isolation from an external network. + +This isolation could be enabled by physical or logical separation between machines on the internal network and an external network. +Regardless of the level of isolation from the external network, a cluster in a disconnected environment does not have access to public services hosted by Red{nbsp}Hat and requires additional setup to maintain full cluster functionality. + +|Restricted Network +|An environment or network with limited connection to an external network. + +A physical connection may exist between machines on the internal network and an external network, but network traffic is limited by additional configurations, such as with firewalls and proxies. +|==== \ No newline at end of file diff --git a/modules/mirroring-operator-catalog.adoc b/modules/mirroring-operator-catalog.adoc new file mode 100644 index 000000000000..a38afb7ef7af --- /dev/null +++ b/modules/mirroring-operator-catalog.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * disconnected/mirroring/using-olm.adoc + +:_mod-docs-content-type: CONCEPT +[id="olm-mirror-catalog_{context}"] += Mirroring an Operator catalog + +[role="_abstract"] +For instructions about mirroring Operator catalogs for use with disconnected clusters, see "Mirroring Operator catalogs for use with disconnected clusters". + +[IMPORTANT] +==== +As of {product-title} 4.11, the default Red{nbsp}Hat-provided Operator catalog releases in the file-based catalog format. The default Red{nbsp}Hat-provided Operator catalogs for {product-title} 4.6 through 4.10 released in the deprecated SQLite database format. + +The `opm` subcommands, flags, and functionality related to the SQLite database format are also deprecated and will be removed in a future release. The features are still supported and must be used for catalogs that use the deprecated SQLite database format. + +Many of the `opm` subcommands and flags for working with the SQLite database format, such as `opm index prune`, do not work with the file-based catalog format. For more information about working with file-based catalogs, see "Operator Framework packaging format", "Managing custom catalogs", and "Mirroring images for a disconnected installation by using the oc-mirror plugin v2". +==== \ No newline at end of file diff --git a/modules/olm-creating-catalog-from-index.adoc b/modules/olm-creating-catalog-from-index.adoc index ecef00db9d7c..6fb1a801f27e 100644 --- a/modules/olm-creating-catalog-from-index.adoc +++ b/modules/olm-creating-catalog-from-index.adoc @@ -3,6 +3,7 @@ // * post_installation_configuration/preparing-for-users.adoc // * operators/admin/olm-restricted-networks.adoc // * operators/admin/managing-custom-catalogs.adoc +// * disconnected/using-olm.adoc ifdef::openshift-origin[] :index-image: catalog @@ -78,30 +79,32 @@ ifdef::olm-restricted-networks[] apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: - name: my-operator-catalog <1> - namespace: {namespace} <2> + name: my-operator-catalog + namespace: {namespace} spec: sourceType: grpc grpcPodConfig: - securityContextConfig: <3> - image: //{index-image}:{tag} <4> + securityContextConfig: + image: //{index-image}:{tag} displayName: My Operator Catalog - publisher: <5> + publisher: updateStrategy: - registryPoll: <6> + registryPoll: interval: 30m ---- -<1> If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object. -<2> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace. -<3> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. +where: + +`metadata.name`:: Specifies the value for the `metadata.name` parameter. If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object. +`metadata.namespace`:: Specifies the value for the `metadata.namespace` parameter. If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace. +`spec.grpcPodConfig.securityContextConfig`:: Specifies the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. + [NOTE] ==== If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`. ==== -<4> Specify your index image. If you specify a tag after the image name, for example `:{tag}`, the catalog source pod uses an image pull policy of `Always`, meaning the pod always pulls the image prior to starting the container. If you specify a digest, for example `@sha256:`, the image pull policy is `IfNotPresent`, meaning the pod pulls the image only if it does not already exist on the node. -<5> Specify your name or an organization name publishing the catalog. -<6> Catalog sources can automatically check for new versions to keep up to date. +`spec.image`:: Specifies your index image. If you specify a tag after the image name, for example `:{tag}`, the catalog source pod uses an image pull policy of `Always`, meaning the pod always pulls the image before starting the container. If you specify a digest, for example `@sha256:`, the image pull policy is `IfNotPresent`, meaning the pod pulls the image only if it does not already exist on the node. +`spec.publisher`:: Specifies your name or an organization name publishing the catalog. +`spec.updateStrategy.registryPoll`:: Specifies the value for the `spec.updateStrategy.registryPoll` parameter. The catalog sources can automatically check for new versions to keep up to date. -- endif::[] ifndef::olm-restricted-networks[] @@ -114,32 +117,34 @@ apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: my-operator-catalog - namespace: {namespace} <1> + namespace: {namespace} annotations: - olm.catalogImageTemplate: <2> + olm.catalogImageTemplate: "//:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}" spec: sourceType: grpc grpcPodConfig: - securityContextConfig: <3> - image: //: <4> + securityContextConfig: + image: //: displayName: My Operator Catalog - publisher: <5> + publisher: updateStrategy: - registryPoll: <6> + registryPoll: interval: 30m ---- -<1> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace. -<2> Optional: Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. -<3> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. +where: + +`metadata.namespace`:: Specifies the value for the `metadata.namespace` parameter. If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace. +`metadata.annotations`:: Specifies the value for the `metadata.annotations` parameter. This is optional to set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. +`spec.grpcPodConfig.securityContextConfig`:: Specifies the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. + [NOTE] ==== If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`. ==== -<4> Specify your index image. If you specify a tag after the image name, for example `:{tag}`, the catalog source pod uses an image pull policy of `Always`, meaning the pod always pulls the image prior to starting the container. If you specify a digest, for example `@sha256:`, the image pull policy is `IfNotPresent`, meaning the pod pulls the image only if it does not already exist on the node. -<5> Specify your name or an organization name publishing the catalog. -<6> Catalog sources can automatically check for new versions to keep up to date. +`spec.image`:: Specifies your index image. If you specify a tag after the image name, for example `:{tag}`, the catalog source pod uses an image pull policy of `Always`, meaning the pod always pulls the image before starting the container. If you specify a digest, for example `@sha256:`, the image pull policy is `IfNotPresent`, meaning the pod pulls the image only if it does not already exist on the node. +`spec.publisher`:: Specifies your name or an organization name publishing the catalog. +`spec.updateStrategy.registryPoll`:: Specifies the value for the `spec.updateStrategy.registryPoll` parameter. The catalog sources can automatically check for new versions to keep up to date. -- endif::[] diff --git a/modules/pref-methods-working-discc-env.adoc b/modules/pref-methods-working-discc-env.adoc new file mode 100644 index 000000000000..f1f90c7541b5 --- /dev/null +++ b/modules/pref-methods-working-discc-env.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * disconnected/mirroring/about.adoc + +:_mod-docs-content-type: REFERENCE +[id="preferred-methods_{context}"] += Preferred methods for working with disconnected environments + +// Not sure about the heading above, I'm trying to find some phrasing that basically says "You should probably use these things if you don't have a strong reason to go with other options". +[role="_abstract"] +You can choose between multiple options for most aspects of managing a cluster in a disconnected environment. +For example, when mirroring images you can choose between using the oc-mirror {oc-first} plugin or using the `oc adm` command. + +However, some options provide a simpler and more convenient user experience for disconnected environments, and are the preferred method over their alternatives. + +Unless your organizational needs require you to choose another option, use the following methods for mirroring images, installing your cluster, and updating your cluster: + +* Mirror your images using the oc-mirror plugin v2. For more information, see "Mirroring images for a disconnected installation by using the oc-mirror plugin v2". + +* Install your cluster using the Agent-based Installer. For more information, see "Installing a cluster with customizations". + +* Update your cluster using a local OpenShift Update Service instance. For more information, see "Updating a cluster in a disconnected environment using the OpenShift Update Service". \ No newline at end of file diff --git a/modules/prereq-olm.adoc b/modules/prereq-olm.adoc new file mode 100644 index 000000000000..e2c5cc3583ba --- /dev/null +++ b/modules/prereq-olm.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * disconnected/mirroring/using-olm.adoc + +:_mod-docs-content-type: CONCEPT +[id="olm-restricted-network-prereqs_{context}"] += Prerequisites + +[role="_abstract"] +You must meet several prerequisites before using OLM in a disconnected environment. + +The following prerequisites must be met: + +* You are logged in to your {product-title} cluster as a user with `cluster-admin` privileges. + +* If you are using OLM in a disconnected environment on {ibm-z-name}, you must have at least 12 GB allocated to the directory where you place your registry. \ No newline at end of file