Edited README #158

NancyHarvey · 2017-09-11T20:12:10Z

Wordsmithed for brevity, consistency and active (not passive) voice.
Updated mentions of Kraken to kraken, Krakenlib to kraken-lib.
See inline comments for some questions.

@coffeepac - for review after I add inline comments

Wordsmithed for brevity, consistency and active (not passive) voice. Updated mentions of Kraken to kraken, Krakenlib to kraken-lib. See inline comments for some questions.

NancyHarvey · 2017-09-11T20:12:56Z

README.md


 ```
 brew tap 'samsung-cnct/homebrew-k2cli'
 brew install k2cli
 ```

-Otherwise, the latest official build can be found here: https://github.com/samsung-cnct/k2cli/releases. You should use the latest version unless you have a specific reason to use a different version.
+Otherwise, you can find the latest official build [here](https://github.com/samsung-cnct/k2cli/releases). Use the latest version, unless you have a specific reason for using a different one.


Provide an example of what a valid reason might be?

specific reasons would include:

reliant on a deprecated/removed feature

reliant on a bug that has since been fixed

using more then three minor versions old version of kubernetes

however, I don't think we need to specify any of these. or if we do only the 'different version of kubernetes' is something I'd be comfortable advertising.

sounds like just leaving as is is good then, right?

leaving as-is is fine.

NancyHarvey · 2017-09-11T20:14:07Z

README.md


-There are a great many options that you can modify to control the deployment of your Kubernetes cluster.  Here we introduce only a couple options that may be of interest to you before starting your first cluster.  
+You can modify many options to control the deployment of your Kubernetes cluster. Here we focus on a couple that may be of interest before starting your first cluster.  


Provide examples or link(s) to more info about other, more advanced options to give them a flavor of quantity/type available?

the full set of kraken configuration options can be found here: https://samsung-cnct.github.io/k2/

NancyHarvey · 2017-09-11T20:15:09Z

README.md

-Kraken uses the Krakenlib image (github.com/samsung_cnct/k2) for all of its operations. The Krakenlib image ships with `kubectl` and `helm`
-installed and through the `kraken tool` subcommand you can access these tools. Using the `kraken tool` subcommand helps ensure you are
+## Working with Your Cluster (Using kraken)
+For all of its operations, kraken uses the kraken-lib image (github.com/samsung_cnct/k2) that ships with the installed `kubectl` and `helm`. You can access these tools through the `kraken tool` subcommand. Using this subcommand helps ensure you're


what URL should this be and should we put the link on "kraken-lib image"?

we should put the link on 'kraken-lib image' and the link to the image is 'quay.io/samsung_cnct/k2' We need to update it but haven't yet. I will handle updating all references to it later.

NancyHarvey · 2017-09-11T20:16:06Z

README.md

-### Updating your cluster
-You may update your nodepools with Kraken, specifically the Kubernetes version, the nodepool counts and instance types. To do so, please make desired changes in your configuration file, and then run Kraken's cluster update command, as described below, pointing to your configuration file.
+## Updating your Cluster
+You can update your node pools, node pool counts and instance types with kraken (specifically, the Kubernetes version). To do so, please make desired changes in your configuration file, and then run Kraken's cluster update command, as described below, pointing to your configuration file.


"(specifically, the Kubernetes version)" -- necessary to say? This begs the question of what other versions are there?

We do want to mention common things that can be updated as a bit of marketing hook, I think. Maybe a better phrasing would be 'You can update all aspects of your node pools including count, Kubernetes version, instance type and more.'

NancyHarvey · 2017-09-11T20:17:12Z

README.md

-While not something to be done in production, during development when you are done with your cluster (or with a quickstart) it's
-best to clean up your resources. To destroy the running cluster from this guide, simply run:
+## Destroying the Running Cluster
+During development (not production), when you're done with your cluster or with a quickstart, we recommend cleaning up your resources by destroying the running cluster. From this guide, simply run:


Is this accurate the way I reworded?

This may be a valid operation to do in production. I would remove the leading clause and start the sentence with 'When you're done...'

NancyHarvey · 2017-09-11T20:18:07Z

README.md

-We accept pull requests from all users and do not require a contributor license agreement. To simplify merging we prefer pull requests that are based on the current Master
-and from a feature branch in your personal fork of the Kraken repo.
+# Contributing Features, Bug Fixes and More
+We welcome all types of contributions from the community and and don't require a contributor license agreement. To simplify merging, we prefer pull requests based on a feature branch in your personal fork that's based off the current master of the kraken repo. For more details, please refer to our [kraken-lib Contributing](https://github.com/samsung-cnct/k2/blob/master/CONTRIBUTING.md) document. 


seemed logical to point to kraken-lib Contributing file here ... make sense?

thats good. means we only have to keep it up to date in one place.

alejandroEsc · 2017-09-11T20:14:14Z

README.md

-#### Asset changes
-Asset are stored in the `/data` directory of this project's directory. Any changes made to files will only take if you
+### Asset changes
+Asset changes are stored in the `/data` directory of this project's directory. Any file changes only get implemented if you


not changes, actual assests are stored.

thanks - will fix

NancyHarvey · 2017-09-11T20:19:58Z

README.md

 ```
 kraken tool helm list
 ```

-To install the Kafka chart maintained by Samsung CNCT.
+To install the Kafka chart maintained by Samsung CNCT:


Any need to explain why/in what instances they'd want to do this instead of Helm chart above it?

we don't need to explain this. if someone is using a locally installed helm they have their reasons and we only need to show how to support their choice, not rationalize it.

Asset changes >> assets are store in ...

leahnp · 2017-09-11T20:16:01Z

README.md

-# Kraken
-Kraken is a command-line interface for [Krakenlib](https://github.com/samsung-cnct/k2).
+# kraken
+This document will help you get started deploying Kubernetes to AWS using kraken, a command-line interface for [kraken-lib](https://github.com/samsung-cnct/k2). kraken currently also supports deployments to GKE, but not by default.


should we specify "a high available/HA Kubernetes cluster..." since that's our differentiating factor?

that is a big thing so if there's a good way to insert that I think it makes sense.

leahnp · 2017-09-11T20:17:08Z

README.md

-# Kraken
-Kraken is a command-line interface for [Krakenlib](https://github.com/samsung-cnct/k2).
+# kraken
+This document will help you get started deploying Kubernetes to AWS using kraken, a command-line interface for [kraken-lib](https://github.com/samsung-cnct/k2). kraken currently also supports deployments to GKE, but not by default.


Instead of "but not by default" should we link to our docs on deploying a GKE cluster?

Sounds logical. Can you send me the link, please? I don't have it handy.

Curiously, we explain how just a few lines down with: `For a GKE configuration file, run:

kraken generate --provider gke1` My concern with saying "not by default" is we turn away those customers before they see how easy it is. Perhaps we can say "kraken currently also supports deployments to GKE, to generate a GKE config file use the following command: kraken generate --provider gke1"

saying 'not by default' is probably too strong. we have a default configuration file for GKE in kraken-lib. Could remove the 'but not by default' with 'and instructions for GKE follow this AWS section' or something similar.

leahnp · 2017-09-11T20:17:59Z

README.md

-### Installing/Fetching the Official Build
-Installation on OSX can happen via Brew by:
+## Installing/Fetching the Official Build
+You can install the official build on OS X via Brew by:

 ```
 brew tap 'samsung-cnct/homebrew-k2cli'
 brew install k2cli


k2cli is confusing - maybe we need a footnote that explains the name change?

we should leave this for now. I need to file an issue to change this to be kraken instead of k2cli. it'll be part of the Open Source punch list.

coffeepac · 2017-09-11T22:46:35Z

README.md


 *  **Deployment Region and Availability Zones**  
-In the default generated configuration file, all clusters begin their lives in the AWS Region US East. This can be modified to locate the cluster in a region or to modify the availability zones to a value that may be more suitable to individual use cases.  For reference, the [Global AWS Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/) provides a complete list of Regions and Availability Zones.  These fields are named `definitions.providerConfigs.region`, and `definitions.providerConfigs.subnet.az` respectively.  Note that there are actually three total `.subnet.az` values defined so that the cluster can be spread across multiple failure domains.  You should update all three to availability zones that are within the region selected.  
+In the default-generated configuration file, all clusters begin their lives in the AWS Region US East. You can move the default region and  modify the availability zones, if needed. For reference, the [Global AWS Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/) provides a complete list of regions and availability zones. These fields are named `definitions.providerConfigs.region`, and `definitions.providerConfigs.subnet.az` respectively. Note three total `.subnet.az` values are defined, so the cluster can be spread across multiple failure domains. Be sure to update all three to availability zones within your selected region.  


'AWS Region "us-east-1"'

coffeepac

some nits, some questions answered.

good first cut!

@coffeepac

From @coffeepac, @alajandroEsc and @leahnp Just need URL for GKE documentation for line samsung-cnct#2 per Leah's suggestion

leahnp

Great work Nancy - thank you!

@coffeepac

Per @coffeepac's comment to leave as is (last line about GKE deployments)

@coffeepac

Removed "but not by default" and pointed to GKE config a little lower per @coffeepac comment

Edited README

9288bf2

Wordsmithed for brevity, consistency and active (not passive) voice. Updated mentions of Kraken to kraken, Krakenlib to kraken-lib. See inline comments for some questions.

NancyHarvey requested a review from coffeepac September 11, 2017 20:12

NancyHarvey commented Sep 11, 2017

View reviewed changes

alejandroEsc suggested changes Sep 11, 2017

View reviewed changes

NancyHarvey commented Sep 11, 2017

View reviewed changes

Fixed line #319 per comment from @alejandroEsc

af90393

Asset changes >> assets are store in ...

leahnp reviewed Sep 11, 2017

View reviewed changes

coffeepac reviewed Sep 11, 2017

View reviewed changes

coffeepac suggested changes Sep 11, 2017

View reviewed changes

Implemented 9/11 feedback

c39eefc

From @coffeepac, @alajandroEsc and @leahnp Just need URL for GKE documentation for line samsung-cnct#2 per Leah's suggestion

leahnp previously approved these changes Sep 12, 2017

View reviewed changes

Reverted end of line 2 back to original

1c2ab96

Per @coffeepac's comment to leave as is (last line about GKE deployments)

NancyHarvey dismissed leahnp’s stale review via 1c2ab96 September 12, 2017 18:24

Added in-doc reference at end of line 2

3c5cbd6

Removed "but not by default" and pointed to GKE config a little lower per @coffeepac comment

coffeepac approved these changes Sep 12, 2017

View reviewed changes

alejandroEsc approved these changes Sep 12, 2017

View reviewed changes

coffeepac merged commit 34f567e into samsung-cnct:master Sep 12, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Edited README #158

Edited README #158

NancyHarvey commented Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

coffeepac Sep 11, 2017

NancyHarvey Sep 12, 2017

coffeepac Sep 12, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

alejandroEsc Sep 11, 2017

NancyHarvey Sep 11, 2017

NancyHarvey Sep 11, 2017

coffeepac Sep 11, 2017

leahnp Sep 11, 2017

coffeepac Sep 11, 2017

leahnp Sep 11, 2017

NancyHarvey Sep 12, 2017

leahnp Sep 12, 2017

NancyHarvey Sep 12, 2017

coffeepac Sep 12, 2017

leahnp Sep 11, 2017

coffeepac Sep 11, 2017 •

edited

Loading

coffeepac Sep 11, 2017

coffeepac left a comment

leahnp left a comment


		There are a great many options that you can modify to control the deployment of your Kubernetes cluster. Here we introduce only a couple options that may be of interest to you before starting your first cluster.
		You can modify many options to control the deployment of your Kubernetes cluster. Here we focus on a couple that may be of interest before starting your first cluster.

Edited README #158

Edited README #158

Conversation

NancyHarvey commented Sep 11, 2017

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

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

coffeepac Sep 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coffeepac left a comment

Choose a reason for hiding this comment

leahnp left a comment

Choose a reason for hiding this comment

coffeepac Sep 11, 2017 •

edited

Loading