-
Notifications
You must be signed in to change notification settings - Fork 1.9k
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.
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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: | ||||||
|
|
||||||
|
wking marked this conversation as resolved.
Outdated
|
||||||
| . Configure the Update Service target namespace: | ||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ NAMESPACE=FIXME-default-operand-namespace | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. And then
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Do we have the name of the |
||||||
| ---- | ||||||
| + | ||||||
| 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: | ||||||
| + | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. UpdateService requires
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. UpdateService now only needs |
||||||
| [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 | ||||||
| ---- | ||||||
| + | ||||||
|
wking marked this conversation as resolved.
Outdated
|
||||||
| 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. | ||||||
| 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... | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How do you do this?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
| //// | ||
| 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: | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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:
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Do we have the right value for this?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 :( There was a problem hiding this comment. Choose a reason for hiding this commentThe 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> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Which one is this?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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}" | ||
| ---- | ||
| 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 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agree. I've introduced the sections headers with either |
||
|
|
||
| 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: | ||
|
kalexand-rh marked this conversation as resolved.
Outdated
|
||
|
|
||
| .. 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. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this always true?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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?
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @wking, did you decide on this?
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
| <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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
| 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 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agree. I've introduced the sections headers with either |
||
|
|
||
| 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*. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It should be defaulted to
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @wking, did this default behavior change?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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*. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Does this apply?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm still not sure :(
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not seeing option |
||
| + | ||
| 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. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What credentials does the manual strategy require?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm still not sure :(
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: |
||
|
|
||
| . 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*. | ||
Uh oh!
There was an error while loading. Please reload this page.