Kubernetes ReplicationController: Basic Commands with Practical Examples

Intro

Kubernetes ReplicationController (RC) ensures a specified number of pod replicas are running at any given time. Although ReplicaSets and Deployments have largely superseded it, ReplicationController remains a foundational concept for understanding pod replication and self-healing. This guide provides practical commands, configuration examples, troubleshooting techniques, and recovery workflows for developers, DevOps engineers, and startup teams who need to operate ReplicationControllers in real clusters.

The goal is operational safety: observe before changing, limit the blast radius, use placeholders instead of secrets, verify results, and document recovery steps if the expected state is not reached. Each section includes concrete commands, expected output, failure signals, and recovery decisions.

Version and Environment Inventory

Before working with ReplicationControllers, verify your cluster version and the API resources available. ReplicationControllers are part of the core/v1 API group and remain supported in all current Kubernetes versions, though they are considered legacy.

Check Cluster and Client Versions

kubectl version --short

Expected output includes client and server versions:

Client Version: v1.26.0
Server Version: v1.26.0

If the server version is older than the client, commands may fail; use a matching kubectl version.

Verify ReplicationController API Availability

kubectl api-resources | grep replicationcontrollers

Expected output:

replicationcontrollers            rc          v1                                      true         ReplicationController

If the resource is not listed, the cluster may have restricted API access. Check RBAC permissions with:

kubectl auth can-i list replicationcontrollers

Expected output: yes.

Confirm Prerequisites

• A running Kubernetes cluster (minikube, kind, GKE, EKS, etc.).
• kubectl installed and configured with cluster access.
• Basic understanding of pods and labels.

Read-only observation: Always start with kubectl get commands to understand the current state before making changes.

Practical Kubernetes Checks

Run these commands to gather initial state:

kubectl get pods -o wide
kubectl get replicationcontrollers
kubectl get nodes

Save outputs with timestamps for later comparison:

kubectl get replicationcontrollers -o yaml > rc-before.yaml
date >> rc-before.yaml

Minimal test: Before applying any change, ensure you can create a simple ReplicationController in a test namespace. Use kubectl port-forward or a local service type to verify traffic before moving to a load balancer or ingress.

Safe Configuration Path

Operating ReplicationControllers safely means making incremental, reversible changes. Follow this path:

Step 1: Inspect Current State

Use read-only commands to see existing ReplicationControllers:

kubectl get replicationcontrollers --all-namespaces

Example output:

NAMESPACE   NAME    DESIRED   CURRENT   READY   AGE
default     nginx   3         3         3       5m

Step 2: Understand the ReplicationController Manifest

A basic ReplicationController YAML:

apiVersion: v1
kind: ReplicationController
metadata:
  name: nginx-rc
spec:
  replicas: 3
  selector:
    app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Key fields:

• spec.replicas: desired number of pods.
• spec.selector: must match labels in the pod template. If omitted, it defaults to the template labels.
• spec.template: pod template used to create new pods.

Step 3: Apply the Manifest with Verification

Create the ReplicationController:

kubectl apply -f nginx-rc.yaml

Expected output:

replicationcontroller/nginx-rc created

Verify pods are created:

kubectl get pods -l app=nginx

Expected output:

NAME              READY   STATUS    RESTARTS   AGE
nginx-rc-abcde    1/1     Running   0          10s
nginx-rc-fghij    1/1     Running   0          10s
nginx-rc-klmno    1/1     Running   0          10s

Step 4: Make Small Changes

To scale the ReplicationController, use the kubectl scale command:

kubectl scale replicationcontroller nginx-rc --replicas=5

Expected output:

replicationcontroller/nginx-rc scaled

Verify the new pods:

kubectl get rc nginx-rc

Output:

NAME       DESIRED   CURRENT   READY   AGE
nginx-rc   5         5         5       10m

Step 5: Verify Traffic Locally

Use port-forward to test one pod:

kubectl port-forward rc/nginx-rc 8080:80

Then access http://localhost:8080 in a browser or with curl. Expect the nginx welcome page.

Blast radius control: Never apply changes directly to production without testing in a sandbox namespace. Use --dry-run=client to validate manifests:

kubectl apply -f nginx-rc.yaml --dry-run=client

Verification and Diagnostics

After applying changes, verify the ReplicationController's health and diagnose issues.

Basic Verification Commands

kubectl get rc nginx-rc
kubectl describe rc nginx-rc

The describe output includes events, selector, and pod statuses. Look for SuccessfulCreate events and any failures.

Check pod status in detail:

kubectl get pods -l app=nginx -o wide

If a pod is not running, inspect it:

kubectl describe pod <pod-name>

Example failure section:

Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Warning  FailedScheduling  2m    default-scheduler  0/3 nodes are available: 3 Insufficient cpu.

This indicates insufficient resources. Recovery: scale down or add nodes.

Check Logs

For a running pod:

kubectl logs <pod-name>

For a crashed pod, check previous logs:

kubectl logs <pod-name> --previous

Example crash loop log:

Error: unable to start application: config file not found

Recovery: fix the config file path in the pod template.

Verify ReplicationController Status via YAML

kubectl get rc nginx-rc -o yaml

Look at status.replicas, status.readyReplicas, and status.observedGeneration. If ready replicas are lower than desired, the RC is unhealthy.

Advanced Diagnostics

• Check events across the namespace:

kubectl get events --sort-by=.metadata.creationTimestamp

• Watch pod changes live:

kubectl get pods -l app=nginx --watch

Failure Modes and Recovery

ReplicationControllers can fail in various ways. Here are common failure modes and how to recover.

Failure Mode 1: Pods Not Created

Symptom: kubectl get rc shows desired=3 but current=0.

Diagnosis:

kubectl describe rc nginx-rc

Look for events like:

Warning  FailedCreate  ReplicationController  Error creating: pods is forbidden: User cannot create resource pods in namespace default

Cause: RBAC restrictions.

Recovery: Fix RBAC permissions or use a namespace with proper access. Verify with:

kubectl auth can-i create pods

Expected yes.

Failure Mode 2: Pods CrashLoopBackOff

Symptom: Pods are in CrashLoopBackOff state.

Diagnosis:

kubectl get pods -l app=nginx
kubectl logs <pod-name> --previous

Example log:

nginx: [emerg] unexpected end of file, expecting ";" in /etc/nginx/conf.d/default.conf:10

Cause: Misconfigured config file.

Recovery: Correct the config in the pod template, update the RC manifest, and apply. Delete existing pods to force recreation:

kubectl delete pod -l app=nginx

The RC will automatically replace them.

Failure Mode 3: RC Cannot Scale

Symptom: kubectl scale fails or no pods are added.

Diagnosis:

kubectl describe rc nginx-rc

Look for resource quota errors:

Warning  FailedCreate  ReplicationController  Error creating: pods is forbidden: exceeded quota

Cause: Namespace resource quota exceeded.

Recovery: Increase quota or reduce replicas. Check quota:

kubectl get resourcequota

Failure Mode 4: Selector Mismatch

Symptom: RC reports desired replicas but no pods are selected; or extra pods are selected.

Diagnosis: Compare spec.selector in RC with pod labels:

kubectl get rc nginx-rc -o jsonpath='{.spec.selector}'
kubectl get pods -l app=nginx --show-labels

If labels don't match, the RC won't manage those pods.

Recovery: Fix the selector in the manifest and apply again. Note that changing selector is disruptive; consider deleting and recreating the RC.

General Recovery Workflow

1. Take a snapshot before changes:

kubectl get rc nginx-rc -o yaml > rc-backup.yaml

1. Apply the fix.
2. Verify:

kubectl get pods -l app=nginx

1. If recovery fails, restore from backup:

kubectl apply -f rc-backup.yaml

Operations Checklist

Use this checklist for daily ReplicationController operations.

Pre-Change Checklist

• [ ] Confirm cluster version and API access.
• [ ] Inspect current RC and pods:

  kubectl get rc,pods -l app=<label>

• [ ] Backup current RC manifest:

  kubectl get rc <name> -o yaml > backup-<name>.yaml

• [ ] Test change in dry-run:

  kubectl apply -f <manifest> --dry-run=client

Change Execution Checklist

• [ ] Apply the change:

  kubectl apply -f <manifest>

• [ ] Monitor rollout (if scaling):

  kubectl rollout status rc/<name>   # Note: rollout status works for Deployments, not RCs; use get rc instead

For RC, use:

  kubectl get rc <name> -w

• [ ] Verify pod readiness:

  kubectl get pods -l <selector>

• [ ] Check logs for errors:

  kubectl logs <pod-name> --tail=20

Post-Change Verification Checklist

• [ ] Confirm desired=current=ready:

  kubectl get rc <name>

• [ ] Test application endpoint via port-forward or service.
• [ ] Document the change and any unexpected behavior.

Example Walkthrough: Scale and Verify

# Scale nginx-rc to 4 replicas
kubectl scale rc nginx-rc --replicas=4
# Watch pods being created
kubectl get pods -l app=nginx -w
# After pods are ready, verify
kubectl get rc nginx-rc
# Test one pod
kubectl port-forward rc/nginx-rc 8080:80
# curl localhost:8080

Conclusion

Kubernetes ReplicationController commands are essential for managing pod replication, even in legacy environments. By following a safe configuration path, verifying every change, and having recovery plans for common failures, you can ensure high availability and quick troubleshooting. Always start with read-only observations, limit changes, and document recovery steps.

Next steps: practice creating and scaling a ReplicationController in a test cluster, experiment with failure scenarios like deleting pods and observing self-healing, and then migrate to Deployments for more advanced features like rolling updates. Remember to review dependencies such as ReplicaSet, Deployment, and Pod to understand the evolution of replication in Kubernetes.

A reliable operational workflow makes failures visible, protects sensitive data, limits changes to intended resources, and defines recovery verification before incidents force decisions.