---
title: "Enable kubectl to manage Calico APIs"
description: "Install the Calico Open Source aggregated API server on an existing cluster so kubectl can manage projectcalico.org/v3 resources without calicoctl."
product: "Calico Open Source"
version: "3.32 (latest)"
section: "Operations"
canonical_url: "https://docs.tigera.io/calico/latest/operations/install-apiserver"
---

# 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.

> **SUCCESS:** You can use [native v3 CRDs](https://docs.tigera.io/calico/latest/operations/native-v3-crds.md) to manage `projectcalico.org/v3` resources directly with `kubectl` without installing the aggregation API server. If you are setting up a new cluster and want a simpler architecture, consider native v3 CRDs 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.

> **SECONDARY:** 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](https://docs.tigera.io/calico/latest/operations/datastore-migration.md).

- Upgrade to Calico v3.20+ using the appropriate [upgrade instructions](https://docs.tigera.io/calico/latest/operations/upgrading.md).

- 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](https://docs.tigera.io/calico/latest/operations/native-v3-crds.md), `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:

- [calicoctl node](https://docs.tigera.io/calico/latest/reference/calicoctl/node.md)
- [calicoctl ipam](https://docs.tigera.io/calico/latest/reference/calicoctl/ipam.md)
- [calicoctl version](https://docs.tigera.io/calico/latest/reference/calicoctl/version.md)

## How to

### Install the API server

Select the method below based on your installation method.

<!-- tabs -->

**Tab: Operator install**

1. Create an instance of an `operator.tigera.io/APIServer` with the following command.

   ```bash
   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.

   ```bash
   kubectl get tigerastatus apiserver
   ```

   You should see the following output:

   ```text
   NAME        AVAILABLE   PROGRESSING   DEGRADED   SINCE
   apiserver   True        False         False      1m10s
   ```

**Tab: Manifest install**

1. Create the following manifest, which will install the API server as a deployment in the `calico-apiserver` namespace.

   ```bash
   kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.1/manifests/apiserver.yaml
   ```

   You will notice that the API server remains in a `ContainerCreating` state, as it is waiting for credentials to be provided for authenticating the main Kubernetes API server.

2. Generate a private key and CA bundle using the following openssl command. This certificate will be used by the main API server to authenticate with the Calico API server.

   > **SECONDARY:** Please note in the following command `-addext` argument requires openssl 1.1.1 or above. You can check your version of openssl using `openssl version`.

   ```text
   openssl req -x509 -nodes -newkey rsa:4096 -keyout apiserver.key -out apiserver.crt -days 365 -subj "/" -addext "subjectAltName = DNS:calico-api.calico-apiserver.svc"
   ```

3. Provide the key and certificate to the Calico API server as a Kubernetes secret.

   ```bash
   kubectl create secret -n calico-apiserver generic calico-apiserver-certs --from-file=apiserver.key --from-file=apiserver.crt
   ```

4. Configure the main API server with the CA bundle.

   ```bash
   kubectl patch apiservice v3.projectcalico.org -p \
       "{\"spec\": {\"caBundle\": \"$(kubectl get secret -n calico-apiserver calico-apiserver-certs -o go-template='{{ index .data "apiserver.crt" }}')\"}}"
   ```

<!-- /tabs -->

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:

```bash
kubectl api-resources | grep '\sprojectcalico.org'
```

You should see the following output:

```text
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
```

> **SECONDARY:** 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.

```bash
kubectl get ippools
```

You should see output that looks like this:

```text
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.

<!-- tabs -->

**Tab: Operator install**

```bash
   kubectl delete apiserver default
```

**Tab: Manifest install**

```bash
   kubectl delete -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.1/manifests/apiserver.yaml
```

<!-- /tabs -->

Once removed, you will need to use calicoctl to manage projectcalico.org/v3 APIs, unless you are using [native v3 CRDs](https://docs.tigera.io/calico/latest/operations/native-v3-crds.md) where `kubectl` works directly.

## Next steps

**Recommended tutorials**

- [Secure a simple application using the Kubernetes NetworkPolicy API](https://docs.tigera.io/calico/latest/network-policy/get-started/kubernetes-policy/kubernetes-policy-basic.md)
- [Control ingress and egress traffic using the Kubernetes NetworkPolicy API](https://docs.tigera.io/calico/latest/network-policy/get-started/kubernetes-policy/kubernetes-policy-advanced.md)
- [Run a tutorial that shows blocked and allowed connections in real time](https://docs.tigera.io/calico/latest/network-policy/get-started/kubernetes-policy/kubernetes-demo.md)