Kubectl Book Final Edits

docs/book/CONTRIBUTING.md

@@ -1,23 +1,39 @@
 # Contributing
 
-## Running Locally
+## Process
+
+### Fixing Issues
+
+1. Open an Issue
+1. Create a PR
+1. Email PR to sig-cli@googlegroups.com with subject `Kubectl Book: Fix Issue <Issue> in <PR>`
+1. Optional: Come to sig-cli meeting to discuss
+
+### Adding New Content
+
+1. Open an Issue with proposed content
+1. Email sig-cli@googlegroups.com with subject `Kubectl Book: Proposed Content <Issue>`
+1. Optional: Come to sig-cli meeting to discuss
+
+## Editing
+
+### Running Locally
 
 - Install [GitBook Toolchain](https://toolchain.gitbook.com/setup.html)
-- From `docs/book` run `npm ci`  to install node_modules locally (don't run install, it updates the shrinkwrap.json)
-- From `docs/book` run `npm audit` to make sure there are no vulnerabilities
+- From `docs/book` run `npm install`  to install node_modules locally (don't run install, it updates the shrinkwrap.json)
 - From `docs/book` run `gitbook serve`
 - Go to `http://localhost:4000` in a browser
 
-## Adding a Section
+### Adding a Section
 
 - Update `SUMMARY.md` with a new section formatted as `## Section Name`
 
-## Adding a Chapter
+### Adding a Chapter
 
 - Update `SUMMARY.md` under section with chapter formatted as `* [Name of Chapter](pages/section_chapter.md)`
 - Add file `pages/section_chapter.md`
 
-## Adding Examples to a Chapter
+### Adding Examples to a Chapter
 
 ```bash
 {% method %}
@@ -27,7 +43,7 @@ Formatted code
 {% endmethod %}
 ```
 
-## Adding Notes to a Chapter
+### Adding Notes to a Chapter
 
 ```bash
 {% panel style="info", title="Title of Note" %}
@@ -42,20 +58,15 @@ Notes may have the following styles:
 - warning
 - danger
 
-## Building and Publishing a release
+### Building and Publishing a release
 
 - Run `gitbook build`
-- Push fies in `_book` to a server (e.g. `firebase deploy`)
+- Push fies in `_book` to a server
 
-## Adding GitBook plugins
+### Adding GitBook plugins
 
 - Update `book.json` with the plugin
-- Run `npm i <npm-plugin-name>`
-- Run `npm strinkwrap`
-- Run `npm audit` - fix issues by hand updating `npm-shrinkwrap.json` libraries with the fixed versions
-- Run `npm ci` - install the new version
-- Run `npm audit` - verify the fixes
-- Commit `npm-shrinkwrap.json` and `package.json`
+- Run `npm install <npm-plugin-name>`
 
 ### Cool plugins
 

docs/book/README.md

@@ -5,6 +5,13 @@
 - Kubectl may be used for scripting and building higher-level frameworks
 {% endpanel %}
 
+{% panel style="success", title="Feedback and Contributing" %}
+**Provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)**
+
+See [CONTRIBUTING](https://github.com/kubernetes/kubectl/blob/master/docs/book/CONTRIBUTING.md) for
+instructions on filing/fixing issues and adding new content.
+{% endpanel %}
+
 # Kubectl
 
 Kubectl is the Kubernetes cli version of a swiss army knife, and can do many things.

docs/book/SUMMARY.md

@@ -47,7 +47,7 @@
 * [Directory Layout](pages/app_composition_and_deployment/structure_directories.md)
 * [Branches Layout](pages/app_composition_and_deployment/structure_branches.md)
 * [Repository Layout](pages/app_composition_and_deployment/structure_repositories.md)
-* [Multi-Tier Layout](pages/app_composition_and_deployment/structure_multi_tier_apps.md)
+* [Shared Base Layout](pages/app_composition_and_deployment/structure_multi_tier_apps.md)
 
 ## App Deployment
 

docs/book/pages/app_composition_and_deployment/publishing_bases.md

@@ -1,5 +1,10 @@
 {% panel style="warning", title="Experimental" %}
-This chapter contains some recommendations that are actively being explored, and may evolve.
+**Content in this chapter is experimental and will evolve based on user feedback.**
+
+Leave feedback on the conventions by creating an issue in the [kubectl](https://github.com/kubernetes/kubectl/issues)
+GitHub repository.
+
+Also provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)
 {% endpanel %}
 
 {% panel style="info", title="TL;DR" %}

docs/book/pages/app_composition_and_deployment/structure_branches.md

@@ -1,7 +1,11 @@
-{% panel style="warning", title="Experimental Conventions" %}
-Conventions in this chapter may evolve.
-{% endpanel %}
+{% panel style="warning", title="Experimental" %}
+**Content in this chapter is experimental and will evolve based on user feedback.**
 
+Leave feedback on the conventions by creating an issue in the [kubectl](https://github.com/kubernetes/kubectl/issues)
+GitHub repository.
+
+Also provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)
+{% endpanel %}
 
 {% panel style="info", title="TL;DR" %}
 Decouple changes to Config to be deployed to separate Environments.
@@ -27,21 +31,22 @@ Use with techniques described in [Directories](structure_directories.md) and [Br
 
 ## Workflow Example
 
-Summary of workflow with Branches:
+### Diagram
+
+#### Scenario
 
 1. Live Prod App version is *v1*
-1. Changes are introduced to Base Branch Config
-  - To be release with version *v2*
-1. Outage requires changes to the Config running in Prod (*v1*)
-1. Prod Branch Config Updated (*v1*)
+1. *v2* changes committed to Base Branch Config
+1. *v2* rolled out to Staging
+  - Deployed by continuous deployment
+1. Live Prod App requires change to *v1* (unrelated to *v2*)
+  - Change memory resources in Prod
+1. Prod Branch Config Updated at *v1*
   - Deployed immediately by continuous deployment
-1. *v2* changes are rolled out with the *v2* release
+1. *v2* changes rolled out separately
  - Tag on Base Branch merged into Prod Branch
  - Prod Branch continuously deployed
 
-
-### Diagram
-
 {% sequence width=1000 %}
 
 participant Base Branch as BB
@@ -258,7 +263,7 @@ PB-->PC: Deploy v2
 Note over PC: At v2 release
 Note over BB,PC: Unrelated Prod Outage
 Note left of PB: Alice: App SRE
-Note over PB: Alice rolls back v2 merge
+Note over PB: Alice rolls back v2 merge commit
 PB-->PC: Deploy v1
 Note over PC: At v1 release
 Note over BB,PC: Prod Outage resolved

docs/book/pages/app_composition_and_deployment/structure_directories.md

@@ -1,3 +1,12 @@
+{% panel style="warning", title="Experimental" %}
+**Content in this chapter is experimental and will evolve based on user feedback.**
+
+Leave feedback on the conventions by creating an issue in the [kubectl](https://github.com/kubernetes/kubectl/issues)
+GitHub repository.
+
+Also provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)
+{% endpanel %}
+
 {% panel style="info", title="TL;DR" %}
 - Use **directory hierarchy to structure Resource Config**
   - Separate directories for separate Environment and Cluster [Config Variants](../app_customization/bases_and_variants.md)
@@ -25,6 +34,14 @@ exists in the same Repository as the source code that is being deployed.
 | Env            | **No** - Contains other dirs | Base and Cluster dirs.  | `test/`, `staging/`, `prod/` |
 | Cluster        | **Yes** - Manually or Continuously  | Deployable Config. | `us-west1`, `us-east1`, `us-central1` |
 
+
+### Bases
+
+A Kustomize Base (e.g. `bases:`) provides shared Config that is customized by some consuming `kustomization.yaml`.
+
+The directory structure outlined in this chapter organizes Bases into a hierarchy as:
+`app-bases/environment-bases/cluster`
+ 
 ## Workflow Example
 
 - Changes made to *env/cluster/* roll out to **only that specific env-cluster**
@@ -45,6 +62,15 @@ graph TD;
   T("test/bases/ ")---|base|TUW("test/us-west/ ");
 ```
 
+### Scenario
+
+1. Alice modifies prod/us-west1 with change A
+  - Change gets pushed to prod us-west1 cluster by continuous deployment
+1. Alice modifies prod/bases with change B
+  - Change gets pushed to all prod clusters by continuous deployment
+1. Alice modifies bases with change C
+  - Change gets pushed to all clusters by continuous deployment
+
 {% sequence width=1000 %}
 
 participant Config in Git as B
@@ -162,7 +188,7 @@ B-->SC: B deployed
 B-->WC: B deployed
 Note over B,EC: Prod Outage caused by B
 B-->TC: B deployed
-Note over B: Bob rolls back bases/ to A
+Note over B: Bob rolls back bases/ git commits to A
 B-->WC: A deployed
 B-->TC: A deployed
 B-->EC: A deployed

docs/book/pages/app_composition_and_deployment/structure_multi_tier_apps.md

@@ -1,9 +1,17 @@
+{% panel style="warning", title="Experimental" %}
+**Content in this chapter is experimental and will evolve based on user feedback.**
+
+Leave feedback on the conventions by creating an issue in the [kubectl](https://github.com/kubernetes/kubectl/issues)
+GitHub repository.
+
+Also provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)
+{% endpanel %}
 
 {% panel style="info", title="TL;DR" %}
 - The same Base may be used multiple times for different Applications within the same project.
 {% endpanel %}
 
-# Advanced Composition
+# Composition with Shared Bases
 
 ## Motivation
 
@@ -12,14 +20,14 @@ Users may want to reuse the **same base multiple times within the same Apply Pro
 - Define a very generic base (e.g. "Java Application") used by multiple Applications within a Project.
 - Define multiple Environments (e.g. Staging, Canary, Prod) within a Project.
 
-## 3-Tier Composition
+## Composition With A Shared Base
 
 ```mermaid
 graph TD;
-  B("Generic Base ")---|base|A1("App 1 ");
-  B("Generic Base ")---|base|A2("App 2 ");
-  A1("App 1 ")---|base|C("Composite App ");
-  A2("App 2 ")---|base|C("Composite App ");
+  B("B ")---|base|A1("A1 ");
+  B("B ")---|base|A2("A2 ");
+  A1("A1 ")---|base|C("A ");
+  A2("A2 ")---|base|C("A ");
 ```
 
 

docs/book/pages/app_composition_and_deployment/structure_repositories.md

@@ -1,5 +1,10 @@
-{% panel style="warning", title="Experimental Conventions" %}
-Conventions in this chapter may evolve.
+{% panel style="warning", title="Experimental" %}
+**Content in this chapter is experimental and will evolve based on user feedback.**
+
+Leave feedback on the conventions by creating an issue in the [kubectl](https://github.com/kubernetes/kubectl/issues)
+GitHub repository.
+
+Also provide feedback on new kubectl docs at the [survey](https://www.surveymonkey.com/r/JH35X82)
 {% endpanel %}
 
 
@@ -38,6 +43,13 @@ Use with techniques described in [Directories](structure_directories.md) and [Br
 
 ## Diagram
 
+### Scenario
+
+1. Alice modifies java Base Repo and tags it v2
+  - Change doesn't get pushed anywhere yet
+1. Bob modifies GuestBook App Repo to use v2 of the java Base
+  - Change gets pushed by continuous deployment
+
 {% sequence width=1000 %}
 
 participant Base Repo as BR

docs/book/pages/app_customization/bases_and_variants.md

@@ -18,7 +18,20 @@ Examples:
   but with variants between the environments.
 - a project may be deployed to **different clusters** that are tuned differently or running
   different versions of the project.
-  
+
+## Bases
+
+Bases are shared Resource Config in a `kustomization.yaml` to be used and customized by another `kustomization.yaml`.
+
+Examples of Bases:
+
+- Common Java Base
+  - Used in multiple Apps (e.g. Guest Book, Calendar, Auth)
+- Common Guest Book App Base
+  - Used in multiple Environments (e.g. Test, Staging, Prod)
+- Common Prod Guest Book App Base
+  - Used in multiple clusters (e.g. us-west, us-east, us-canary)
+
 ## Referring to a Base
 
 A project can add a Base by adding a path (relative to the `kustomization.yaml`) to **`base` that

docs/book/pages/kubectl_book/getting_started.md

@@ -68,7 +68,7 @@ Create or Update Kubernetes Resources from Remote Config.
 
 {% sample lang="yaml" %}
 ```bash
-kubectl apply -k https://github.com/kubernetes/kubectl/docs/book/examples/nginx
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/kubectl/master/docs/book/examples/nginx/nginx.yaml
 ```
 
 ```bash
@@ -83,7 +83,7 @@ Create or Update Kubernetes Resources from Local Config.
 
 {% sample lang="yaml" %}
 ```bash
-kubectl apply -k ./examples/nginx
+kubectl apply -f ./examples/nginx/nginx.yaml
 ```
 
 ```bash
@@ -98,7 +98,7 @@ Print the Resources that were Applied.
 
 {% sample lang="yaml" %}
 ```bash
-kubectl get -k ./examples/nginx/ --show-labels
+kubectl get -f ./examples/nginx/nginx.yaml --show-labels
 ```
 
 ```bash