Enable Calico API Service in Kubernetes: Step‑by‑Step Guide

Prerequisites

Have a Kubernetes cluster where Calico is installed using the Kubernetes API datastore (see related migration guide).

Calico version must be v3.20 or newer.

A machine with OpenSSL 1.1.1 or later.

Prepare Environment

1. Download the Calico API server manifest

curl -Lo /etc/kubernetes/addons/calico-apiserver.yaml https://raw.githubusercontent.com/projectcalico/calico/v3.27.4/manifests/apiserver.yaml

Tip: the default deployment namespace is calico-system .

2. Change the deployment namespace to kube-system

sed -ri.bak 's/namespace: calico-apiserver/namespace: kube-system/g' /etc/kubernetes/addons/calico-apiserver.yaml

Tip: also remove the namespace‑creation section from the manifest.

3. Pull the Calico API server image and push it to a private registry

sudo docker pull calico/apiserver:v3.27.4
sudo docker tag calico/apiserver:v3.27.4 core.jiaxzeng.com/library/calico/apiserver:v3.27.4
sudo docker push core.jiaxzeng.com/library/calico/apiserver:v3.27.4

4. Update the image reference in the manifest

sudo sed -ri.bak 's@image: calico/apiserver:v3.27.4@image: core.jiaxzeng.com/library/calico/apiserver:v3.27.4@g' /etc/kubernetes/addons/calico-apiserver.yaml

Deploy Calico API Service

1. Generate a self‑signed certificate for the API server

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

2. Create a secret with the certificate in the kube-system namespace

kubectl create secret -n kube-system generic calico-apiserver-certs --from-file=apiserver.key --from-file=apiserver.crt

3. Apply the manifest to deploy the API server

kubectl apply -f /etc/kubernetes/addons/calico-apiserver.yaml

4. Patch the APIService with the CA bundle

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

5. Verify that Calico resources are available

kubectl api-resources | grep projectcalico.org/v3

Uninstall Calico API Service

kubectl -n kube-system delete secret calico-apiserver-certs
kubectl delete -f /etc/kubernetes/addons/calico-apiserver.yaml

Summary

After completing these steps you will have enabled the Calico API service, allowing you to manage Calico custom resources (NetworkPolicy, GlobalNetworkPolicy, IPPool, etc.) directly with kubectl, improving operational efficiency and network security in your Kubernetes clusters.