What is the difference between ReplicaSet and ReplicationController?

Replica Set is the next generation of Replication Controller. Replication controller is kinda imperative, but replica sets try to be as declarative as possible.

1.The main difference between a Replica Set and a Replication Controller right now is the selector support.

+--------------------------------------------------+-----------------------------------------------------+
|                   Replica Set                    |               Replication Controller                |
+--------------------------------------------------+-----------------------------------------------------+
| Replica Set supports the new set-based selector. | Replication Controller only supports equality-based |
| This gives more flexibility. for eg:             | selector. for eg:                                   |
|          environment in (production, qa)         |             environment = production                |
|  This selects all resources with key equal to    | This selects all resources with key equal to        |
|  environment and value equal to production or qa | environment and value equal to production           |
+--------------------------------------------------+-----------------------------------------------------+

2.The second thing is the updating the pods.

+-------------------------------------------------------+-----------------------------------------------+
|                      Replica Set                      |            Replication Controller             |
+-------------------------------------------------------+-----------------------------------------------+
| rollout command is used for updating the replica set. | rolling-update command is used for updating   |
| Even though replica set can be used independently,    | the replication controller. This replaces the |
| it is best used along with deployments which          | specified replication controller with a new   |
| makes them declarative.                               | replication controller by updating one pod    |
|                                                       | at a time to use the new PodTemplate.         |
+-------------------------------------------------------+-----------------------------------------------+

These are the two things that differentiates RS and RC. Deployments with RS is widely used as it is more declarative.

For now, the difference should be insignificant in most cases. ReplicaSet has a generalized label selector: https://github.com/kubernetes/kubernetes/issues/341#issuecomment-140809259. It should support all the features the replication controller supports.

Will ReplicaSet eventually replace ReplicationController? Why would I want to use Deployment and ReplicaSet instead of ReplicationController?

This boils down to rolling update vs deployment. Please read docs on deployment to understand the difference: http://kubernetes.io/docs/user-guide/deployments/. In short, if you start a rolling update and close your laptop, your replicas have some mix of intermediate image versions. If you create a deployement and close your laptop, the deployment either gets POSTed successfully to apiserver, in which case it works server side, or it doesn't, in which case all your replicas are still on the old version.

The bad thing is that nearly all current documentation is about ReplicationControllers.

Agreed, most docs are being updated. Unfortunately docs on the internet are harder to update than the ones on github.

The functionality of both Replica Controller and Replica Set is quiet the same - they are responsible to make sure that X number of pods with label that is equal to there label selector will be scheduled to different nodes on the cluster.
(Where X is the value that is specified in the spec.replicas field in the Replica Controller / Replica Set yaml).

ReplicaSet is a replacement for the Replica controller and supports richer expressions for the label selector. You can choose between 4 values of operators In, NotIn, Exists, DoesNotExist - see Set-based requirement.

A rule of thumb: When you see Replica Controller is mentioned in one the docs or other tutorials - refer to it as ReplicaSet AND consider using Deployment instead.

---

There is also a small difference in the syntax between Replica Controller:

apiVersion: v1
kind: ReplicationController
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    app: nginx

And the ReplicaSet which contains matchLabels field under the selector:

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels: #<-- This was added
      tier: nginx