Cilium 1.20 CLI 命令详解：cilium 与 hubble

目标：系统整理 Cilium 1.20 配套的两套命令行工具——cilium CLI（v0.20.1，集群安装/状态/连通性管理）与 hubble CLI（v1.20.2，流观测客户端）的命令体系、核心参数与实战用法。所有帮助文本与命令回显均在本系列实测环境（k3s v1.36.5 单节点 + Cilium 1.20.4）逐行照抄；安装过程见《Cilium 1.20 部署指南：在 k3s 上安装与验证》。

一、两套 CLI 的定位

工具	版本	定位	典型命令
cilium	v0.20.1	集群生命周期管理：安装、升级、卸载、状态、连通性测试、配置	cilium install / status / connectivity test
hubble	v1.20.2	流量观测客户端：读取 Hubble 服务端（Relay）的流事件	hubble status / observe / list nodes

两套工具都通过 kubeconfig 连接集群；hubble CLI 还需要能访问 hubble-relay 的 4245 端口（本地端口转发，见 3.4 与 FAQ）。

cilium version

实测输出：

cilium-cli: v0.20.1 compiled with go1.27.1 on linux/amd64
cilium image (default): v1.20.1
cilium image (stable): v1.20.4
cilium image (running): 1.20.4

二、cilium CLI 命令详解

2.1 命令总览

cilium --help

实测输出（照抄）：

CLI to install, manage, & troubleshooting Cilium clusters running Kubernetes.

Cilium is a CNI for Kubernetes to provide secure network connectivity and
load-balancing with excellent visibility using eBPF

Examples:

Install Cilium in current Kubernetes context

  $ cilium install

Check status of Cilium

  $ cilium status

Enable the Hubble observability layer

  $ cilium hubble enable

Perform a connectivity test

  $ cilium connectivity test

Usage:
  cilium [flags]
  cilium [command]

Available Commands:
  bgp          Access to BGP control plane
  clustermesh  Multi Cluster Management
  completion   Generate the autocompletion script for the specified shell
  config       Manage Configuration
  connectivity Connectivity troubleshooting
  context      Display the configuration context
  encryption   Cilium encryption
  features     Report which features are enabled in Cilium agents
  help         Help about any command
  hubble       Hubble observability
  install      Install Cilium in a Kubernetes cluster using Helm
  multicast    Manage multicast groups
  status       Display status
  sysdump      Collects information required to troubleshoot issues with Cilium and Hubble
  uninstall    Uninstall Cilium using Helm
  upgrade      Upgrade a Cilium installation a Kubernetes cluster using Helm
  version      Display detailed version information

Flags:
      --as string                  Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
      --as-group stringArray       Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --context string             Kubernetes configuration context
      --helm-release-name string   Helm release name (default "cilium")
  -h, --help                       help for cilium
      --kubeconfig string          Path to the kubeconfig file
  -n, --namespace string           Namespace Cilium is running in. Can also be set via CILIUM_NAMESPACE env var (default "kube-system")

Use "cilium [command] --help" for more information about a command.

全局要点：cilium CLI 底层就是 Helm（--helm-release-name 默认 cilium），默认命名空间 kube-system（-n 或环境变量 CILIUM_NAMESPACE 可改）。

2.2 cilium status：健康状态一把抓

cilium status --wait=false

实测输出（逐行照抄）：

    /¯¯\
 /¯¯\__/¯¯\    Cilium:             OK
 \__/¯¯\__/    Operator:           OK
 /¯¯\__/¯¯\    Envoy DaemonSet:    OK
 \__/¯¯\__/    Hubble Relay:       OK
    \__/       ClusterMesh:        disabled

DaemonSet              cilium                   Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet              cilium-envoy             Desired: 1, Ready: 1/1, Available: 1/1
Deployment             cilium-operator          Desired: 1, Ready: 1/1, Available: 1/1
Deployment             hubble-relay             Desired: 1, Ready: 1/1, Available: 1/1
Containers:            cilium                   Running: 1
                       cilium-envoy             Running: 1
                       cilium-operator          Running: 1
                       clustermesh-apiserver
                       hubble-relay             Running: 1
Cluster Pods:          17/17 managed by Cilium
Helm chart version:    1.20.4
Image versions         cilium             quay.io/cilium/cilium:v1.20.4@sha256:20fe92e4c86641233a450098c158d2d29085f3419931ab6bf681d2485dedf16e: 1
                       cilium-envoy       quay.io/cilium/cilium-envoy:v1.39.5-1792733054-8c73b2816bc8239e27f1fd53b271884688137459@sha256:547ab45f6092f681d9f54f3be9fa8fb1e705c9c5dc2df388efe3a52aa6965629: 1
                       cilium-operator    quay.io/cilium/operator-generic:v1.20.4@sha256:7a7a3489dc66ad67e420d285c8a8d2e169b0957ad15e120f593d27081bf38d82: 1
                       hubble-relay       quay.io/cilium/hubble-relay:v1.20.4@sha256:cb23408209697ed30d2bc462e1f01eb622ea4423a891458f78bc88d7255bbfc1: 1

常用 flags：

--wait：阻塞等待所有组件就绪（安装/滚动更新后必用）；
--wait=false：立即返回当前状态（脚本化巡检用）；
--wait-duration 180s：限定最长等待时长，避免无限阻塞。

2.3 cilium config view：运行时生效配置

cilium config view

输出 Agent 实际生效的全部配置键值（本环境实测 161 个键），是验证参数修改结果的第一入口。配置体系与改参数闭环的完整详解见《Cilium 1.20 配置参数详解》。常用组合：

cilium config view | grep '^bpf-policy-map-max'

2.4 cilium install / upgrade / uninstall：生命周期三件套

安装（--set 与 values 键名映射、逐行回显与排障见部署篇第五节）：

cilium install --version 1.20.4 \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=10.89.69.10 \
  --set k8sServicePort=6443 \
  --set ipam.operator.clusterPoolIPv4PodCIDRList=10.200.0.0/16 \
  --set hubble.relay.enabled=true \
  --set operator.replicas=1 \
  --set routingMode=tunnel \
  --set tunnelProtocol=vxlan

实测输出（照抄）：

ℹ️  Using Cilium version 1.20.4
🔮 Auto-detected cluster name: default
🔮 Auto-detected kube-proxy has not been installed
ℹ️  Cilium will fully replace all functionalities of kube-proxy

升级（底层等价 helm upgrade，改完必须 cilium status --wait 验证）：

cilium upgrade --version 1.20.4 --set bpf.policyMapMax=32768

卸载：

cilium uninstall

三个命令共用全局 flags：--version（chart 版本）、--set k=v（values 覆盖）、-n kube-system（发布命名空间）、--helm-release-name（发布名，默认 cilium）。

2.5 cilium connectivity test：官方连通性矩阵

cilium connectivity test

行为：自动创建 cilium-test-1 等测试命名空间，部署 client/echo 测试负载，按官方矩阵执行 70+ 项动作（Pod 间、Service、DNS、NetworkPolicy L3/L4/L7）并输出汇总；结束时自动清理。

本系列单节点环境实测结论（汇总行照抄）：

❌ 2/22 tests failed (4/73 actions), 12 tests skipped, 0 scenarios skipped:

失败项均为 pod-to-world 外网访问（环境无公网出口，curl (28) Timeout was reached）；跳过项均为需要第二个节点的跨节点场景。结论解读与排障见部署篇第七节。

常用 flags：

--force-deploy：中断后重跑时强制重建测试负载；
--test '<匹配表达式>'：只跑部分测试（如 --test '!/pod-to-world/' 排除外网项）；
--timeout 5m：单步超时。

2.6 cilium hubble 子命令组

cilium hubble --help

实测输出（照抄）：

Hubble observability

Usage:
  cilium hubble [command]

Available Commands:
  disable      Disable Hubble observability using Helm
  enable       Enable Hubble observability using Helm
  port-forward Forward the relay port to the local machine
  ui           Open the Hubble UI

Flags:
  -h, --help   help for hubble

Global Flags:
      --as string                  Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
      --as-group stringArray       Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --context string             Kubernetes configuration context
      --helm-release-name string   Helm release name (default "cilium")
      --kubeconfig string          Path to the kubeconfig file
  -n, --namespace string           Namespace Cilium is running in. Can also be set via CILIUM_NAMESPACE env var (default "kube-system")

Use "cilium hubble [command] --help" for more information about a command.

cilium hubble enable：为已有集群补装 Hubble（等价 --set hubble.relay.enabled=true 的 helm 操作）；
cilium hubble disable：关闭 Hubble；
cilium hubble port-forward：把 hubble-relay 端口转发到本机 localhost:4245（hubble CLI 的数据通道，实测执行后 hubble status 即通）；
cilium hubble ui：在浏览器打开 Hubble UI。

2.7 其他运维子命令速查

命令	用途
cilium clustermesh status/enable/connect	多集群 ClusterMesh 的开启、状态与互联
cilium bgp peers / routes	查看 BGP 控制面邻居与路由宣告
cilium encryption status	加密（WireGuard/IPsec）状态
cilium features status	汇报 Agent 当前启用的特性清单
cilium sysdump	一键收集排障材料（组件状态、日志、配置打包）
cilium context / multicast	显示当前上下文；管理多播组

三、hubble CLI 命令详解

3.1 命令总览

hubble --help

实测输出（照抄）：

Hubble is a utility to observe and inspect recent Cilium routed traffic in a cluster.

Usage:
  hubble [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Modify or view hubble config
  help        Help about any command
  list        List Hubble objects
  observe     Observe flows and events of a Hubble server
  status      Display status of Hubble server
  version     Display detailed version information

Global Flags:
      --config string   Optional config file (default "/root/.config/hubble/config.yaml")
  -D, --debug           Enable debug messages

Get help:
  -h, --help	Help for any command or subcommand

Use "hubble [command] --help" for more information about a command.

3.2 hubble status：服务端健康与缓冲水位

前置：先打通到 Relay 的端口转发（另开终端保持运行）：

cilium hubble port-forward

然后：

hubble status

实测输出（照抄）：

Healthcheck (via localhost:4245): Ok
Current/Max Flows: 4,095/4,095 (100.00%)
Flows/s: 108.32
Connected Nodes: 1/1

解读：Current/Max Flows 是每节点流缓冲的水位（环形缓冲，写满后覆盖最旧事件，100% 属正常）；Flows/s 是当前事件速率；Connected Nodes 是 Relay 已连上的节点数。

3.3 hubble list nodes：节点连接视图

hubble list nodes

实测输出（照抄）：

NAME         STATUS      AGE     FLOWS/S   CURRENT/MAX-FLOWS
k3s-server   Connected   4m52s   108.54    4095/4095 (100.00%)

3.4 hubble observe：流观测主命令

hubble observe 读取流缓冲并支持 60+ 个过滤参数，是最常用的排障命令。帮助文本（hubble observe --help）实测共 190 行，以下分段照抄核心部分。

用法与子命令：

Usage:
  hubble observe [flags]
  hubble observe [command]

Available Commands:
  agent-events Observe Cilium agent events
  debug-events Observe Cilium debug events
  flows        Observe flows of a Hubble server

Selectors Flags（取数范围）（照抄）：

      --all            Get all flows stored in Hubble's buffer. Note: this option may cause Hubble to return a lot of data. It is recommended to only use it along filters to limit the amount of data returned.
      --first uint     Get first N flows stored in Hubble's buffer. When querying against Hubble Relay, this gets N flows per instance of Hubble connected to that Relay.
  -f, --follow         Follow flows output
      --last uint      Get last N flows stored in Hubble's buffer (default 20). When querying against Hubble Relay, this gets N flows per instance of Hubble connected to that Relay.
      --since string   Filter flows since a specific date. The format is relative (e.g. 3s, 4m, 1h43,, ...) or one of:
                         StampMilli:             Jan _2 15:04:05.000
                         YearMonthDay:           2006-01-02
                         YearMonthDayHour:       2006-01-02T15-07:00
                         YearMonthDayHourMinute: 2006-01-02T15:04-07:00
                         RFC3339:                2006-01-02T15:04:05-07:00
                         RFC3339Milli:           2006-01-02T15:04:05.999-07:00
                         RFC3339Micro:           2006-01-02T15:04:05.999999-07:00
                         RFC3339Nano:            2006-01-02T15:04:05.999999999-07:00
                         RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700
                        
      --until string   Filter flows until a specific date. The format is relative (e.g. 3s, 4m, 1h43,, ...) or one of:
                         StampMilli:             Jan _2 15:04:05.000
                         YearMonthDay:           2006-01-02
                         YearMonthDayHour:       2006-01-02T15-07:00
                         YearMonthDayHourMinute: 2006-01-02T15:04-07:00
                         RFC3339:                2006-01-02T15:04:05-07:00
                         RFC3339Milli:           2006-01-02T15:04:05.999-07:00
                         RFC3339Micro:           2006-01-02T15:04:05.999999-07:00
                         RFC3339Nano:            2006-01-02T15:04:05.999999999-07:00
                         RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700

Filters Flags（过滤条件），最常用的一批（照抄）：

  -A, --all-namespaces filter[=true]        Show all flows in any Kubernetes namespace.
      --cel-expression filter               Filter flows using the given CEL expression
      --drop-reason-desc filter             Show only flows which match this drop reason describe (e.g. "POLICY_DENIED", "UNSUPPORTED_L3_PROTOCOL")
      --encrypted filter[=true]             Show only encrypted flows (WireGuard/IPsec)
      --fqdn filter                         Show all flows related to the given fully qualified domain name (e.g. "*.cilium.io").
      --from-ip filter                      Show all flows originating at the given IP address. Each of the source IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
      --from-label filter                   Show only flows originating in an endpoint with the given labels (e.g. "key1=value1", "reserved:world")
      --from-namespace filter               Show all flows originating in the given Kubernetes namespace.
      --from-pod filter                     Show all flows originating in the given pod name prefix([namespace/]<pod-name>). If namespace is not provided, 'default' is used
      --from-port filter                    Show only flows with the given source port (e.g. 8080)
      --http-method filter                  Show only flows which match this HTTP method (e.g. "get", "post")
      --http-path filter                    Show only flows which match this HTTP path regular expressions (e.g. "/page/\\d+")
      --http-status filter                  Show only flows which match this HTTP status code prefix (e.g. "404", "5+")
      --identity filter                     Show all flows related to an endpoint with the given security identity
      --ip filter                           Show all flows originating or terminating at the given IP address. Each of the IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
  -l, --label filter                        Show only flows related to an endpoint with the given labels (e.g. "key1=value1", "reserved:world")
  -n, --namespace filter                    Show all flows related to the given Kubernetes namespace.
      --node-name filter                    Show all flows which match the given node names (e.g. "k8s*", "test-cluster/*.company.com")
      --not filter[=true]                   Reverses the next filter to be blacklist i.e. --not --from-ip 2.2.2.2
      --not-reply filter[=true]             Show only non-reply flows
      --pod filter                          Show all flows related to the given pod name prefix ([namespace/]<pod-name>). If namespace is not provided, 'default' is used.
      --port filter                         Show only flows with given port in either source or destination (e.g. 8080)
      --protocol filter                     Show only flows which match the given L4/L7 flow protocol (e.g. "udp", "http")
      --reply filter[=true]                 Show only reply flows
      --service filter                      Shows flows where either the source or destination IP address matches the ClusterIP address of the given service name prefix ([namespace/]<svc-name>). If namespace is not provided, 'default' is used. 
      --tcp-flags filter                    Show only flows which match the given TCP flags (e.g. "syn", "ack", "fin")
      --to-ip filter                        Show all flows terminating at the given IP address. Each of the destination IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
      --to-namespace filter                 Show all flows terminating in the given Kubernetes namespace.
      --to-pod filter                       Show all flows terminating in the given pod name prefix([namespace/]<pod-name>). If namespace is not provided, 'default' is used
      --to-port filter                      Show only flows with the given destination port (e.g. 8080)
      --to-service filter                   Shows flows where the destination IP address matches the ClusterIP address of the given service name prefix ([namespace/]<svc-name>). If namespace is not provided, 'default' is used
      --traffic-direction filter            Show all flows in the given traffic direction (either ingress or egress)
      --verdict filter                      Show only flows with this verdict [FORWARDED, DROPPED, AUDIT, REDIRECTED, ERROR, TRACED, TRANSLATED]

Formatting Flags（输出格式）（照抄）：

  -o, --output string        Specify the output format, one of:
                               compact:  Compact output
                               dict:     Each flow is shown as KEY:VALUE pair
                               jsonpb:   JSON encoded GetFlowResponse according to proto3's JSON mapping
                               json:     Alias for jsonpb
                               table:    Tab-aligned columns
                              (default "compact")
      --print-node-name      Print node name in output
      --print-policy-names   Print policy names in output
      --time-format string   Specify the time format for printing. This option does not apply to the json and jsonpb output type. One of:
                               StampMilli:             Jan _2 15:04:05.000
                               YearMonthDay:           2006-01-02
                               YearMonthDayHour:       2006-01-02T15Z07:00
                               YearMonthDayHourMinute: 2006-01-02T15:04Z07:00
                               RFC3339:                2006-01-02T15:04:05Z07:00
                               RFC3339Milli:           2006-01-02T15:04:05.999Z07:00
                               RFC3339Micro:           2006-01-02T15:04:05.999999Z07:00
                               RFC3339Nano:            2006-01-02T15:04:05.999999999Z07:00
                               RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700
                               (default "StampMilli")

Server Flags（连接方式），核心三行（照抄）：

  -P, --port-forward                  Automatically forward the relay port to the local machine. Analoguous to running: 'cilium hubble port-forward'.
      --port-forward-port uint16      Local port to forward to. 0 will select a random port. This option is only considered when --port-forward is set. (default 4245)
      --server string                 Address of a Hubble server. Ignored when --input-file or --port-forward is provided. (default "localhost:4245")

💡 提示：-P 可让 observe 自动完成端口转发，免去单独运行 cilium hubble port-forward——hubble observe -P --last 10 是一条命令直达的排障形态。

3.5 实战一：观察放行流量（FORWARDED）

先在测试负载中触发一次 HTTP 请求，再取最近事件：

kubectl -n cilium-test-1 exec deploy/client -- \
  curl -s --max-time 5 http://echo-same-node.cilium-test-1.svc.cluster.local:8080/ -o /dev/null

hubble observe --last 15

实测输出（照抄，字段含义见下）：

Oct 23 20:29:21.091: 10.0.0.250:46782 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8080 (ID:52222) to-stack FORWARDED (TCP Flags: ACK, PSH)
Oct 23 20:29:21.091: 10.0.0.250:46782 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8080 (ID:52222) to-stack FORWARDED (TCP Flags: ACK, FIN)
Oct 23 20:29:21.091: 10.0.0.250:46782 (host) -> cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8080 (ID:52222) to-endpoint FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:46782 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8080 (ID:52222) to-stack FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:50804 (host) -> cilium-test-1/l7-lb-7ddb9855ff-pg7xt:8181 (ID:31636) to-endpoint FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:50804 (host) <- cilium-test-1/l7-lb-7ddb9855ff-pg7xt:8181 (ID:31636) to-stack FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:45636 (host) -> cilium-test-1/l7-lb-7ddb9855ff-pg7xt:8080 (ID:31636) to-endpoint FORWARDED (TCP Flags: ACK, FIN)
Oct 23 20:29:21.091: 10.0.0.250:45636 (host) <- cilium-test-1/l7-lb-7ddb9855ff-pg7xt:8080 (ID:31636) to-stack FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:49424 (host) -> cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8181 (ID:52222) to-endpoint FORWARDED (TCP Flags: ACK, FIN)
Oct 23 20:29:21.091: 10.0.0.250:49424 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8181 (ID:52222) to-stack FORWARDED (TCP Flags: ACK)
Oct 23 20:29:21.091: 10.0.0.250:49424 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8181 (ID:52222) to-stack FORWARDED (TCP Flags: ACK, PSH)
Oct 23 20:29:21.091: 10.0.0.250:49424 (host) <- cilium-test-3/l7-lb-7ddb9855ff-bfjp4:8181 (ID:52222) to-stack FORWARDED (TCP Flags: ACK, FIN)
Oct 23 20:29:21.091: 10.0.0.250:55450 (host) <- cilium-test-2/l7-lb-7ddb9855ff-vhdzh:8080 (ID:46057) to-stack FORWARDED (TCP Flags: ACK, PSH)
Oct 23 20:29:21.091: 10.0.0.250:55450 (host) <- cilium-test-2/l7-lb-7ddb9855ff-vhdzh:8080 (ID:46057) to-stack FORWARDED (TCP Flags: ACK, FIN)
Oct 23 20:29:21.091: 10.0.0.250:55450 (host) -> cilium-test-2/l7-lb-7ddb9855ff-vhdzh:8080 (ID:46057) to-endpoint FORWARDED (TCP Flags: ACK, FIN)

一行流事件的字段结构：时间: 源IP:端口 (源身份) 方向目标:端口 (安全身份ID) 数据面方向判定 (TCP标志)。-> 请求方向、<- 应答方向；to-endpoint/to-stack 描述数据面路径；FORWARDED 表示放行。

3.6 实战二：定位被策略拒绝的流量（DROPPED）

被 NetworkPolicy 拒绝的流量用 --verdict DROPPED 一击定位：

hubble observe --last 5 --verdict DROPPED

实测输出（照抄）：

Oct 23 20:29:18.861: 10.0.0.250:52514 (ID:11151) <> cilium-test-1/echo-same-node-55ddf564bd-zfc85:8080 (ID:4685) Policy denied DROPPED (TCP Flags: SYN)
Oct 23 20:29:19.885: 10.0.0.250:52514 (ID:11151) <> cilium-test-1/echo-same-node-55ddf564bd-zfc85:8080 (ID:4685) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Oct 23 20:29:19.885: 10.0.0.250:52514 (ID:11151) <> cilium-test-1/echo-same-node-55ddf564bd-zfc85:8080 (ID:4685) Policy denied DROPPED (TCP Flags: SYN)
Oct 23 20:29:20.909: 10.0.0.250:52514 (ID:11151) <> cilium-test-1/echo-same-node-55ddf564bd-zfc85:8080 (ID:4685) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Oct 23 20:29:20.909: 10.0.0.250:52514 (ID:11151) <> cilium-test-1/echo-same-node-55ddf564bd-zfc85:8080 (ID:4685) Policy denied DROPPED (TCP Flags: SYN)

解读：<> 表示连接被拦截；policy-verdict:none INGRESS DENIED 说明入方向策略检查没有匹配到放行规则（default deny）→ Policy denied DROPPED 丢包。排障路径：确认源/目标身份 → 检查命中端点的 NetworkPolicy/CiliumNetworkPolicy → 补充放行规则 → 用同命令复核变为 FORWARDED。

3.7 实战三：结构化输出

机器处理时切换输出格式：

hubble observe --last 1 -o dict
hubble observe --last 5 -o jsonpb | jq '.flow[].verdict'

-o dict 把一行摘要展开为键值对；-o jsonpb 输出完整 proto3 JSON（含 Time、Verdict、IP、l4、l7 全字段），适合接脚本或日志管道。

四、常见问题

4.1 hubble status 报 connection refused

现象：Healthcheck (via localhost:4245) 失败、dial tcp 127.0.0.1:4245: connect: connection refused。原因：hubble CLI 默认连本机 4245，而 hubble-relay 在集群里。解决任选其一：

cilium hubble port-forward     # 方式一：常驻端口转发
hubble observe -P --last 10    # 方式二：observe 用 -P 自动转发

4.2 hubble observe 没有输出

流缓冲只保留最近事件：过滤条件太窄或目标流量太早都可能查不到。放宽 --last 数值、去掉部分过滤，或先制造目标流量（curl/ping）再查；-f 可挂起等待新事件实时输出。

4.3 Flows 显示 100.00% 是不是满了会丢

Hubble 每节点流缓冲是环形结构，写满后覆盖最旧事件（hubble status 的 100% 表示缓冲被写满过），查询"最近 N 条"不受影响；需要长留存时应接 Prometheus/Grafana 或流日志外送，而不是调大本地缓冲。

4.4 cilium status 某组件不 OK 怎么排查

按输出定位组件后逐层下钻：kubectl -n kube-system get pods -o wide 看对应 Pod 状态 → kubectl logs 看 Agent 日志 → 仍无法定位时 cilium sysdump 打包全部排障材料一并分析。

五、参考链接

cilium CLI 命令参考：https://docs.cilium.io/en/stable/reference/cmdref/
hubble CLI 命令参考：https://docs.cilium.io/en/stable/reference/hubble-cli/
Hubble 观测文档：https://docs.cilium.io/en/stable/observability/hubble/
cilium-cli 发布页：https://github.com/cilium/cilium-cli/releases
hubble 发布页：https://github.com/cilium/hubble/releases

本系列导航

《Cilium 1.20 介绍与选型指南》——定位、eBPF 架构与 Calico/Flannel 量化对比
《Cilium 1.20 部署指南：在 k3s 上安装与验证》——从零安装与完整验证回显
《Cilium 1.20 配置参数详解》——三层配置体系与改参数闭环
本篇：Cilium 1.20 CLI 命令详解：cilium 与 hubble