Migrate Calico to an operator-managed installation
Switch your Calico installation from manifest-based resources to an installation managed by the Calico operator.
The Calico operator provides a number of advantages over traditional manifest-based installation of Calico resources, including but not limited to:
- Automatic platform and configuration detection.
- A simplified upgrade procedure.
- Well-defined split between end-user configuration and product code.
- Resource reconciliation and lifecycle management.
Operator vs manifest based installations
Most Calico installations in the past have been manifest-based, meaning that Calico is installed directly as a set of Kubernetes resources in a
The Calico operator is a Kubernetes application that installs and manages the lifecycle of a Calico installation by creating and updating Kubernetes resources such as Deployments, DaemonSets, Secrets, without the need for direct user intervention.
There are a few key differences to be aware of, if you are familiar with manifest-based installs and are looking to use the operator:
- Calico resources will be migrated from the
kube-systemnamespace used by the Calico manifests to a new
- Calico resources will no longer be hand-editable, as the Calico operator will reconcile undesired changes in order to maintain an expected state.
- Calico resources can instead be configured via the
For new clusters, you can simply follow the steps in the quickstart guide to get started with the operator.
For existing clusters using the
calico.yaml manifest to install Calico, upon installing the operator, it will detect the existing Calico resources on the cluster
and calculate how to take ownership of them. The operator will maintain existing customizations, if supported, and warn about any unsupported configurations that it detects.
Before you begin
- Ensure that your Calico installation is configured to use the Kubernetes datastore. If your cluster uses etcdv3 directly, you must follow the datastore migration procedure before following this document.
- Migration to Calico v3.26 operator-managed installation is supported only from Calico v3.26 manifest-based installation
Migrate a cluster to the operator
Do not edit or delete any resources in the
kube-system Namespace during the following procedure as it may interfere with the upgrade.
Install the Tigera Calico operator and custom resource definitions.
kubectl apply --server-side --force-conflicts -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.4/manifests/tigera-operator.yamlnote
Due to the large size of the CRD bundle,
kubectl applymight exceed request limits. Instead, use
Trigger the operator to start a migration by creating an
Installationresource. The operator will auto-detect your existing Calico settings and fill out the spec section.
kubectl create -f - <<EOF
Monitor the migration status with the following command:
kubectl describe tigerastatus calico
Now that the migration is complete, you will see Calico resources have moved to the
kubectl get pods -n calico-system
You should see output like this:
NAME READY STATUS RESTARTS AGE
calico-kube-controllers-7688765788-9rqht 1/1 Running 0 17m
calico-node-4ljs6 1/1 Running 0 14m
calico-node-bd8mc 1/1 Running 0 14m
calico-node-cpbd8 1/1 Running 0 14m
calico-node-jl97q 1/1 Running 0 14m
calico-node-xw2nj 1/1 Running 0 14m
calico-typha-57bf79f96f-6sk8x 1/1 Running 0 14m
calico-typha-57bf79f96f-g99s9 1/1 Running 0 14m
calico-typha-57bf79f96f-qtchs 1/1 Running 0 14m
At this point, the operator will have automatically cleaned up any Calico resources in the
kube-systemnamespace. No manual cleanup is required.