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-11T00:00:00.000Z"

Calico

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