I'm really liking Kubernetes — we're in the process of migrating to it.<p>If there's on area that is in dire need of improvement, though, it's the documentation. If you look around, there is essentially <i>no</i> documentation that starts from first principles, going through the different components (and their lifecycle, dependencies, requirements and so on) one by one, irrrespectively of the cloud environment. There is a "Kubernetes from scratch" [1] document, but it's just a bunch of loose fragments that lacks almost all the necessary detail, and has too many dependencies. (Tip: ask the user to install from source, and leave out how to use images, cloud providers and other things that obscure the workings of everything.)<p>Almost all of the documentation assumes you're running kube-up or some other automated setup, which is of course convention, but hides a huge amount of magic in a bunch of shell scripts, Salt config and so on that prevents true understanding. If you run it for, say, AWS, then you'll end up with a configuration that <i>you don't understand</i>. It doesn't help that much of the official documentation is heavily skewed towards GCE/GKE, where certain things have a level of automatic magic that you won't benefit from when you run on bare metal, for example. kube-up will help someone get it up and running fast, but does <i>not</i> help someone who needs to maintain it in a careful, controller manner.<p>Right now, I have a working cluster, but getting there involved a bunch of trial and error, a <i>lot</i> of open browser tabs, source code reading, and so on. (Quick, what version of Docker does Kubernetes want? Kubernetes doesn't seem to tell us, and it doesn't even verify it on startup. One of the reefs that I ran aground on was when 1.11 didn't work, and had to revert to 1.9, based on a random Github issue I found.)<p>[1] <a href="http://kubernetes.io/docs/getting-started-guides/scratch/" rel="nofollow">http://kubernetes.io/docs/getting-started-guides/scratch/</a>