Skip to main content
Let’s review the installation options for Argo Rollouts. There are two controller installation modes that differ by scope and required permissions. Choose the one that matches your cluster governance, security posture, and team boundaries.

​
Overview

Argo Rollouts supports:
  • A default, cluster-wide controller that can manage rollout resources across all namespaces.
  • A restricted, namespace-scoped controller that operates only inside its own namespace (blind to other namespaces).
Both options require installing the Rollouts CustomResourceDefinitions (CRDs) once for the cluster. You can combine either controller mode with a CLI installation to manage and visualize rollouts from your workstation.
Installation ModeScopeRequired PermissionsTypical Use Case
Cluster-wide controllerAll namespaces (single controller)Cluster administrator privileges to install controller and CRDsCentralized deployments, single-operator management for entire cluster
Namespace-scoped controllerSingle namespace onlyNamespace-level admin to install controller; Cluster admin required only once to install CRDs for clusterMulti-tenant clusters, team isolation, limited blast radius

​
1) Cluster-wide (default) installation

This is the most common method for installing Argo Rollouts.
  • Scope: Installs a single controller that can manage rollout resources across every namespace in the cluster.
  • Permissions: Requires a cluster administrator to install (controller needs cluster-wide RBAC).
  • Use cases: Ideal for centralized management of application deployments, especially when a single operator manages rollouts for all teams.
  • Integration note: When used together with GitOps tools such as ArgoCD, the controller typically runs in the same namespace used for rollout management. For example, see the GitOps with ArgoCD workflow for related patterns.
Cluster-wide installation requires cluster-admin privileges. Ensure your security policy allows a controller with cluster-scoped permissions before proceeding.

​
2) Namespace-scoped (restricted) installation

This option limits the controller’s visibility and control to a single namespace.
  • Scope: Controller operates only within the namespace where it is installed; it cannot see or manage resources in other namespaces.
  • Permissions:
    • A namespace administrator can install the controller in that namespace.
    • A cluster administrator must install Rollouts CRDs once for the entire cluster (a one-time step).
  • Use cases: Best for multi-tenant or strongly isolated clusters where teams run independent controllers and you want to limit cross-namespace impact.
Namespace-scoped controllers help enforce isolation between teams. If you need multi-tenant separation without repeated cluster-admin operations, install the CRDs once and allow team admins to run namespace-scoped controllers.

​
One-time CRD installation (required for namespace-scoped)

When using namespace-scoped controllers, CRDs must exist cluster-wide so that the Kubernetes API recognizes Rollout custom resources. This is a single cluster-admin operation and does not grant controller access to all namespaces. Suggested flow:
  1. Cluster admin installs Rollouts CRDs.
  2. Namespace admins install the namespace-scoped controller in their namespace.
A dedicated CLI for Argo Rollouts greatly simplifies rollout management and visualization from the command line. Installing the CLI is optional but highly recommended. Typical installation steps (replace URLs and version tags with the current release from the official docs or repository):
  • Download the binary for your OS.
  • Make it executable:
    • chmod +x ./<binary-name>
  • Move it into your PATH:
    • sudo mv ./<binary-name> /usr/local/bin/<binary-name>
Example (generic): 
# download example (update URL/version accordingly)
curl -LO https://github.com/argoproj/argo-rollouts/releases/download/vX.Y.Z/argo-rollouts-linux-amd64

# make executable
chmod +x ./argo-rollouts-linux-amd64

# move to PATH
sudo mv ./argo-rollouts-linux-amd64 /usr/local/bin/argo-rollouts
Using the CLI enables quick rollout status checks, traffic-shift visualizations, and troubleshooting commands. Check the official Argo Rollouts documentation for the latest installation instructions and binaries.

​
Quick decision guide

  • Use cluster-wide installation if:
    • You want centralized control over all rollouts.
    • You have cluster-admin privileges and a small number of operators.
  • Use namespace-scoped installation if:
    • You operate a multi-tenant cluster and need to isolate teams.
    • You prefer giving namespace admins control without granting cluster-wide permissions (CRDs still need one-time cluster admin installation).

Watch Video