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

wking · 2020-10-07T23:40:03Z

Mixing in some precedent from logging/, the Update Service blog post, the GitHub docs, and some aspirational v1 goals ;). Still quite a few WIPs and FIXMEs scattered throughout.

CC @openshift/openshift-team-cincinnati

vikram-redhat · 2020-10-08T01:29:09Z

@wking hey - is this for 4.6?

wking · 2020-10-08T02:00:11Z

It's a separate product, so not tied to the OCP core. But yeah, should go GA alongside the early OCP 4.6.z.

wking · 2020-10-08T04:51:53Z

CI:

wking is not a team member of @openshift/team-documentation, not building a preview.

But after gutting a number of xrefs and trimming down to a single _topic_map.yml entry (because I build the whole tree (indirectly) from update_service/index.adoc), it is at least compiling now.

vikram-redhat · 2020-10-08T06:55:59Z

wking is not a team member of @openshift/team-documentation, not building a preview.

Happy to add you @wking :).

LalatenduMohanty

Are you planning to add how to install the operator and the OSUS image in this docs?

LalatenduMohanty · 2020-10-08T12:13:41Z

update_service/graph-data.adoc

at least two OpenShift update release payloads into container image registries reachable by the target clusters I do not think this correct. OSUS can start without any primary or secondary metadata and we have tested this in the past. Also having this type of prerequisite is not user friendly.

I don't see a point in an Update Service that serves only empty graphs, and phrasing this as a prereq gives us space to talk about these data inputs.

wking · 2020-10-08T15:03:37Z

Happy to add you @wking :).

Is there a way to get previews on my PRs without getting pinged when folks need real docs maintainers?

vikram-redhat · 2020-10-08T20:24:35Z

Happy to add you @wking :).

Is there a way to get previews on my PRs without getting pinged when folks need real docs maintainers?

I added you to the preview bot. If you rebase against master and then restart the build, you should get a preview. Some quick things to keep in mind:

Previews take about 5 minutes to generate after the build finishes.
A "." in your branch name generates a faulty link to the preview.
Previews get updated with every new commit you make (in about 5 minutes).

Let me know if you run into any issues.

vikram-redhat · 2020-10-14T23:03:58Z

Hey @wking @kalexand-rh - are there any updates on this getting in for this GA?

kalexand-rh · 2020-10-15T12:27:26Z

Hey @wking @kalexand-rh - are there any updates on this getting in for this GA?

I have time to take a look today if @wking says it's ready. I think he wanted to take a pass at fixing the modules before I gave feedback.

openshift-docs-preview-bot · 2020-10-17T04:27:13Z

The preview will be available shortly at:

https://update-service-operator-docs--ocpdocs.netlify.com/

kalexand-rh

Please pick whatever the official name for the service/Operator is and be consistent. This is actually looking good. Ping me if you want to talk about anything or need to know reasons why. :)

modules/update-restricted.adoc

modules/update-service-create-service-cli.adoc

kalexand-rh · 2020-10-19T20:21:17Z

update_service/index.adoc

You should retitle this assembly to something more descriptive.

_topic_map.yml

kalexand-rh · 2020-10-19T20:22:43Z

update_service/index.adoc

You need an intro sentence that sets the context for the assembly.

Currently this assembly is "everything you need to be an Update Service admin", and I include modules/update-service-overview.adoc to give folks context about what the Update Service is about. I'm not sure what other context to provide, unless we shard this out into several assemblies, in which case I guess we could explain the current assembly vs. the other Update Service assemblies? I'm agnostic about sharding into assemblies. If you have a particular set of assemblies you'd like to see, just tell me what they are, and I'll pivot to that structure.

kalexand-rh · 2020-10-19T20:30:03Z

update_service/index.adoc

Suggested change

// You can install the {product-title} Update Service by deploying the Update Service operator, using the {product-title} xref FIXME ../../update_service/install/web-console.adoc[web console] or xref FIXME ../../update_service/install/cli.adoc[CLI].

// You can install the {product-title} Update Service by deploying the Update Service Operator by using the {product-title} xref FIXME ../../update_service/install/web-console.adoc[web console] or xref FIXME ../../update_service/install/cli.adoc[CLI].

I'd probably remove the xrefs and say something about "by using one of the following sections." If you keep the xrefs, you'll need to include an explicit anchor to the first heading using the H1 anchor name from the module and the context statement from the assembly. (assuming that you are trying to link to the next two modules.)

Did the , -> by with adf5ca0732 -> 2c77ff9ce2

I will try to sort out the xrefs in a future reroll; I'd like to make it easy for folks to skip forward to view the approach they are interested in with a click here, but I may end up throwing in that towel and using your by using one of the following sections..

update_service/index.adoc

jottofar · 2020-10-29T13:31:53Z

modules/update-service-create-service-cli.adoc

UpdateService requires registry and repository:

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

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?

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.

modules/update-service-create-service-cli.adoc

modules/update-service-overview.adoc

jottofar · 2020-10-30T19:40:44Z

modules/update-service-overview.adoc

Can we introduce the OSUS acronym here (or somewhere) for readability and to start socializing the acronym.

@wking, do you know if this is an acceptable acronym to socialize?

I don't like socializing acronyms, but don't block on me ;)

@kalexand-rh I assume we have an established "standard" in documents about whether and/or when we use acronyms? Assuming so I'm not suggesting we break new ground so just roll with the standard.

@jottofar, I've seen hard rules for only product-level initializations. OCP is forbidden, but OLM is fine. CVO is used throughout the docs, so I see no problem with using OSUS. It's a judgement call, but I'm not convinced that it's mine to make.

If customers are going to be told that this is OSUS, then I think we should go ahead and use the acronym. It's apparently confusing that customer-facing folks refer to IPI and UPI installation methods but docs don't.

Going back and looking at this again I see I have it wrong. I was originally referring to OpenShift Container Platform Update Service. But OSUS, which is used by the team, is the acronym for OpenShift Update Service. That name was chosen, at least partly, because OpenShift Container Platform Update Service is too much of a mouthful. I think the action here is to change all occurrences of OpenShift Container Platform Update Service to OpenShift Update Service. And the latter is short enough to not worry about referring to the acronym. I don't think we want to have OpenShift Container Platform OpenShift Update Service unless we're breaking some consistency rule.

Sorry, just remembered {product-title}. So I'm sure we need to keep {product-title} which means change would be to OpenShift Container Platform OpenShift Update Service. As I said, that really is a mouthful and it's used throughout so using OSUS, i.e. OpenShift Container Platform OSUS, seems reasonable to me.

I've changed this from OpenShift Container Platform Update Service to OpenShift Update Service throughout.

jottofar · 2020-10-30T20:04:30Z

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

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

@wking, did this default behavior change?

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.

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.

modules/update-service-install-cli.adoc

jottofar · 2020-10-30T20:30:19Z

modules/update-service-install-cli.adoc

Shouldn't this

Specify the name of the Operator channel.

be

Specify the name of the CatalogSource that provides the Operator.

modules/update-service-install-cli.adoc

kalexand-rh

@wking, I have some questions!

kalexand-rh · 2021-01-28T16:21:19Z

modules/update-service-create-service-cli.adoc

Do we have the name of the default-operand-namespace?

kalexand-rh · 2021-02-04T18:48:27Z

modules/update-service-create-service-cli.adoc

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?

kalexand-rh · 2021-02-04T18:48:45Z

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

How do you do this?

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.

kalexand-rh · 2021-02-04T18:49:08Z

modules/update-service-graph-data.adoc

Do we have the right value for this?

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 :(

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

kalexand-rh · 2021-02-04T19:13:13Z

modules/update-service-install-cli.adoc

@wking, did you decide on this?

kalexand-rh · 2021-02-04T19:14:50Z

modules/update-service-install-cli.adoc

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

kalexand-rh · 2021-02-04T19:15:20Z

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

@wking, did this default behavior change?

kalexand-rh · 2021-02-04T19:15:37Z

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

Does this apply?

I'm still not sure :(

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

kalexand-rh · 2021-02-04T19:15:59Z

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

What credentials does the manual strategy require?

I'm still not sure :(

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.

kalexand-rh · 2021-02-04T19:18:38Z

modules/update-service-overview.adoc

@wking, do you know if this is an acceptable acronym to socialize?

Mixing in some precedent from logging/, the Update Service blog post [1], the GitHub docs [2], and some more recent operator CRD changes like [3,4]. Kathryn didn't want us asking the user to poll [5], so I'm using POSIX-shell 'while' loops to poll on the user's behalf. [1]: https://www.openshift.com/blog/openshift-update-service-update-manager-for-your-cluster [2]: https://github.com/openshift/cincinnati-operator/blob/2df239a8486d2ba3aa0d9925e5d505105ab36afe/docs/disconnected-cincinnati-operator.md [3]: openshift/cincinnati-operator#66 [4]: openshift/cincinnati-operator#85 [5]: openshift#26219 (comment)

netlify · 2021-02-05T00:49:30Z

Deploy preview for osdocs ready!

Built with commit cfc495b

https://deploy-preview-26219--osdocs.netlify.app

shellyyang1989 · 2021-03-24T08:16:08Z

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


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

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.

shellyyang1989 · 2021-03-24T08:21:37Z

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


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

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.

jottofar · 2021-03-24T20:38:18Z

/close

openshift-ci-robot · 2021-03-24T20:38:32Z

@jottofar: Closed this PR.

Details

In response to this:

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

jottofar · 2021-03-24T20:39:38Z

This PR has been superseded by #29630.

openshift-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 7, 2020

wking force-pushed the update-service-operator-docs branch 9 times, most recently from 9b258e8 to 2ae8db1 Compare October 8, 2020 04:44

LalatenduMohanty suggested changes Oct 8, 2020

View reviewed changes

vikram-redhat added this to the Future Release milestone Oct 8, 2020

vikram-redhat added the branch/enterprise-4.6 label Oct 8, 2020

wking mentioned this pull request Oct 8, 2020

virt/upgrading-virt-about: Move out of modules to allow xref #26257

Closed

wking force-pushed the update-service-operator-docs branch 3 times, most recently from d88502d to adf5ca0 Compare October 17, 2020 04:24

kalexand-rh reviewed Oct 19, 2020

View reviewed changes

wking force-pushed the update-service-operator-docs branch from adf5ca0 to 2c77ff9 Compare October 19, 2020 23:36

kalexand-rh removed this from the Future Release milestone Oct 20, 2020

vikram-redhat added this to the Future Release milestone Oct 20, 2020

wking force-pushed the update-service-operator-docs branch from 2c77ff9 to e747446 Compare October 27, 2020 04:58

vikram-redhat modified the milestones: Future Release, Next Release Oct 27, 2020

vikram-redhat added the branch/enterprise-4.7 label Oct 27, 2020

jottofar reviewed Oct 29, 2020

View reviewed changes

modules/update-service-create-service-cli.adoc Outdated Show resolved Hide resolved

jottofar reviewed Oct 30, 2020

View reviewed changes

modules/update-service-overview.adoc Outdated Show resolved Hide resolved

jottofar reviewed Oct 30, 2020

View reviewed changes

modules/update-service-install-cli.adoc Outdated Show resolved Hide resolved

jottofar reviewed Oct 30, 2020

View reviewed changes

wking force-pushed the update-service-operator-docs branch from e747446 to 17c7c94 Compare November 16, 2020 23:13

wking force-pushed the update-service-operator-docs branch from 17c7c94 to 6d253db Compare November 16, 2020 23:15

wking commented Jan 22, 2021

View reviewed changes

modules/update-service-install-cli.adoc Outdated Show resolved Hide resolved

kalexand-rh reviewed Feb 4, 2021

View reviewed changes

kalexand-rh force-pushed the update-service-operator-docs branch from 6d253db to aa36f88 Compare February 5, 2021 00:44

kalexand-rh force-pushed the update-service-operator-docs branch from aa36f88 to 5d14dba Compare February 5, 2021 00:49

some updates

cfc495b

kalexand-rh force-pushed the update-service-operator-docs branch from 5d14dba to cfc495b Compare February 5, 2021 00:53

shellyyang1989 reviewed Mar 24, 2021

View reviewed changes

openshift-ci-robot closed this Mar 24, 2021

	// You can install the {product-title} Update Service by deploying the Update Service operator, using the {product-title} xref FIXME ../../update_service/install/web-console.adoc[web console] or xref FIXME ../../update_service/install/cli.adoc[CLI].
	// You can install the {product-title} Update Service by deploying the Update Service Operator by using the {product-title} xref FIXME ../../update_service/install/web-console.adoc[web console] or xref FIXME ../../update_service/install/cli.adoc[CLI].

		@@ -0,0 +1,121 @@
		[id="update-service-install-cli_{context}"]
		= Installing the {product-title} Update Service by using the CLI

		@@ -0,0 +1,34 @@
		[id="update-service-install-web-console_{context}"]
		= Installing the {product-title} Update Service by using the web console

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

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

Uh oh!

Conversation

wking commented Oct 7, 2020

Uh oh!

vikram-redhat commented Oct 8, 2020

Uh oh!

wking commented Oct 8, 2020

Uh oh!

wking commented Oct 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vikram-redhat commented Oct 8, 2020

Uh oh!

LalatenduMohanty left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wking commented Oct 8, 2020

Uh oh!

vikram-redhat commented Oct 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vikram-redhat commented Oct 14, 2020

Uh oh!

kalexand-rh commented Oct 15, 2020

Uh oh!

openshift-docs-preview-bot commented Oct 17, 2020

Uh oh!

kalexand-rh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

wking commented Oct 8, 2020 •

edited

Loading

vikram-redhat commented Oct 8, 2020 •

edited

Loading