diff --git a/_topic_map.yml b/_topic_map.yml index 81186e4a7cbd..6b0fba264478 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -393,8 +393,10 @@ Name: Updating clusters Dir: updating Distros: openshift-origin,openshift-enterprise Topics: -- Name: Understanding the update service +- Name: Understanding the OpenShift Update Service File: understanding-the-update-service +- Name: Installing and configuring the OpenShift Update Service + File: installing-update-service - Name: Updating a cluster between minor versions File: updating-cluster-between-minor - Name: Updating a cluster within a minor version from the web console diff --git a/modules/update-restricted.adoc b/modules/update-restricted.adoc index bd32b581d8fc..997e1067da35 100644 --- a/modules/update-restricted.adoc +++ b/modules/update-restricted.adoc @@ -7,6 +7,13 @@ Update the restricted network cluster to the {product-title} version that you downloaded the release images for. +//TODO: Add xrefs in the following note when functionality is enabled. + +[NOTE] +==== +If you have a local OpenShift Update Service, you can update by using the connected web console or CLI instructions instead of this procedure. +==== + .Prerequisites * You mirrored the images for the new release to your registry. @@ -28,5 +35,5 @@ If you use an `ImageContentSourcePolicy` for the mirror registry, you can use th + [NOTE] ==== -You can only configure global pull secrets for clusters that have an `ImageContentSourcePolicy` object. You cannot add a pull secret to a project. +You can only configure global pull secrets for clusters that have an `ImageContentSourcePolicy` object. You cannot add a pull secret to a project. ==== diff --git a/modules/update-service-configure-cvo.adoc b/modules/update-service-configure-cvo.adoc new file mode 100644 index 000000000000..4000c48638c7 --- /dev/null +++ b/modules/update-service-configure-cvo.adoc @@ -0,0 +1,42 @@ +[id="update-service-configure-cvo"] += Configuring the Cluster Version Operator (CVO) + +After the OpenShift Update Service Operator has been installed and the OpenShift Update Service application created CVO can be updated to pull graph data from the locally installed OpenShift Update Service. + +.Prerequisites + +* The OpenShift Update Service Operator has been installed. +* The Openshift Update Service graph-data container image has been created and pushed to a repository accessible to the OpenShift Update Service. +* The current release and update target releases have been mirrored to a locally accessible registry. +* The OpenShift Update Service application has been created. + +.Procedure + +. Set the OpenShift Update Service target namespace, for example, `openshift-update-service`: ++ +[source,terminal] +---- +$ NAMESPACE=openshift-update-service +---- + +. Set the name of the OpenShift Update Service application, for example, `service`: ++ +[source,terminal] +---- +$ NAME=service +---- + +. Obtain the policy engine route: ++ +[source,terminal] +---- +$ POLICY_ENGINE_GRAPH_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.policyEngineURI}/api/upgrades_info/v1/graph{"\n"}' updateservice "${NAME}")" +---- + +. Patch the CVO ClusterVersion to use the local OpenShift Update Service: ++ +[source,terminal] +---- +$ PATCH="{\"spec\":{\"upstream\":\"${POLICY_ENGINE_GRAPH_URI}\"}}" +$ oc patch clusterversion version -p $PATCH --type merge +---- diff --git a/modules/update-service-create-service-cli.adoc b/modules/update-service-create-service-cli.adoc new file mode 100644 index 000000000000..263c035baf3d --- /dev/null +++ b/modules/update-service-create-service-cli.adoc @@ -0,0 +1,82 @@ +[id="update-service-create-service-cli_{context}"] += Creating an OpenShift Update Service application by using the CLI + +You can use the {product-title} CLI to create an OpenShift Update Service application. + +.Prerequisites + +* The OpenShift Update Service Operator has already been installed. +* The Openshift Update Service graph-data container image has already been created and pushed to a repository accessible to the OpenShift Update Service. +* The current release and update target releases have already been mirrored to a locally accessible registry. + +.Procedure + +To create an OpenShift Update Service application by using the {product-title} CLI: + +. Configure the OpenShift Update Service target namespace, for example, `openshift-update-service`: ++ +[source,terminal] +---- +$ NAMESPACE=openshift-update-service +---- ++ +The namespace must match the `targetNamespaces` value from the OperatorGroup. + +. Configure the name of the OpenShift Update Service application, for example, `service`: ++ +[source,terminal] +---- +$ NAME=service +---- + +. Configure the local registry and repository for the release images as configured in "Mirroring the {product-title} image repository", for example, `registry.example.com/ocp4/openshift4-release-images`: +//TODO: Add xref to the preceding step when allowed. ++ +[source,terminal] +---- +$ RELEASE_IMAGES=registry.example.com/ocp4/openshift4-release-images +---- + +. Set the local pullspec for the graph-data image to the graph-data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`: +//TODO: Add xref to the preceding step when allowed. ++ +[source,terminal] +---- +$ GRAPH_DATA_IMAGE=registry.example.com/openshift/graph-data:latest +---- + +. Create an OpenShift Update Service application object: ++ +[source,terminal] +---- +$ oc -n "${NAMESPACE}" create -f - < *Installed Operators*. + +. Choose *OpenShift Update Service* from the list of installed Operators. + +. Click the *Update Service* tab. + +. Click *Create UpdateService*. + +. Enter a name in the *Name* field, for example, `service`. + +. Enter the local pullspec in the *Graph Data Image* field to the graph-data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`. +//TODO: Add xref to preceding step when allowed. + +. In the *Releases* field, enter the local registry and repository created to contain the release images in "Mirroring the OpenShift Container Platform image repository", for example, `registry.example.com/ocp4/openshift4-release-images`. +//TODO: Add xref to preceding step when allowed. + +. Enter `2` in the *Replicas* field. + +. Click *Create* to create the OpenShift Update Service application. + +. Verify the OpenShift Update Service application: + +** From the *UpdateServices* list in the *Update Service* tab, click the Update Service application just created. + +** Click the *Resources* tab. + +** Verify each application resource has status *Created*. diff --git a/modules/update-service-delete-service-cli.adoc b/modules/update-service-delete-service-cli.adoc new file mode 100644 index 000000000000..1c6c37fef1a4 --- /dev/null +++ b/modules/update-service-delete-service-cli.adoc @@ -0,0 +1,35 @@ +[id="update-service-delete-service-cli_{context}"] += Deleting an OpenShift Update Service application by using the CLI + +You can use the {product-title} CLI to delete an OpenShift Update Service application. + +.Procedure + +To delete an OpenShift Update Service application by using the {product-title} CLI: + +. Get the OpenShift Update Service application name using the namespace the OpenShift Update Service application was created in, for example, `openshift-update-service`: ++ +[source,terminal] +---- +$ oc get updateservice -n openshift-update-service +---- ++ +.Example output +[source,terminal] +---- +NAME AGE +service 6s +---- + +. Delete the OpenShift Update Service application using the `Name` value from the previous step and the namespace the OpenShift Update Service application was created in, for example, `openshift-update-service`: ++ +[source,terminal] +---- +$ oc delete updateservice service -n openshift-update-service +---- ++ +.Example output +[source,terminal] +---- +updateservice.updateservice.operator.openshift.io "service" deleted +---- diff --git a/modules/update-service-delete-service-web-console.adoc b/modules/update-service-delete-service-web-console.adoc new file mode 100644 index 000000000000..94f81d611f98 --- /dev/null +++ b/modules/update-service-delete-service-web-console.adoc @@ -0,0 +1,22 @@ +[id="update-service-delete-service-web-console_{context}"] += Deleting an OpenShift Update Service application by using the web console + +You can use the {product-title} web console to delete an OpenShift Update Service application by using the OpenShift Update Service Operator. + +.Prerequisites + +* The OpenShift Update Service Operator has already been installed. + +.Procedure + +To delete an OpenShift Update Service application by using the {product-title} web console: + +. In the {product-title} web console, click *Operators* -> *Installed Operators*. + +. Choose *OpenShift Update Service* from the list of installed Operators. + +. Click the *Update Service* tab. + +. From the list of installed OpenShift Update Service applications, select the menu icon at the far right of the application to be deleted and then click *Delete UpdateService*. + +. From the *Delete UpdateService?* pop up click the *Delete* button to confirm the deletion. diff --git a/modules/update-service-graph-data.adoc b/modules/update-service-graph-data.adoc new file mode 100644 index 000000000000..b3c3db15b174 --- /dev/null +++ b/modules/update-service-graph-data.adoc @@ -0,0 +1,31 @@ +[id="update-service-graph-data_{context}"] += Creating the OpenShift Update Service graph data container image + +The OpenShift Update Service requires a graph-data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the upgrade graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume accessible by the service. + +.Procedure + +. Create a Dockerfile, for example, `./Dockerfile`, containing the following: ++ +[source,terminal] +---- +FROM registry.access.redhat.com/ubi8/ubi:8.1 + +RUN curl -L -o cincinnati-graph-data.tar.gz https://github.com/openshift/cincinnati-graph-data/archive/master.tar.gz + +CMD exec /bin/bash -c "tar xvzf cincinnati-graph-data.tar.gz -C /var/lib/cincinnati/graph-data/ --strip-components=1" +---- + +. Use the docker file created in the above step to build a graph-data container image, for example, `registry.example.com/openshift/graph-data:latest`: ++ +[source,terminal] +---- +$ podman build -f ./Dockerfile -t registry.example.com/openshift/graph-data:latest +---- + +. Push the graph-data container image created in the above step to a repository accessible to the OpenShift Update Service, for example, `registry.example.com/openshift/graph-data:latest`: ++ +[source,terminal] +---- +$ podman push registry.example.com/openshift/graph-data:latest +---- diff --git a/modules/update-service-install-cli.adoc b/modules/update-service-install-cli.adoc new file mode 100644 index 000000000000..417e65fadb55 --- /dev/null +++ b/modules/update-service-install-cli.adoc @@ -0,0 +1,119 @@ +[id="update-service-install-cli_{context}"] += Installing the OpenShift Update Service Operator by using the CLI + +You can use the {product-title} CLI to install the OpenShift Update Service Operator. + +.Procedure + +To install the OpenShift Update Service Operator by using the {product-title} CLI: + +. Create a Namespace for the OpenShift Update Service Operator: + +.. Create a Namespace object YAML file, for example, `update-service-namespace.yaml`, for the OpenShift Update Service Operator: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: openshift-update-service + annotations: + openshift.io/node-selector: "" + labels: + openshift.io/cluster-monitoring: "true" <1> +---- +<1> Set the `openshift.io/cluster-monitoring` label to enable operator recommended cluster monitoring on this namespace. + +.. Create the Namespace: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- ++ +For example: ++ +[source,terminal] +---- +$ oc create -f update-service-namespace.yaml +---- + +. Install the OpenShift Update Service Operator by creating the following objects: + +.. Create an Operator Group object YAML file, for example, `update-service-operator-group.yaml`: ++ +[source,yaml] +---- +apiVersion: operators.coreos.com/v1 +kind: OperatorGroup +metadata: + name: update-service-operator-group +spec: + targetNamespaces: + - openshift-update-service +---- + +.. Create an Operator Group object: ++ +[source,terminal] +---- +$ oc -n openshift-update-service create -f .yaml +---- ++ +For example: ++ +[source,terminal] +---- +$ oc -n openshift-update-service create -f update-service-operator-group.yaml +---- + +.. Create a Subscription object YAML file, for example, `update-service-subscription.yaml`: ++ +.Example Subscription +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: update-service-subscription +spec: + channel: v1 + installPlanApproval: "Automatic" + source: "redhat-operators" <1> + sourceNamespace: "openshift-marketplace" + name: "cincinnati-operator" +---- +<1> Specify the name of the CatalogSource that provides the Operator. For clusters that do not use a custom Operator Lifecycle Manager (OLM), specify `redhat-operators`. If your {product-title} cluster is installed on a restricted network, also known as a disconnected cluster, specify the name of the CatalogSource object created when you configured the Operator Lifecycle Manager (OLM). + +.. Create the Subscription object: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- ++ +For example: ++ +[source,terminal] +---- +$ oc -n openshift-update-service create -f update-service-subscription.yaml +---- ++ +The OpenShift Update Service Operator is installed to the `openshift-update-service` namespace and targets the `openshift-update-service` namespace. + +. Verify the Operator installation: ++ +[source,terminal] +---- +$ oc -n openshift-update-service get clusterserviceversions +---- ++ +.Example output +[source,terminal] +---- +NAME DISPLAY VERSION REPLACES PHASE +update-service-operator.v4.6.0 OpenShift Update Service 4.6.0 Succeeded +... +---- ++ +If the OpenShift Update Service Operator is listed, installation succeeded. The version number might be different than shown. diff --git a/modules/update-service-install-web-console.adoc b/modules/update-service-install-web-console.adoc new file mode 100644 index 000000000000..3314e7424946 --- /dev/null +++ b/modules/update-service-install-web-console.adoc @@ -0,0 +1,35 @@ +[id="update-service-install-web-console_{context}"] += Installing the OpenShift Update Service Operator by using the web console + +You can use the {product-title} web console to install the OpenShift Update Service Operator. + +.Procedure + +To install the OpenShift Update Service Operator using the {product-title} web console: + +. In the {product-title} web console, click *Operators* -> *OperatorHub*. ++ +[NOTE] +==== +Enter `Update Service` into the *Filter by keyword...* field to find the operator faster. +==== + +. Choose *OpenShift Update Service* from the list of available Operators, and click *Install*. + +.. `v1` will be selected as the *Update Channel* since it is the only channel available in this release. + +.. Select *A specific namespace on the cluster* under *Installation Mode*. + +.. Select a namespace for *Installed Namespace* or accept the recommended namespace `openshift-update-service`. + +.. Select an *Approval Strategy*: ++ +** The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available. ++ +** The *Manual* strategy requires a cluster administrator to approve the Operator update. + +.. Click *Install*. + +. Verify that the OpenShift Update Service Operator is installed by switching to the *Operators* -> *Installed Operators* page. + +. Ensure that *OpenShift Update Service* is listed in the selected namespace with a *Status* of *Succeeded*. diff --git a/modules/update-service-mirror-release.adoc b/modules/update-service-mirror-release.adoc new file mode 100644 index 000000000000..222808f55436 --- /dev/null +++ b/modules/update-service-mirror-release.adoc @@ -0,0 +1,171 @@ +[id="update-service-mirror-release_{context}"] += Mirroring the {product-title} image repository + +The OpenShift Update Service requires a locally accessible registry containing update release payloads. + +[IMPORTANT] +==== +To avoid excessive memory usage by the OpenShift Update Service application, it is recommended that you mirror release images to a separate repository, as described in the following procedure. +==== + +.Prerequisites + +* Review and complete the steps from "Mirroring images for a disconnected installation" up to but not including the section entitled *Mirroring the {product-title} image repository*. +//TODO: Add xref to preceding step when allowed. +* You configured a mirror registry to use in your restricted network and can access the certificate and credentials that you configured. +ifndef::openshift-origin[] +* You downloaded the pull secret from the +link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and modified it to include authentication to your mirror repository. +endif::[] +ifdef::openshift-origin[] +* You have created a pull secret for your mirror repository. +endif::[] +* If you use self-signed certificates that do not set a Subject Alternative Name, you must precede the `oc` commands in this procedure with `GODEBUG=x509ignoreCN=0`. If you do not set this variable, the `oc` commands will fail with the following error: ++ +[source,terminal] +---- +x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0 +---- + +.Procedure + +Complete the following steps on the mirror host: + +. Review the +link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page] +to determine the version of {product-title} to which you want to upgrade and determine the corresponding tag on the link:https://quay.io/repository/openshift-release-dev/ocp-release?tab=tags[Repository Tags] page. + +. Set the required environment variables: +.. Export the release version: ++ +[source,terminal] +---- +$ OCP_RELEASE= +---- ++ +For ``, specify the tag that corresponds to the version of {product-title} to +install, such as `4.6.4`. + +.. Export the local registry name and host port: ++ +[source,terminal] +---- +$ LOCAL_REGISTRY=':' +---- ++ +For ``, specify the registry domain name for your mirror +repository, and for ``, specify the port that it +serves content on. + +.. Export the local repository name: ++ +[source,terminal] +---- +$ LOCAL_REPOSITORY='' +---- ++ +For ``, specify the name of the repository to create in your +registry, such as `ocp4/openshift4`. + +.. Export an additional local repository name to contain the release images: ++ +[source,terminal] +---- +$ LOCAL_RELEASE_IMAGES_REPOSITORY='' +---- ++ +For ``, specify the name of the repository to +create in your registry, such as `ocp4/openshift4-release-images`. + +.. Export the name of the repository to mirror: ++ +[source,terminal] +---- +$ PRODUCT_REPO='openshift-release-dev' +---- ++ +For a production release, you must specify `openshift-release-dev`. + +.. Export the path to your registry pull secret: ++ +[source,terminal] +---- +$ LOCAL_SECRET_JSON='' +---- ++ +For ``, specify the absolute path to and file name of the pull secret for your mirror registry that you created. + +.. Export the release mirror: ++ +[source,terminal] +---- +$ RELEASE_NAME="ocp-release" +---- ++ +For a production release, you must specify `ocp-release`. + +.. Export the type of architecture for your server, such as `x86_64`: ++ +[source,terminal] +---- +$ ARCHITECTURE= +---- + +.. Export the path to the directory to host the mirrored images: ++ +[source,terminal] +---- +$ REMOVABLE_MEDIA_PATH= <1> +---- +<1> Specify the full path, including the initial forward slash (/) character. + +. Mirror the version images to the internal container registry: +** If your mirror host does not have Internet access, take the following actions: +... Connect the removable media to a system that is connected to the Internet. +... Review the images and configuration manifests to mirror: ++ +[source,terminal] +---- +$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ + --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run +---- +... Mirror the images to a directory on the removable media: ++ +[source,terminal] +---- +$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} +---- +... Export a local temporary repository name: ++ +[source,terminal] +---- +$ TEMP_REPOSITORY='' +---- ++ +For ``, specify the name of a temporary repository to create in your +registry, such as `ocp4/temp`. +... Take the media to the restricted network environment and upload the images to the temporary repository in the local container registry. Uploading the images to the temporary repository allows you to then mirror them from there to the final repositories at which time the release images will be mirrored to a separate repository. ++ +[source,terminal] +---- +$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${TEMP_REPOSITORY} <1> +$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ + --from=${LOCAL_REGISTRY}/${TEMP_REPOSITORY} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} +---- ++ +<1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images. + +** If the local container registry is connected to the mirror host, take the following actions: +... Directly push the release images to the local registry by using following command: ++ +[source,terminal] +---- +$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ + --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} +---- diff --git a/modules/update-service-overview.adoc b/modules/update-service-overview.adoc index aaa3d41ec522..f7b72dab3835 100644 --- a/modules/update-service-overview.adoc +++ b/modules/update-service-overview.adoc @@ -9,53 +9,28 @@ // * updating/updating-disconnected-cluster.adoc [id="update-service-overview_{context}"] -= About the {product-title} update service += About the OpenShift Update Service -The {product-title} update service is the hosted service that provides over-the-air -updates to both {product-title} and {op-system-first}. It provides a graph, -or diagram that contain _vertices_ and the _edges_ that connect them, of -component Operators. The edges in the graph show which versions you can safely -update to, and the vertices are update payloads that specify the intended state -of the managed cluster components. +The OpenShift Update Service (OSUS) is the service that provides over-the-air updates to both {product-title} and {op-system-first}. It provides a graph, or diagram, that contains _vertices_ and the _edges_ that connect them, of component Operators. The edges in the graph show which versions you can safely update to, and the vertices are update payloads that specify the intended state of the managed cluster components. -The Cluster Version Operator (CVO) in your cluster checks with the -{product-title} update service to see the valid updates and update paths based -on current component versions and information in the graph. When you request an -update, the {product-title} CVO uses the release image for that update to -upgrade your cluster. The release artifacts are hosted in Quay as container -images. +The Cluster Version Operator (CVO) in your cluster checks with the OpenShift Update Service to see the valid updates and update paths based on current component versions and information in the graph. When you request an update, the {product-title} CVO uses the release image for that update to upgrade your cluster. The release artifacts are hosted in Quay as container images. //// By accepting automatic updates, you can automatically keep your cluster up to date with the most recent compatible components. //// -To allow the {product-title} update service to provide only compatible updates, -a release verification pipeline exists to drive automation. Each release -artifact is verified for compatibility with supported cloud platforms and system -architectures as well as other component packages. After the pipeline confirms -the suitability of a release, the {product-title} update service notifies you -that it is available. +To allow the OpenShift Update Service to provide only compatible updates, a release verification pipeline exists to drive automation. Each release artifact is verified for compatibility with supported cloud platforms and system architectures as well as other component packages. After the pipeline confirms the suitability of a release, the OpenShift Update Service notifies you that it is available. [IMPORTANT] ==== -Because the update service displays all valid updates, you must not force an update to a version that the update service does not display. +Because the OpenShift Update Service displays all valid updates, you must not force an update to a version that the OpenShift Update Service does not display. ==== //// -The interaction between the registry and the {product-title} update service is different during -bootstrap and continuous update modes. When you bootstrap the initial -infrastructure, the Cluster Version Operator finds -the fully qualified image name for the shortname of the images that it needs to -apply to the server during installation. It looks at the imagestream that it needs -to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control -plane to come up and load the Cluster Version Operator. +The interaction between the registry and the OpenShift Update Service is different during bootstrap and continuous update modes. When you bootstrap the initial infrastructure, the Cluster Version Operator finds the fully qualified image name for the shortname of the images that it needs to apply to the server during installation. It looks at the imagestream that it needs to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control plane to come up and load the Cluster Version Operator. //// -During continuous update mode, two controllers run. One continuously updates -the payload manifests, applies them to the cluster, and outputs the status of -the controlled rollout of the Operators, whether they are available, upgrading, -or failed. The second controller polls the {product-title} update service to -determine if updates are available. +During continuous update mode, two controllers run. One continuously updates the payload manifests, applies them to the cluster, and outputs the status of the controlled rollout of the Operators, whether they are available, upgrading, or failed. The second controller polls the OpenShift Update Service to determine if updates are available. [IMPORTANT] ==== @@ -65,3 +40,5 @@ If your upgrade fails, contact Red Hat support. ==== During the upgrade process, the Machine Config Operator (MCO) applies the new configuration to your cluster machines. It cordons the number of nodes that is specified by the `maxUnavailable` field on the machine configuration pool and marks them as unavailable. By default, this value is set to `1`. It then applies the new configuration and reboots the machine. If you use Red Hat Enterprise Linux (RHEL) machines as workers, the MCO does not update the kubelet on these machines because you must update the OpenShift API on them first. Because the specification for the new version is applied to the old kubelet, the RHEL machine cannot return to the `Ready` state. You cannot complete the update until the machines are available. However, the maximum number of nodes that are unavailable is set to ensure that normal cluster operations are likely to continue with that number of machines out of service. + +The OpenShift Update Service is composed of an Operator and one or more application instances. diff --git a/modules/update-service-uninstall-cli.adoc b/modules/update-service-uninstall-cli.adoc new file mode 100644 index 000000000000..afcef7ae3704 --- /dev/null +++ b/modules/update-service-uninstall-cli.adoc @@ -0,0 +1,105 @@ +[id="update-service-uninstall-cli_{context}"] += Uninstalling the OpenShift Update Service Operator by using the CLI + +You can use the {product-title} CLI to uninstall the OpenShift Update Service Operator. + +.Prerequisites + +- All OpenShift Update Service applications have been deleted. + +.Procedure + +To uninstall the OpenShift Update Service Operator by using the {product-title} CLI: + +. Change to the project containing the OpenShift Update Service Operator (for example, `openshift-update-service`). ++ +[source,terminal] +---- +$ oc project openshift-update-service +---- ++ +.Example output +[source,terminal] +---- +Now using project "openshift-update-service" on server "https://example.com:6443". +---- + +. Get the name of the OpenShift Update Service Operator operatorgroup: ++ +[source,terminal] +---- +$ oc get operatorgroup +---- ++ +.Example output +[source,terminal] +---- +NAME AGE +openshift-update-service-fprx2 4m41s +---- + +. Delete the operatorgroup (for example, `openshift-update-service-fprx2`): ++ +[source,terminal] +---- +$ oc delete operatorgroup openshift-update-service-fprx2 +---- ++ +.Example output +[source,terminal] +---- +operatorgroup.operators.coreos.com "openshift-update-service-fprx2" deleted +---- + +. Get the name of the OpenShift Update Service Operator subscription: ++ +[source,terminal] +---- +$ oc get subscription +---- ++ +.Example output +[source,terminal] +---- +NAME PACKAGE SOURCE CHANNEL +update-service-operator update-service-operator updateservice-index-catalog v1 +---- + +. Using the `Name` value from the previous step, check the current version of the subscribed OpenShift Update Service Operator in the `currentCSV` field: ++ +[source,terminal] +---- +$ oc get subscription update-service-operator -o yaml | grep " currentCSV" +---- ++ +.Example output +[source,terminal] +---- + currentCSV: update-service-operator.v0.0.1 +---- + +. Delete the subscription (for example, `update-service-operator`): ++ +[source,terminal] +---- +$ oc delete subscription update-service-operator +---- ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com "update-service-operator" deleted +---- + +. Delete the CSV for the OpenShift Update Service Operator using the `currentCSV` value from the previous step: ++ +[source,terminal] +---- +$ oc delete clusterserviceversion update-service-operator.v0.0.1 +---- ++ +.Example output +[source,terminal] +---- +clusterserviceversion.operators.coreos.com "update-service-operator.v0.0.1" deleted +---- diff --git a/modules/update-service-uninstall-web-console.adoc b/modules/update-service-uninstall-web-console.adoc new file mode 100644 index 000000000000..cb98d6271c22 --- /dev/null +++ b/modules/update-service-uninstall-web-console.adoc @@ -0,0 +1,18 @@ +[id="update-service-uninstall-web-console_{context}"] += Uninstalling the OpenShift Update Service Operator by using the web console + +You can use the {product-title} web console to uninstall the OpenShift Update Service Operator. + +.Prerequisites + +- All OpenShift Update Service applications have been deleted. + +.Procedure + +To uninstall the OpenShift Update Service Operator using the {product-title} web console: + +. In the {product-title} web console, click *Operators* -> *Installed Operators*. + +. Click *Uninstall Operator* from the menu of *OpenShift Update Service* from the list of installed Operators. + +. From the *Uninstall Operator?* confirmation dialog, click *Uninstall* to confirm the uninstall. diff --git a/updating/installing-update-service.adoc b/updating/installing-update-service.adoc new file mode 100644 index 000000000000..ca881f903b41 --- /dev/null +++ b/updating/installing-update-service.adoc @@ -0,0 +1,68 @@ +[id="installing-update-service"] += Installing and configuring the OpenShift Update Service +include::modules/common-attributes.adoc[] +:context: update-service + +toc::[] + +// The following include statements pull in the module files that comprise +// the assembly. Include any combination of concept, procedure, or reference +// modules required to cover the user story. You can also include other +// assemblies. + +For clusters with internet accessibility, Red Hat provides over-the-air updates through an OpenShift Container Platform update service as a hosted service located behind public APIs. However, for clusters in a restricted network, there’s no way to access these public APIs to obtain this information. In order to provide a similar user upgrade experience in a restricted network users can install and configure the OpenShift Update Service locally, i.e. accessible within their disconnected network, to provide over-the-air updates for your cluster and its underlying operating system as described in the following sections. + +include::modules/update-service-overview.adoc[leveloffset=+1] + +[id="update-service-prereqs"] +== Prerequisites + +* For more information on installing Operators, see xref:../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-in-namespace[Installing Operators in your namespace]. +* If the release images are contained in a secure registry, complete steps in xref:../registry/configuring-registry-operator.adoc#images-configuration-cas_configuring-registry-operator[Configuring additional trust stores for image registry access]. + +[id="update-service-install"] +== Installing the OpenShift Update Service Operator + +The OpenShift Update Service is installed by first installing the OpenShift Update Service Operator by using the {product-title} web console or CLI. + +[NOTE] +==== +For clusters that are installed on restricted networks, also known as disconnected clusters, Operator Lifecycle Manager by default cannot access the Red Hat-provided OperatorHub sources hosted on remote registries because those remote sources require full internet connectivity. For more information, see xref:../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks]. +==== + +include::modules/update-service-install-web-console.adoc[leveloffset=+2] + +include::modules/update-service-install-cli.adoc[leveloffset=+2] + +include::modules/update-service-graph-data.adoc[leveloffset=+2] + +include::modules/update-service-mirror-release.adoc[leveloffset=+2] + +[id="update-service-create-service"] +== Creating an OpenShift Update Service application + +You can create an OpenShift Update Service application by using the {product-title} web console or CLI. + +include::modules/update-service-create-service-web-console.adoc[leveloffset=+2] + +include::modules/update-service-create-service-cli.adoc[leveloffset=+2] + +include::modules/update-service-configure-cvo.adoc[leveloffset=+2] + +[id="update-service-delete-service"] +== Deleting an OpenShift Update Service application + +You can delete an OpenShift Update Service application by using the {product-title} web console or CLI. + +include::modules/update-service-delete-service-web-console.adoc[leveloffset=+2] + +include::modules/update-service-delete-service-cli.adoc[leveloffset=+2] + +[id="update-service-uninstall"] +== Uninstalling the OpenShift Update Service Operator + +The OpenShift Update Service is uninstalled by first deleting all OpenShift Update Service applications by using the {product-title} web console or CLI. + +include::modules/update-service-uninstall-web-console.adoc[leveloffset=+2] + +include::modules/update-service-uninstall-cli.adoc[leveloffset=+2] diff --git a/updating/understanding-the-update-service.adoc b/updating/understanding-the-update-service.adoc index 92393c64789b..e230d084da9b 100644 --- a/updating/understanding-the-update-service.adoc +++ b/updating/understanding-the-update-service.adoc @@ -5,6 +5,13 @@ include::modules/common-attributes.adoc[] toc::[] +For clusters with internet accessibility, Red Hat provides over-the-air updates through an {product-title} update service as a hosted service located behind public APIs. + +[NOTE] +==== +Because clusters cannot access public APIs in a restricted network, you can install the OpenShift Update Service locally if you are in a disconnected network. See xref:../updating/installing-update-service.adoc#installing-update-service[Installing and configuring the OpenShift Update Service]. +==== + include::modules/update-service-overview.adoc[leveloffset=+1] include::modules/unmanaged-operators.adoc[leveloffset=+1] diff --git a/updating/updating-restricted-network-cluster.adoc b/updating/updating-restricted-network-cluster.adoc index 0ee8e9b3aa7b..e92e534943f2 100644 --- a/updating/updating-restricted-network-cluster.adoc +++ b/updating/updating-restricted-network-cluster.adoc @@ -54,3 +54,9 @@ include::modules/update-configuring-image-signature.adoc[leveloffset=+2] include::modules/update-restricted.adoc[leveloffset=+1] include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1] + +[id="additional-resources_security-container-signature"] +== Additional resources +* xref:../post_installation_configuration/machine-configuration-tasks.adoc#machine-config-overview-post-install-machine-configuration-tasks[Machine Config Overview] + +* xref:../updating/installing-update-service.adoc#installing-update-service[Installing and configuring the OpenShift Update Service] diff --git a/welcome/index.adoc b/welcome/index.adoc index bda0c7c6c76f..99849808f53b 100644 --- a/welcome/index.adoc +++ b/welcome/index.adoc @@ -233,6 +233,8 @@ There is a separate process for xref:../updating/updating-disconnected-cluster.adoc#updating-disconnected-cluster[updating a cluster on a restricted network]. //// +- **xref:../updating/installing-update-service.adoc#installing-update-service[Understanding the OpenShift Update Service]**: Learn about installing and managing a local OpenShift Update Service for recommending {product-title} updates in restricted network environments. + === Monitor the cluster - **xref:../logging/cluster-logging.adoc#cluster-logging[Work with OpenShift Logging]**: Learn about OpenShift Logging and configure different OpenShift Logging types, such as Elasticsearch, Fluentd, Kibana, and Curator.