calico

name: calico description: >- Calico CNI via Tigera Operator for Kubernetes. Use for IPPools, NetworkPolicy/GlobalNetworkPolicy, BGP peering, FelixConfiguration/BPF, K3s/RKE2/Rancher, airgap, or pod networking troubleshooting. 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