Skip to main content
Version: 3.27 (latest)

Enable kubectl to manage Calico APIs

Big picture

[ Feature status: GA in Calico v3.20+ ]

Install the Calico API server on an existing cluster to enable management of Calico APIs using kubectl.


The API server provides a REST API for Calico, and allows management of APIs using kubectl without the need for calicoctl.


Starting in Calico v3.20.0, new operator-based installations of Calico include the API server component by default, so the instructions in this document are not required.

Before you begin

  • Make sure you have a cluster with Calico installed using the Kubernetes API data store. If not, you can migrate from etcd.

  • Upgrade to Calico v3.20+ using the appropriate upgrade instructions.

  • For non-operator installations, you will need a machine with openssl installed.


calicoctl vs kubectl

In previous releases, calicoctl has been required to manage Calico API resources in the API group. The calicoctl CLI tool provides important validation and defaulting on these APIs. The Calico API server performs that defaulting and validation server-side, exposing the same API semantics without a dependency on calicoctl.

calicoctl is still required for the following subcommands:

How to

Install the API server

Select the method below based on your installation method.

  1. Create an instance of an with the following contents.

    kind: APIServer
    name: default
    spec: {}
  2. Confirm it appears as Available with the following command.

    kubectl get tigerastatus apiserver

    You should see the following output:

    apiserver True False False 1m10s

After following the above steps, you should see the API server pod become ready, and Calico API resources become available. You can check whether the APIs are available with the following command:

kubectl api-resources | grep '\'

You should see the following output:

bgpconfigurations                 bgpconfig,bgpconfigs                                false        BGPConfiguration
bgppeers false BGPPeer
clusterinformations clusterinfo false ClusterInformation
felixconfigurations felixconfig,felixconfigs false FelixConfiguration
globalnetworkpolicies gnp,cgnp,calicoglobalnetworkpolicies false GlobalNetworkPolicy
globalnetworksets false GlobalNetworkSet
hostendpoints hep,heps false HostEndpoint
ippools false IPPool
kubecontrollersconfigurations false KubeControllersConfiguration
networkpolicies cnp,caliconetworkpolicy,caliconetworkpolicies true NetworkPolicy
networksets netsets true NetworkSet
profiles false Profile

kubectl may continue to prefer the API group due to the way it caches APIs locally. You can force kubectl to update by removing its cache directory for your cluster. By default, the cache is located in $(HOME)/.kube/cache.

Use kubectl for APIs

Once the API server has been installed, you can use kubectl to interact with the Calico APIs. For example, you can view and edit IP pools.

kubectl get ippools

You should see output that looks like this:

NAME                  CREATED AT
default-ipv4-ippool 2021-03-19T16:47:12Z

Uninstall the Calico API server

To uninstall the API server, use the following instructions depending on your install method.

   kubectl delete apiserver default

Once removed, you will need to use calicoctl to manage APIs.

Next steps

Recommended tutorials