Change:
<ins> # Availability This document collects advice on reasoning about and provisioning for high-availability when using Kubernetes clusters. ## Failure modes This is an incomplete list of things that could go wrong, and how to deal with them. Root causes: - VM(s) shutdown - network partition within cluster, or between cluster and users. - crashes in Kubernetes software - data loss or unavailability of persistent storage (e.g. GCE PD or AWS EBS volume). - operator error misconfigures kubernetes software or application software. Specific scenarios: - Apiserver VM shutdown or apiserver crashing - Results - unable to stop, update, or start new pods, services, replication controller - existing pods and services should continue to work normally, unless they depend on the Kubernetes API - Apiserver backing storage lost - Results - apiserver should fail to come up. - kubelets will not be able to reach it but will continute to run the same pods and provide the same service proxying. - manual recovery or recreation of apiserver state necessary before apiserver is restarted. - Supporting services (node controller, replication controller manager, scheduler, etc) VM shutdown or crashes - currently those are colocated with the apiserver, and their unavailability has similar consequences as apiserver - in future, these will be replicated as well and may not be co-located - they do not have own persistent state - Node (thing that runs kubelet and kube-proxy and pods) shutdown - Results - pods on that Node stop running - Kubelet software fault - Results - crashing kubelet cannot start new pods on the node - kubelet might delete the pods or not - node marked unhealthy - replication controllers start new pods elsewhere - Cluster operator error - Results: - loss of pods, services, etc - lost of apiserver backing store - users unable to read API - etc Mitigations: - Action: Use IaaS providers automatic VM restarting feature for IaaS VMs. - Mitigates: Apiserver VM shutdown or apiserver crashing - Mitigates: Supporting services VM shutdown or crashes - Action use IaaS providers reliable storage (e.g GCE PD or AWS EBS volume) for VMs with apiserver+etcd. - Mitigates: Apiserver backing storage lost - Action: Use Replicated APIserver feature (when complete: feature is planned but not implemented) - Mitigates: Apiserver VM shutdown or apiserver crashing - Will tolerate one or more similtaneous apiserver failures. - Mitigates: Apiserver backing storage lost - Each apiserver has independent storage.  Etcd will recover from loss of one member.  Risk of total data loss greatly reduced. - Action: Snapshot apiserver PDs/EBS-volumes periodically - Mitigates: Apiserver backing storage lost - Mitigates: Some cases of operator error - Mitigates: Some cases of kubernetes software fault - Action: use replication controller and services in front of pods - Mitigates: Node shutdown - Mitigates: Kubelet software fault - Action: applications (containers) designed to tolerate unexpected restarts - Mitigates: Node shutdown - Mitigates: Kubelet software fault - Action: Multiple independent clusters (and avoid making risky changes to all clusters at once) - Mitigates: Everything listed above. ## Chosing Multiple Kubernetes Clusters You may want to set up multiple kubernetes clusters, both to have clusters in different regions to be nearer to your users; and to tolerate failures and/or invasive maintenance. ### Scope of a single cluster On IaaS providers such as Google Compute Engine or Amazon Web Services, a VM exists in a [zone](https://cloud.google.com/compute/docs/zones) or [availability zone](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). We suggest that all the VMs in a Kubernetes cluster should be in the same availability zone, because: - compared to having a single global Kubernetes cluster, there are fewer single-points of failure - compared to a cluster that spans availability zones, it is easier to reason about the availability properties of a single-zone cluster. - when the Kubernetes developers are designing the system (e.g. making assumptions about latency, bandwidth, or correlated failures) they are assuming all the machines are in a single data center, or otherwise closely connected. It is okay to have multiple clusters per availability zone, though on balance we think fewer is better. Reasons to prefer fewer clusters are: - improved bin packing of Pods in some cases with more nodes in one cluster. - reduced operational overhead (though the advantage is diminished as ops tooling and processes matures). - reduced costs for per-cluster fixed resource costs, e.g. apiserver VMs (but small as a percentage of overall cluster cost for medium to large clusters). Reasons to have multiple clusters include: - strict security policies requiring isolation of one class of work from another (but, see Partitioning Clusters below). - test clusters to canary new Kubernetes releases or other cluster software. ### Selecting the right number of clusters The selection of the number of kubernetes clusters may be a relatively static choice, only revisted occasionally. By contrast, the number of nodes in a cluster and the number of pods in a service may be change frequently according to load and growth. To pick the number of clusters, first, decide which regions you need to be in to have adequete latency to all your end users, for services that will run on Kubernetes (if you use a Content Distribution Network, the latency requirements for the CDN-hosted content need not be considered).  Legal issues might influence this as well. For example, a company with a global customer base might decide to have clusters in US, EU, AP, and SA regions. Call the number of regions to be in `R`. Second, decide how many clusters should be able to be unavailable at the same time, while still being available.  Call the number that can be unavailable `U`.  If you are not sure, then 1 is a fine choice. If it is allowable for load-balancing to direct traffic to any region in the event of a cluster failure, then then you need `R + U` clusters.  If it is not (e.g you want to ensure low latency for all users in the event of a cluster failure), then you need to have `R * U` clusters (`U` in each of `R` regions).  In any case, try to put each cluster in a different zone. Finally, if any of your clusters would need more than the maximum recommended number of nodes for a Kubernetes cluster, then you may need even more clusters.  Our roadmap ( https://github.com/GoogleCloudPlatform/kubernetes/blob/24e59de06e4da61f5dafd4cd84c9340a2c0d112f/docs/roadmap.md) calls for maximum 100 node clusters at v1.0 and maximum 1000 node clusters in the middle of 2015. ## Working with multiple clusters When you have multiple clusters, you would typically create services with the same config in each cluster and put each of those service instances behind a load balancer (AWS Elastic Load Balancer, GCE Forwarding Rule or HTTP Load Balancer), so that failures of a single cluster are not visible to end users. </ins>

Discussion:
<!-- STOP -- PLEASE READ! GitHub is not the right place for support requests. If you're looking for help, check and the . You can also post your question on the or the forum. If the matter is security related, please disclose it privately via --Issue: Many e2e are using optional condition fields such as Reason or Message to verify whether pod is failed or reached to the expected state having known expected reason and message. These are valid scenarios but we can not promote such e2e to Conformance as these Reasons and Messages may change over a period of time. This is observed mostly if we are expecting Pods/Jobs to get failed due to certain expected reason and message but failure may have tons of other reasons. References: 1) 2) 3) 4) 5) 6) [Conformance e2e] 7) [Conformance e2e] ........ So how such situations can be taken care while writing e2e? verifying status and message against non-empty field would resolve this issue but there would not be preciseness of e2e behavior._
/area conformance
What if we emphasize on using core libraries const for such reasons and messages, would it be fine? e.g.
No
/assign
Guidance on enum-like fields: Status fields: Old event guidance: Event guide: Events and contents of condition reasons and messages are not covered by API compatibility guarantees. They are passed through for human consumption, not machine consumption. Operational behaviors may be tuned by parameters, , or removed and not be considered breaking changes. For instance, when CrashLoopBackoff and ImagePullBackoff were introduced, they were new reasons not previously reported. Clients erroneously dependent on the previously reported reasons would no longer work. Similarly, when we change events to conform to the new style guide, their message text will change. Events may be aggressively garbage collected or even completely disabled in order to reduce apiserver load, and watching events is discouraged. We run old e2e tests against newer releases of Kubernetes. When those tests have been dependent on specific reasons, messages, and events, they have broken in the past. When contributors are encouraged to patch old e2e tests in order to pass version-skew testing, that should be a red flag that we are breaking backward compatibility.

We really need a policy that does not require significant technical analysis on a test-by-test basis. Tests that are dependent on such text may also indicate API deficiencies, or the tests may simply be testing what the code currently does rather than the API contract, and should be unit tests instead. I'll comment with case by case analysis in a bit.
is overly specific and shouldn't be checking the message. is overly specific and shouldn't be checking the reason. shouldn't be checking for events, or lack thereof. . 't be checking an event, and cluster autoscaling shouldn't be covered by conformance, anyway. 't be checking condition reason or message, or number of conditions. This is testing the implementation, not the required behavior. . As written, none of those tests are acceptable e2e tests, much less conformance tests.
I'm going to PR the main doc with a distillation of this and close this issue.
Note that this seems to be partly due to an organically evolved pattern to leave broken pods on nodes in order to work around bad controller behavior: