What is the difference between a pod and a deployment?

I have been creating pods with type:deployment but I see that some documentation uses type:pod, more specifically the documentation for multi-container pods:

apiVersion: v1
kind: Pod
metadata:
  name: ""
  labels:
    name: ""
  namespace: ""
  annotations: []
  generateName: ""
spec:
  ? "// See 'The spec schema' for details."
  : ~

But to create pods I can just use a deployment type:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: ""
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: ""
    spec:
      containers:
        etc

I noticed the pod documentation says:

The create command can be used to create a pod directly, or it can create a pod or pods through a Deployment. It is highly recommended that you use a Deployment to create your pods. It watches for failed pods and will start up new pods as required to maintain the specified number. If you don’t want a Deployment to monitor your pod (e.g. your pod is writing non-persistent data which won’t survive a restart, or your pod is intended to be very short-lived), you can create a pod directly with the create command.

Note: We recommend using a Deployment to create pods. You should use the instructions below only if you don’t want to create a Deployment.

But this raises the question of what kind:pod is good for? Can you somehow reference pods in a deployment? I didn't see a way. It looks like what you get with pods is some extra metadata but none of the deployment options such as replica or a restart policy. What good is a pod that doesn't persist data, survives a restart? I think I'd be able to create a multi-container pod with a deployment as well.

Radek's answer is very good, but I would like to pitch in from my experience, you will almost never use an object with the kind pod, because that doesn't make any sense in practice.

Because you need a deployment object - or other Kubernetes API objects like a replication controller or replicaset - that needs to keep the replicas (pods) alive (that's kind of the point of using kubernetes).

What you will use in practice for a typical application are:

1. Deployment object (where you will specify your apps container/containers) that will host your app's container with some other specifications.

2. Service object (that is like a grouping object and gives it a so-called virtual IP (cluster IP) for the pods that have a certain label - and those pods are basically the app containers that you deployed with the former deployment object).

You need to have the service object because the pods from the deployment object can be killed, scaled up and down, and you can't rely on their IP addresses because they will not be persistent.

So you need an object like a service, that gives those pods a stable IP.

Just wanted to give you some context around pods, so you know how things work together.

Hope that clears a few things for you, not long ago I was in your shoes :)

Both Pod and Deployment are full-fledged objects in the Kubernetes API. Deployment manages creating Pods by means of ReplicaSets. What it boils down to is that Deployment will create Pods with spec taken from the template. It is rather unlikely that you will ever need to create Pods directly for a production use-case.

Kubernetes has three Object Types you should know about:

• Pods - runs one or more closely related containers
• Services - sets up networking in a Kubernetes cluster
• Deployment - Maintains a set of identical pods, ensuring that they have the correct config and that the right number of them exist.

Pods:

• Runs a single set of containers
• Good for one-off dev purposes
• Rarely used directly in production

Deployment:

• Runs a set of identical pods
• Monitors the state of each pod, updating as necessary
• Good for dev
• Good for production

And I would agree with other answers, forget about Pods and just use Deployment. Why? Look at the second bullet point, it monitors the state of each pod, updating as necessary.

So, instead of struggling with error messages such as this one:

Forbidden: pod updates may not change fields other than spec.containers[*].image

So just refactor or completely recreate your Pod into a Deployment that creates a pod to do what you need done. With Deployment you can change any piece of configuration you want to and you need not worry about seeing that error message.