From 7aa9ce389ae3a2abf6838aa04059fe81133e1577 Mon Sep 17 00:00:00 2001
From: Janet Kuo <chiachenk@google.com>
Date: Fri, 13 May 2016 18:04:40 -0700
Subject: [PATCH] Adding kubectl user conventions

---
 _data/reference.yml                    |  2 ++
 docs/user-guide/kubectl-conventions.md | 30 ++++++++++++++++++++++++++
 docs/user-guide/kubectl-overview.md    |  2 +-
 3 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 docs/user-guide/kubectl-conventions.md

diff --git a/_data/reference.yml b/_data/reference.yml
index 8c51c319ec..371a17655d 100644
--- a/_data/reference.yml
+++ b/_data/reference.yml
@@ -52,6 +52,8 @@ toc:
     path: /docs/user-guide/kubectl-overview/
   - title: kubectl for Docker Users
     path: /docs/user-guide/docker-cli-to-kubectl/
+  - title: kubectl Usage Conventions
+    path: /docs/user-guide/kubectl-conventions/
   - title: JSONpath Support
     path: /docs/user-guide/jsonpath/
   - title: kubectl Cheat Sheet
diff --git a/docs/user-guide/kubectl-conventions.md b/docs/user-guide/kubectl-conventions.md
new file mode 100644
index 0000000000..6273c750e7
--- /dev/null
+++ b/docs/user-guide/kubectl-conventions.md
@@ -0,0 +1,30 @@
+---
+---
+
+* TOC
+{:toc}
+
+## Using `kubectl` in Reusable Scripts 
+
+If you need stable output in a script, you should:
+
+* Request one of the machine-oriented output forms, such as `-o name`, `-o json`, `-o yaml`, `-o go-template`, or `-o jsonpath` 
+* Specify `--output-version`, since those output forms (other than `-o name`) output the resource using a particular API version
+* Specify `--generator` to pin to a specific behavior forever, if using generator-based commands (such as `kubectl run` or `kubectl expose`)
+* Don't rely on context, preferences, or other implicit state
+
+## Best Practices
+
+### `kubectl run`
+
+In order for `kubectl run` to satisfy infrastructure as code:
+
+* Always tag your image with a version-specific tag and don't move that tag to a new version. For example, use `:v1234`, `v1.2.3`, `r03062016-1-4`, rather than `:latest` (see [Best Practices for Configuration](/docs/user-guide/config-best-practices/#container-images) for more information.)
+* If the image is lightly parameterized, capture the parameters in a checked-in script, or at least use `--record`, to annotate the created objects with the command line.
+* If the image is heavily parameterized, definitely check in the script.
+* If features are needed that are not expressible via `kubectl run` flags, switch to configuration files checked into source control.
+* Pin to a specific generator version, such as `kubectl run --generator=deployment/v1beta1`
+
+### `kubectl apply`
+
+* To use `kubectl apply` to update resources, always create resources initially with `kubectl apply` or with `--save-config`. See [managing resources with kubectl apply](/docs/user-guide/managing-deployments/#kubectl-apply) for the reason behind it. 
diff --git a/docs/user-guide/kubectl-overview.md b/docs/user-guide/kubectl-overview.md
index 5b85ba6e00..5d75ad691b 100644
--- a/docs/user-guide/kubectl-overview.md
+++ b/docs/user-guide/kubectl-overview.md
@@ -269,4 +269,4 @@ $ kubectl logs -f <pod-name>
 
 ## Next steps
 
-Start using the [kubectl](/docs/user-guide/kubectl/kubectl) commands.
\ No newline at end of file
+Start using the [kubectl](/docs/user-guide/kubectl/kubectl) commands.