{"action":"closed","issue":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/7257","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/7257/labels{/name}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/7257/comments","events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/7257/events","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/issues/7257","id":70521377,"number":7257,"title":"Document best practices for Kubernetes users","user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/area/usability","name":"area/usability","color":"bfe5bf"},{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/kind/documentation","name":"kind/documentation","color":"c7def8"},{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/priority/P2","name":"priority/P2","color":"fbca04"},{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/team/UX","name":"team/UX","color":"d2b48c"}],"state":"closed","locked":false,"assignee":{"login":"mikedanese","id":1787169,"avatar_url":"https://avatars.githubusercontent.com/u/1787169?v=3","gravatar_id":"","url":"https://api.github.com/users/mikedanese","html_url":"https://github.com/mikedanese","followers_url":"https://api.github.com/users/mikedanese/followers","following_url":"https://api.github.com/users/mikedanese/following{/other_user}","gists_url":"https://api.github.com/users/mikedanese/gists{/gist_id}","starred_url":"https://api.github.com/users/mikedanese/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mikedanese/subscriptions","organizations_url":"https://api.github.com/users/mikedanese/orgs","repos_url":"https://api.github.com/users/mikedanese/repos","events_url":"https://api.github.com/users/mikedanese/events{/privacy}","received_events_url":"https://api.github.com/users/mikedanese/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/milestones/6","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/milestones/v1.0","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/milestones/6/labels","id":969317,"number":6,"title":"v1.0","description":"Issues that need to be resolved for v1.0 of Kubernetes.","creator":{"login":"goltermann","id":9358478,"avatar_url":"https://avatars.githubusercontent.com/u/9358478?v=3","gravatar_id":"","url":"https://api.github.com/users/goltermann","html_url":"https://github.com/goltermann","followers_url":"https://api.github.com/users/goltermann/followers","following_url":"https://api.github.com/users/goltermann/following{/other_user}","gists_url":"https://api.github.com/users/goltermann/gists{/gist_id}","starred_url":"https://api.github.com/users/goltermann/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/goltermann/subscriptions","organizations_url":"https://api.github.com/users/goltermann/orgs","repos_url":"https://api.github.com/users/goltermann/repos","events_url":"https://api.github.com/users/goltermann/events{/privacy}","received_events_url":"https://api.github.com/users/goltermann/received_events","type":"User","site_admin":false},"open_issues":45,"closed_issues":763,"state":"open","created_at":"2015-02-06T20:27:16Z","updated_at":"2015-07-17T22:23:05Z","due_on":null,"closed_at":null},"comments":10,"created_at":"2015-04-23T21:45:11Z","updated_at":"2015-07-17T22:23:05Z","closed_at":"2015-07-17T22:23:05Z","body":"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.\r\n\r\nOff the top of my head:\r\n* Use the latest stable API version (currently v1)\r\n* Use YAML rather than JSON (more user friendly for config)\r\n* 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.\r\n* Create service before corresponding replication controllers so that the scheduler can spread the pods comprising the service. #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)\r\n* Use `kubectl create -f <directory>` where possible. Another little-known feature.\r\n* 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.\r\n* 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.\r\n* 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.\r\n* Service should use a subset of the labels used by the replication controllers whose pods it targets. #8524\r\n* Use kubectl run and expose where appropriate, at least presented as an alternative\r\n* Use headless services where appropriate\r\n* Use kubectl bulk operations (via files and/or labels) for get and delete\r\n* Use kubectl delete rather than stop\r\n* No naked pods, except for RestartNever scenarios. (A minimal Job is coming. #1624)\r\n* Use Deployment (#1743) for RestartAlways services rather than RC directly, when we have that.\r\n* 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](https://github.com/GoogleCloudPlatform/kubernetes/blob/072137764665182394975e1e1459ade58ee25719/pkg/kubectl/rolling_updater.go#L112)\r\n* Put object description in an annotation\r\n\r\ncc @smarterclayton @thockin "}}