Improve readme #120

KnVerey · 2017-07-07T00:52:14Z

@Shopify/cloudplatform @kirs @xldenis

This PR improves the repo's README. Until now, its secondary features were far-better documented than the main ones! I'm giving a presentation on this gem at a meetup early next week, so I would like for these improvements to be in before we (hopefully) get more people interested in reading about it.

Helps with #105

kirs

I love the new README 😍 Thanks for working on it.
I have just a few suggestions.

kirs · 2017-07-07T07:49:32Z

README.md

- - The target namespace must already exist in the target context
- - `ENV['GOOGLE_APPLICATION_CREDENTIALS']` must point to the credentials for an authenticated service account if your user's auth provider is GCP
- - `ENV['ENVIRONMENT']` must be set to use the default template path (`config/deploy/$ENVIRONMENT`) in the absence of the `--template-dir=DIR` option
+- `ENV[REVISION]` **(required)**: the SHA of the commit you are deploying. Will be exposed to your ERB templates as `current_sha`.


ENV[REVISION] may be unclear for someone outside of Ruby because AFAIK most Linux tools refer to env variables like $REVISION

kirs · 2017-07-07T07:52:16Z

README.md

+
+:closed_lock_with_key:	[Creates Kubernetes secrets from encrypted EJSON](#deploying-kubernetes-secrets-from-ejson), which you can safely commit to your repository
+
+:running:	[Runs tasks at the beginning of the deploy](#deploy-time-tasks) using pods (example use case: Rails migrations)


Maybe "using bare pods"?

kirs · 2017-07-07T07:53:01Z

README.md

+*Requirements:*
+
+* The pod's name should include `<%= deployment_id %>` to ensure that a unique name will be used on every deploy (the deploy will fail if a pod with the same name already exists).
+* The pod's `spec.restartPolicy` must be set to `Never`


I'd mention why it has be be Never (because it's a one-off task)

It will help people to learn more about restartPolicy, not just blindly following the instruction

kirs · 2017-07-07T07:55:07Z

README.md

+
+## Highlights
+
+:eyes:	Watches the changes you requested to make sure they complete successfully.


Maybe "to make sure they rollout successfully"?

For the deployment process, the definition of "complete" may be unclear

kirs · 2017-07-07T07:56:02Z

README.md

+
+
+
+## Table of contents


I love the new structure!

kirs · 2017-07-07T08:01:08Z

README.md


-[![Build status](https://badge.buildkite.com/0f2d4956d49fbc795f9c17b0a741a6aa9ea532738e5f872ac8.svg?branch=master)](https://buildkite.com/shopify/kubernetes-deploy-gem)
+`kubernetes-deploy` is a command line tool that helps you ship changes to a Kubernetes namespace and understand the result. At Shopify, we use it within our much-beloved, open-source [Shipit](https://github.com/Shopify/shipit-engine#kubernetes) deployment app.


I'd also mention why a separate deployment tool is needed for k8s (for instance because running kubectl apply from CI doesn't give a lot of control over it)

Great suggestion. I'll take a stab at it!

kirs · 2017-07-07T08:02:38Z

README.md

+* Your cluster must be running Kubernetes v1.6.0 or higher
+* Each app must have a deploy directory containing its Kubernetes templates (see [Templates](#templates))
+* You must remove the` kubectl.kubernetes.io/last-applied-configuration` annotation from any resources in the namespace that are not included in your deploy directory. If you do not, kubernetes-deploy will delete them.
+* Each app managed by `kubernetes-deploy` must have its own exclusive namespace. (This requirement can be bypassed with the `--no-prune` option, but it is not recommended.)


Maybe exclusive namespace => exclusive Kubernetes namespace?

kirs · 2017-07-07T08:03:23Z

README.md

+
+* Your cluster must be running Kubernetes v1.6.0 or higher
+* Each app must have a deploy directory containing its Kubernetes templates (see [Templates](#templates))
+* You must remove the` kubectl.kubernetes.io/last-applied-configuration` annotation from any resources in the namespace that are not included in your deploy directory. If you do not, kubernetes-deploy will delete them.


Just curious, do you remove them by editing YAMLs? I never saw this annotation.

That is the annotation that gets added when you create/update things via kubectl apply--I should probably mention that explicitly. It's what the pruning feature uses to identify which resources kubectl is authorized to manage. The easiest way to remove it is kubectl edit (and then remember not to kubectl apply the thing in the future!).

kirs · 2017-07-07T08:03:54Z

README.md

+
+:eyes:	Watches the changes you requested to make sure they complete successfully.
+
+:interrobang:	Provides debug information for changes that failed.


Great feature list!

KnVerey · 2017-07-07T18:21:18Z

Updated! Please take another look, particularly at the new intro para.

dalehamel · 2017-07-07T18:42:19Z

@KnVerey I really like this. I think some future work could be:

Description of a few workflows like:
Getting started - using stuff from an 'examples' directory
Walk through the steps of a deploy
Screen record your terminal running a deploy locally, and turn it into a gif - put this right near the top of the readme to add a bit of "wow" factor and get people interested. If a picture is worth a thousand words, a gif is worth a million?

None of this needs to be incorporated into this PR, just some ideas :)

KnVerey · 2017-07-07T19:05:30Z

I don't think there's a way to PR this change, but wdyt about updating the repo's description? Currently it is:

Collection of scripts to deploy apps to Kubernetes

I'm thinking of pulling one of these lines from this PR:

A command-line tool that helps you ship changes to a Kubernetes namespace and understand the result

A command-line tool providing clear, actionable pass/fail results for Kubernetes deploys

dalehamel · 2017-07-07T19:08:37Z

A command-line tool that helps you ship changes to a Kubernetes namespace and understand the result

My vote^

kirs · 2017-07-10T09:00:07Z

README.md


-## Installation
+Especially in a CI/CD environment, we need a clear, actionable pass/fail result for each deploy. Providing this was the foundational goal of `kubernetes-deploy`, which has grown to support the following core features:


kirs

One nit, otherwise looks great 👌

kirs · 2017-07-10T09:02:27Z

README.md

+
+All templates must be YAML formatted. You can also use ERB. The following local variables will be available to your ERB templates by default:
+
+* `current_sha`: The value of `ENV['REVISION']`


Let's stick with $REVISION that's used above

kirs · 2017-07-10T09:04:27Z

README.md

+*Options:*
+
+- `--bindings=BINDINGS`: Makes additional variables available to your ERB templates. For example, `kubernetes-deploy my-app cluster1 --bindings=color=blue,size=large` will expose `color` and `size`.
+- `--verbose-log-prefix`: Prefixes each log line with `[#{context}][#{namespace}][#{severity}][#{datetime}]` instead of just `[#{severity}][#{datetime}]`. Useful if you're running multiple concurrent deploys in Shipit.


Maybe in the future we refer to kubernetes-deploy --help as the full source of documentation of extra flags, instead of the README

(because IMO things like --verbose-log-prefix are not going to be used frequently enough to highlight in the README)

This is a good idea.

wfarr · 2017-07-10T13:59:06Z

cc @alindeman, who I've spoken to about this project before, and can provide some truly fresh 👀 from outside Shopify on the documentation

KnVerey · 2017-07-11T04:52:22Z

I'm going to merge this now. I'll make a follow-up that adds a gif, improves --help and removes the more obscure option descriptions from the readme. I can address any further feedback in that one.

Improve readme

36d916c

kirs reviewed Jul 7, 2017

View reviewed changes

kirs reviewed Jul 10, 2017

View reviewed changes

kirs approved these changes Jul 10, 2017

View reviewed changes

Incorporate feedback

80e24e0

KnVerey force-pushed the improve_readme branch from 6c553dd to 80e24e0 Compare July 11, 2017 04:48

KnVerey merged commit 018711d into master Jul 11, 2017

KnVerey deleted the improve_readme branch July 11, 2017 04:52

KnVerey mentioned this pull request Jul 11, 2017

Improve help and add GIF to readme #121

Merged

n1koo had a problem deploying to rubygems July 11, 2017 14:16 Failure

n1koo deployed to rubygems July 11, 2017 14:47 Active

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve readme #120

Improve readme #120

KnVerey commented Jul 7, 2017

kirs left a comment

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

KnVerey Jul 7, 2017

kirs Jul 7, 2017

kirs Jul 7, 2017

KnVerey Jul 7, 2017

kirs Jul 7, 2017

KnVerey commented Jul 7, 2017

dalehamel commented Jul 7, 2017

KnVerey commented Jul 7, 2017

dalehamel commented Jul 7, 2017

kirs Jul 10, 2017

kirs left a comment

kirs Jul 10, 2017

kirs Jul 10, 2017 •

edited

Loading

kirs Jul 10, 2017

ibawt Jul 10, 2017

wfarr commented Jul 10, 2017

KnVerey commented Jul 11, 2017


		:closed_lock_with_key: [Creates Kubernetes secrets from encrypted EJSON](#deploying-kubernetes-secrets-from-ejson), which you can safely commit to your repository

		:running: [Runs tasks at the beginning of the deploy](#deploy-time-tasks) using pods (example use case: Rails migrations)


		## Highlights

		:eyes: Watches the changes you requested to make sure they complete successfully.


		[![Build status](https://badge.buildkite.com/0f2d4956d49fbc795f9c17b0a741a6aa9ea532738e5f872ac8.svg?branch=master)](https://buildkite.com/shopify/kubernetes-deploy-gem)
		`kubernetes-deploy` is a command line tool that helps you ship changes to a Kubernetes namespace and understand the result. At Shopify, we use it within our much-beloved, open-source [Shipit](https://github.com/Shopify/shipit-engine#kubernetes) deployment app.


		:eyes: Watches the changes you requested to make sure they complete successfully.

		:interrobang: Provides debug information for changes that failed.


		## Installation
		Especially in a CI/CD environment, we need a clear, actionable pass/fail result for each deploy. Providing this was the foundational goal of `kubernetes-deploy`, which has grown to support the following core features:


		All templates must be YAML formatted. You can also use ERB. The following local variables will be available to your ERB templates by default:

		* `current_sha`: The value of `ENV['REVISION']`

Improve readme #120

Improve readme #120

Conversation

KnVerey commented Jul 7, 2017

kirs 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

Choose a reason for hiding this comment

KnVerey commented Jul 7, 2017

dalehamel commented Jul 7, 2017

KnVerey commented Jul 7, 2017

dalehamel commented Jul 7, 2017

Choose a reason for hiding this comment

kirs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kirs Jul 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wfarr commented Jul 10, 2017

KnVerey commented Jul 11, 2017

kirs Jul 10, 2017 •

edited

Loading