Adding recommended storage guidelines to scaling and performance guide #6033

ghost · 2017-10-30T19:15:18Z

Related to #5623

ghost · 2017-10-31T13:07:26Z

@lpsantil Hi Louis, this is the follow up PR for #5623. Please review the files changed. Thanks.

lpsantil · 2017-10-31T15:32:09Z

LGTM

ghost · 2017-11-01T15:19:22Z

[rev_history]
|xref:../scaling_performance/optimizing_storage.adoc#scaling-performance-optimizing-storage[Optimizing Storage]
|Added the xref:../scaling_performance/optimizing_storage.adoc#general-storage-guidelines[General Storage Guidelines] section for optimizing OpenShift storage.
%

ghost · 2017-11-01T15:20:07Z

@openshift/team-documentation Please peer review this PR and revision history.

gaurav-nelson · 2017-11-01T23:40:40Z

scaling_performance/optimizing_storage.adoc

s/OpenShift/{product-title}

gaurav-nelson · 2017-11-01T23:43:30Z

scaling_performance/optimizing_storage.adoc

We can set column widths to [cols="1,4,3",options="header"] instead, as it renders better.

gaurav-nelson · 2017-11-01T23:48:00Z

scaling_performance/optimizing_storage.adoc

maybe s/capabilities will vary widely/capabilities varies widely

If the latter then it's 'capabilities vary widely'

gaurav-nelson · 2017-11-01T23:48:42Z

scaling_performance/optimizing_storage.adoc

s/via/through

gaurav-nelson · 2017-11-01T23:56:48Z

scaling_performance/optimizing_storage.adoc

Usually I prefer ✅ for Yes and 🞩 for No. Up to you if you want to change that. 😇

gaurav-nelson · 2017-11-01T23:58:42Z

scaling_performance/optimizing_storage.adoc

We do explain the full form later but maybe we should explain the full form of ROX and RWX before we use them?

gaurav-nelson · 2017-11-02T00:06:24Z

scaling_performance/optimizing_storage.adoc

For this section, I think we should use points for each sentence, like:

In a non-scaled/HA {product-title} registry cluster deployment: * The preferred storage back-end type is object storage followed by block storage. The storage back-end type does not need to support ReadWriteMany * (RWX) access mode. The storage back-end type must ensure read-after-write * consistency. All NAS back-end types (excluding CNS/CRS GlusterFS as it uses an object storage interface) are expressly not recommended for {product-title} Registry cluster deployment with production workloads. * While hostPath volumes are configurable for a non-scaled/HA {product-title} Registry cluster deployment, they are not recommended.

Same for Scaled registry, metrics, logging, and applications section if possible.

Should we also highlight whats not recommend by using admonitions? I am not sure. 😕 ❔

@gaurav-nelson YES! We do need to mention what to use. Here is an email from openshift-users email list from yesterday, 11/1/2017.

I am confused over persistent storage for logging (elasticsearch). The latest advanced installer docs [1] specifically describes how to define using NFS for persistent storage, but the docs for "aggregating container logs" [2] says that NFS should not be used (except in one particular scenario) and seems to suggest that the only really suitable scenario is to use a volume (disk) directly mounted to each logging node. Could someone clarify the situtation?

The above misreading is not exactly the case for Logging.

My goal is to reference this page from the Registry, Metrics, and Logging install docs once this PR lands. There are probably a couple other places which could do with a reference to this doc as well.

gaurav-nelson · 2017-11-02T00:13:35Z

scaling_performance/optimizing_storage.adoc

Btrfs is the correct term https://en.wikipedia.org/wiki/Btrfs

gaurav-nelson · 2017-11-02T00:25:09Z

scaling_performance/optimizing_storage.adoc

Should it be Portable Operating System Interface (POSIX) ?

gaurav-nelson · 2017-11-02T00:36:34Z

Some comments and questions form me @tmorriso-rh rest LGTM 📈

ncbaratta

I need to do another review after the suggested changes are made.

ncbaratta · 2017-11-06T19:26:39Z

scaling_performance/optimizing_storage.adoc

delete 'sometimes'

ncbaratta · 2017-11-06T19:28:04Z

scaling_performance/optimizing_storage.adoc

delete 'sometimes'

ncbaratta · 2017-11-06T19:34:38Z

scaling_performance/optimizing_storage.adoc

"storage back-end types" is very clunky. IBM styleguide does suggest using something more detailed than 'back-end' if possible and 'types' I also feel need rewording.

Would 'storage systems' make just as much sense? Or does that change the meaning?

This goes for all occurrences of this phrase that follow.

@nengard I think "storage systems" is too specific, IMO. That would refer to a specific vendor or even vendor solution for vendors that offer more than one product/solution.

I think agree with you now. Maybe, you're searching for "storage technology".

ncbaratta · 2017-11-06T19:35:31Z

scaling_performance/optimizing_storage.adoc

We should be sure to spell out HA the first time it appears in a chapter.

ncbaratta · 2017-11-06T19:36:04Z

scaling_performance/optimizing_storage.adoc

Should 'hostPath' be styled as a literal?

ncbaratta · 2017-11-06T19:44:19Z

scaling_performance/optimizing_storage.adoc

Issue 'with' production workloads.

ncbaratta · 2017-11-06T19:45:09Z

scaling_performance/optimizing_storage.adoc

Define 'PV' the first time you use it.

ncbaratta · 2017-11-06T19:45:32Z

scaling_performance/optimizing_storage.adoc

Does "OpenShift Container Platform" have an attribute?

ncbaratta · 2017-11-06T19:46:00Z

scaling_performance/optimizing_storage.adoc

comma after 'mechanisms'

ncbaratta · 2017-11-06T19:46:34Z

scaling_performance/optimizing_storage.adoc

If the latter then it's 'capabilities vary widely'

ghost · 2017-11-07T15:43:47Z

@nengard and @lpsantil Changes made. PTAL. Thanks.

ncbaratta · 2017-11-07T20:01:05Z

scaling_performance/optimizing_storage.adoc

Not sure we want to say 'topic'.

ncbaratta · 2017-11-07T20:02:03Z

scaling_performance/optimizing_storage.adoc

"The following table lists the available persistent storage options for {product-title}."

Technology (or technologies) is a appropriate here. Most of the technologies are only supported buy purchasing them from a 3rd party.

Thanks @lpsantil so then:

"The following table lists the available persistent storage technologies for {product-title}."

ncbaratta · 2017-11-07T20:02:30Z

scaling_performance/optimizing_storage.adoc

Is this necessary? "This type of storage is presented to the operating system as a block device."

Again, try to minimize the words. A table is supposed to be easy to browse through:

"Referred to as a Storage Area Network (SAN). This type of storage is suitable for applications that need full control of storage and operate at a low level on files bypassing the file system. It is usually a non-shareable type of storage, which means that only one client at a time can mount an endpoint of this type."

Consider doing the same will the other descriptions below.

I was intentionally this verbose because not all OpenShift administrators will have strong Storage experience. The verbosity here provides baseline understanding w/o resorting to citation heavy descriptions.

I think we can still get across the same amount of information without so many extraneous words.

ncbaratta · 2017-11-07T20:06:26Z

scaling_performance/optimizing_storage.adoc

Are footnotes common in these books? If not I'd use Notes not Footnotes. Footnotes are a very academic paper thing and not common in technical documentation.

ncbaratta · 2017-11-07T20:12:06Z

scaling_performance/optimizing_storage.adoc

Remove "s" from "provides"

"GlusterFS provide interfaces..." ?

ncbaratta · 2017-11-07T20:19:49Z

scaling_performance/optimizing_storage.adoc

what is ROX

ReadOnlyMany [0][1].

[0] https://docs.openshift.com/container-platform/3.6/architecture/additional_concepts/storage.html#pv-access-modes
[1] https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes

We should make that clear on the first usage. Always spell it out the first time.

ncbaratta · 2017-11-07T20:20:16Z

scaling_performance/optimizing_storage.adoc

why isn't Btrfs monospaced as well?

ncbaratta · 2017-11-07T20:21:26Z

scaling_performance/optimizing_storage.adoc

There was no hyphen in thin pool above - so either add up there, or remove here.

Thin pool is a noun, and thin-pool is an adjective, correct?

You are right, ignore my comment ;) hehe

ncbaratta · 2017-11-07T20:21:45Z

scaling_performance/optimizing_storage.adoc

Add hyphen? or leave and remove above.

ncbaratta · 2017-11-07T20:22:08Z

scaling_performance/optimizing_storage.adoc

thin-pool or thin pool - be consistent.

lpsantil · 2017-11-07T17:59:37Z

scaling_performance/optimizing_storage.adoc

s/all NAS/NAS/

lpsantil · 2017-11-07T22:54:46Z

scaling_performance/optimizing_storage.adoc

s/all NAS/NAS/

ghost · 2017-11-08T15:18:39Z

@nengard PTAL.

ghost · 2017-11-09T15:53:48Z

@nengard @lpsantil I used bullet lists in the table to help with readability. I agree with Louis that the information is important since this a guidelines document. So, hoping the lists makes the table easier to read. PTAL.

vikram-redhat · 2017-11-20T01:30:27Z

@tmorriso-rh - Hey Traci - this hasn't been picked the 3.7 stage branch.

ghost self-assigned this Oct 30, 2017

ghost added branch/enterprise-3.6 branch/enterprise-3.7 labels Oct 30, 2017

ghost added this to the Next Release milestone Oct 30, 2017

ghost mentioned this pull request Oct 31, 2017

Storage Recommendation addition #5623

Closed

gaurav-nelson reviewed Nov 1, 2017

View reviewed changes

scaling_performance/optimizing_storage.adoc Outdated

Copy link

Contributor

gaurav-nelson Nov 1, 2017

Choose a reason for hiding this comment

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

s/OpenShift/{product-title}

gaurav-nelson reviewed Nov 1, 2017

View reviewed changes

scaling_performance/optimizing_storage.adoc Outdated

Copy link

Contributor

gaurav-nelson Nov 1, 2017

Choose a reason for hiding this comment

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

s/via/through

gaurav-nelson reviewed Nov 1, 2017

View reviewed changes

gaurav-nelson reviewed Nov 2, 2017

View reviewed changes

scaling_performance/optimizing_storage.adoc Outdated

Copy link

Contributor

gaurav-nelson Nov 2, 2017

Choose a reason for hiding this comment

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

Btrfs is the correct term https://en.wikipedia.org/wiki/Btrfs

gaurav-nelson reviewed Nov 2, 2017

View reviewed changes

ncbaratta suggested changes Nov 6, 2017

View reviewed changes

ncbaratta suggested changes Nov 7, 2017

View reviewed changes

lpsantil reviewed Nov 7, 2017

View reviewed changes

Adding recommended storage guidelines

0b2c34f

ncbaratta added the peer-review-done Signifies that the peer review team has reviewed this PR label Nov 9, 2017

ghost merged commit 9d43121 into openshift:master Nov 13, 2017

ghost mentioned this pull request Nov 13, 2017

Enterprise 3.6 stage - Adding recommended storage guidelines to scaling and performance guide #6336

Merged

ghost mentioned this pull request Nov 20, 2017

[enterprise-3.7] Adding recommended storage guidelines #6337

Merged

vikram-redhat modified the milestones: Next Release, Staging, Published - 21/Nov/2017 Nov 20, 2017

ghost deleted the PR-5623-adding-storage-best-practices branch November 30, 2017 19:38

This pull request was closed.

Adding recommended storage guidelines to scaling and performance guide #6033

Adding recommended storage guidelines to scaling and performance guide #6033

Uh oh!

Conversation

ghost commented Oct 30, 2017

Uh oh!

ghost commented Oct 31, 2017

Uh oh!

lpsantil commented Oct 31, 2017

Uh oh!

ghost commented Nov 1, 2017 • edited by vikram-redhat Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Nov 1, 2017

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!

gaurav-nelson Nov 1, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

lpsantil Nov 2, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaurav-nelson Nov 2, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaurav-nelson commented Nov 2, 2017

Uh oh!

ncbaratta 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lpsantil Nov 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

ghost commented Nov 1, 2017 •

edited by vikram-redhat

Loading

gaurav-nelson Nov 1, 2017 •

edited

Loading

lpsantil Nov 2, 2017 •

edited

Loading

gaurav-nelson Nov 2, 2017 •

edited

Loading

lpsantil Nov 6, 2017 •

edited

Loading