🚨 Kubernetes Error Guide: 'Failed to create new replica set ... is forbidden'

Exact Error Message

A Deployment is stuck — its rollout never advances and the new revision never appears. kubectl describe shows the Deployment controller could not even create the ReplicaSet object for the new revision:

$ kubectl describe deployment api
Conditions:
  Type           Status  Reason
  ----           ------  ------
  Progressing    False   FailedCreate
Events:
  Type     Reason        Age                From                   Message
  ----     ------        ----               ----                   -------
  Warning  FailedCreate  8s (x6 over 1m)    deployment-controller  Failed to create new replica set "api-6c4b9f7d5d": replicasets.apps "api-6c4b9f7d5d" is forbidden: exceeded quota: object-quota, requested: count/replicasets.apps=1, used: count/replicasets.apps=5, limited: count/replicasets.apps=5

The key phrase is Failed to create new replica set "..." is forbidden:. Unlike a FailedCreate on a ReplicaSet (which is about pods), this failure is about the ReplicaSet object itself being rejected.

What the Error Means

A Deployment rolls out by creating a new ReplicaSet for each revision. That create replicaset API call passes through admission control just like any other object. When an admission plugin rejects it, the Deployment controller cannot create the new revision at all, sets Progressing: False with reason FailedCreate, and records the Failed to create new replica set event on the Deployment.

Because the ReplicaSet never exists, there is no child object to inspect — the entire error lives on the Deployment. This is distinct from ReplicaFailure, where the ReplicaSet does exist but its pods are forbidden. Here, the rejection happens one layer higher: object-count quota, RBAC on the Deployment controller, or a validating webhook that denies replicasets.

Common Causes

• Object-count ResourceQuota — a quota on count/replicasets.apps or count/deployments.apps is exhausted, often from accumulated old revisions (exceeded quota: ... count/replicasets.apps).
• RBAC denial — the deployment-controller or an aggregated identity lacks create on replicasets in the namespace (cannot create resource "replicasets").
• Validating admission webhook — a policy engine (OPA Gatekeeper, Kyverno) denies the ReplicaSet for a label/annotation/policy reason.
• Namespace terminating — the target namespace is Terminating, so all object creation is forbidden (unable to create new content in namespace ...: namespace is being terminated).
• LimitRange / mutating webhook failure — a webhook in the create path errors out (failed calling webhook) and fails closed.

How to Reproduce the Error

Cap the number of ReplicaSet objects, then force several revisions so the quota fills:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: object-quota
  namespace: demo
spec:
  hard:
    count/replicasets.apps: "2"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: demo
spec:
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels: { app: api }
  template:
    metadata:
      labels: { app: api }
    spec:
      containers:
        - name: app
          image: registry.k8s.io/pause:3.9

kubectl apply -f quota-and-deploy.yaml
kubectl set image deployment/api app=registry.k8s.io/pause:3.10 -n demo
kubectl rollout status deployment/api -n demo

Waiting for deployment "api" rollout to finish: ...
error: deployment "api" exceeded its progress deadline

Each set image wants a new ReplicaSet; once the object quota is hit, Failed to create new replica set appears.

Diagnostic Commands

# Read the FailedCreate event on the Deployment itself
kubectl describe deployment <DEPLOY> | grep -A8 Events

# Confirm the Progressing condition reason
kubectl get deployment <DEPLOY> -o jsonpath='{.status.conditions}'

# Object-count quota usage in the namespace
kubectl describe resourcequota -n <NS>

# How many ReplicaSets already exist (old revisions count too)
kubectl get replicasets -n <NS>

# Check for admission webhooks that gate replicasets
kubectl get validatingwebhookconfigurations
kubectl get namespace <NS> -o jsonpath='{.status.phase}'

The describe deployment Events block holds the verbatim is forbidden: reason — that string determines the fix.

Step-by-Step Resolution

1. Read the forbidden reason on the Deployment. Classify the first words after is forbidden::

exceeded quota: ... count/replicasets.apps   -> object-count quota
cannot create resource "replicasets"         -> RBAC
admission webhook "..." denied the request   -> policy webhook
namespace is being terminated                -> namespace stuck Terminating

2. Clear an object-count quota. Old ReplicaSets from prior revisions consume the count. Lower revisionHistoryLimit and prune, or raise the quota:

kubectl get replicasets -n <NS>
# many api-xxxxx with 0 desired -> stale revisions occupying the quota

Set revisionHistoryLimit: 3 on the Deployment so Kubernetes garbage-collects old ReplicaSets automatically, freeing the count.

3. Fix RBAC denials. If the message says an identity cannot create resource "replicasets", a custom RBAC setup is too tight. Confirm the controller’s permissions:

kubectl auth can-i create replicasets -n <NS> --as=system:serviceaccount:kube-system:deployment-controller

4. Fix a policy webhook denial. admission webhook "..." denied the request names the policy. Read its message, then bring the Deployment template into compliance (required labels, signed images, etc.) or fix a misconfigured policy.

5. Recover a terminating namespace. namespace is being terminated means the namespace is stuck deleting, often on a finalizer. Identify and clear the blocking finalizer or recreate the namespace.

6. Let the rollout retry. The Deployment controller retries ReplicaSet creation continuously. Once admission passes, the new ReplicaSet is created and the rollout proceeds without a manual restart.

Prevention and Best Practices

• Set a sane revisionHistoryLimit (3-5) so stale ReplicaSets are reaped and never exhaust object-count quotas.
• When using object-count quotas, account for the extra ReplicaSet each rollout temporarily creates.
• Configure admission webhooks with a namespaceSelector and a sensible failurePolicy so an unhealthy webhook does not block every Deployment.
• Alert on Progressing: False / FailedCreate — it means a rollout could not even begin.
• Never leave namespaces in Terminating: audit finalizers regularly. More patterns in Kubernetes & Helm guides.

Related Errors

• ReplicaFailure: True — the ReplicaSet exists but its pods are forbidden.
• ProgressDeadlineExceeded — the rollout-timeout symptom this failure often triggers.
• FailedScheduling — a later stage where admitted pods cannot be placed.

Frequently Asked Questions

How is this different from ReplicaFailure? ReplicaFailure means the ReplicaSet was created but cannot create its pods. Failed to create new replica set means the ReplicaSet object was rejected, so no child exists at all. Check whether a new ReplicaSet appears in kubectl get rs.

Why does an object-count quota fill up from old revisions? Each rollout leaves the previous ReplicaSet scaled to zero but still present, up to revisionHistoryLimit. Those zero-replica objects still count toward count/replicasets.apps. Lowering the history limit frees them.

The rollout shows exceeded its progress deadline — is that the same bug? That is the downstream symptom. Because no ReplicaSet was created, the Deployment never progresses and eventually trips the progress deadline. Fix the forbidden create and the deadline error clears.

Can a broken webhook really block all Deployments? Yes. A ValidatingWebhookConfiguration with failurePolicy: Fail and an unreachable backend rejects every matching create, including ReplicaSets. Scope webhooks narrowly and monitor their backend health.