If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/flannel-io/flannel shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 10 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live flannel-io/flannel repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/flannel-io/flannel.

What it runs against: a local clone of flannel-io/flannel — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in flannel-io/flannel | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of flannel-io/flannel. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/flannel-io/flannel.git
#   cd flannel
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of flannel-io/flannel and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "flannel-io/flannel(\\.git)?\\b" \\
  && ok "origin remote is flannel-io/flannel" \\
  || miss "origin remote is not flannel-io/flannel (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "pkg/backend/backend.go" \\
  && ok "pkg/backend/backend.go" \\
  || miss "missing critical file: pkg/backend/backend.go"
test -f "pkg/ip/ip.go" \\
  && ok "pkg/ip/ip.go" \\
  || miss "missing critical file: pkg/ip/ip.go"
test -f "pkg/subnet/subnet.go" \\
  && ok "pkg/subnet/subnet.go" \\
  || miss "missing critical file: pkg/subnet/subnet.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "Documentation/configuration.md" \\
  && ok "Documentation/configuration.md" \\
  || miss "missing critical file: Documentation/configuration.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/flannel-io/flannel"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Flannel is a layer 3 network fabric for Kubernetes that allocates subnet leases to each host and forwards packets between nodes using VXLAN, cloud provider integrations, or other backend mechanisms. It runs a single flanneld binary agent per node and stores network state in either the Kubernetes API or etcd, solving the problem of providing routable IPs for containers across a multi-node cluster without port mapping complexity. Monorepo structure: main agent code in root, backend implementations in pkg/backends/ (vxlan, host-gw, aws, gce, aliyun, etc.), Kubernetes integration via pkg/subnet/kube/, CNI plugin in pkg/ip/cni.go. pkg/network/ handles core networking abstractions, pkg/ip/ manages subnet allocation. Helm charts and manifests in Documentation/kustomization/. Build artifacts via Makefile and GitHub Actions workflows in .github/workflows/.

Kubernetes cluster operators and platform engineers who need to deploy multi-node clusters with a simple, container-native networking layer. Also relevant for developers integrating flannel into distributions like K3s or building custom Kubernetes deployments that require a CNI plugin.

Production-ready and actively maintained. The project has OpenSSF Scorecard certification, comprehensive CI/CD workflows (build, e2e tests on K3s and generic Kubernetes, CodeQL analysis, release automation), and visible recent activity. Go codebase of 439k LOC with Dockerfile and Makefile support indicates a mature, containerized deployment model.

Standard open source risks apply.

Active development visible in workflows: e2eTests.yaml and k3s-e2eTests.yml run on every PR, golangci-lint enforces code quality, trivy scans for vulnerabilities, release.yml manages versioning. ADR (Architecture Decision Records) in Documentation/adrs/ shows ongoing architecture discussions (e.g., nftables implementation decisions). Dependabot active for dependency updates.

git clone https://github.com/flannel-io/flannel.git
cd flannel
make
# Binary at bin/flanneld
# For Kubernetes: kubectl apply -f Documentation/kube-flannel.yml
# Or: helm repo add flannel https://flannel-io.github.io/flannel/ && helm install flannel --set podCidr="10.244.0.0/16"

Daily commands:

make          # Builds flanneld binary to bin/
make install  # Installs to system (may require sudo)
# Typically run as: flanneld --kube-subnet-mgr (uses Kubernetes API) or with etcd backend
# See Documentation/running.md and Documentation/configuration.md for modes

• pkg/backend/backend.go — Core backend abstraction that defines how packets are forwarded; all network fabric implementations inherit from here
• pkg/ip/ip.go — IP subnet and lease management logic; fundamental to flannel's allocation and routing model
• pkg/subnet/subnet.go — Subnet lease storage and coordination interface; abstracts etcd/Kubernetes API as backing store
• Makefile — Build and release automation; required to understand compilation targets and version management
• Documentation/configuration.md — Canonical source for all configuration options; essential reference for debugging and feature enablement
• Documentation/backends.md — Explains each forwarding backend (VXLAN, hostgw, cloud providers); needed to choose and extend backends

Add a New Cloud Backend

1. Create a new backend package directory under pkg/backend/yourcloud/ with main implementation file (pkg/backend/yourcloud/yourcloud.go)
2. Implement the Backend interface from pkg/backend/backend.go (Register, Run, Stop methods) (pkg/backend/backend.go)
3. Add config struct to pkg/common/common.go and parse it in main config handling (pkg/common/common.go)
4. Register the backend in the backend factory function in pkg/backend/backend.go (pkg/backend/backend.go)
5. Document backend configuration options in Documentation/backends.md (Documentation/backends.md)
6. Add integration tests in e2e tests referencing your cloud provider credentials (.github/workflows/e2eTests.yaml)

Add a New Subnet Store Backend (etcd vs Kubernetes API)

1. Create a new store package under pkg/subnet/yourstore/ implementing the subnet.SubnetLeaseManager interface (pkg/subnet/yourstore/yourstore.go)
2. Implement required methods: AcquireLease, RenewLease, WatchLeases, RevokeLease (pkg/subnet/subnet.go)
3. Add store type detection in main.go and instantiate your store based on configuration (main.go)
4. Document the new store option in Documentation/configuration.md (Documentation/configuration.md)

Add Support for a New Network Forwarding Mechanism

1. Create pkg/backend/newmech/newmech.go implementing Backend interface (pkg/backend/newmech/newmech.go)
2. Use pkg/net/net.go utilities to configure network interfaces and routes (pkg/net/net.go)
3. Register in backend factory and add tests under e2e/ (pkg/backend/backend.go)
4. Update Documentation/backends.md with performance characteristics and use cases (Documentation/backends.md)

Add a Configuration Option or Feature Flag

1. Add field to the Config struct in pkg/common/common.go (pkg/common/common.go)
2. Parse the option from environment variables or config file in main.go initialization (main.go)
3. Use the flag in your backend or subnet manager logic (pkg/backend/backend.go)
4. Document in Documentation/configuration.md with example values (Documentation/configuration.md)

• Go — Single, statically-compiled binary (flanneld) deployable to all nodes; excellent networking library support (netlink, iptables)
• etcd or Kubernetes API as coordination backend — Distributed lease allocation and subnet discovery without central broker; leverages existing infrastructure
• VXLAN / host-gw / cloud-native backends — Multiple forwarding mechanisms allow flexibility across private data centers, public clouds, and bare metal
• DaemonSet deployment model (Kubernetes) — Ensures flanneld runs on every node; auto-scales with cluster; integrates with standard Kubernetes lifecycle

• Single binary per node (flanneld) vs. embedded agent in container runtime

  • Why: Simplifies deployment and reduces runtime coupling; operator controls upgrade timing
  • Consequence: Adds small network overhead vs. native CNI but gains operational flexibility

• Pluggable backends with shared subnet manager interface

  • Why: Allows different forwarding mechanisms (VXLAN, direct routes, cloud APIs) on different clusters
  • Consequence: Complexity in testing all backend combinations; operator must match backend to infrastructure

• etcd or Kubernetes API as coordination layer (no custom control plane)

  • Why: Reuses existing cluster state store; no additional operational burden
  • Consequence: Performance limited by etcd/API server latency; cannot optimize for flannel-specific queries

• Layer 3 overlay networking (IP forwarding) vs. Layer 2 bridging

  • Why: Simpler, more scalable, avoids broadcast storms; integrates with standard routing
  • Consequence: Cannot support all workloads requiring Layer 2 semantics (limited L2 multicast support)

• CNI plugin implementation (flanneld is the agent; CNI is managed separately via containernetworking/plugins)
• Container runtime integration (runs as system daemon, not embedded in Docker/containerd)
• Traffic encryption at network layer (separate concern; IPsec or WireGuard via extensions)
• Network policy enforcement (not a replacement for Kubernetes NetworkPolicy; works alongside)
• Multi-cluster networking (single cluster scope; no federation built in)
• IPv6-only or dual-stack (primarily IPv4; IPv6 support partial/experimental)

Privileged mode required: flanneld needs root/CAP_NET_ADMIN to manage iptables, routes, and tunnels — manifests in Documentation/kube-flannel.yml use privileged containers. Backend-specific networking: VXLAN backend requires UDP 8472 multicast or unicast routes; host-gw requires direct IP connectivity; cloud backends need API credentials in env vars. etcd vs Kube subnet manager: choosing wrong one (env var FLANNEL_BACKEND_TYPE) breaks subnet allocation — kube-subnet-mgr (Kubernetes default) vs etcd-only modes have different failure modes. ipMasq rules interaction: can conflict with other networking policies if not carefully ordered. Go version lock: go 1.25.0 specified in go.mod — older Go versions may fail. Platform assumptions: Linux-centric core; Windows support is separate codepath (hcsshim).

• VXLAN (Virtual Extensible LAN) — Flannel's most popular backend — encapsulates L3 packets in L2 frames to tunnel across infrastructure; understanding VXLAN overhead and multicast/unicast modes is critical for production deployments
• Subnet Lease Allocation — Core flannel concept: each node gets an atomic lease on a /24 subnet from a larger pool; prevents IP collisions and enables stateless routing — understanding the lease lifecycle is essential for debugging multi-node issues
• CNI (Container Network Interface) — Flannel implements the CNI plugin spec to integrate with kubelet; this abstraction allows swappable networking backends — you need to understand how CNI handshakes work to debug pod networking failures
• IP Masquerading (IP Masq) — Flannel uses iptables NAT rules to masquerade cross-node traffic; misunderstanding masq rules causes packets to be silently dropped or routed incorrectly — see pkg/ip/ipmasq.go
• Network Namespaces (netns) — Flannel uses Linux network namespaces to isolate pod networking from the host; vishvananda/netns calls are critical for setting up routes and interfaces per-container
• Backend Abstraction Pattern — Flannel defines a Backend interface that lets you swap implementation strategies (VXLAN, host-gw, cloud-native); understanding this pattern is key to adding new backends or debugging backend-specific bugs
• Kubernetes Subnet Manager vs etcd Subnet Manager — Two different modes for storing subnet leases: kube-subnet-mgr uses Kubernetes objects (no extra etcd), etcd mode uses standalone etcd cluster — choice affects disaster recovery and architecture significantly

• containernetworking/cni — Defines the CNI specification that flannel implements; flannel is one reference implementation of this standard
• projectcalico/calico — Alternative Kubernetes networking solution focused on network policy (which flannel explicitly delegates to calico); often deployed alongside flannel
• coreos/etcd — Optional backend store for flannel's network state; flannel can use etcd directly instead of Kubernetes API
• kubernetes/kubernetes — Primary user ecosystem; flannel integrates deeply with Kubernetes API and is deployed as DaemonSet on every node
• k3s-io/k3s — Ships flannel by default; one of the most common deployment paths for flannel in production

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for nftables backend implementation

The repo has an ADR (Architecture Decision Record) at Documentation/adrs/add-nftables-implementation.md indicating nftables support was added, but there are likely minimal tests for this backend. Nftables is a critical networking component that needs robust testing alongside the existing iptables tests. This would improve reliability for users on modern Linux systems.

• [ ] Review Documentation/adrs/add-nftables-implementation.md to understand the nftables backend design
• [ ] Locate nftables backend implementation in the codebase (likely in pkg/backends or similar)
• [ ] Create test file pkg/backends/nftables_test.go with unit tests covering rule creation, deletion, and conflict resolution
• [ ] Add integration tests in the e2eTests workflow to validate nftables operations on test systems
• [ ] Compare test coverage with existing iptables tests (pkg/backends/iptables_test.go) to ensure parity

Add Helm chart CI validation workflow to catch configuration drift

The repo has a Helm chart (chart/kube-flannel/) but no dedicated CI workflow to validate Helm template rendering and schema compliance. Currently, only build.yaml, e2eTests.yaml, and golangci-lint.yaml exist. A Helm chart validation workflow would prevent misconfigurations from being released and ensure the chart stays in sync with the actual DaemonSet deployment.

• [ ] Create .github/workflows/helm-lint.yaml workflow file
• [ ] Add helm lint step for chart/kube-flannel/ to validate YAML syntax and Chart.yaml correctness
• [ ] Add helm template rendering test to verify all conditions and edge cases in templates/ (config.yaml, daemonset.yaml, rbac.yaml, serviceaccount.yaml)
• [ ] Validate rendered manifests against Kubernetes API schema using kubeval or similar
• [ ] Add workflow trigger on changes to chart/ directory to catch drift early

Add kustomization-based deployment tests to e2e test suite

The repo provides kustomization overlays at Documentation/kustomization/kube-flannel/ but there's no CI coverage for Kustomize-based deployments. This is a first-class deployment method that deserves e2e testing alongside the raw YAML and Helm approaches already covered in e2eTests.yaml and k3s-e2eTests.yml.

• [ ] Review Documentation/kustomization/kube-flannel/kustomization.yaml to understand overlay structure
• [ ] Add kustomize build step to .github/workflows/e2eTests.yaml to validate kustomization.yaml correctness
• [ ] Create new test stage in e2eTests.yaml that deploys flannel using kustomize build and applies it to test cluster
• [ ] Verify CNI plugin initialization and network connectivity with kustomize-deployed flannel
• [ ] Add example kustomization overlays for common use cases (e.g., with nftables backend, with custom VXLAN settings) to Documentation/kustomization/

• Add integration tests for the Aliyun (Ali Cloud) backend in Documentation/ — currently only AWS/GCE have detailed examples; repo lists ali-create-instance*.png images but no test coverage visible
• Document the nftables implementation decision (see Documentation/adrs/add-nftables-implementation.md) with runnable examples — ADR exists but integration guide for users wanting to switch from iptables is incomplete
• Add missing error handling tests in pkg/ip/ipcmd.go for iptables command failures — network setup commands can fail silently on misconfigured systems; tests could catch this before prod

• Medium · Outdated Go Version — go.mod (go 1.25.0). The project specifies Go 1.25.0 in go.mod. While this appears to be a future version, production deployments should use stable, widely-tested Go versions. Ensure the actual build process uses a supported Go version (currently 1.22.x or 1.23.x are recommended for production). Fix: Verify the actual Go version used in CI/CD pipelines and production builds. Update to the latest stable Go release (1.23.x LTS recommended). Review GitHub Actions workflows for Go version specifications.
• Medium · Incomplete Dependency Management Review — go.mod (incomplete require section). Multiple indirect dependencies are present with transitive pull-ins from cloud SDKs (tencentcloud-sdk-go, AWS via k8s.io) and networking libraries. The go.mod file shows truncated output ('// indire'), suggesting incomplete dependency listing. This makes it difficult to assess all transitive dependency risks. Fix: Run 'go mod graph' and 'go mod why' to audit all transitive dependencies. Use tools like 'nancy' or 'gosec' to scan for known vulnerabilities. Consider using 'go mod tidy' and reviewing the complete dependency tree.
• Medium · Potential Hardcoded Credentials in Sample Configuration — dist/sample_subnet.env and potentially .env files. The file 'dist/sample_subnet.env' suggests sample environment configuration files are present. Environment files can accidentally contain sensitive data like API keys, credentials, or tokens if not properly managed. Fix: Ensure all .env files in dist/ and Documentation/ are sample files with placeholder values only. Add .env to .gitignore if not already present. Document that users should never commit actual credentials. Implement pre-commit hooks to detect and prevent credential commits.
• Medium · Cloud Provider SDK Integration Risks — Dependencies: tencentcloud-sdk-go, k8s.io/client-go (AWS), Documentation/tencentcloud-vpc-backend.md. The codebase integrates with multiple cloud providers (TencentCloud, AWS via k8s.io, Alibaba Cloud based on documentation). These integrations require credentials (access keys, secret keys) which, if improperly handled, could lead to credential exposure or unauthorized cloud resource access. Fix: Implement strict credential management: use IAM roles/service accounts instead of static credentials. Document secure credential handling in SECURITY.md. Audit cloud SDK usage for proper credential handling and temporary credential support. Review credential passing mechanisms in flannel configuration.
• Medium · Incomplete Security Policy Documentation — SECURITY.md (incomplete). The SECURITY.md file is truncated at 'Disclosure Policy' section. The complete vulnerability response timeline and SLA are not visible, which could confuse users about expected response times for security reports. Fix: Complete the SECURITY.md file with full disclosure policy including: expected response timelines (e.g., 90-day window), patch release schedules, and security contact information. Specify whether pre-disclosure coordination with major cloud providers occurs.
• Low · Dependency on Legacy JWT Library Pattern — go.mod (commented replace directive). The commented-out replace directive 'replace github.com/dgrijalva/jwt-go => github.com/golang-jwt/jwt/v4' suggests a historical migration from an unmaintained JWT library. While currently commented out, this indicates the codebase may have had this dependency. Fix: Verify that no active dependencies on github.com/dgrijalva/jwt-go exist. Run 'go mod graph | grep dgrijalva' to confirm. If transitively required, ensure it comes through a trusted path. Keep the replacement directive as documentation of the migration path.
• Low · Docker Image Build Without Explicit Security Scanning — .dockerignore, .github/workflows/trivy.yml. While trivy.yml workflow is present for scanning, the .dockerignore and docker build process configuration are not visible for detailed review. Dockerfile best practices (multi-stage builds, minimal base images, non-root user) cannot be verified from provided files. Fix: Ensure Dockerfile uses minimal base images (alpine or distroless recommended). Implement multi-stage builds to reduce attack surface. Run container as non-root user. Verify trivy scanning occurs for all published images. Document base image and scanning results in

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.