Document best practices for Kubernetes users

[bgrant0607]

We should document best practices for using Kubernetes, especially within the context of creating new examples (#4926), so that reviewers can check for the issues. This is a successor to #1603.

Off the top of my head:

• Use the latest stable API version (currently v1)
• Use YAML rather than JSON (more user friendly for config)
• Group related objects together in a single file. This currently requires a List object in YAML, but it's still better than separate files. Almost nobody knows about this feature.
• Create service before corresponding replication controllers so that the scheduler can spread the pods comprising the service. Update examples to create service before RC (so that spreading works) #11144 (or, create the RC without specifying replicas, create the service, then scale up the RC, which may work better in an example using progressive disclosure and may have benefits in real scenarios also, such as ensuring one replica works before creating lots of them)
• Use kubectl create -f <directory> where possible. Another little-known feature.
• Don't use hostPort unless absolutely necessary (e.g., for a node daemon). Use the apiserver proxying or port forwarding for debug/admin access, or a service for external service access. Though Remove HostPort from most examples #1487 was closed, hostPort is still in several examples.
• Don't specify default values unnecessarily. Now that we default the selector and labels in RC, it should get slimmer. Eventually we'll need a user's guide that can cover more advanced topics, but we want examples to look simple, in general.
• We should establish a convention other than "name" for label keys. (Different names and port numbers #3394) Probably some combination of "app", "component", ... I put some examples in labels.md.
• Service should use a subset of the labels used by the replication controllers whose pods it targets. Should provide better information on how to select multiple labels #8524
• Use kubectl run and expose where appropriate, at least presented as an alternative
• Use headless services where appropriate
• Use kubectl bulk operations (via files and/or labels) for get and delete
• Use kubectl delete rather than stop
• No naked pods, except for RestartNever scenarios. (A minimal Job is coming. Job Controller #1624)
• Use Deployment (Deployment resource (was Evaluate adoption of OpenShift template configs and/or deployments) #1743) for RestartAlways services rather than RC directly, when we have that.
• In the meantime, put a version number or hash as a suffix to the name and in a label on a ReplicationController, to facilitate rolling update, as we do for --image
• Put object description in an annotation

cc @smarterclayton @thockin

[erictune]

Step 1: put above text into examples/README.md

[bgrant0607]

@erictune Yes, that's my plan. Plan to create a PR when I get a chance.

[smarterclayton]

On Apr 23, 2015, at 5:45 PM, Brian Grant notifications@github.com wrote:

We should document best practices for using Kubernetes, especially within the context of creating new examples (#4926), so that reviewers can check for the issues. This is a successor to #1603.

Off the top of my head:

Use the latest stable API version (currently v1beta3)
Use YAML rather than JSON (more user friendly for config)
Group related objects together in a single file. This currently requires a List object in YAML, but it's still better than separate files. Almost nobody knows about this feature.
Add comments directly inline with JSON about important points in that single file. We actually support multi-object json AND yaml (doesn't have to be on a list) from kubect -f
Use kubectl create -f where possible. Another little-known feature.
Don't use hostPort unless absolutely necessary (e.g., for a node daemon). Use the apiserver proxying or port forwarding for debug/admin access, or a service for external service access. Though #1487 was closed, hostPort is still in several examples.
Don't specify default values unnecessarily. Now that we default the selector and labels in RC, it should get slimmer. Eventually we'll need a user's guide that can cover more advanced topics, but we want examples to look simple, in general.
We should establish a convention other than "name" for label keys. (#3394) Probably some combination of "app", "component", ... I put some examples in labels.md.
Use kubectl run-container where appropriate, at least presented as an alternative
Use headless services where appropriate
Use kubectl bulk operations (via files and/or labels) for get and delete
Use kubectl delete rather than stop (once we change its default behavior)
No naked pods, except for RestartNever scenarios. (A minimal Job is coming soon. #1624)
Use Deployment (#1743) for RestartAlways services rather than RC directly, when we have that.
cc @smarterclayton @thockin

—
Reply to this email directly or view it on GitHub.

[bgrant0607]

@smarterclayton How would one put comments into JSON?

Yes, -f supports multiple objects without List -- that's the next bullet. YAML requires List for multiple objects in the same file, because the yaml-to-json converter doesn't yet support the document separator (---).

[smarterclayton]

On Apr 23, 2015, at 7:01 PM, Brian Grant notifications@github.com wrote:

@smarterclayton How would one put comments into JSON?

In YAML, typo
Yes, -f supports multiple objects without List -- that's the next bullet. YAML requires List for multiple objects in the same file, because the yaml-to-json converter doesn't yet support the document separator (---).

We do support the stream separator in STDIN pipes and URLs today. Would not be hard to add that to Paths (I thought it was)
—
Reply to this email directly or view it on GitHub.

[bgrant0607]

See #5840.

[bgrant0607]

cc @kelseyhightower for his input on best practices for using K8s

[kelseyhightower]

@bgrant0607 Just getting around to reviewing this.

[bgrant0607]

I wove many/most of these practices into the new user-guide content. A bullet list of guidelines in docs/examples would be useful, as well.

[mikedanese]

Creating this comment for personal notekeeping.

We should establish a convention other than "name" for label keys. (#3394) Probably some combination of "app", "component", ... I put some examples in labels.md.

Has convention been established for this yet?