Skip to content

WIP: update_service: Add docs for the OpenShift Update Service #26219

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wking wants to merge 2 commits into from
Closed

WIP: update_service: Add docs for the OpenShift Update Service #26219

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
70c32c8
update_service: Add docs for the OpenShift Update Service
wking Oct 7, 2020
cfc495b
some updates
kalexand-rh Feb 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions _topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions modules/update-restricted.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
76 changes: 76 additions & 0 deletions modules/update-service-create-service-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$ NAMESPACE=FIXME-default-operand-namespace
$ NAMESPACE=FIXME-default-operand-namespace <1>

Copy link
Member Author

@wking wking Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And then <1> This must match... below? Do we need the <1> linkage if this is the only line of code-ish stuff in the Configure the Update Service target namespace list entry?

Copy link
Contributor

@kalexand-rh kalexand-rh Jan 28, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have the name of the 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:
+
Copy link
Contributor

@jottofar jottofar Oct 29, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

UpdateService requires registry and repository:

The UpdateService "example" is invalid:
* spec.registry: Required value
* spec.repository: Required value

Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, how do you want users to define this? Around line 28, do we also need to set $REGISTRY=registry.example.com and $REPOSITORY=registry.example.com/openshift/ or some other thing?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

UpdateService now only needs releases for this information. In the API docs, I picked quay.io/openshift-release-dev/ocp-release as the example value, but yeah, registry.example.com/openshift would work too.

[source,terminal]
----
$ oc -n "${NAMESPACE}" create -f - <<EOF
apiVersion: updateservice.operator.openshift.io/v1
kind: UpdateService
metadata:
name: ${NAME}
spec:
replicas: 2
repository:
registry:
releaseImages: ${RELEASE_IMAGES} # FIXME: aspirational
graphDataImage: ${GRAPH_DATA_IMAGE}
EOF
----

. Verify the Update Service:

.. 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:
+
[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.
44 changes: 44 additions & 0 deletions modules/update-service-create-service-web-console.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
[id="update-service-create-service-web-console_{context}"]
= Creating an Update Service by using the web console

You can use the {product-title} web console to create an Update Service by using the {product-title} Update Service Operator.

.Procedure

To create an Update Service by using the {product-title} web console:

. Switch to the *Administration* -> *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: <name> <1>
spec:
replicas: 2
releaseImages: <release-images> <2>
graphDataImage: <graph-data-image> <3>
----
+
<1> For `<name>`, specify a name for your Update Service, such as `openshift`.
<2> FIXME: aspirational. For `<release-images>`, specify the local registry and repository for the release images, such as `registry.example.com/openshift/release`.
<3> For `<graph-data-image>`, 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...
Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you do this?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oc -n your-namespace get -o yaml updateservice your-name and look under status.conditions for... I dunno, exactly. We should get some CI or experiments to get more details.

////
87 changes: 87 additions & 0 deletions modules/update-service-graph-data.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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=<path>
----

.. Configure the path to your {product-title} pull secret:
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having the pull secret needs to be a prereq in this module. The prereqs section goes before the procedure section, and contains an unordered list. Something like:

.Prerequisites

* You have a copy of the pull secret that you used to configure your mirror registry before you installed the {product-title} cluster.

Copy link
Member Author

@wking wking Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done with adf5ca0732 -> 2c77ff9ce2. But I have not added entries for "access to removable media" or "network access to Red Hat's hosted services (for the initial pull onto the removable media). Are there central docs around which prereqs need to be listed and which can be implicitly assumed (and clarified later in the steps themselves)? Or do we just make judgement calls on each PR?

+
[source,terminal]
----
$ OCP_PULL_SECRET=<path>
----

.. 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
Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have the right value for this?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unfortunately we have no official graph-images today. The blog post talks through building your own. I am not excited about that approach, but there was only so much we've had time to get working in our image-release pipeline :(

Copy link

@shellyyang1989 shellyyang1989 Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the graph data has not released as an image yet, the procedure for building the image is required in this doc.

----

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

.. Configure the path to your local registry pull secret:
+
[source,terminal]
----
$ LOCAL_PULL_SECRET=<path>
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which one is this?

Copy link
Member Author

@wking wking Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the one that allow you to push the image up to your local mirror registry.

----

.. Configure the local registry name and host port:
+
[source,terminal]
----
$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>'
----
+
For `<local_registry_host_name>`, specify the registry domain name for your mirror
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you're using this style of explanation, you need to use a <1> tag on the command and before the comment.

repository, and for `<local_registry_host_port>`, specify the port that it
serves content on.

.. Configure the local repository name:
+
[source,terminal]
----
$ LOCAL_REPOSITORY='<local_repository_name>'
----
+
For `<local_repository_name>`, specify the name of the repository to create in your
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.

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}"
----
121 changes: 121 additions & 0 deletions modules/update-service-install-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
[id="update-service-install-cli_{context}"]
= Installing the {product-title} Update Service by using the CLI
Copy link

@shellyyang1989 shellyyang1989 Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The session is introducing the way to install the update service operator but the title is saying installing the Update Service. I would suggest to change it to Installing the {product-title} Update Service operator by using the CLI

Copy link
Contributor

@jottofar jottofar Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. I've introduced the sections headers with either Operator or application to distinguish between operator and operand. This PR is obsolete and will be closed. Please see #29630 for latest.


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 <file-name>.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 <file-name>.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.
Copy link
Contributor

@kalexand-rh kalexand-rh Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this always true?

Copy link
Member Author

@wking wking Oct 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure, but this is cribbed from:

$ git --no-pager grep 'Specify.*as the channel' origin/master
origin/master:modules/cluster-logging-deploy-cli.adoc:<2> Specify `4.6` as the channel.
origin/master:modules/cluster-logging-deploy-cli.adoc:<2> Specify `4.6` as the channel.
origin/master:modules/metering-install-operator.adoc:<3> Specify {product-version} as the channel.

Copy link
Contributor

@jottofar jottofar Oct 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we're not tied to the OCP version do we want to instead make this OSUS Operator version, i.e. v1?

Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wking, did you decide on this?

Copy link
Contributor

@jottofar jottofar Feb 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

v1 is the onlychannel we have now.

<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 <file-name>.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
Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't install the Operator in this way, so I can't update this output.

...
----
+
If the {product-title} Update Service Operator is listed, installation succeeded. The version number might be different than shown.
34 changes: 34 additions & 0 deletions modules/update-service-install-web-console.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
[id="update-service-install-web-console_{context}"]
= Installing the {product-title} Update Service by using the web console
Copy link

@shellyyang1989 shellyyang1989 Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here. It's introducing the way to install the Update Service operator but the title is saying Installing the Update Service.

Copy link
Contributor

@jottofar jottofar Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. I've introduced the sections headers with either Operator or application to distinguish between operator and operand. This PR is obsolete and will be closed. Please see #29630 for latest.


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*.
Copy link
Contributor

@jottofar jottofar Oct 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be defaulted to A specific namespace on the cluster which appears to be something we can restrict it to as well.

Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wking, did this default behavior change?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm agnostic about which namespaces the operator gets installed to, or if it watches all namespaces. @jottofar is more familiar with what our bundle recommends. The text we're commenting on I probably cribbed from the logging docs, which may set things up differently.

Copy link
Contributor

@jottofar jottofar Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should come up defaulted to single namespace of "openshift-update-service". May be safer to have user leave it defaulted as did not do a lot of testing in the end with any other namespace although can't think of a reason why it would be an issue.


. 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*.
Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this apply?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not sure :(

Copy link
Contributor

@jottofar jottofar Feb 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not seeing option Enable operator recommended cluster monitoring on this namespace in the 4.6 OperatorHub console page.

+
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.
Copy link
Contributor

@kalexand-rh kalexand-rh Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What credentials does the manual strategy require?

Copy link
Member Author

@wking wking Feb 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not sure :(

Copy link
Contributor

@jottofar jottofar Feb 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is explained in https://docs.openshift.com/container-platform/4.6/operators/user/olm-installing-operators-in-namespace.html#olm-installing-operators-from-operatorhub_olm-installing-operators-in-namespace which we'll have already linked to as a prereq:
If you select manual updates, when a newer version of an Operator is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.


. 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*.
Loading