update_service: Add docs for the OpenShift Update Service

_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

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.
 ====

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
+----

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 - <<EOF
+apiVersion: updateservice.operator.openshift.io/v1
+kind: UpdateService
+metadata:
+  name: ${NAME}
+spec:
+  replicas: 2
+  releases: ${RELEASE_IMAGES}
+  graphDataImage: ${GRAPH_DATA_IMAGE}
+EOF
+----
+
+. Verify the OpenShift Update Service application:
+
+.. Use the following command to obtain a policy engine route:
++
+[source,terminal]
+----
+$ while sleep 1; do POLICY_ENGINE_GRAPH_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.policyEngineURI}/api/upgrades_info/v1/graph{"\n"}' updateservice "${NAME}")"; SCHEME="${POLICY_ENGINE_GRAPH_URI%%:*}"; if test "${SCHEME}" = http -o "${SCHEME}" = https; then break; fi; done
+----
++
+You might need to poll until the command succeeds.
+
+.. Retrieve a graph from the policy engine. Be sure to specify a valid version for *channel*. For example, if running in {product-title} {product-version} use version {product-version}, e.g. *stable-{product-version}*:
++
+[source,terminal]
+----
+$ while sleep 10; do HTTP_CODE="$(curl --header Accept:application/json --output /dev/stderr --write-out "%{http_code}" "${POLICY_ENGINE_GRAPH_URI}?channel=stable-4.6")"; if test "${HTTP_CODE}" -eq 200; then break; fi; echo "${HTTP_CODE}"; done
+----
++
+This polls until the graph request succeeds, although depending on which release images you have mirrored, the resulting graph might be empty.

modules/update-service-create-service-web-console.adoc

@@ -0,0 +1,42 @@
+[id="update-service-create-service-web-console_{context}"]
+= Creating an OpenShift Update Service application by using the web console
+
+You can use the {product-title} web console to create an Update Service application by using the OpenShift Update Service Operator.
+
+.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} 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.
+
+. 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*.

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
+----

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.

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
+----