calico

name: calico description: Calico CNI and network policy engine via Tigera Operator for Kubernetes. Use when deploying Calico with Tigera Operator Helm chart, configuring IPPools (VXLAN/IPIP/BGP encapsulation), writing Calico NetworkPolicy or GlobalNetworkPolicy resources, setting up BGP peering (BGPPeer, BGPConfiguration, route reflectors), tuning FelixConfiguration (BPF dataplane, iptables, logging, flow logs), upgrading Calico versions, enabling or disabling Calico on K3s/RKE2/Rancher clusters, configuring airgapped Calico deployments, or troubleshooting pod networking issues (node NotReady, DNS failures, cross-node connectivity, VXLAN/IPIP tunnel problems). last_updated: 2026-03-11

Kubernetes CNI and network policy engine deployed via Tigera Operator. Provides pod networking (VXLAN, IPIP, or native BGP), network policy enforcement, and optional BPF dataplane.

Architecture

Tigera Operator (manages lifecycle)
├── calico-node (DaemonSet) - BGP, routing, Felix agent
├── calico-typha (Deployment) - fan-out datastore cache
├── calico-kube-controllers - sync K8s resources to Calico
├── calico-apiserver - Calico API extension
└── CRDs - IPPool, NetworkPolicy, BGP*, Felix*, etc.

Deployment via Tigera Operator

Helm Install

helm repo add projectcalico https://docs.tigera.io/calico/charts
helm install calico projectcalico/tigera-operator --version v3.29.3 \
  --namespace tigera-operator --create-namespace -f values.yaml

Minimal values.yaml

tigera-operator:
  installation:
    calicoNetwork:
      ipPools:
        - cidr: 10.42.0.0/16
          encapsulation: VXLAN
          natOutgoing: true
          nodeSelector: all()

For K3s/Rancher integration (enable/disable, airgap, HA), see references/frameworks/k3s.md.

Upgrade

# 1. Check compatibility matrix: https://docs.tigera.io/calico/latest/getting-started/kubernetes/requirements
# 2. Update chart
helm repo update
helm upgrade calico projectcalico/tigera-operator --version v3.29.3 \
  --namespace tigera-operator -f values.yaml
# 3. Monitor rollout
kubectl rollout status daemonset/calico-node -n calico-system
kubectl get tigerastatus

IP Pools & Encapsulation

Mode	Field	Use Case
VXLAN	`encapsulation: VXLAN`	Default, works across L3 networks
VXLANCrossSubnet	`encapsulation: VXLANCrossSubnet`	VXLAN only for cross-subnet
IPIP	`encapsulation: IPIP`	Legacy, tunnel-based
IPIPCrossSubnet	`encapsulation: IPIPCrossSubnet`	IPIP only for cross-subnet
None	`encapsulation: None`	Native routing / BGP peering required

For IP pool management (multiple pools, node-specific pools, migration), see references/ip-pools.md.

Network Policy

Calico extends Kubernetes NetworkPolicy with richer selectors and global scope:

Resource	Scope	Key Features
`NetworkPolicy`	Namespaced	L3-L7 rules, DNS policy, service accounts
`GlobalNetworkPolicy`	Cluster-wide	Host endpoint protection, ordered evaluation

apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: allow-web
  namespace: default
spec:
  selector: app == 'web'
  ingress:
    - action: Allow
      source:
        selector: app == 'frontend'
      destination:
        ports: [80, 443]
  egress:
    - action: Allow

For policy patterns (deny-all, DNS allow, egress control, host endpoints), see references/network-policy.md.

BGP Configuration

For environments using native routing instead of overlay:

apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64512
  nodeToNodeMeshEnabled: true
  listenPort: 179

For BGP peering (external peers, route reflectors, communities, BGPFilter), see references/bgp.md.

Felix Configuration

Felix is the per-node agent handling policy enforcement and routing:

apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
  name: default
spec:
  bpfEnabled: false          # true for BPF dataplane
  logSeverityScreen: Info     # Debug, Info, Warning, Error, Fatal
  ipipEnabled: true
  vxlanEnabled: true

For advanced Felix tuning (BPF dataplane, flow logs, connection tracking, MTU, wireguard), see references/felix.md.

Troubleshooting

First commands:

kubectl get tigerastatus                    # overall health
kubectl get pods -n calico-system           # component status
kubectl get ippool -o yaml                  # pool config
calicoctl node status                       # BGP peering state

For debugging workflows (node NotReady, cross-node failures, DNS issues, VXLAN/IPIP problems), see references/troubleshooting.md.

Common Issues

Symptom	Likely Cause	Reference
Node stuck NotReady	Calico-node crashloop, IPPool misconfigured	troubleshooting.md
Pods can't reach other nodes	VXLAN/IPIP port blocked (UDP 4789/IP proto 4)	troubleshooting.md
DNS resolution fails	NetworkPolicy blocking CoreDNS egress	network-policy.md
BGP session down	Wrong AS number, firewall blocking TCP 179	bgp.md
High CPU on calico-node	Felix log level Debug, excessive policies	felix.md
"Failed to discover tenancy mode"	CRDs not applied before operator start (v3.28.3+)	troubleshooting.md

Upstream Docs

Installation: https://docs.tigera.io/calico/latest/getting-started/
CRD reference: https://docs.tigera.io/calico/latest/reference/resources/
Felix config: https://docs.tigera.io/calico/latest/reference/resources/felixconfig
calicoctl: https://docs.tigera.io/calico/latest/operations/calicoctl/

References

references/ip-pools.md - IP pool management, multiple pools, migration
references/network-policy.md - Policy patterns, deny-all, DNS, host endpoints
references/bgp.md - BGP peering, route reflectors, communities, filters
references/felix.md - Felix tuning, BPF dataplane, flow logs, wireguard
references/troubleshooting.md - Debugging pod networking, node issues
references/frameworks/k3s.md - K3s/Rancher: enable, disable, airgap, HA