Fix “CRD Not Registered” Errors After Installing Argo Rollouts

Introduction

After installing Argo Rollouts, some users may encounter the dreaded “CRD Not Registered” error. This usually happens when the cluster hasn’t fully recognized the required Custom Resource Definitions (CRDs), which are essential for Argo Rollouts to manage advanced deployment strategies like canary and blue-green releases.

In this guide, we’ll walk you through the common causes of this error and provide step-by-step solutions to resolve it. By following these best practices, you can ensure that your Argo Rollouts installation is fully functional, allowing you to safely manage deployments in your Kubernetes cluster without interruptions.

What “CRD Not Registered” Really Means

After installing Argo Rollouts, one of the most confusing errors you can hit is some variation of “CRD not registered,” “no matches for kind,” or “the server doesn’t have a resource type” when you try to apply a Rollout or related manifest. The wording may differ slightly depending on your kubectl version, but the root cause is that Kubernetes does not yet recognize the Argo Rollouts Custom Resource Definitions (CRDs).

Argo Rollouts relies on CRDs to add new API types such as Rollout, AnalysisRun, and Experiment to your cluster. Until those CRDs are registered successfully with the Kubernetes API server, anything that references those types will fail. That means even a perfectly valid Rollout YAML will be rejected if the cluster has never heard of rollouts.argoproj.io.

Understanding this distinction is important: when you see CRD‑related errors, you are not troubleshooting your application deployment yet, you are troubleshooting the platform extension that Argo Rollouts brings to Kubernetes.

In this guide, you will walk through how CRD registration works, why these errors appear after an installation, and how to systematically verify, fix, and prevent them.

How Argo Rollouts CRDs Are Installed

When you install Argo Rollouts via the official manifest or a Helm chart, you are effectively asking Kubernetes to do two things:

1. Register the CRDs that define the new resource types.
2. Run the controller that watches those resources and reconciles their state.

CRD registration happens at the cluster level. The CRDs for Argo Rollouts live under the API group argoproj.io and include definitions like rollouts.argoproj.io. These definitions tell the API server how to store, validate, and serve the new resources.

If anything interrupts that process, partial applies, missing permissions, version mismatches, or timing issues, your cluster may end up in a state where the controller is running, but the CRDs are not actually recognized. Alternatively, some CRDs may be present but not all, leading to more subtle problems when you try to use specific features.

A solid troubleshooting approach starts by separating the CRD layer from the controller layer and confirming, step by step, that the API server truly knows about the Argo Rollouts types.

Step-by-Step Guide to Fix “CRD Not Registered” Errors in Argo Rollouts

Step 1: Confirm the Error and Context

When you see a “CRD not registered” style message, capture the exact command you ran and the full error. The most common scenarios look like this:

kubectl apply -f rollout.yaml

…followed by an error such as:

error: unable to recognize "rollout.yaml": no matches for kind "Rollout" in version "argoproj.io/v1alpha1"

or:

Error from server (NotFound): error when creating "rollout.yaml": the server could not find the requested resource (post rollouts.argoproj.io)

These messages indicate that, from the API server’s perspective, Rollout is an unknown type. Before you rework manifests or change namespaces, you should check whether the CRDs are actually installed.

Step 2: Check Whether Argo Rollouts CRDs Exist

Start by listing CRDs that belong to the Argo Rollouts API group:

kubectl get crds | grep rollouts.argoproj.io

If the installation went well, you should see entries such as rollouts.argoproj.io in the output. If this command returns no rows, your CRDs are simply not present, and you are dealing with a failed or incomplete installation.

You can also ask for the specific CRD directly:

kubectl get crd rollouts.argoproj.io -o yaml

If this returns a NotFound error, the CRD has never been registered, or it has been removed. On the other hand, if it returns a full YAML definition with metadata, spec, and status sections, the CRD itself exists and you need to look for more subtle causes.

At this stage, you should also confirm that you are targeting the correct cluster. A surprisingly common pattern is to install Argo Rollouts into one cluster while your kubeconfig context points at another. Running:

kubectl config current-context

and comparing it against your installation notes is a quick way to rule out this category of issues.

Step 3: Re-apply the Official CRD Manifests Safely

If the CRD does not exist, the most direct fix is to reapply the official Argo Rollouts manifests, focusing on the sections that define the CRD.

When using the standard manifest approach, the project ships a combined install.yaml that contains both the CRDs and the controller deployment. You can re‑apply it safely using:

kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml

Applying the manifest is idempotent: if a CRD is already defined with the same version, Kubernetes treats it as an update, not a duplicate. If it was missing, this step will create it.

After re‑applying, check the CRD again:

kubectl get crd rollouts.argoproj.io

You should now see it listed, along with a CREATED timestamp and a stored version. If the CRD still does not appear, you may be experiencing permission or network issues when fetching the manifest.

Step 4: Investigate RBAC and Permissions

CRD operations are sensitive and often restricted in locked‑down environments. If the user or service account applying the manifest lacks the required permissions, the CRD sections may fail while other parts of the manifest still succeed.

Look for clues in the output of your apply command. If you see messages like “forbidden: User X cannot create resource customresourcedefinitions” or “insufficient permissions,” it means the API server rejected the CRD creation.

In that case, you have two options:

• Ask a cluster administrator with cluster‑admin privileges to apply the Argo Rollouts install manifest on your behalf.
• Use a temporary, higher‑privileged context solely for installation, in accordance with your organization’s policies.

Once a cluster admin successfully applies the manifest, verify the CRDs again. You should not need elevated permissions for everyday use of Rollout resources, but installing the CRDs is a one‑time cluster‑level task that often requires admin rights.

Step 5: Check for Version Mismatches and Deprecated APIs

Sometimes the CRD exists, but clients still report errors like “no matches for kind.” This can happen when there is a mismatch between the API version your manifests use and the version configured in the CRD.

Inspect the CRD’s spec:

kubectl get crd rollouts.argoproj.io -o jsonpath='{.spec.versions}' | jq

You should see which versions are served (for example, v1alpha1 or another version). Make sure the manifests you apply reference the same version in their apiVersion field. If you are using an older example that points to a deprecated version, the API server may refuse to serve it.

Keeping your Argo Rollouts installation aligned with a reasonably recent release generally avoids this class of problems. If you upgrade Argo Rollouts, allow the included CRD definitions to update the stored versions so your manifests stay compatible.

Step 6: Confirm Namespaces and API Reachability

If the CRD exists and the versions look correct, but your Rollout manifests still fail, check that you are not encountering namespace confusion or transient API issues.

Remember that CRDs are cluster‑scoped. A Rollout is namespaced, but the CRD itself is not. That means Rollout should be recognized in any namespace as long as the CRD is registered.

You can run a minimal test in a scratch namespace:

kubectl create namespace rollout-test

cat <<EOF | kubectl apply -f -

apiVersion: argoproj.io/v1alpha1

kind: Rollout

metadata:

  name: test-rollout

  namespace: rollout-test

spec:

  replicas: 1

  selector:

    matchLabels:

      app: test-rollout

  template:

    metadata:

      labels:

        app: test-rollout

    spec:

      containers:

        - name: test

          image: nginx:stable

          ports:

            - containerPort: 80

EOF

If this small rollout succeeds, the CRD is working, and your earlier error may be specific to the original namespace, context, or tooling. If it fails with the same “no matches” style error, double‑check that you are still pointing at the cluster where Argo Rollouts is installed.

Look at Controller Logs for Related Clues

Although CRD registration is primarily an API server concern, the Argo Rollouts controller logs can still provide useful hints, especially after upgrades or partial installations. If the controller cannot discover or watch the CRDs it expects, it may log warnings or errors.

Find the controller pod in the argo-rollouts namespace:

kubectl get pods -n argo-rollouts

Then inspect its logs:

kubectl logs deploy/argo-rollouts -n argo-rollouts

Look for messages about failed watches, unknown resources, or reconciliation errors. While these logs will not fix CRD registration on their own, they can confirm that the controller is at least running and attempting to interact with the API types you expect.

Preventing CRD Issues in Future Installs and Upgrades

Once you resolve the immediate “CRD not registered” problem, it is worth updating your installation and upgrade practices to avoid similar issues later.

A few practical habits help:

• Treat Argo Rollouts CRDs as cluster‑level infrastructure and manage them with the same discipline as other critical controllers.
• Use a single source of truth for installation manifests or Helm values, and keep it in version control.
• When upgrading, read the release notes, especially around CRD changes or breaking API updates.

If you are using GitOps with Argo CD or another tool, make sure the CRDs are managed in a way that is compatible with your cluster lifecycle. Some organizations prefer to install CRDs with a dedicated bootstrap process and then let GitOps tools manage only namespaced resources. Others are comfortable with Argo CD owning CRDs, as long as they understand the implications.

Conclusion: Make CRD Health a First‑Class Check

“CRD not registered” errors are frustrating, but they are also very fixable when you understand what they point to. Rather than rewriting your rollout manifests or questioning Argo Rollouts itself, you can focus on the cluster’s understanding of the argoproj.io API group and the rollouts.argoproj.io CRD.

By methodically checking whether the CRDs exist, re‑applying official manifests, validating permissions, aligning API versions, and testing with a minimal rollout, you turn a vague error message into a concrete set of checks. Once the CRD is properly registered, Argo Rollouts can behave like any other well‑integrated Kubernetes extension.

Over time, you can bake these checks into your installation runbooks and upgrade procedures so that CRD health is always verified early. That way, when you start defining rollouts for real applications, you can focus on strategy and behavior rather than low‑level platform surprises.

FAQs: “CRD Not Registered” and Argo Rollouts

Latest Post:

• How Argo Rollouts Works: Canary & Blue-Green Strategies
• Argo Rollouts Features: Blue-Green, Canary & Traffic Control
• Argo Rollouts vs Kubernetes Deployments: Key Differences & Benefits
• Is Argo Rollouts Safe? Security & Production Readiness Explained
• Business Use Cases for Argo Rollouts: Safe Deployments, KPIs & Continuous Delivery