OTelのKubernetes属性がstableになった — k8sattributesのデフォルトが反転する前にすべきこと

はじめに — stable昇格は静かに過ぎ去った
4か月間の昇格タイムライン
実際に壊れる7つのこと
2つのフィーチャーゲートと真理値表
RFCの4段階ロールアウト — デフォルトはいつ反転するのか
今やるべきこと — 窓が開いている間に
正直なトレードオフ — 二重発行はタダではない
実際に影響を受けるのは誰か — そして受けないのは誰か
おわりに
参考資料

はじめに — stable昇格は静かに過ぎ去った

2026年6月12日、semconv v1.42.0がリリースされ、OpenTelemetryのKubernetes属性の一群がstableに昇格しました。チェンジログの一行にはこうあります — "Promote a selection of k8s and container registry attributes to stable"。

そして、何も起きませんでした。

正確に言えば、何も起こらないように設計されています。あなたがCollectorのk8sattributesプロセッサを動かしているなら、まさに今この瞬間も旧スキーマ(以下v0)をそのまま送出しているはずです。最新リリースのcollector-contrib v0.156.0(2026-07-07)時点でも、該当のフィーチャーゲートはいまだalphaであり、alphaではデフォルトがv0だからです。

これは猶予であって免除ではありません。CollectorのRFCが定めたロールアウトどおりなら、ゲートがbetaに上がった瞬間にデフォルト動作がv1専用へ反転します。そしてこの変更の性質が厄介です — エラーは出ません。ダッシュボードがただ空になるだけです。

本稿では、実際に何が変わるのか、いつ反転するのか、今開いている窓でやるべきことは何かを整理します。そして最後に、これが思ったよりずっと狭い問題だという話もします。

4か月間の昇格タイムライン

まず事実関係を時系列で並べます。すべてsemconvリポジトリのリリースとマージ済みPRで確認できるものです。

2026-02-19  semconv v1.40.0   k8s.pod.name など -> stability: beta
2026-03-02  PR #3491 オープン  "Promote a selection of k8s/container attributes to RC"
2026-03-09  PR #3491 マージ    beta -> release_candidate
2026-03-16  公式ブログ告知     "Kubernetes attributes promoted to release candidate"
2026-04-28  semconv v1.41.0   42属性がrelease_candidateとしてリリースに反映
2026-05-11  semconv v1.41.1   引き続きrelease_candidate
2026-06-12  semconv v1.42.0   -> stable  (チェンジログ #3382)
2026-07-03  semconv v1.43.0   stable維持
2026-07-07  contrib v0.156.0  フィーチャーゲートは依然alpha (v0.145.0から)

PR #3491の本文には意図がはっきりと書かれています — 「これはstableにする前の最後の中間段階の昇格であり、フィードバックを求める最後の呼びかけだ」と。3月16日の公式ブログ(Christos Markou/Elastic、David Ashpole/Google)も「release_candidateにとどまっている間がフィードバックを出すときだ」と釘を刺しています。

その窓は6月12日に閉じました。属性はもうstableです。

ここで見ておくべきなのは、最後の2行の間の食い違いです。semconvは6月12日にstableを宣言しましたが、7月7日のCollectorリリースでもゲートはalphaのままです。後で見るように、RFCには「semconvが該当コンベンションをstableと表示するリリースと同じCollectorリリースで、ゲートをbetaに引き上げる」と書かれています。つまり今は、RFCが描いた絵より遅れている状態です。なぜ遅れているのか、正確にどのリリースで反転するのかは、私が確認できる資料にはありません — なので日付を作り出すことはしません。ただし方向性は決まっており、あなたに与えられているのはその間の時間です。

実際に壊れる7つのこと

v0とv1の間のbreaking changeは、k8sattributesプロセッサのREADMEにきっちり7個、明記されています。

container.image.tag              ->  container.image.tags
k8s.pod.labels.KEY               ->  k8s.pod.label.KEY
k8s.pod.annotations.KEY          ->  k8s.pod.annotation.KEY
k8s.node.labels.KEY              ->  k8s.node.label.KEY
k8s.node.annotations.KEY         ->  k8s.node.annotation.KEY
k8s.namespace.labels.KEY         ->  k8s.namespace.label.KEY
k8s.namespace.annotations.KEY    ->  k8s.namespace.annotation.KEY

6つは複数形が単数形に変わるだけです。labelsがlabelになり、annotationsがannotationになる。実際の属性名で見るとこうなります。

v0:  k8s.pod.labels.app       = "checkout"
v1:  k8s.pod.label.app        = "checkout"

文字一つです。そしてまさにこの点が危険です。名前がまるごと変わればクエリはエラーを出すか目に見えて壊れますが、存在しない属性でフィルタするクエリはたいてい静かに空の結果を返します。アラートは発火せず(条件に合う時系列がないので)、ダッシュボードのパネルは「No data」を表示し、誰も夜中に叩き起こされません。それが数日後、「そういえばこのグラフ、いつから空だったっけ?」として返ってきます。

7番目は性格が異なります。container.image.tagからcontainer.image.tagsへの変更は、名前が変わるだけでなく型も変わります。プロセッサのドキュメントによれば、前者はAny Str、後者はAny Sliceです。文字列一つから配列への変更なので、名前を直してもtag = "v1.2.3"のような等値フィルタは配列に対して思ったとおりには動きません。これは文字列置換では終わらず、クエリ自体を書き直す必要のある変更です。

2つのフィーチャーゲートと真理値表

Collectorは、SDK側のOTEL_SEMCONV_STABILITY_OPT_IN環境変数方式をあえて使いません。RFCの言葉を借りれば、その方式は「Collectorネイティブには感じられず」、特にアップグレード後に以前の動作へロールバックすることをサポートしていないからです。代わりに、対になる2つのフィーチャーゲートを使います。どちらもv0.145.0から存在し、現在はalphaです。

processor.k8sattributes.EmitV1K8sConventions — オンにすると新しい(stable)スキーマを送出します。
processor.k8sattributes.DontEmitV0K8sConventions — オンにすると古い(legacy)スキーマを止めます。

重要なのは、この2つが独立しているという点です。だから4通りの組み合わせが生まれ、RFCは真理値表をこう定義しています。

EmitV1	DontEmitV0	結果の動作
オフ	オフ	v0のみ発行(現在のデフォルト)
オフ	オン	起動時にエラー — テレメトリが一切出なくなるため
オン	オフ	v0とv1を両方発行(二重発行)
オン	オン	v1のみ発行

3行目がこの記事の要点です。両方オンにしなくても、EmitV1だけをオンにすれば2つのスキーマが同時に出ます。移行期間中、旧ダッシュボードと新ダッシュボードを共存させられるということです。

2行目も覚えておく価値があります。「新しい方をオフにして古い方もオフにする」という組み合わせは、静かに無視されるのではなく起動失敗になります。設定ミスでテレメトリが音もなく消えるより、はるかに良い設計です。

ゲートはCollector起動時のフラグでオンにします。

# 二重発行: v0とv1を同時に送出する (移行期間用)
otelcol-contrib --config=config.yaml \
  --feature-gates=+processor.k8sattributes.EmitV1K8sConventions

# 移行完了: v1のみを送出する
otelcol-contrib --config=config.yaml \
  --feature-gates=+processor.k8sattributes.EmitV1K8sConventions,+processor.k8sattributes.DontEmitV0K8sConventions

RFCの4段階ロールアウト — デフォルトはいつ反転するのか

semconv-feature-gates RFCは、ゲートのペアが踏んでいく段階をこう釘付けにしています。2つのゲートは常に同じ速度で一緒に動きます。

alpha — 両方ともデフォルトはオフ。デフォルト動作はv0のみ発行。ユーザーは望めば二重発行やv1専用にオプトインできます。RFCはこの段階で、コンポーネントが起動時に警告ログを残さなければならないと規定しています("A warning message must be logged by the component at startup indicating the upcoming change")。
beta — semconvが当該コンベンションをstableと表示するリリースが出たら、同じCollectorリリースでゲートがbetaに昇格します。このとき、デフォルト動作がv1専用へ反転します。 今度は逆に、v0を使うにはオプトアウトが必要になります。
stable — betaからマイナーリリース4回分が過ぎるとstable段階に上がります。この時点からはv1しか使えません。
削除 — そこからさらにマイナーリリース4回分が過ぎると、ゲート自体が消えます。

今、私たちは1段階目にいて、semconv側の条件(v1.42.0のstable昇格)はすでに満たされています。だから2段階目は予定された出来事です。上で述べたとおり、正確なリリース番号は確認されていないので断定しません。ただ、計画を立てるときに基準にできる事実は2つあります — 反転はCollectorをアップグレードした瞬間にやってきて、beta以降マイナーリリース8回が過ぎると元に戻す手段自体がなくなります。

Collectorを自動アップグレードしているなら(オペレーターのイメージタグをlatestにしたままにしている、あるいはレンダリングされたチャートバージョンを固定していない)、この反転はあなたが選んだ日ではなく、どの日にでもやってきます。

今やるべきこと — 窓が開いている間に

順番が重要です。RFCがわざわざ二重発行の段階を設けた理由がこれです。

1. まず自分が影響を受けるかどうかを確認します。 Collectorの設定でk8sattributesプロセッサのextractブロックを見ます。labelsやannotationsのサブ項目はありますか?metadataリストにcontainer.image.tagはありますか?どちらもなければ — 後で説明するように — あなたはこの変更と無関係です。

2. 二重発行をオンにします。 EmitV1K8sConventionsだけをオンにして、v0とv1が同時に出るようにします。この時点からバックエンドには両方の名前が存在するので、旧ダッシュボードは生き続けたまま、新しい名前でクエリを試してみることができます。元に戻すのも簡単です。

3. クエリとダッシュボードを移行します。 複数形から単数形へ変わる6つは、機械的な置換に近いです。container.image.tagは先述の型変更があるため、手作業で見る必要があります。

4. v0をオフにします。 新しいクエリがデータを返すことを確認したうえで、DontEmitV0K8sConventionsをオンにします。この時点の動作がそのまま今後のデフォルトになるので、未来を先取りして体験するわけです。

5. そのうえでCollectorをアップグレードします。 すでにv1専用で動いているなら、ゲートがbetaに反転してもあなたには何も起きません。それが目標です。

肝心なのは2ステップ目と5ステップ目を切り離すことです。何もしないままアップグレードすると、スキーマの切り替えとバージョンアップグレードが同じ日、同じ時刻に重なり、何かが空になったときにどちらが原因か分からなくなります。

正直なトレードオフ — 二重発行はタダではない

二重発行の段階を「とりあえずオンにしておけば安全」であるかのように語りたくありません。代償があります。

リソース属性が二重になります。 ラベルを5個抽出していたなら、今は10個付くことになります。これはすべてのスパン・メトリクス・ログのリソースに載って出ていくので、ネットワークとストレージの両方にコストがかかります。正確に何パーセント増えるかは、あなたが何個のラベルを抜いているかに完全に依存するので、ここで数字を作り出すことはしません — ただ、自分のパイプラインで実測するのは難しくありません。

メトリクスの場合はカーディナリティのほうが痛いです。 リソース属性が時系列アイデンティティに入るバックエンドでは、同じ値を持つ属性が2つの名前で存在することが時系列数に影響を与えることがあります。バックエンドごとにリソース属性の扱い方が違うので一律には言えず、二重発行をオンにする前にまず小さな1つのネームスペースだけでオンにしてみて、計測値を見るほうが安全です。

だから二重発行は終着点ではなく橋です。 RFCのロールアウト自体がそれを前提としています — 二重発行の組み合わせは、stable段階になると消えます。オンにしたなら最後まで見届ける必要があります。「とりあえずオンにして後で」が最も高くつく選択です。

実際に影響を受けるのは誰か — そして受けないのは誰か

ここがこの記事で一番重要な節かもしれません。ここまでの話は「K8sセマンティック規約が壊れる」ように聞こえますが、実際に壊れる範囲は噂よりずっと狭いのです。

あなたが毎日使っている属性は変わりません。 k8s.pod.name、k8s.namespace.name、k8s.deployment.name、k8s.node.name、k8s.container.name、k8s.pod.uid — すべて名前そのままです。breaking changeのリストには入っていません。大半のダッシュボードはこれらの属性の上に立っており、そういうダッシュボードには何も起きません。

変わるのはラベル/アノテーション抽出とcontainer.image.tagだけです。 そしてラベル抽出でさえ条件付きです — プロセッサのREADMEによれば、複数形の名前はtag_nameを指定しなかったときに使われるデフォルトフォーマットです。つまりextract設定でラベルごとにtag_nameを明示して自分の名前を付けてきたなら、その名前はあなたのものであり、今回の改名とは無関係です。影響を受けるのは、デフォルトフォーマットに頼っていた設定です。

# tag_name を指定した場合 — 属性名は 'l2'。今回の変更とは無関係。
extract:
  labels:
    - tag_name: l2
      key: label2
      from: pod

# tag_name がない場合 — デフォルトフォーマットに従うので影響を受ける。
# v0: k8s.pod.labels.label2   ->   v1: k8s.pod.label.label2
extract:
  labels:
    - key: label2
      from: pod

そして、stableになったのも「一部」です。 semconv v1.43.0のk8sレジストリをパースしてみると、属性89個のうちstableは42個で、残り45個はまだdevelopment、2個はexperimentalです。3月のブログのタイトルも"a selection of"でした。だから「K8sコンベンションはもう全部安定した」と読んではいけません — ワークロード関連の相当数は、いまだに変わりうる場所にいます。今回安定した42個は、k8sattributesやresourcedetectionのような、安定化を目指したCollectorコンポーネントが実際に使っていたものです。

まとめるとこうです。

今すぐ動くべき場合

k8sattributesのextractでtag_nameなしにラベル/アノテーションを抜いている。
container.image.tagでフィルタまたはグルーピングするクエリがある。
Collectorを自動追従でアップグレードしていて、アップグレードのタイミングを自分で選んでいない。

気にしなくていい場合

k8s.pod.name / k8s.namespace.name / k8s.deployment.name 程度しか使っていない — 大多数はここに当てはまります。
ラベル抽出に常にtag_nameを明示してきた。
Collectorのバージョンを固定していて、アップグレードを意図的に計画している — それなら、この記事は次のアップグレードチケットに貼るメモです。

おわりに

この話の教訓は「OTelがまた名前を変えた」ではありません。むしろ逆に近いです。semconvはbeta → release_candidate → stableを4か月かけて踏み、そのたびに告知し、最後の呼びかけまで付けました。Collector側は真理値表が明確なゲートのペアと二重発行の窓、そしてマイナーリリース8回分にわたる猶予を設計しています。静かな失敗を防ぐために備えられるものは、ほぼすべて備えたと言えます。

それでもこの手の変更が人を傷つける地点はいつも同じです — デフォルトが反転する瞬間と、あなたがアップグレードを押す瞬間が同じだからです。今は、その2つの瞬間の間に時間が残っている、珍しい状態です。semconvはすでにstableを宣言し、Collectorのデフォルトはまだ反転していません。この隙間こそ、二重発行をオンにし、クエリを移し、確認して先に進むのにちょうどいい場所です。

そして繰り返しますが、確認してみたらextractブロックにラベルがなかった — なら、それで終わりです。それがこの記事の一番よくある結末で、確認には5分もかかりません。