Skip to main content
Calico Open Source 3.33 (latest) documentation

Enable kubectl to manage Calico APIs

Big picture​

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

A simpler alternative: native v3 CRDs

New installs of Calico default to native v3 CRDs, which serve projectcalico.org/v3 resources directly with no aggregation API server. This page covers installing or enabling the aggregation API server instead.

Native v3 CRDs are the successor to the aggregation API server. The aggregation API server will continue to be supported until native v3 CRDs are fully supported on all platforms, and will be removed in a future release.

Value​

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

note

New installs default to native v3 CRDs, not the aggregation API server. Use this page if you want the aggregation API server, or are adding it to an existing cluster.

Install in API server mode (v1 CRDs)​

New installs default to v3 CRD mode. To install in the aggregation API-server mode instead, install the v1 CRDs before the operator decides the mode - the operator runs in API-server mode whenever the crd.projectcalico.org/v1 CRDs are present.

Install the v1 CRD chart before the Tigera Operator:

helm template calico-crds projectcalico/crd.projectcalico.org.v1 --version v3.33.0 | kubectl apply --server-side -f -

Then continue with your normal install. The aggregation API server is deployed automatically.

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.

Concepts​

calicoctl vs kubectl​

In previous releases, calicoctl has been required to manage Calico API resources in the projectcalico.org/v3 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.

Alternatively, when using native v3 CRDs, projectcalico.org/v3 resources are native CRDs, so kubectl works directly without needing either the API server or calicoctl for resource management.

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 operator.tigera.io/APIServer with the following command.

    kubectl create -f - <<EOF
    apiVersion: operator.tigera.io/v1
    kind: APIServer
    metadata:
      name: default
    spec: {}
    EOF

  2. Confirm it appears as Available with the following command.

    kubectl get tigerastatus apiserver

    You should see the following output:

    NAME        AVAILABLE   PROGRESSING   DEGRADED   SINCE
    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 '\sprojectcalico.org'

You should see the following output:

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

kubectl may continue to prefer the crd.projectcalico.org 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 projectcalico.org 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 projectcalico.org/v3 APIs, unless you are using native v3 CRDs where kubectl works directly.

Next steps​

Recommended tutorials