fleet-management

Grafana Fleet Management + Alloy Configuration

ドキュメント: https://grafana.com/docs/grafana-cloud/send-data/fleet-management/

OpAMP を介して Alloy コレクターにパイプラインをリモート配布します。一度作成し、マッチャーで対象を指定して、再起動せずに即時適用できます。

前提条件

• Fleet Management が有効な Grafana Cloud スタック
• Fleet Management にアクセスできる API トークン（Authorization: Bearer <STACK_ID>:<TOKEN>）
• 対象にインストールされた Alloy ≥ 1.0（スタンドアロン、または grafana/alloy Helm チャート経由）
• alloy CLI がローカルにインストールされていること（alloy fmt による構文検証用）

概念

• コレクター — 一意の ID と属性を持つ Alloy インスタンス
• パイプライン — Fleet Management に保存された、名前付きの Alloy River 設定
• マッチャー — 属性に基づいてパイプラインをコレクターに割り当てるセレクター
• 属性 — コレクターのキー／値ラベル（env、team、region）

よくあるワークフロー

1. パイプラインを作成、検証、デプロイする

# 1. Save the pipeline to a local file (lint catches typos before remote)
cat > pipeline.alloy <<'EOF'
prometheus.scrape "default" {
  targets    = []
  forward_to = [prometheus.remote_write.grafana_cloud.receiver]
  scrape_interval = "60s"
}

prometheus.remote_write "grafana_cloud" {
  endpoint {
    url = "https://prometheus-prod-01-eu-west-0.grafana.net/api/prom/push"
    basic_auth {
      username = "<METRICS_USERNAME>"
      password = env("GRAFANA_CLOUD_API_KEY")
    }
  }
}
EOF

# 2. Validate syntax LOCALLY before sending to Fleet Management
alloy fmt pipeline.alloy            # rewrites in place or errors with line number
alloy validate pipeline.alloy       # full semantic check (newer Alloy releases)

# 3. Create the pipeline via API (see references/api.md for the payload schema)
BASE=https://fleet-management-prod-us-east-0.grafana.net
TOKEN=<STACK_ID>:<API_TOKEN>
PAYLOAD=$(jq -n --rawfile c pipeline.alloy '{
  name:"k8s-metrics", contents:$c,
  matchers:[{name:"env",value:"production",type:"EQUAL"}]
}')
curl -s -X POST "$BASE/pipeline.v1.PipelineService/CreatePipeline" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "$PAYLOAD" | jq

# 4. Verify it rolled out — every targeted collector should report APPLIED within 1-2 polls
curl -s -X POST "$BASE/collector.v1.CollectorService/ListCollectors" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}' \
  | jq '.collectors[] | select(.attributes[]?.value=="production")
        | {name, remoteConfigStatus}'
# Expect every row: remoteConfigStatus == "REMOTE_CONFIG_STATUS_APPLIED"

2. REMOTE_CONFIG_STATUS_FAILED のコレクターをトラブルシューティングする

# 1. Find failed collectors and surface the error message
curl -s -X POST "$BASE/collector.v1.CollectorService/ListCollectors" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}' \
  | jq '.collectors[] | select(.remoteConfigStatus=="REMOTE_CONFIG_STATUS_FAILED")
        | {name, msg:.remoteConfigStatusMessage}'

# 2. Re-validate the offending pipeline locally
alloy fmt pipeline.alloy

# 3. Inspect Alloy directly — UI at port 12345 shows per-component health
#    http://<COLLECTOR_HOST>:12345 → Graph / Components / Clustering tabs
kubectl -n monitoring logs -l app.kubernetes.io/name=alloy --tail=100 | grep -iE 'remote|error'

# 4. After fixing + re-pushing, re-list collectors and confirm the row flips to APPLIED.

失敗メッセージのデコーダーテーブル：references/api.md。

3. ブートストラップブロックで新しい Alloy をオンボーディングする

ブートストラップの remotecfg ブロックのみがローカル設定として必要です。

remotecfg {
  url = "https://<FLEET_MANAGEMENT_HOST>"
  basic_auth { username = "<STACK_ID>"; password = env("GRAFANA_CLOUD_API_KEY") }
  poll_frequency = "1m"
  attributes = { "env" = env("ENVIRONMENT"), "team" = "platform" }
}

# Verify after start
curl -s http://localhost:12345/api/v0/web/components \
  | jq '.[] | select(.id=="remotecfg") | {id, health:.health.state}'
# health.state == "healthy"

ブートストラップの完全な手順（スタンドアロン + Helm）とアシスタントツールの一覧：references/bootstrap.md。

リソース

• Fleet Management のドキュメント
• Alloy コンポーネント
• OpAMP 仕様