Doc review #135

wabernat · 2018-06-15T16:01:49Z

This pull request (I hope) brings my local up to date and adds RST files for new features.

smaffulli

thanks for the edits William, the text reads a lot better. It seems to me that some of the lines are out of the line character limiti (78, I think --please double-check).

The new files you added need to be discussed in a separate pull request, IMO. The file names contain spaces and that's not good. Also it's not clear to me why the directory and file names are capitalized.
Let's split the commit so that the fixes to the existing docs can go in faster, while we discuss the new files separately.

smaffulli · 2018-06-15T16:09:20Z

swarm-production/README.md

-persistent containers to this particular node, assign label `io.zenko.type` with
-value `storage` to the node:
+Here, we choose the host `s3-node-zenko-swarm-1.na.scality.cloud` with ID
+`ng8quztnef0r1x90le4d6lssj`. To ensure that Docker Swarm only schedules persistent containers to this node, assign the `io.zenko.type` label with


this line is not wrapped

smaffulli · 2018-06-15T16:09:49Z

swarm-production/README.md

-and upload anonymous stats. Zenko Orbit allows easy configuration of users,
-remote storage locations, replication and more, as well as instance monitoring.
+By default, the stack registers itself at the
+[Zenko Orbit](https://www.zenko.io/admin) portal and uploads anonymous stats. Zenko Orbit allows easy configuration of users, remote storage locations,


This line is not wrapping

smaffulli · 2018-06-15T16:10:00Z

swarm-production/README.md


-If you would like to opt out of the remote management and monitoring, before
-deploying you can export this environment variable:
+To opt out of remote management and monitoring, export this environment variable before deployment:


this line is too long.

smaffulli · 2018-06-15T16:11:04Z

swarm-production/README.md

-the `ENDPOINT` variable configured above if applicable, or whatever the
-`hostname -f` command returns.
- > IMPORTANT: when using default port 80, it should never be specified after the
- > endpoint address. If using a custom port, it must be specified.


Check wrapping settings in your editor.

Working on these. Capitalized headings is a "book" artifact. We'll have to resolve this issue for content reuse. I can certainly un-capitalize the file names, but the headings will need to be fixed manually to one standard or the other ("up" or "down"). Either way is going to be work.

ssalaues · 2018-06-15T16:55:38Z

Try to do a rebase against master in the branch. It looks like you have the commits from #123 showing up in this PR as well

wabernat · 2018-06-15T17:52:59Z

Will do.

…

On Fri, Jun 15, 2018 at 9:55 AM, Salim Salaues ***@***.***> wrote: Try to do a rebase on master in the branch. It looks like you have the commits from #123 <#123> showing up in this PR as well — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#135 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AiJ6GHl5I_BFg56avy67H5B4PjVVd5MWks5t8-cOgaJpZM4UpzKo> .

-- William Abernathy Sr. Tech Writer San Francisco

ghost · 2018-06-15T19:45:34Z

There were the following issues with this Pull Request

Commit: 587f845
- ✖ message may not be empty
  , - ✖ type may not be empty

You may need to change the commit messages to comply with the repository contributing guidelines.

🤖 This comment was generated by commitlint[bot]. Please report issues here.

Happy coding!

JianqinWang · 2018-07-23T21:47:10Z

docs/Operations/Introduction.rst is blank, is it intentional for that file to be commited with this PR?

JianqinWang · 2018-07-23T21:53:04Z

docs/Installation/MetalK8s-CentOS7.4_install.rst

+
+  ::
+
+      $ kubectl logs my-zenko-cloudserver-front-<id> | grep 'Instance ID' \


This segment is formatted strangely. The first line is the command and the rest of the section is the example output, but by having \ appending each line, it looks like this should be one massive command that is run.

Also, we should probably clarify that the Instance ID is the value that users are looking for and the reason why users are grabbing logs, with a quick comment that this ID will be used to register the instance on zenko.io

JianqinWang · 2018-07-23T21:54:08Z

docs/Installation/MetalK8s-CentOS7.4_install.rst

+               {%- set node = ((pv.spec.nodeAffinity.required.nodeSelectorTerms|first).matchExpressions
+                    |first)['values']|first -%}
+               {%- set _ = released_pv.setdefault(node, []).append(pv) -%}
+           {%- endfor -%}


at least in the render mode via Github, the last line is incorrectly formatted (missing the leading tab/spaces and does not line up with the for statement).

This is a persistent problem with rst. Every renderer seems to have a different take on this. I believe I've fixed this, but that depends on your renderer, I guess...

Keep an eye on this.

JianqinWang · 2018-07-23T21:54:58Z

docs/install/MetalK8s-CentOS7.4_install.rst

@@ -0,0 +1,615 @@
+Introduction


This looks like an exact copy of docs/Installation/MetalK8s-CentOS8.5_install.rst. I assume this is an accidental duplication.

I rebased this morning, and can't find the MetalK8s-CentOS8.5_install.rst doc anymore. I assume it's been clobbered.

Ah. I see the problem. I'll clobber one of the instances.

This directory and file no longer exist.

In your commits I still see a lot of commits that are already included in master, afaik when you rebase off master those commits shouldn't show up in the PR.

tmacro · 2018-07-26T23:53:24Z

swarm-production/README.md

+## Testing
+
+To use the `tests` folder, update the credentials in
+`Zenko/tests/utils/s3SDK.js` with credentials generated in Zenko Orbit.


should be Zenko/tests/backbeat/s3SDK.js

Also theres a boatload of evironment variables that need to be set for it to run

jonathan-gramain · 2018-07-26T23:57:51Z

docs/NewFeatures/lifecycle_expiration_policies.rst

+    from the bucket on which they are stored. At present, files
+    exceeding a preset date *cannot be transitioned* to STANDARD\_IA or
+    GLACIER storage classes.
+=======


Everything from this point seems to be duplicating the above text. Remove?

Gitcrap. Sorry. Thought I'd got that. Fixed (again)

jonathan-gramain · 2018-07-27T00:00:33Z

docs/NewFeatures/lifecycle_expiration_policies.rst

+time has passed since the object’s creation. Zenko supports expiration of
+versioned or non-versioned objects, when a defined number of days has
+passed since those objects’ creation. This enables automatic deletion of
+older versions of versioned objects to reclaim storage space.


Additionally, we can also expire current version of objects with separate rules, it's also supported in Orbit. (for versioned buckets, it adds a delete marker like when a user deletes the object without specifying a version ID).

Using Zenko from the command line or from Orbit, you can expire the
current version of an object with a separate rule. For versioned buckets, add
a delete marker on an event, such as when a user deletes an object without first
specifying a version ID.

jonathan-gramain · 2018-07-27T00:01:36Z

docs/NewFeatures/lifecycle_expiration_policies.rst

+Cloud users can apply lifecycle expiration rules (specified in Amazon’s
+`AWS S3 API <https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html>`__)
+to buckets managed through Zenko. These rules are triggered after a defined
+time has passed since the object’s creation. Zenko supports expiration of


We may mention we can also trigger expiration of current versions based on a date at which the rule starts applying (but no Orbit support as of now, doable with S3 API).

"Zenko supports expiration of versioned or non-versioned objects, when a
defined number of days has passed since those objects’ creation. This enables
automatic deletion of older versions of versioned objects to reclaim storage
space. Zenko also supports triggering expiration of current versions on a date
from which a rule applies. This is currently feasible using the S3 API, but not
with Orbit."

jonathan-gramain · 2018-07-27T00:04:00Z

docs/NewFeatures/lifecycle_expiration_policies.rst

+Bucket lifecycle characteristics inhere to each bucket. Zenko’s lifecycle
+management feature enforces, but does not set these characteristics. When
+lifecycle expiration is enabled, the host cloud enforces buckets’ lifecycle
+rules. If CRR operation is enabled, Zenko replicates the expiration rules to


"If CRR operation is enabled, Zenko replicates the expiration rules to all backup clouds"

This is how it is currently, but this is more of a bug that needs to be addressed, as AWS does not replicate lifecycle actions, neither do we want this behavior for Zenko. So better not to mention this as we plan to fix the current behavior soon enough.

Fixed line-length issue, and review is dated, out-of-sync

rahulreddy · 2018-07-30T22:37:37Z

tests/.secrets.env.example

@@ -1,5 +1,3 @@
-export ZENKO_STORAGE_ACCOUNT_ACCESS_KEY=


Is this an intended change?

No. My suspicion is that this is an unfortunate byproduct of my Git legerdemain, but I'm not good enough at it to even know when I've fscked it up.

I copied the file over from the dev/0.9 branch. I hope that's the end of this issue.

philipyoo

minor change 👍
I really like this, looks very nice!

philipyoo · 2018-07-30T22:35:41Z

docs/NewFeatures/CRR_statistics.rst

+pending, processing, and completed objects. It returns the number of
+errors that occurred during replication, the current throughput—in
+operations per second or replicating objects per second—and the number
+of total MB completing per second. A health check system has also been


instead of MB -> bytes

ssalaues · 2018-07-30T22:43:35Z

docs/Operations/Useful_kubectl_Commands.rst

+
+  ::
+
+  $ kubectl get pods -n kube-ops -o wide | grep es-client


Definitely useful list of commands but I think some of these are very specific to a metal-k8s install. es-client for example

These came across with the quickstart from MetalK8s, and I moved them out of that file, but was too timid to delete them altogether. If you think it best (and insofar as these are handled already in the MetalK8s documentation) we can eliminate this file altogether.

Following through on this after discussion w/Salim. Deleting Useful_kubectl_commands.rst. This leaves the Operations directory empty, so I'll delete that as well.

bennettbuchanan · 2018-07-30T22:42:31Z

docs/NewFeatures/CRR_statistics.rst

+This feature enables replication status tracking. The replication system
+exposes metrics through a REST API to monitor the replication of
+pending, processing, and completed objects. It returns the number of
+errors that occurred during replication, the current throughput—in


Maybe "failures" is a more accurate word choice compared with "errors".

bennettbuchanan · 2018-07-30T22:43:16Z

docs/NewFeatures/CRR_statistics.rst

+exposes metrics through a REST API to monitor the replication of
+pending, processing, and completed objects. It returns the number of
+errors that occurred during replication, the current throughput—in
+operations per second or replicating objects per second—and the number


I think "in replication operations per second" works well enough to not need the "or" here.

Does this work?

"It returns the number of failures that occurred during replication, the current throughput—in replication operations or objects per second—and the total of bytes completing per second."

It returns the number of failures that occurred during replication, the current throughput in replication operations per second, and the total of bytes completing per second.

Sounds perfect to me! @philipyoo What do you think?

wabernat · 2018-07-31T22:03:52Z

...and there was much rejoicing...

…

On Tue, Jul 31, 2018 at 2:23 PM, Salim Salaues ***@***.***> wrote: Merged #135 <#135>. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#135 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AiJ6GEjc8BFJzuz5tsVA9pljNcbXqTn0ks5uMMrDgaJpZM4UpzKo> .

-- William Abernathy Sr. Tech Writer San Francisco

-- <https://www.scality.com/download-idc-marketscape/?utm_source=ScalityEmail&utm_medium=Email&utm_campaign=2018Predictions>

bennettbuchanan · 2018-07-31T22:05:35Z

🍾

smaffulli previously requested changes Jun 15, 2018

View reviewed changes

wabernat force-pushed the DocReview branch from f207dc6 to d629183 Compare June 15, 2018 18:13

scality deleted a comment Jun 19, 2018

JianqinWang reviewed Jul 23, 2018

View reviewed changes

ssalaues closed this Jul 24, 2018

ssalaues mentioned this pull request Jul 26, 2018

Rewrote Installation Guide #225

Closed

ssalaues changed the base branch from master to development/0.9 July 26, 2018 22:16

ssalaues reopened this Jul 26, 2018

wabernat force-pushed the DocReview branch 2 times, most recently from 3f13dd2 to e771e91 Compare July 26, 2018 23:36

tmacro reviewed Jul 26, 2018

View reviewed changes

tmacro approved these changes Jul 27, 2018

View reviewed changes

jonathan-gramain reviewed Jul 27, 2018

View reviewed changes

rahulreddy reviewed Jul 30, 2018

View reviewed changes

philipyoo reviewed Jul 30, 2018

View reviewed changes

ssalaues reviewed Jul 30, 2018

View reviewed changes

bennettbuchanan reviewed Jul 30, 2018

View reviewed changes

wabernat force-pushed the DocReview branch from e771e91 to 0f78d56 Compare July 30, 2018 23:48

ssalaues approved these changes Jul 31, 2018

View reviewed changes

Doc: New RST files, extensive rework

622854b

wabernat force-pushed the DocReview branch from 0f78d56 to 622854b Compare July 31, 2018 20:36

ssalaues merged commit 3c58dde into development/0.9 Jul 31, 2018

ssalaues deleted the DocReview branch July 31, 2018 21:23


		::

		$ kubectl logs my-zenko-cloudserver-front-<id> \| grep 'Instance ID' \

Doc review #135

Doc review #135

Conversation

wabernat commented Jun 15, 2018

smaffulli left a comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ssalaues commented Jun 15, 2018 • edited Loading

wabernat commented Jun 15, 2018 via email

ghost commented Jun 15, 2018

JianqinWang commented Jul 23, 2018

Choose a reason for hiding this comment

JianqinWang Jul 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JianqinWang Jul 23, 2018 • 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

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

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philipyoo left a comment

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

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

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

Choose a reason for hiding this comment

wabernat commented Jul 31, 2018 via email

bennettbuchanan commented Jul 31, 2018

ssalaues commented Jun 15, 2018 •

edited

Loading

JianqinWang Jul 23, 2018 •

edited

Loading

JianqinWang Jul 23, 2018 •

edited

Loading