cilium CLI

Active contributors: sayboras, mhofstetter, michi-covalent, rolinh, glibsm

Purpose

The cilium CLI under cilium-cli/ is the user-facing administrative tool. It installs Cilium into a cluster, performs upgrades, runs the connectivity test suite, exercises Hubble, manages BGP / Cluster Mesh / encryption / Gateway API features, and produces sysdumps for support cases.

It used to live in a separate repo (cilium/cilium-cli) and has been merged into the monorepo. Its layout still reflects that history.

Directory layout

cilium-cli/
├── cli/             # cobra command tree (subcommands)
├── cmd/             # main package
├── install/         # `cilium install` and `cilium upgrade`
├── connectivity/    # `cilium connectivity test`
├── clustermesh/     # `cilium clustermesh ...`
├── hubble/          # `cilium hubble enable/disable/port-forward`
├── bgp/             # `cilium bgp peers / routes`
├── encrypt/         # `cilium encrypt status`
├── multicast/       # `cilium multicast ...`
├── status/          # `cilium status`
├── sysdump/         # `cilium sysdump`
├── features/        # `cilium features status`
├── config/          # `cilium config`
├── api/             # k8s + Cilium API helpers
├── k8s/             # Kubernetes client wrapper
├── internal/        # internal helpers (HTTP, retries, etc.)
├── utils/           # cross-cutting utilities
├── defaults/        # versioned defaults (image tags, helm values)
├── logging/         # CLI logging
└── Makefile

Key subcommands

Command	Path	What it does
cilium install	cilium-cli/install/	Installs the Cilium Helm chart, with cloud detection.
cilium upgrade	cilium-cli/install/upgrade.go	Runs Helm upgrade with the chart embedded in the CLI.
cilium uninstall	cilium-cli/install/uninstall.go	Uninstalls Cilium and cleans up resources.
cilium status	cilium-cli/status/	Aggregates DaemonSet readiness, identity counts, and feature flags.
cilium connectivity test	cilium-cli/connectivity/	Massive end-to-end test suite with hundreds of scenarios.
cilium hubble *	cilium-cli/hubble/	Toggles Hubble, port-forwards Relay, runs queries.
cilium clustermesh *	cilium-cli/clustermesh/	Connects two clusters, generates certificates, prints status.
cilium bgp *	cilium-cli/bgp/	Reads BGP peers, advertised routes, route policies.
cilium sysdump	cilium-cli/sysdump/	Collects a tarball of cluster state for support cases.
cilium features status	cilium-cli/features/	Reports which Cilium features are enabled in the live cluster.

How it works

The CLI talks to two surfaces:

• kube-apiserver via client-go. Most commands inspect or modify Kubernetes objects (DaemonSet, ConfigMap, Cilium CRDs).
• Agent REST API via the generated client at api/v1/client/. This drives commands like cilium hubble observe, cilium endpoint list (when port-forwarded), and cilium status for in-pod data.

graph LR
    User[User]
    CLI[cilium CLI]
    Helm[(Embedded Helm chart)]
    K8s[kube-apiserver]
    AgentREST[Agent /v1/...]

    User --> CLI
    CLI --> Helm
    CLI --> K8s
    CLI --> AgentREST
    Helm --> CLI

The Helm chart is embedded at build time using go:embed against install/kubernetes/cilium/. Versioned defaults (image tags, recommended Helm values) live under cilium-cli/defaults/.

Connectivity test framework

The connectivity test (cilium-cli/connectivity/) is itself a small framework:

• tests/ — individual scenarios (pod-to-pod, pod-to-service, north-south, FQDN, encryption, ...).
• check/ — the runner that deploys probe pods and asserts flows through Hubble.
• manifests/ — YAML for probe pods (echo-same-node, echo-other-node, client, ...).
• Each scenario takes labels, runs, and reports a pass/fail using a combination of kubectl exec probes and Hubble flow assertions.

CI exercises a curated subset on every PR; full suites run on release-blocking workflows.

Integration points

• Embeds the Helm chart from install/kubernetes/cilium/.
• Imports pkg/k8s/, pkg/option/, pkg/version/, and the generated agent API client.
• Output formats: human, json, yaml, markdown (depending on subcommand).

Entry points for modification

• New subcommands: add a file under cilium-cli/cli/ and register it in the cobra root.
• New connectivity scenarios: implement a check.Scenario under cilium-cli/connectivity/tests/ and register it in tests/tests.go.
• New install knobs: extend cilium-cli/install/install.go and update embedded Helm values.

Key source files

File	Purpose
cilium-cli/cmd/cilium.go	Cobra root command.
cilium-cli/install/install.go	The install flow with cloud detection.
cilium-cli/connectivity/check/test.go	Connectivity test core.
cilium-cli/sysdump/sysdump.go	Sysdump collector.
cilium-cli/Makefile	Build, vendor, lint targets.