メインコンテンツまでスキップ

ラベル

X-Yabanin-Labels は帰属ラベルを運びます。_ を含むキー(ci.job_name など)は、そのヘッダーに入れます。

X-Yabanin-Label-<key> は単一のラベル用です。リバースプロキシは、名前に _ を含むヘッダーを落とすことがよくあります(nginx の underscores_in_headers off)。そのため、それらのキーが信頼できるのは X-Yabanin-Labels 経由だけです。yb クライアントは常にリストヘッダーを使います。キーごとのヘッダーは、手動の呼び出し用です。

ワイヤ形式​

リストヘッダーは、カンマ区切りの key=value ペアで、キーはソートされています。値はパーセントエンコードされます。正規の CI および git キーには、ci.system、ci.pipeline、ci.pipeline_url、ci.job、ci.job_name、ci.stage、ci.workflow、ci.trigger、ci.run_attempt、git.repo、git.ref、git.base_ref、git.sha、git.mr、task が含まれます。

プロファイルと優先度​

.yabanin.yml のバージョン 1 は、labels.static、labels.from_env、labels.extract、require を持ちます。未知のフィールドはエラーです。ファイルの検索順は、--profile、次に YABANIN_PROFILE、次に <git root>/.yabanin.yml です。

クライアントでは、後の層が勝ちます。

  1. CI またはローカル git のコンテキスト。
  2. .yabanin.yml の labels.static。yb プロファイルに保存されたラベルは、他の何もそのキーを設定していないときだけ埋めます。
  3. labels.from_env。
  4. labels.extract。
  5. --label key=value。

on_missing: fail は、コマンドの実行前に yb を終了コード 3 で終了させます。

ゲートウェイのマージ​

ゲートウェイは、ソースを弱いものから強いものへマージします。後のソースは、前の値がロックされていない限り、前の値を置き換えます。

  1. API キーに保存されたラベル(key)。labels_locked は、リクエストが別の値を送っても、それらを勝たせます。落とされたキーは locked として報告されます。
  2. セッションキーに保存されたラベル(session)。呼び出し元が ybs_ のときです。ロックされたセッションラベルは、リクエストに対して同じように振る舞います。
  3. X-Yabanin-Labels と X-Yabanin-Label-<key>(request)。

各ソースは、最大 20 ラベルを受け付けます。マージ後の有効な集合は、最大で max_labels(デフォルト方針では 32)です。値は最大 128 文字です。接頭辞 yabanin. は予約されています。シークレットのように見える値は落とされ、エコーされません。

ラベルは支出を帰属させます。認可チェックではありません。リクエストの許可または拒否は、キー、組織ロール、ルートによって決まり、ラベルではありません。

組織方針​

GET /api/label-policy?org_id= には analytics.read が必要です。PUT と DELETE には policies.manage が必要です。保存された方針がない組織は、デフォルトを使います。すべてのキーが許可され、必須はなく、無効なラベルは落とされ、欠落した必須キーは許可されます。デフォルトは、ブランチ名から Jira キーも導出します。

{"from": "git.ref", "regex": "\\b([A-Z][A-Z0-9]{1,9}-\\d{1,7})\\b", "to": "issue", "template": "$1"}

ブランチ feature/PAY-123-login は、したがって issue=PAY-123 と issue.project=PAY を保存します。

#123 を記録する GitLab の流儀では、独自の導出規則を追加できます。

{"from": "git.ref", "regex": "#(\\d+)", "to": "issue", "template": "$1"}

コストセンターはチームキーに置いたままにします。そのキーに cost_center(および labels_locked)を設定します。そのキーからのすべてのリクエストがセンターを運び、クライアントはそれを置き換えられません。rollup_keys には、すでに cost_center と team が含まれます。

チケットが欠けていてもトラフィックを通したい、厳格な組織:

{"required_keys": ["issue"], "on_missing": "warn"}

warn はリクエストを転送し、X-Yabanin-Labels-Missing を設定します。on_missing: reject は 400 missing_required_labels を返します。on_invalid: reject は 400 invalid_labels を返します。デフォルトの drop はリクエストを維持し、破棄したキーを X-Yabanin-Labels-Dropped に列挙します。

rollup_keys は、どのラベルキーを label_rollup_hourly へ書き込むかを選びます。リストは最大 40 キーです。デフォルトには task、issue、issue.project、ci.pipeline、ci.job_name、ci.trigger、git.repo、git.mr、team、cost_center、env、service が含まれます。リストにないキーも、リクエストには保存されます。ロールアップの次元にはなりません。

保存された方針は、メモリに 30 秒、Redis に 60 秒キャッシュされます。put または delete は、そのキャッシュを破棄します。

キーラベルとセッションキー​

PUT /api/api-keys/{id}/labels(keys.manage)は、キーのラベルと、フラグ labels_locked、can_mint_sessions、can_read_usage を保存します。失敗したボディは {key, reason} 付きの 400 で、シークレット値はエコーしません。

POST /v1/yabanin/session-keys は、can_mint_sessions を持つ yb_ キーからのみ受け付けられます。ボディでは、ttl_seconds を 60 から 43200(デフォルト 7200)、ならびに max_tokens、max_cost_usd、labels、lock_labels を設定できます。保存されるのは、方針が受け付けるラベルだけです。1 分間に 60 個を超えて発行すると、429 を返します。セッションは自身のトークン上限とコスト上限に対して消費し、それでも親キーのホワイトリストと制限に従います。監査と制限が見るのは、親の id です。親を無効化、ローテーション、または削除すると、そのセッションキーは失効します。セッションキーは、別のセッションキーを発行できません。