Contents
前提条件とインストール環境の準備
Kubernetes クラスタと CLI ツール（kubectl, helm）が 対応バージョン であることを最初にチェックします。これにより、Cilium がサポートする Kubernetes バージョン範囲外での不具合を防げます。
kubectl と Helm のバージョン確認方法
まずはクライアント側とサーバー側の両方を確認してください。
|
1 2 3 4 5 6 7 8 9 |
# クライアント版 (推奨: 1.27.x 以上) kubectl version --client --short # サーバー版 (Kubernetes 1.24〜1.28 が対象) kubectl version -o yaml | grep "serverVersion" # Helm のバージョン (v3.12 以降推奨) helm version --short |
kubectl version の出力例
|
1 2 3 4 5 6 7 8 9 |
clientVersion: major: "1" minor: "27" gitVersion: v1.27.4 serverVersion: major: "1" minor: "27" gitVersion: v1.27.3 |
サーバーの gitVersion が 1.24〜1.28 の範囲に入っていることを必ず確認し、公式ドキュメント（https://docs.cilium.io/en/stable/observability/hubble/setup/）と照らし合わせてください。
ローカルクラスター構築 (kind / minikube)
ローカル環境は 軽量でリセットが容易 なことから、開発・検証に最適です。以下では kind と minikube の両方の手順を示します。
kind クラスターの作成と LoadBalancer 対応
kind はデフォルトで LoadBalancer タイプの Service を外部に公開できません。そのため MetalLB などのロードバランサ実装を併用するか、代替として NodePort を使用します。ここでは最もシンプルな NodePort + ポートマッピング の例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# 1. kind のインストール（Homebrew） brew install kind # 2. クラスタ設定ファイル (kind-config.yaml) 作成 cat <<'EOF' > kind-config.yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane image: kindest/node:v1.27.3 extraPortMappings: # Hubble UI 用に NodePort をホスト側へマッピング - containerPort: 30080 # Service の nodePort (例) hostPort: 30080 EOF # 3. クラスタ作成（--name は任意） kind create cluster --config=kind-config.yaml |
ポイント
extraPortMappingsはkindが内部で Docker コンテナを起動しているため、ホストマシンのポートとコンテナ側ポートを結びつけます。
本番環境では MetalLB など正式な LoadBalancer 実装に置き換えることが推奨されます。
minikube クラスターの作成
|
1 2 3 4 5 6 7 |
# Homebrew でインストール brew install minikube # Kubernetes バージョン 1.27 系を指定して起動 minikube start --kubernetes-version=v1.27.3 \ --extra-config=apiserver.service-node-port-range=30000-32767 |
minikube は --driver=docker（デフォルト）でも LoadBalancer が自動的に NodePort に変換されるため、特別な設定は不要です。
Hubble UI のデプロイとアクセス設定
このセクションでは Helm Chart を用いた Hubble UI のインストール と、外部からのアクセス手段（Ingress / port‑forward）を解説します。
Helm Chart の取得と values.yaml カスタマイズ例
公式リポジトリを追加し、デフォルトの values.yaml を取得した上で必要な項目だけを書き換えます。
|
1 2 3 4 5 6 |
helm repo add cilium https://helm.cilium.io/ helm repo update # デフォルト values の保存 (ローカル編集用) helm show values cilium/hubble-ui > hubble-values.yaml |
hubble-values.yaml に追記すべき主な設定
| 項目 | 推奨値 / コメント |
|---|---|
ui.service.type |
NodePort（kind/minikube では LoadBalancer が機能しないため） |
ui.service.nodePort |
任意のポート (例: 30080)。extraPortMappings と合わせる |
ui.relay.enabled |
true（Relay 経由でメトリクス取得） |
ui.relay.address |
hubble-relay.hubble.svc.cluster.local:4245 |
ingress.enabled |
必要に応じて true。外部 DNS と TLS がある場合のみ有効化 |
ingress.hosts[0].host |
本番環境の FQDN（例: hubble.example.com） |
ingress.tls[0].secretName |
事前に作成した TLS シークレット名 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
ui: service: type: NodePort # ローカルは NodePort、クラウドは LoadBalancer 推奨 nodePort: 30080 port: 80 relay: enabled: true address: hubble-relay.hubble.svc.cluster.local:4245 ingress: enabled: false # テスト時は無効化、必要に応じて true に変更 |
デプロイコマンドと namespace 対策
Helm はデフォルトで対象の Namespace が存在しないとエラーになります。--create-namespace オプションを付与して自動作成させるか、事前に kubectl create ns してください。
|
1 2 3 4 5 |
helm upgrade --install hubble-ui cilium/hubble-ui \ -f hubble-values.yaml \ --namespace kube-system \ --create-namespace # Namespace が無い場合は自動作成 |
デプロイ完了後は以下でリソースが正しく作成されたか確認します。
|
1 2 |
kubectl -n kube-system get all -l app.kubernetes.io/name=hubble-ui |
アクセス方法：Ingress と port‑forward の使い分け
| 手段 | 特徴 | 推奨シーン |
|---|---|---|
| Ingress | TLS 終端やホスト名でのルーティングが可能。外部 DNS が必要。 | 本番環境・複数サービス共存時 |
| port‑forward | 手軽にローカルから確認できる。一時的なデバッグ向き。 | ローカル開発・トラブルシュート |
port‑forward の実行例
|
1 2 3 |
kubectl -n kube-system port-forward svc/hubble-ui 8080:80 # ブラウザで http://localhost:8080 にアクセス |
Ingress 設定例（NGINX Ingress Controller 前提）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: hubble-ui-ingress namespace: kube-system annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" spec: tls: - hosts: - hubble.example.com secretName: hubble-tls # 事前に作成した TLS シークレット rules: - host: hubble.example.com http: paths: - path: / pathType: Prefix backend: service: name: hubble-ui port: number: 80 |
ダッシュボード外観のカスタマイズ
デフォルトテーマはシンプルですが、社内ブランディングやユーザー体験向上のために テーマ・ロゴ・日本語化 を行うケースが多いです。
テーマ・ロゴ差し替え ConfigMap 設定例
ui.configMap にキー/バリューを格納するだけで UI が自動的に更新されます。プラグインバイナリなどの大容量ファイルは ConfigMap ではなく PersistentVolume または init コンテナ を利用してください。
|
1 2 3 4 5 6 7 8 9 |
apiVersion: v1 kind: ConfigMap metadata: name: hubble-ui-config namespace: kube-system data: theme: "dark" # "light" か "dark" logoURL: "https://assets.example.com/logo.svg" |
ConfigMap を作成したら Deployment の再起動で反映させます。
|
1 2 |
kubectl rollout restart deployment hubble-ui -n kube-system |
日本語化設定と環境変数
Hubble UI は LANG または HUBBLE_UI_LANG 環境変数で言語を切り替えられます。日本語リソースは公式イメージに同梱されているので、以下のように values に追記してください。
|
1 2 3 4 5 |
ui: env: - name: HUBBLE_UI_LANG value: "ja" |
独自翻訳が必要な場合は ui.customTranslations ConfigMap に JSON 形式でキー/バリューを追加し、マウントパス /etc/hubble-ui/translations/custom.json を指定します。JSON の構造は公式サンプルと 完全一致 必要です（ドキュメント参照）。
Grafana との統合手順
Cilium が出力する Prometheus メトリクスを Grafana に取り込むことで、ネットワーク可視化が容易になります。ここでは データソース設定 と 公式ダッシュボードのインポート手順 を示します。
Prometheus データソースの追加方法
Grafana UI で以下を実行してください。
- Configuration → Data Sources → Add data source
- 種類に Prometheus を選択
- URL に
http://cilium-prometheus.cilium.svc:9090（クラスタ内部 DNS）または外部公開エンドポイントを入力 - Access は Server、他項目はデフォルトのままで Test & Save
注意：Grafana が別 Namespace にある場合は
cilium-prometheus.cilium.svc:9090へ名前解決できるよう ServiceAccount の RBAC を確認してください。
公式ダッシュボードのインポート手順と ID 確認
2024年10月時点で Cilium/Hubble 用に公開されている Grafana ダッシュボードは ID 16613（旧 ID 16612 は非推奨）です。最新情報は https://grafana.com/grafana/dashboards/16613 を必ず確認してください。
- Grafana UI → Create → Import
- 「Import via grafana.com」欄に
16613と入力し Load - データソース選択画面で先ほど作成した Prometheus ソースを指定して Import
インポート完了後、左上の Refresh ボタンでリアルタイムデータが表示されます。変数 namespace・pod が自動的にクラスタ情報と連携し、フィルタリングが容易です。
カスタム機能拡張と運用ベストプラクティス
本番環境で長期運用する際は Relay のカスタムフィルタ・Helm 管理の徹底・セキュリティ設定 が鍵になります。
Relay プラグインの実装と配置方法（バイナリは ConfigMap に格納しない）
Relay は gRPC ベースのプラグインを外部バイナリとして読み込めますが、Kubernetes では ConfigMap に大容量バイナリを入れない のがベストプラクティスです。代わりに以下の2通りが推奨されます。
- init コンテナでバイナリを取得し、EmptyDir にコピー
- Docker イメージにプラグインを組み込み、Sidecar としてマウント
例：init コンテナ方式
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
apiVersion: apps/v1 kind: Deployment metadata: name: hubble-relay namespace: kube-system spec: replicas: 1 selector: matchLabels: app.kubernetes.io/name: hubble-relay template: metadata: labels: app.kubernetes.io/name: hubble-relay spec: volumes: - name: plugins emptyDir: {} - name: config configMap: name: hubble-relay-config initContainers: - name: fetch-plugin image: curlimages/curl:8.7.1 command: ["sh", "-c"] args: - | curl -L -o /plugins/myfilter.so https://example.com/plugins/myfilter.so && \ chmod +x /plugins/myfilter.so volumeMounts: - name: plugins mountPath: /plugins containers: - name: relay image: cilium/hubble-relay:v1.19.0 args: ["--config", "/etc/relay/relay.yaml"] volumeMounts: - name: plugins mountPath: /plugins - name: config mountPath: /etc/relay |
hubble-relay-config ConfigMap（バイナリ参照のみ）
|
1 2 3 4 5 6 7 8 9 10 |
apiVersion: v1 kind: ConfigMap metadata: name: hubble-relay-config namespace: kube-system data: relay.yaml: | plugins: - path: /plugins/myfilter.so |
この構成なら ConfigMap にバイナリを格納しない ため、サイズ制限や文字エンコーディングの問題を回避できます。
Helm 管理のベストプラクティス（values の外部化・helmfile）
Helm のアップグレード時に手動で values を書き換えると設定が失われやすいです。以下は Git 管理された values ファイル と helmfile によるデプロイ例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# helmfile.yaml repositories: - name: cilium url: https://helm.cilium.io/ releases: - name: hubble-ui namespace: kube-system chart: cilium/hubble-ui version: "1.19.0" # 必要に応じて更新 createNamespace: true values: - ./hubble-values.yaml # カスタマイズ済みファイルを参照 |
変更があれば git commit で履歴化し、以下コマンドで安全に適用します。
|
1 2 |
helmfile apply |
セキュリティ強化ポイント：RBAC・TLS・OIDC
| 項目 | 推奨設定例 |
|---|---|
| RBAC (最小権限) | yaml<br>apiVersion: rbac.authorization.k8s.io/v1<br>kind: Role<br>metadata:<br> name: hubble-ui-reader<br> namespace: kube-system<br>rules:<br>- apiGroups: [""]<br> resources: ["pods","services"]<br> verbs: ["get","list"]<br> |
| TLS 終端 (Ingress) | Ingress の tls 設定で証明書を指定し、Service は ClusterIP に限定。外部からは Ingress が TLS を終端するだけにします。 |
| OIDC 認証 (NGINX) | yaml<br>metadata:<br> annotations:<br> nginx.ingress.kubernetes.io/auth-url: "https://sso.example.com/oauth2/auth"<br> nginx.ingress.kubernetes.io/auth-signin: "https://sso.example.com/oauth2/start?rd=$request_uri"<br> |
| ネットワークポリシー | NetworkPolicy で UI Pod へのアクセスは Ingress コントローラの Namespace のみ許可。 |
これらを組み合わせることで、外部からの不正アクセスや権限昇格リスクを大幅に低減できます。
まとめ
- kubectl/helm バージョン と Kubernetes サーバーバージョン を必ず確認し、Cilium のサポート範囲内か検証する。
- ローカル環境では
LoadBalancerが使えないため、NodePort + extraPortMappings もしくは MetalLB を利用する。 - Helm デプロイ時は
--create-namespaceオプションで Namespace の自動作成を忘れずに。 - Ingress と port‑forward の使い分けや、Grafana ダッシュボード ID（2024年は
16613）の最新確認を徹底する。 - Relay プラグインは ConfigMap にバイナリを格納しない 設計にし、init コンテナかサイドカーで提供する。
- 運用では helmfile + Git 管理, RBAC/ TLS / OIDC の３層防御を実装して安全性を確保する。
本ガイドが Cilium と Hubble UI の導入・運用の一助となれば幸いです。質問や環境固有の課題があれば、公式 Slack（cilium.io/slack）や GitHub Discussions で共有してください。