My apologies if this question sounds obvious, but the Kubernetes and Google cloud documentation is extremely confusing and contradictory in places.
Anyway, I have pushed a Dockerized web-server to my private Google Container Registry. I want this container to be restarted if it dies, but I only need one single instance to be running at any given moment. Moreover, there's a bunch of environment variables that need to be defined for the server to be correctly configured.
I have already created a new cluster. But where do I go from here? Some tutorials say one should declare pod and service files, but then the next tutorial says one shouldn't declare pods directly but use deployments instead. The result is that I'm terribly confused.
What's the best approach for this simple use case? Also, what is the recommended documentation for using Kubernetes in Google Cloud? (Google's official docs seem out of date.)
Based on your description, I would suggest you use a Deployment with replicas set to 1. The Deployment will ensure that there is always one instance of your pod running. You can define your environment variables in the pod template spec of your Deployment manifest.
In the documentation, you might also see suggestions to use replication controllers for the same purpose. This is definitely an option but Deployments are considered the successor to replication controllers and are usually recommended at this point.
A bare pod is not intended to be durable and will not be restarted in the case of a node failure or other type of eviction.
The documentation is out-of-date in many places but, as far as I know, the authoritative location (even for GKE) is http://kubernetes.io/docs/.
@ryan 's answer is totally clear.
To have a pod that is durable, one must create it using Deployments.
A Deployment is generally preferable because it defines a ReplicaSet to ensure that the desired number of Pods is always available and specifies a strategy to replace Pods, in your case, it is one.
If you create a pod directly without Deployment, you will have to create and manage the pods manually.
Objects of kind Pod will not be rescheduled (or self-healed) in the event of a node failure or pod termination.
You can use replica set instead, but it is less flexible than the Deployment.