diff --git a/_topic_map.yml b/_topic_map.yml index 61f6ed29c5ad..aac88537f6ba 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1691,6 +1691,13 @@ Topics: - Name: Uninstalling metering File: metering-uninstall --- +Name: OpenShift Update Service +Dir: update_service +Distros: openshift-enterprise,openshift-origin,openshift-webscale +Topics: +- Name: Installing and configuring the OpenShift Update Service + File: installing-update-service +--- Name: Scalability and performance Dir: scalability_and_performance Distros: openshift-origin,openshift-enterprise,openshift-webscale diff --git a/modules/update-restricted.adoc b/modules/update-restricted.adoc index a266fb2bdda1..6659c4a7ffec 100644 --- a/modules/update-restricted.adoc +++ b/modules/update-restricted.adoc @@ -7,6 +7,12 @@ Update the restricted network cluster to the {product-title} version that you downloaded the release images for. +[NOTE] +==== +// If you have xref FIXME ../update_service/index.adoc[a local {product-title} Update Service], you can update by using the connected xref FIXME ../updating/updating-cluster.adoc[web console] or xref FIXME ../updating/updating-cluster-cli.adoc[CLI] instructions. +This section explains the update procedure in the absence of an available Update Service. +==== + .Prerequisites * You mirrored the images for the new release to your registry. diff --git a/modules/update-service-create-service-cli.adoc b/modules/update-service-create-service-cli.adoc new file mode 100644 index 000000000000..837bb98cfd94 --- /dev/null +++ b/modules/update-service-create-service-cli.adoc @@ -0,0 +1,76 @@ +[id="update-service-create-service-cli_{context}"] += Creating an Update Service by using the CLI + +You can use the {product-title} CLI to create an Update Service by using the {product-title} Update Service Operator. + +.Procedure + +To create an Update Service by using the {product-title} CLI: + +. Configure the Update Service target namespace: ++ +[source,terminal] +---- +$ NAMESPACE=FIXME-default-operand-namespace +---- ++ +The namespace must match the `targetNamespaces` value from the OperatorGroup. + +. Configure the name of the Update Service: ++ +[source,terminal] +---- +$ NAME=example +---- + +. Configure the local registry and repository for the release images: ++ +[source,terminal] +---- +$ RELEASE_IMAGES=registry.example.com/openshift/release +---- + +. Configure the local pullspec for the graph-data image: ++ +[source,terminal] +---- +$ GRAPH_DATA_IMAGE=registry.example.com/openshift/graph-data:latest +---- + +. Create an Update Service object: ++ +[source,terminal] +---- +$ oc -n "${NAMESPACE}" create -f - < *Custom Resource Definitions* page. + +. On the *Custom Resource Definitions* page, click *UpdateService*. + +. On the *Custom Resource Definition Overview* page, select *View Instances* from the *Actions* menu. + +. On the *UpdateServices* page, click *Create UpdateService*. ++ +You might have to refresh the page to load the data. + +.. In the YAML field, replace the code with the following YAML: ++ +[source,yaml] +---- +apiVersion: updateservice.openshift.io/v1 +kind: UpdateService +metadata: + name: <1> +spec: + replicas: 2 + releaseImages: <2> + graphDataImage: <3> +---- ++ +<1> For ``, specify a name for your Update Service, such as `openshift`. +<2> FIXME: aspirational. For ``, specify the local registry and repository for the release images, such as `registry.example.com/openshift/release`. +<3> For ``, specify the local pullspec for the graph-data image, such as `registry.example.com/openshift/graph-data:latest`. + +.. Click *Create* to create the Update Service components. + +//// +. Verify the Update Service: + +.. FIXME: check the UpdateService YAML for status... +//// diff --git a/modules/update-service-graph-data.adoc b/modules/update-service-graph-data.adoc new file mode 100644 index 000000000000..c6abb8015669 --- /dev/null +++ b/modules/update-service-graph-data.adoc @@ -0,0 +1,87 @@ +[id="update-service-graph-data_{context}"] += Mirroring the {product-title} Update Service graph data + +The {product-title} Update Service requires a graph-data container image, from which the Update Service retrieves information about channel membership and blocked update edges. + +.Prerequisites + +* An link:https://cloud.redhat.com/openshift/install/pull-secret[{product-title} pull secret]. +* A pull secret for the local registry. + +.Procedure + +. On a machine connected to the internet, retrieve the graph-data container image from the hosted services. + +.. Configure the path to the directory on your removable media to host the mirrored images: ++ +[source,terminal] +---- +$ REMOVABLE_MEDIA_PATH= +---- + +.. Configure the path to your {product-title} pull secret: ++ +[source,terminal] +---- +$ OCP_PULL_SECRET= +---- + +.. Mirror the graph-data container image to the removable media: ++ +[source,terminal] +---- +$ oc image mirror -a "${OCP_PULL_SECRET}" --dir="${REMOVABLE_MEDIA_PATH}" FIXME-where-registry.redhat.ren:5443/ocp4/openshift4 file://openshift/graph-data:latest +---- + +. Transfer the removable media to your restricted network. + +. On a computer that is connected to your restricted network, upload the graph-data container image to your local registry. + +.. Configure the path to the directory that contains the mirrored images: ++ +[source,terminal] +---- +$ REMOVABLE_MEDIA_PATH= +---- + +.. Configure the path to your local registry pull secret: ++ +[source,terminal] +---- +$ LOCAL_PULL_SECRET= +---- + +.. Configure 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. + +.. Configure the local repository name: ++ +[source,terminal] +---- +$ LOCAL_REPOSITORY='' +---- ++ +For ``, specify the name of the repository to create in your +registry, such as `openshift/graph-data`. + +.. Configure the local image tag: ++ +[source,terminal] +---- +$ LOCAL_TAG=latest +---- + +.. Mirror the graph-data container image to the local registry: ++ +[source,terminal] +---- +$ oc image mirror -a "${LOCAL_PULL_SECRET}" --from-dir="${REMOVABLE_MEDIA_PATH}" file://openshift/graph-data:latest "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${LOCAL_TAG}" +---- diff --git a/modules/update-service-install-cli.adoc b/modules/update-service-install-cli.adoc new file mode 100644 index 000000000000..197e098d9ad7 --- /dev/null +++ b/modules/update-service-install-cli.adoc @@ -0,0 +1,121 @@ +[id="update-service-install-cli_{context}"] += Installing the {product-title} Update Service by using the CLI + +You can use the {product-title} CLI to install the {product-title} Update Service Operator. + +.Procedure + +To install the {product-title} Update Service Operator by using the {product-title} CLI: + +. Create a Namespace for the {product-title} Update Service Operator: + +.. Create a Namespace object YAML file, for example, `update-service-namespace.yaml`, for the {product-title} Update Service Operator: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: openshift-updateservice + 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 {product-title} 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: + - FIXME-default-operand-namespace +---- + +.. Create an Operator Group object: ++ +[source,terminal] +---- +$ oc -n openshift-updateservice create -f .yaml +---- ++ +For example: ++ +[source,terminal] +---- +$ oc -n openshift-updateservice 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: "{product-version}" <1> + installPlanApproval: "Automatic" + source: "redhat-operators" <2> + sourceNamespace: "openshift-marketplace" + name: "FIXME-update-service-operator" +---- +<1> Specify `{product-version}` as the channel. +<2> 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-updateservice create -f update-service-subscription.yaml +---- ++ +The Update Service Operator is installed to the `openshift-updateservice` namespace and targets the `FIXME-default-operand-namespace` namespace. + +. Verify the Operator installation: ++ +[source,terminal] +---- +$ oc -n FIXME-default-operand-namespace get clusterserviceversions +---- ++ +.Example output +[source,terminal] +---- +NAMESPACE NAME DISPLAY VERSION REPLACES PHASE +default elasticsearch-operator.4.6.0-202007012112.p0 Elasticsearch Operator 4.6.0-202007012112.p0 Succeeded +FIXME +... +---- ++ +If the {product-title} 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..b7a66c2b5369 --- /dev/null +++ b/modules/update-service-install-web-console.adoc @@ -0,0 +1,34 @@ +[id="update-service-install-web-console_{context}"] += Installing the {product-title} Update Service by using the web console + +You can use the {product-title} web console to install the {product-title} Update Service Operator. + +.Procedure + +To install the {product-title} Update Service Operator using the {product-title} web console: + +. In the {product-title} web console, click *Operators* -> *OperatorHub*. + +. Choose *{product-title} Update Service* from the list of available Operators, and click *Install*. + +. FIXME: Does this apply? Ensure that the *All namespaces on the cluster* is selected under *Installation Mode*. + +. Select a namespace for *Installed Namespace*, such as the default `openshift-updateservice` namespace. + +. FIXME: Does this apply? Select *Enable operator recommended cluster monitoring on this namespace*. ++ +This option sets the `openshift.io/cluster-monitoring: "true"` label in the namespace object. + +. Select *{product-version}* as the *Update Channel*. + +. 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 user with FIXME credentials to approve the Operator update. + +. Click *Install*. + +. Verify that the {product-title} Update Service Operator installed by switching to the *Operators* -> *Installed Operators* page. + +. Ensure that *{product-title} Update Service* is listed in all projects with a *Status* of *Succeeded*. diff --git a/modules/update-service-overview.adoc b/modules/update-service-overview.adoc index b57e0e2965c2..bdf57d3bfd88 100644 --- a/modules/update-service-overview.adoc +++ b/modules/update-service-overview.adoc @@ -9,58 +9,32 @@ // * updating/updating-disconnected-cluster.adoc [id="update-service-overview_{context}"] -= About the {product-title} update service += About the {product-title} 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 {product-title} Update Service 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 {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. //// 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 {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. [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 Update Service displays all valid updates, you must not force an update to a version that the 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 {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. //// -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 {product-title} Update Service to determine if updates are available. [IMPORTANT] ==== -Reverting your cluster to a previous version, or a rollback, is not supported. -Only upgrading to a newer version is supported. +Reverting your cluster to a previous version, or a rollback, is not supported. Only upgrading to a newer version is supported. ==== 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. diff --git a/update_service/installing-update-service.adoc b/update_service/installing-update-service.adoc new file mode 100644 index 000000000000..c1d64ab90e77 --- /dev/null +++ b/update_service/installing-update-service.adoc @@ -0,0 +1,45 @@ +[id="installing-update-service"] += Installing and configuring the {product-title} 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. + +You can install and configure the {product-title} Update Service to provide over-the-air updates for your cluster and its underlying operating system. + +include::modules/update-service-overview.adoc[leveloffset=+1] + +[id="update-service-install"] +== Installing the {product-title} Update Service + +You can install the {product-title} Update Service by deploying the Update Service Operator by using the {product-title} web console or CLI. + +include::modules/update-service-install-web-console.adoc[leveloffset=+2] + +include::modules/update-service-install-cli.adoc[leveloffset=+2] + +. Additional resources + +* For more information on installing Operators, see xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-operators-from-operatorhub_olm-adding-operators-to-a-cluster[Installing Operators from the OperatorHub]. + +include::modules/update-service-graph-data.adoc[leveloffset=+2] + +[id="update-service-create-service"] +== Creating an Update Service + +You can create Update Services 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] + +//// +FIXME-deleting-a-service? + +FIXME-uninstalling-the-operator? +//// diff --git a/welcome/index.adoc b/welcome/index.adoc index efaa3eb90c96..fc3ce8ebe70d 100644 --- a/welcome/index.adoc +++ b/welcome/index.adoc @@ -231,6 +231,8 @@ There is a separate process for xref:../updating/updating-disconnected-cluster.adoc#updating-disconnected-cluster[updating a cluster on a restricted network]. //// +- **xref:../update_service/installing-update-service.adoc#installing-update-service[Understanding the {product-title} Update Service]**: Learn about installing and managing a local 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.