procedures: update admin docs for storage classes, storage strategies and storage size #2536

AObuchow · 2023-01-10T18:14:18Z

What does this pull request change?

Update to the storage class documentation:
- Remove mention of Che Server creating PVC's as this is now handled by DevWorkspace Operator
- Update procedure for specifying storage class to be up-to-date with Che Operator CRD
Add additional documentation for configuration of storage
- Explain storage strategies available, as well as default storage strategy
- Add procedure for switching storage strategies
- Explain how storage sizes (persistent volume claim sizes) are configured (i.e. following Kubernetes resource quantity format)
- Add procedure for changing storage sizes

Some notes:

There are some redundancies that I included for clarity, but may be acting as noise:
- For both procedures in the "Configuring storage strategy" page, there are links to configuring the Che Cluster CR
- For the code examples, there are duplicate comments because there are duplicate fields

What issues does this pull request fix or reference?

eclipse-che/che#21885 (comment)

Specify the version of the product this pull request applies to

7.58.0 (I believe)

Pull Request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

Any procedure:
- Successfully tested.
Any page or link rename:
- The page contains a redirection for the previous URL.
- Propagate the URL change in:
  - Dashboard default branding data
  - Chectl constants.ts
Builds on Eclipse Che hosted by Red Hat.
the Validate language on files added or modified step reports no vale warnings.

github-actions · 2023-01-10T18:14:32Z

🎊 Navigate the preview: https://64ed0c7955b72f13818ae02b--eclipse-che-docs-pr.netlify.app 🎊

github-actions · 2023-01-10T18:14:34Z

Click here to review and test in web IDE:

github-actions · 2023-01-10T18:14:35Z

Click here to review and test in web IDE:

max-cx · 2023-01-12T09:13:58Z

Thank you for this PR, Andrew. A technical writer will self-assign it to review it toward RHDEVDOCS-4870.

AObuchow · 2023-01-12T16:27:04Z

@max-cx Sounds good, thank you for the update :)

AObuchow · 2023-01-18T06:04:12Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+:page-aliases: installation-guide:configuring-che-storage-size.adoc
+
+[id="configuring-{prod-id-short}-workspace-pvc-size"]
+= Configuring the storage size in {prod-short}


Not sure, but it might be a bit redundant to say "in Che/DevSpaces" since this is the Che/DevSpaces docs.

Yes, we can avoid mentioning Che/DevSpaces when it's self-explanatory to our readers.

AObuchow · 2023-01-18T06:06:09Z

modules/administration-guide/pages/configuring-che-storage-strategy.adoc

+[id="configuring-{prod-id-short}-storage-strategy"]
+= Configuring the storage strategy in {prod-short}
+
+{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter].


While working on this, I realized that the documentation on requesting persistent storage for workspaces with a devfile (requesting-persistent-storage-for-workspaces.adoc) also should probably be updated to reference the DevWorkspace Operator storage strategy attribute

Please do if you can. Otherwise, please open another issue so that it can be assigned to someone to work on at a later time.

I've created eclipse-che/che#22316 to track this issue and determine if it is valid, as it may not be something Che users need to know about.

AObuchow · 2023-01-18T06:07:50Z

I made a separate page for the procedure regarding configuring the PVC/storage size.

max-cx · 2023-01-30T09:28:09Z

@AObuchow, @osslate will review this PR for RHDEVDOCS-4870.

max-cx · 2023-04-03T16:46:52Z

Picking up the language review as RHDEVDOCS-5132

AObuchow · 2023-04-03T19:29:24Z

@max-cx I fixed the issue with the ECA (the commits had the wrong author)

max-cx · 2023-04-04T12:58:34Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+[id="configuring-{prod-id-short}-workspace-pvc-size"]
+= Configuring the storage size in {prod-short}


The id and the = heading have to be the same (except for the lowercase dashed syntax).
I see there's a sibling page with the heading that reads "Configuring storage classes".

Also, our convention is for the file name to be the same as the id.
Feel free to change the file names, just beware of having to update all the xrefs to the updated file names in the other files in this PR, esp. in modules/administration-guide/nav.adoc and modules/administration-guide/pages/configuring-storage.adoc.

For example (and not sure if size should be singular or plural here):

Suggested change

[id="configuring-{prod-id-short}-workspace-pvc-size"]

= Configuring the storage size in {prod-short}

[id="configuring-storage-size"]

= Configuring storage size

max-cx · 2023-04-04T13:00:08Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+:description: Configuring the storage size in {prod-short}
+:keywords: administration guide, configuring, {prod-id-short}, storage size, PVC size, pvc
+:navtitle: Configuring the storage size in {prod-short}


If you update the id and = title below, the :description: (line 2) and :navtitle: (line 4) values have to be updated too to be the same as the = title.

max-cx · 2023-04-04T14:32:26Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+[id="configuring-{prod-id-short}-workspace-pvc-size"]
+= Configuring the storage size in {prod-short}
+
+The persistent volume claim (PVC) size can be configured when using the `per-user` or `per-workspace` storage strategies. PVC sizes in the Che Cluster Custom Resource must be specified in the format of a https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-che-storage-strategy.adoc[]


We use the link: variation of AsciiDoc syntax.

We need to use active voice rather than passive voice where possible.
Also, we need to focus on the reader and write to the second person, you, or use the imperative form [do] [this].

For example, assuming the proposed changes are still technically correct:

Suggested change

The persistent volume claim (PVC) size can be configured when using the `per-user` or `per-workspace` storage strategies. PVC sizes in the Che Cluster Custom Resource must be specified in the format of a https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-che-storage-strategy.adoc[]

You can configure the persistent volume claim (PVC) size when using the `per-user` or `per-workspace` storage strategies. You must specify the PVC sizes in the `CheCluster` Custom Resource in the format of a link:https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-che-storage-strategy.adoc[].

max-cx · 2023-04-04T14:33:36Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

@@ -0,0 +1,38 @@
+:_content-type: CONCEPT


Correct me if I'm wrong, this seems to be a procedure:

Suggested change

:_content-type: CONCEPT

:_content-type: PROCEDURE

max-cx · 2023-04-04T15:45:35Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+
+The persistent volume claim (PVC) size can be configured when using the `per-user` or `per-workspace` storage strategies. PVC sizes in the Che Cluster Custom Resource must be specified in the format of a https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-che-storage-strategy.adoc[]
+
+.Default persistent volume claim sizes:


FYI, we have an online guide about modular docs.

We reserve the ._<Heading>_ syntax for three sections in a procedure module:
.Prerequisites (only if any are included, otherwise omitted)
.Procedure
.Additional resources (only if any are included, otherwise omitted)

So I suggest removing the . and making that line plain text:

Suggested change

.Default persistent volume claim sizes:

Default persistent volume claim sizes:

max-cx · 2023-04-04T15:47:28Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+* `per-user`: `10Gi`
+* `per-workspace`: `5Gi`
+
+.Procedure


After this point, we need a numbered list.
In AsciiDoc, the numbers can also be added automatically, so you can just start each step as follows (dot, space, sentence) without worrying about putting the correct numbers on the steps:
. This is a sentence for step 1.
. This is a sentence for step 2.
. This is a sentence for step 3.

As it currently stands, the pages on configuring the storage strategy and configuring the storage size only have a single step. Should I still be using the .Procedure heading?

max-cx · 2023-04-04T15:55:58Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+
+.Procedure
+
+Use CheCluster Custom Resource definition to define the persistent volume claim size for the desired storage strategy:


This sentence appears to summarize the use case and if so, then it belongs in the intro paragraph or two that currently starts on line 10.

For now, I'm going to remove this sentence as it doesn't seem to add any extra information that the first paragraph doesn't already have.

max-cx · 2023-04-04T16:01:54Z

modules/administration-guide/pages/configuring-che-storage-size.adoc

+
+Use CheCluster Custom Resource definition to define the persistent volume claim size for the desired storage strategy:
+
+Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource. To set this field prior to installing {prod-short}, see xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[], otherwise consult xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].


WIP

You can move the second sentence into an admonition (NOTE/TIP/IMPORTANT/WARNING) if the info is not one of the steps.

Suggested change

Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource. To set this field prior to installing {prod-short}, see xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[], otherwise consult xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].

. Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource:

[NOTE]

====

* You can set this field at installation. See xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[].

* You can update this field on the command line. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].

====

AObuchow · 2023-04-28T15:50:44Z

Hi @max-cx thank you for the great feedback so far. I just rebased my PR cause I was having some issues with the live preview on the dog fooding instance. Hopefully this should fix the issue I was encountering, and I will be starting to address your feedback finally.

Will ping you once it's all addressed (this might take a few sessions of me working on this) :)

AObuchow · 2023-04-28T17:17:27Z

@max-cx I've added an extra PR to address some of the feedback you've given, though I still need to do some more work on this PR and finish addressing your feedback. You're welcome to wait until I have finished addressing everything before getting back to me, since this is currently a work-in-progress :P

And sorry about the ECA, my git email/name is not configured correctly on the dog fooding instance where I worked on this PR. ~~I will fix that before letting you know that the PR is ready for a second review~~ (unless there's urgency for me to fix this).

Edit: Fixing the ECA will probably require me to re-author the commits. If there's no urgency for me to do this, I'll leave it for when the PR is ready to merge as we'll likely want to squash and reorganize the commit log.

AObuchow · 2023-06-22T17:53:42Z

@max-cx I've finally done the rest of the updates to this PR based on your current feedback. When you have some time, let me know which further changes are required. For your convenience, I'd be happy to any details on a call if you'd prefer :)

ibuziuk · 2023-08-10T09:33:40Z

@AObuchow could you please rebase against main?

AObuchow · 2023-08-10T17:24:29Z

@AObuchow could you please rebase against main?

Done 👍

ibuziuk · 2023-08-28T09:48:15Z

@AObuchow looks like still some checks are failing

ibuziuk · 2023-08-28T09:51:14Z

Approved
@deerskindoll @max-cx could we merge it once all the checks are green? PR was opened more than 8 months ago

deerskindoll · 2023-08-28T11:21:56Z

Approved @deerskindoll @max-cx could we merge it once all the checks are green? PR was opened more than 8 months ago

Sure! How long do you think it will take to clear out the eclipsefdn/eca check? Update: I see, the merge is actually blocked by a change request. @AObuchow can you please resolve the change request?

deerskindoll

lgtm

Signed-off-by: Andrew Obuchowicz <[email protected]>

AObuchow · 2023-08-28T15:22:48Z

Approved @deerskindoll @max-cx could we merge it once all the checks are green? PR was opened more than 8 months ago

Sure! How long do you think it will take to clear out the eclipsefdn/eca check? Update: I see, the merge is actually blocked by a change request. @AObuchow can you please resolve the change request?

Thanks for checking this out @deerskindoll :) I believe I had already addressed the changes requested. I've squashed my commits, though 0cc5c7e (#2536) and 2e93b12 (#2536) could both be squashed into a single commit potentially. Let me know if there's anything missing on my end to get this merged.

deerskindoll

added missing xref description

modules/administration-guide/pages/configuring-storage-sizes.adoc

reviewed and approved

… and storage size (#2536) Co-authored-by: Jana Vrbkova <[email protected]>

AObuchow requested review from rkratky, themr0c, max-cx and a team as code owners January 10, 2023 18:14

AObuchow requested a review from benoitf January 10, 2023 18:14

che-bot added status/code-review target/branch labels Jan 10, 2023

AObuchow commented Jan 18, 2023

View reviewed changes

AObuchow force-pushed the update-storage-administration-guide branch from 4a7a4bb to c09131a Compare April 3, 2023 19:27

AObuchow requested a review from deerskindoll as a code owner April 3, 2023 19:27

max-cx reviewed Apr 4, 2023

View reviewed changes

AObuchow force-pushed the update-storage-administration-guide branch from bbacbe6 to ab73ab8 Compare April 28, 2023 15:49

AObuchow force-pushed the update-storage-administration-guide branch from f209d82 to b001fff Compare June 22, 2023 17:42

AObuchow force-pushed the update-storage-administration-guide branch from b001fff to d147d46 Compare August 10, 2023 17:23

deerskindoll requested a review from max-cx August 14, 2023 14:08

ibuziuk approved these changes Aug 28, 2023

View reviewed changes

deerskindoll approved these changes Aug 28, 2023

View reviewed changes

AObuchow force-pushed the update-storage-administration-guide branch 2 times, most recently from fc94099 to 16c7139 Compare August 28, 2023 15:16

AObuchow added 3 commits August 28, 2023 11:17

procedures: update admin page on configuring storage classes

c3e78fb

Signed-off-by: Andrew Obuchowicz <[email protected]>

procedures: Document Che storage strategies & storage size configuration

0cc5c7e

Signed-off-by: Andrew Obuchowicz <[email protected]>

procedures: document PVC size configuration

2e93b12

Signed-off-by: Andrew Obuchowicz <[email protected]>

AObuchow force-pushed the update-storage-administration-guide branch from 16c7139 to 2e93b12 Compare August 28, 2023 15:19

deerskindoll reviewed Aug 28, 2023

View reviewed changes

modules/administration-guide/pages/configuring-storage-sizes.adoc Outdated Show resolved Hide resolved

Update modules/administration-guide/pages/configuring-storage-sizes.adoc

523a3a2

deerskindoll merged commit 60748e7 into eclipse-che:main Aug 28, 2023
5 checks passed

che-bot removed the status/code-review label Aug 28, 2023

deerskindoll added a commit that referenced this pull request Aug 29, 2023

procedures: update admin docs for storage classes, storage strategies…

304458b

… and storage size (#2536) Co-authored-by: Jana Vrbkova <[email protected]>

deerskindoll added the backported to 7.70.x label Aug 29, 2023

		[id="configuring-{prod-id-short}-workspace-pvc-size"]
		= Configuring the storage size in {prod-short}


		The persistent volume claim (PVC) size can be configured when using the `per-user` or `per-workspace` storage strategies. PVC sizes in the Che Cluster Custom Resource must be specified in the format of a https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-che-storage-strategy.adoc[]

		.Default persistent volume claim sizes:

	.Default persistent volume claim sizes:
	Default persistent volume claim sizes:


		.Procedure

		Use CheCluster Custom Resource definition to define the persistent volume claim size for the desired storage strategy:


		Use CheCluster Custom Resource definition to define the persistent volume claim size for the desired storage strategy:

		Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource. To set this field prior to installing {prod-short}, see xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[], otherwise consult xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].

-Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource. To set this field prior to installing {prod-short}, see xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[], otherwise consult xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+. Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource:
+[NOTE]
+====
+* You can set this field at installation. See xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[].
+* You can update this field on the command line. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+====

procedures: update admin docs for storage classes, storage strategies and storage size #2536

procedures: update admin docs for storage classes, storage strategies and storage size #2536

Conversation

AObuchow commented Jan 10, 2023 • edited Loading

What does this pull request change?

What issues does this pull request fix or reference?

Specify the version of the product this pull request applies to

Pull Request checklist

github-actions bot commented Jan 10, 2023 • edited Loading

github-actions bot commented Jan 10, 2023

github-actions bot commented Jan 10, 2023

max-cx commented Jan 12, 2023 • edited Loading

AObuchow commented Jan 12, 2023

Choose a reason for hiding this comment

max-cx Apr 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AObuchow commented Jan 18, 2023

max-cx commented Jan 30, 2023

max-cx commented Apr 3, 2023

AObuchow commented Apr 3, 2023

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

max-cx Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

AObuchow commented Apr 28, 2023

AObuchow commented Apr 28, 2023 • edited Loading

AObuchow commented Jun 22, 2023

ibuziuk commented Aug 10, 2023

AObuchow commented Aug 10, 2023

ibuziuk commented Aug 28, 2023

ibuziuk commented Aug 28, 2023

deerskindoll commented Aug 28, 2023 • edited Loading

deerskindoll left a comment

Choose a reason for hiding this comment

AObuchow commented Aug 28, 2023

deerskindoll left a comment

Choose a reason for hiding this comment

AObuchow commented Jan 10, 2023 •

edited

Loading

github-actions bot commented Jan 10, 2023 •

edited

Loading

max-cx commented Jan 12, 2023 •

edited

Loading

max-cx Apr 6, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

max-cx Apr 4, 2023 •

edited

Loading

AObuchow commented Apr 28, 2023 •

edited

Loading

deerskindoll commented Aug 28, 2023 •

edited

Loading