あらびき日記

PIM の Role Management Policy を作成する際の InsufficientPermissions を解消する

Fri, 08 May 2026 00:00:00 +0900

Assign Azure resource roles in Privileged Identity Management で言及されているように、Azure resource role に関する PIM の設定の管理者権限を付与するには subscription scope の Owner role や User Access Administrator role が必要です。

Users or members of a group assigned to the Owner or User Access Administrator subscription roles, and Microsoft Entra Global Administrators that enable subscription management in Microsoft Entra ID have Resource administrator permissions by default. These administrators can assign roles, configure role settings, and review access using Privileged Identity Management for Azure resources.

また、Azure portal 上で Owner role や User Access Administrator role を assign する際には次のような condition を指定することができます。

Allow user to only assign selected roles to selected principals (fewer privileges)
Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC (Recommended)
Allow user to assign all roles (highly privileged)

PIM の設定を Terraform で管理して、service principal に terraform apply させる場合、”highly privileged” を避けて “Recommended” となっている condition を選択したいところですが、この condition で User Access Administrator role を付与しても、role management policy の作成には InsufficientPermissions というエラーで失敗してしまいます。

というわけで、このエラーを回避するために試行錯誤した結果について説明します。

結論

試行錯誤の結果、Owner role や User Access Administrator role を付与する際に “Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC” を維持しつつ、role management policy を更新する権限を付与することはできないことがわかりました。
つまり、Allow user to assign all roles (highly privileged) を選択する必要があります。

何とも味気ない結論ですが、以降検証した内容について説明します。

最小再現コード

“Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC (Recommended)” の condition 付きで User Access Administrator role を付与した service principal で次の Terraform file を apply すると InsufficientPermissions のエラーになります。

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "= 4.71.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_subscription" "current" {}

data "azurerm_role_definition" "owner" {
  name  = "Owner"
  scope = data.azurerm_subscription.current.id
}

data "azurerm_role_assignments" "this" {
  scope = data.azurerm_subscription.current.id
}

locals {
  owner_id = [for a in data.azurerm_role_assignments.this.role_assignments : a if a.role_definition_id == data.azurerm_role_definition.owner.role_definition_id && a.principal_type == "User"][0].principal_id
}

resource "azurerm_role_management_policy" "owner" {
  scope              = data.azurerm_subscription.current.id
  role_definition_id = data.azurerm_role_definition.owner.id

  activation_rules {
    approval_stage {
      primary_approver {
        object_id = local.owner_id
        type      = "User"
      }
    }
  }
}

具体的には次のようなエラーになります。

╷
│ Error: updating Scoped Role Management Policy (Scope: "/subscriptions/<subscription-id>"
│ Role Management Policy Name: "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"): unexpected status 400 (400 Bad Request) with error: InsufficientPermissions: The requestor 681e20cf-3e2e-4352-bebd-7b9369bca77a does not have permissions for this request. Please use $filter=asTarget() to filter on the requestor's assignments.
│
│   with azurerm_role_management_policy.owner,
│   on main.tf line 29, in resource "azurerm_role_management_policy" "owner":
│   29: resource "azurerm_role_management_policy" "owner" {
│
│ updating Scoped Role Management Policy (Scope: "/subscriptions/<subscription-id>
│ Role Management Policy Name: "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"): unexpected status 400 (400 Bad Request) with error: InsufficientPermissions: The requestor 681e20cf-3e2e-4352-bebd-7b9369bca77a does
│ not have permissions for this request. Please use $filter=asTarget() to filter on the requestor's assignments.
╵

このエラーメッセージからはわかりませんが、activity log を見ると Microsoft.Authorization/roleManagementPolicies/write action に失敗していることがわかります。

$ az monitor activity-log list \
  --caller 681e20cf-3e2e-4352-bebd-7b9369bca77a \
  --status Failed \
  --offset 24h \
  --query "[?contains(properties.responseBody, 'InsufficientPermissions')] | [0].{authorization: authorization, operationName: operationName, resourceId: resourceId, resourceType: resourceType}"
{
  "authorization": {
    "action": "Microsoft.Authorization/roleManagementPolicies/write",
    "scope": "/subscriptions/<subscription-id>/providers/Microsoft.Authorization/roleManagementPolicies/8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
  },
  "operationName": {
    "localizedValue": "Write Role management policy",
    "value": "Microsoft.Authorization/roleManagementPolicies/write"
  },
  "resourceId": "/subscriptions/<subscription-id>/providers/Microsoft.Authorization/roleManagementPolicies/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
  "resourceType": {
    "localizedValue": "Microsoft.Authorization/roleManagementPolicies",
    "value": "Microsoft.Authorization/roleManagementPolicies"
  }
}

当然 condition にはこの action に対する制限も /subscriptions/<subscription-id>/providers/Microsoft.Authorization/roleManagementPolicies/* に対する制限もありません。

検証

次のように様々な condition で User Access Administrator role を付与した service principal を用意します。

provider "azurerm" {
  features {}
}

data "azurerm_subscription" "current" {}

resource "random_uuid" "unknown" {}

locals {
  service_principals = {
    # Allow user to assign all roles (highly privileged)
    highly_privileged = {
      condition = null
    }
    # Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC (Recommended)
    # - 8e3af657-a8ff-443c-a75c-2fe8c4bcb635: Owner
    # - 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9: User Access Administrator
    # - f58310d9-a9f6-439a-9e8d-f62e7b41a168: Role Based Access Control Administrator
    recommended = {
      condition = <<-EOF
        (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
          )
          OR (
            @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
        AND (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
          )
          OR (
            @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
      EOF
    }
    recommended_minus_delete_cond = {
      condition = <<-EOF
        (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
          )
          OR (
            @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
      EOF
    }
    recommended_minus_write_cond = {
      condition = <<-EOF
        (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
          )
          OR (
            @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
      EOF
    }
    exclude_write = {
      condition = <<-EOF
        !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
      EOF
    }
    exclude_some_role_requests = {
      condition = <<-EOF
        @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
      EOF
    }
    exclude_unknown_role_request = {
      condition = <<-EOF
        @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {${random_uuid.unknown.result}}
      EOF
    }
    recommended_rev = {
      condition = <<-EOF
        (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
          )
          OR (
            @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
          OR (
            Not Exists @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]
          )
        )
        AND (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
          )
          OR (
            @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
      EOF
    }
    recommended_rev = {
      condition = <<-EOF
        (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
          )
          OR (
            @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
          OR (
            Not Exists @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]
          )
        )
        AND (
          (
            !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
          )
          OR (
            @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}
          )
        )
      EOF
    }
  }
}

resource "azuread_application" "this" {
  for_each = local.service_principals

  display_name = each.key
}

resource "azuread_service_principal" "this" {
  for_each = local.service_principals

  client_id = azuread_application.this[each.key].client_id
}

resource "azuread_application_password" "this" {
  for_each = local.service_principals

  application_id = azuread_application.this[each.key].id
}

resource "azurerm_role_assignment" "this" {
  for_each = local.service_principals

  principal_id         = azuread_service_principal.this[each.key].object_id
  role_definition_name = "User Access Administrator"
  scope                = data.azurerm_subscription.current.id

  condition = each.value.condition
}

# condition によっては read 権限すらなくなるので Reader role を付与する
resource "azurerm_role_assignment" "reader" {
  for_each = local.service_principals

  principal_id         = azuread_service_principal.this[each.key].object_id
  role_definition_name = "Reader"
  scope                = data.azurerm_subscription.current.id
}

output "client_id" {
  value = { for k, v in azuread_application.this : k => v.client_id }
}

output "client_secret" {
  value     = { for k, v in azuread_application_password.this : k => v.value }
  sensitive = true
}

terraform apply 後、次のように対象 service principal を変更しつつ最小再現コードに対して terraform apply してみます。

ARM_CLIENT_ID=$(terraform output -json client_id | jq -r .highly_privileged) \
ARM_CLIENT_SECRET=$(terraform output -json client_secret | jq -r .highly_privileged) \
ARM_TENANT_ID=$(az account show --query homeTenantId -o tsv) \
ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv) \
terraform -chdir=/path/to/reproducible-code-dir apply -auto-approve

その結果、最小再現コードの apply の成否は次のようになりました。

service principal	terraform apply
highly_privileged	成功
recommended	失敗
recommended_minus_delete_cond	失敗
recommended_minus_write_cond	成功
exclude_write	失敗
exclude_some_role_requests	失敗
exclude_unknown_role_request	失敗
recommended_rev	成功

上記の結果から、role management policy を作成する際には次の条件が false になっていることがわかります。

!(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})

@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {8e3af657-a8ff-443c-a75c-2fe8c4bcb635, 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9, f58310d9-a9f6-439a-9e8d-f62e7b41a168}

@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals {${random_uuid.unknown.result}}

つまり次のことが言えます。

actioin は Microsoft.Authorization/roleAssignments/write
@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAllValues:GuidNotEquals には何を指定しても false

このことから、recommended_rev では recommended の条件に次の OR 条件を追加したところ、terraform apply に成功することがわかりました。

Not Exists @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]

ところが、この条件を追加することで、Owner などの role も付与できるようになってしまうようで、実質 highly_privileged と同じになってしまうようです。

Exists operator の説明に関係するんでしょうが、Exists operator は RoleDefinitionId をサポートしていません。

また、次のどちらの条件を追加しても結果は同じでした。

Exists @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]
Not Exists @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]

おそらく、サポートしていない attribute に対して Exists operator を使用したことで、condition の評価をする際にエラーになって、無条件で condition を満たしているものとみなされるんじゃないかと思いますが、深追いはしていません。

Amazon のほしい物リストで意図せず旧住所宛に荷物が発送されてしまった時の対応方法

Sun, 01 Feb 2026 00:00:00 +0900

Amazon のほしい物リストのお届け先は、Amazon アカウントのアドレス帳に登録されている住所から選択しますが、アドレス帳の住所を変更してもほしい物リストのお届け先には変更が反映されません。今回、その仕様を知らなくて旧住所に荷物が発送されてしまい、Amazon のカスタマーサービスや配送業者に連絡してもやり取りに苦労したので、どのような対応を行ったかについてまとめます。

対応方法

何が起きたか詳細を説明する前に、結論として2025 年 12 月時点の対応方法について説明します。Amazon のカスタマーサービスは対応する人によって回答内容が変わるので、納得が行かなければ複数回連絡した方が良いです。

なお、今回の配送業者は Amazon とヤマト運輸だったので他の配送業者の対応まではわかりませんが、似たような対応になると思われます。

配送業者が Amazon の場合

カスタマーサービスに 3 回電話しましたが、3 人とも「Amazon が配送業者の場合は後からお届け先を変更することはできない」と言っていたので、お届け先を変更できないのは間違いないでしょう。
よって、配達済み・未配達に限らず次のどちらかになります。

受取人がカスタマーサービスに問い合わせてキャンセルしてもらう
購入者がカスタマーサービスに問い合わせてキャンセルしてもらう

今回は受取人が問い合わせてキャンセルしましたが、それぞれの方法について説明します。

受取人によるキャンセル方法

この方法の場合、事前にキャンセル対象となる注文の注文番号を全て集める必要があります。よって、誰が購入してくれたかを把握していないとこの方法は選択できません。

カスタマーサービスの正式な連絡先は最後までわかりませんでしたが、Amazon.co.jpヘルプ: ヘルプ&カスタマーサービスで「その他のお問い合わせ」、「その他」、「サイトの不具合」、「カスタマサービスへ連絡」、「今すぐ電話をリクエストする」と辿ることで連絡が取れました。
「受取人からはキャンセルできません」とか、「自己責任なので荷物が返送されない限り返金できません」と回答されることもありますが、何度か連絡するとキャンセルしてくれる人が電話に出てくれる可能性があります。
「アカウントの住所を変更してもほしい物リストのお届け先が変わらないことに気付けなくて、旧住所に送られてしまった」と自分には非がなさそうな感じで伝えると良いかもしれません。
キャンセル後、3 時間以内に返金相当の Amazon ギフトカードの残高が受取人の Amazon アカウントに補充されるので、購入者に同額の Amazon ギフトカードを送れば対応完了です。

購入者によるキャンセル方法

2 回程配達に失敗すると、注文履歴の配送状況でキャンセルボタンが出るようなので、それを押すとキャンセルできると思われます。今回は受取人によるキャンセル依頼が先に処理されたようなので、詳細は不明ですが…。
カスタマーサービス曰く、「ほしい物リストのお届け先が旧住所になっていたようなのでキャンセルしたい」とカスタマーサービスに連絡することでもキャンセルできるようです。

配送業者がヤマト運輸で未配達の場合

クロネコメンバーズで荷物を追跡できている荷物（Amazon が出荷元でない荷物？）に関しては、配送先を営業所に変更することで現住所の近くの営業所まで配送してもらえるかもしれません。今回は旧住所も現住所も同じ区だったこともあってか、現住所の近くの営業所への配達に変更可能でした。

クロネコメンバーズで追跡できていない荷物に関しては、次のどちらかになりますが、旧住所が宅配ボックスのある集合住宅だと、後述する「荷物が配達済みの場合」の対応になるかと思います。

現在の住居者が荷物を受け取らないことを祈りながら、ヤマト運輸が配達を諦めて Amazon に返送されて購入者に返金されるまで待つ
一度配達を試みて失敗した後（郵便受けに不在票が入れられた後）、旧住所の管理会社とやり取りして送り状番号を入手し、ヤマト運輸に連絡して現住所に転送してもらう
- ネット上には Amazon のカスタマーサービスに問い合わせることで送り状番号が入手できたという方もいましたが、「今の仕様では、送り状番号は注文者にも受取人にもお伝えできません（カスタマーサービスには閲覧権限がありません）」と突っぱねられました

なお、ヤマト運輸の転送は旧住所と現住所が同じ区で数キロしか離れていなかったとしても有料で着払いです。おそらく通常の配送料と同料金です。

荷物が配達済みの場合（配送業者に関わらず共通）

「配送業者が Amazon の場合」と同じ対応か、旧住所の管理会社に連絡するかの二択です。
旧住所に直接押しかける人もいるようですが、管理会社を通さず現在の入居者とやり取りするのは避けた方が良いでしょう。

何が起きたか？

最近第一子を授かったところ、ありがたいことに複数人から出産祝いを送りたいという主旨のメッセージをいただきました。こういう時には Amazon のほしい物リストを使うのが相手にとっても手軽にプレゼントを送れて良いだろうと考え、10 年ぐらい前に作成したリストの中身を一度空にし、そのリストに欲しい物を追加した上でメッセージをくれた方々に共有したわけです。

ふと、「このリストで購入した商品はどこに配送されるんだろう？」と思って、リストの設定を確認して宛先が自分宛てになっていることも確認しました。

ところが、2 日もあれば配達されそうなプレゼントが何個も購入されているにも関わらず、3 日以上経っても届きません。お届け予定日を共有していただいた方のプレゼントも予定日には届きませんでした。

配送先がおかしいのではと思って検索したところ、見つけたのがこの一文

デフォルトのお届け先住所は、リストの作成時に指定した住所です。

cf. ほしい物リストのお届け先住所を管理する - Amazonカスタマーサービス

アドレス帳で削除済みの住所が使われるなんてあるわけないと思って「ほしい物リスト旧住所」で検索すると、同じトラブルに遭遇している人が何人も出てきます

ここで、荷物が旧住所に送られたんだろうと確信が持てました。後でわかりましたが、「お届け先住所」に具体的な住所が表示されていない場合は「変更前」または「削除済み」の住所が登録されていることを意味するので、変更しないと痛い目にあうみたいですね。

やったこと

以下、やったことについて順を追って説明します。会話内容の詳細はもう忘れてしまったのでかなり端折っていて不正確な部分もありますが、大枠としては間違ってないはずです。

1. Amazon に連絡

通常の注文であれば注文履歴からカスタマーサービスと連絡が取れるわけですが、今回は自分の注文じゃないのでどこから連絡すれば良いのか見つけるのが大変でした。正式な方法かはわかりませんが、Amazon.co.jpヘルプ: ヘルプ&カスタマーサービスで「その他のお問い合わせ」、「その他」、「サイトの不具合」、「カスタマサービスへ連絡」、「今すぐ電話をリクエストする」と辿ることで連絡が取れました。

ざっくりと次のようなやり取りをしました。

私「ほしい物リストで購入した商品が旧住所に送られてしまったようなんですが宛先変更はできますか？」
Amazon「購入者でなければできません」
私「購入者が現住所に宛先を変更してほしいと伝えれば変更できるんですか？」
Amazon「宛先の変更はできないので、購入者からカスタマーサービスにキャンセルの連絡をして再度購入してもらってください」
私「連絡すべき人を把握したいので、誰が購入したか、あるいは何人が購入したか教えてもらうことはできますか？」
Amazon「できません」

この時点で少なくとも 2 人がヤマト運輸、3 人が Amazon で配送されていることがわかっていたので、ヤマト運輸が配送業者になっている商品であれば宛先を変更できるだろうと思って次はヤマト運輸に連絡をしました。

2. ヤマト運輸に連絡

ヤマト運輸で配送になっている 2 人に関しては、1 人は出荷元が Amazon じゃなかったからか、配送には受け取り人の電話番号が必要で事前に共有したこともあり、クロネコメンバーズから近所の営業所受け取りに変更することができました。もう 1 人に関しては配送状況を確認しても配送業者がヤマト運輸ということしかわからず、送り状番号は Amazon 上で確認できないようだったのでヤマト運輸に電話しました。

私「旧住所に配達しようとして失敗している荷物があるんですが宛先を変更することはできますか？」
ヤマト運輸「送り状番号を教えてください」
私「それが Amazon のほしい物リストから購入したんですが、依頼主もわからないようで…」
ヤマト運輸「いや、Amazon であれば注文履歴から Tracking ID がわかるはずですよ」
私「わかりました。もう一度確認します」

ところが、やはり送り状番号はわからなかったので Amazon に連絡することになります。

3. Amazon に連絡

私「ほしい物リストで購入した商品が旧住所に送られてしまったようなんですが宛先変更はできますか？」
Amazon「できません」
私「ヤマト運輸の送り状番号だけでも教えてもらえませんか？」
Amazon「私たちの権限では確認できません」
私「過去に同様のトラブルがあった人は送り状番号を教えてもらえているようなんですが」
Amazon「外部の記事でどうなっているかはわかりませんが今の仕様をお伝えしますね。今は送り状番号を教えることはできません」
私「購入者側から問い合わせれば教えてもらえますか？」
Amazon「教えられません」
私「配送業者が Amazon になっているものだけでもお届け先を変更できないんでしょうか？」
Amazon「できません」
私「ではこちらから旧住所宛に送られている注文をキャンセルすることはできますか？」
Amazon「できません」
私「ではどうするのが最速ですか？」
Amazon「購入者がカスタマーサービスに連絡してキャンセルして、再度購入してください」

どう頑張ってもヤマト運輸の荷物の送り状番号を入手できなさそうだったので再度ヤマト運輸に連絡してみます。

4. ヤマト運輸に連絡

私「旧住所宛に送られてしまった荷物の宛先を変更したいんですが」
ヤマト運輸「送り状番号を教えてください」
私「それがわからなくて…」
ヤマト運輸「送り状番号がわからないのにどうして旧住所宛に送られているってわかったんですか？」
私「Amazon のほしい物リスト経由で購入してもらった荷物なんですが、Amazon の仕様上、旧住所に送られることがわかっていまして」
ヤマト運輸「Amazon で買ったなら送り状番号わかりますよ」
私「今はわからないようになっているようで」
ヤマト運輸「いつわかるようになるんですか？」
私「このご時世は個人情報保護の観点でわからないようになっているみたいです。旧住所の情報をお伝えすることで、送り状番号なしでも何とかなりませんか？」
ヤマト運輸（別の方）「送り状番号がわからなければ私たちは何もできませんでして……」

ヤマト運輸に関しては送り状番号がわからないとどうしようもないことがわかったので、何とかして送り状番号を入手できないかと考えたところ、既に 2 回配達を試みて失敗していることから、旧住所の郵便受けに不在票が溜まっているはずと考え、旧住所の管理会社に連絡することにしました。

また、この頃には Amazon が配送業者になっている場合は配送状況のページにキャンセルボタンが現れたようです。おそらく 2 回以上配送に失敗したらキャンセルボタンが現れものと思われます。

5. 旧住所の管理会社に連絡

私「以前〇〇に入居していた、あらびきと申しますが、どうも〇〇に荷物が送られてしまったらしく、不在票が入っていると思うので確認していただきたいのですが」
管理会社「担当者がちょうどそのエリアに出ていっているので回収してもらいますね」
私「送り方がちょっと特殊でして、具体的には Amazon のほしい物リストなんですが、もしかしたら誰宛ての不在票かわからないかもしれないので、現入居者の方の不在票を回収しないよう注意してください」

その後、担当者の方から連絡があり、最終的に自分宛ての不在票の全ての情報を共有してもらえました。
しかし、ちょうどその頃、発送が遅れていた荷物（Amazon が配送業者）が配達済みになったとの連絡を受けました。当然現住所には届いていませんでした。
何はともあれ、未配達のものに関しては不在票を入手することができたので、再度ヤマト運輸と Amazon に連絡してみます。

6. ヤマト運輸に連絡

私「旧住所宛に送られてしまった荷物の宛先を変更したいんですが」
ヤマト運輸「送り状番号を教えてください」
私「XXXXXXX です」
ヤマト運輸「本人確認のためお名前と宛先になっている住所を教えてください」
私「名前はあらびきたけしです。住所は東京都〇〇区…です」
ヤマト運輸「転送という形になって、お時間がかかるのと、追加料金を着払いでお支払いいただくことになりますがよろしいですか？」
私「クロネコメンバーズからだと営業所への配達に変更できると思うんですが、営業所への配達に変更はできないでしょうか？」
ヤマト運輸「とりあえず住所を教えてもらえますか？」
私「東京都〇〇区…です」
ヤマト運輸「転送料金は着払いになるのでご準備よろしくお願いします」
私「…わかりました」

クロネコメンバーズと連携されていた荷物だと無料で近所の営業所の受け取りに変更できたので、思うところはありましたが、ヤマト運輸が配送業者になっているものに関しては問題が解消しました。

なお、転送依頼後も住所不明になっていて届かなかったので再度連絡をする必要がありました。マンション名の表記について質問された記憶があるので、マンション名や部屋番号を伝え忘れたとは思えないのですが、マンション名や部屋番号が未記入になっていたようです。

7. Amazon に連絡

私「ほしい物リストにあった商品が旧住所宛に送られて配送に失敗しているようなんですが、宛先を変更することはできますか？」
Amazon「できません」
私「キャンセルすることはできますか？」
Amazon「お問い合わせ番号か注文番号はわかりますか？」
私「3 つあって、… です」
Amazon「返金方法として Amazon ギフトカードを送らせていただく形になりますがよろしいですか？」
私「大丈夫です」
Amazon「キャンセルしました。3 時間以内にギフトカードが送られるはずです」
私「旧住所宛に配達済みになった荷物もあるんですが、Amazon さんの方で対応していただけることはありますか？」
Amazon「受け取った方が返送してくれれば返金対応できますが、破棄された場合は自己責任なので何もできません」

配達済みになった荷物に関しては Amazon 側の対応が期待できなかったので、現在の住居者に荷物を取りに伺っても大丈夫か聞いてもらえないか管理会社にお願いしてみたのですが、「大変申し訳ないのですが、現入居者様と取り次ぐ行為は固く禁じられています。ご了承願います。」との回答をいただきました。まぁそうですよね…

再度 Amazon に連絡してみます。

8. Amazon に連絡

私「ほしい物リストのお届け先はアカウントの住所を変更しても変更が反映されないと思うんですが、それによって旧住所宛に送られて配達済みになってしまった商品があるんですが、Amazon さんの方で対応していただけることはありますか？」
Amazon「キャンセルして返金という対応でしたら可能です。注文番号はわかりますか？」
私「XXXXXXXX です」
Amazon「返金は Amazon ギフトカードの形で行われて、受取人様に返金されることになりますがよろしいですか？」
私「？？購入者ではないんですか？」
Amazon「購入者様に返金するには購入者様から連絡していただく必要があります」
私「わかりました。大丈夫です」
Amazon「キャンセルしました。3 時間以内にギフトカードが送られるはずです」

9. Amazon ギフトカードの送信

返金は全て自分のアカウントに対して行われたので、返金対応になった商品を送ってくださった方のメールアドレス宛に同額のギフトカードを送りました。
キャンセルした商品はほしい物リストに復元されないので、もし再購入してもらう場合は「お届け先住所」を更新した上で再度ほしい物リストに追加する必要があります。

これにて全ての対応が終わりました。

Amazonの「ほしい物リスト」の設定にご注意ください！ | LAC WATCH が 2016 年の記事であることを考えると、今後も今の仕様が変わることはなさそうですが、なかなか困った仕様ですね…

Auth0 の Deploy CLI Tool で Auth0 CLI の access token を利用する

Thu, 04 Dec 2025 00:00:00 +0900

Auth0 の Deploy CLI Tool では Create a dedicated Auth0 application で説明されているように Machine to Machine Application を作成し、その client ID/secret を使うのが一般的です。
CI/CD などに組み込む場合はその方法が良いでしょうが、開発者一人ひとりが Auth0 の設定をエクスポートしたい場合などに client ID/secret を利用するのは、開発者体験的にも secret の流出リスク的にも避けたいものです。

そこで、Auth0 CLI は Machine to Machine Application を作成せずとも Auth0 のリソースにアクセスできることから、Auth0 CLI で利用している access token を利用できるのではと考えました。

Auth0 CLI の access token を使って export するサンプルコード

というわけで、完成したのが以下のコードです。

#!/bin/bash

set -euo pipefail

ADDITIONAL_SCOPES=read:guardian_factors,read:mfa_policies,read:self_service_profiles

get_access_token() {
  local token=""
  if ! token=$(jq -er '.tenants["'$domain'"].access_token' $config_file); then
    token=$(get_access_token_from_keychain)
  fi
  echo $token
}

# Retrieves an access token from the macOS keychain.
# This mimics the way the Auth0 CLI stores tokens, based on:
# - https://github.com/auth0/auth0-cli/blob/v1.23.0/internal/keyring/keyring.go#L96-L113
# - https://github.com/zalando/go-keyring/blob/v0.2.6/keyring_darwin.go#L42-L67
get_access_token_from_keychain() {
  local access_token=""

  for i in {0..49}; do
    if ! out=$(security find-generic-password -s "Auth0 CLI Access Token $i" -wa $AUTH0_DOMAIN 2>&1); then
      if [[ $out == *"could not be found"* ]]; then
        echo $access_token
        return 0
      else
        echo $out >&2
        return 1
      fi
    fi

    # go-keyring-base64:ZXlK... => ZXlK... => eyJ...
    access_token+=$(cut -d: -f2 <<< $out | base64 -d)
  done

  echo $access_token
}

decode_jwt() {
  # https://gist.github.com/angelo-v/e0208a18d455e2e6ea3c40ad637aac53?permalink_comment_id=3439919#gistcomment-3439919
  jq -R 'gsub("-";"+") | gsub("_";"/") | split(".") | .[1] | @base64d | fromjson' <<< $1
}

# The Auth0 CLI exits with status 0 on SIGINT, so trap it to stop the script.
trap exit INT

domain=${AUTH0_DOMAIN:?Error: AUTH0_DOMAIN is required}

config_file=~/.config/auth0/config.json

if [ -f $config_file ]; then
  if ! jq -e '.tenants["'$domain'"]' $config_file > /dev/null; then
    auth0 login --domain $domain --scopes $ADDITIONAL_SCOPES
  fi
else
  auth0 login --domain $domain --scopes $ADDITIONAL_SCOPES
fi

token=$(get_access_token)
if [ -n "$token" ]; then
  payload=$(decode_jwt $token)
  exp=$(jq '.exp' <<< $payload)
  require_additional_scopes=$(jq '($ARGS.positional[0] | split(",")) - (.scope | split(" ")) | length > 0' --args $ADDITIONAL_SCOPES <<< $payload)
fi
if [ -z "$token" ] || [ $(date +%s) -ge $exp ] || $require_additional_scopes; then
  auth0 login --domain $domain --scopes $ADDITIONAL_SCOPES
  token=$(get_access_token)
fi

trap - INT
AUTH0_ACCESS_TOKEN=$token a0deploy export --format=yaml -o .

Auth0 CLI の access token を取得する処理はコメントにもあるとおり次の箇所が肝になっていて、それを模倣しています。

Linux に関しては docker container で試した感じだと ~/.config/auth0/config.json に access token が保存されたので深くは処理を追っていません。環境によっては追加の処理が必要かもしれません。

余談: access token の expiration を考慮するのが地味に大変

完成したコードは割とシンプルなコードになっているんじゃないかと思いますが、expiration を考慮するのが大変でした。
access token の expiration は ~/.config/auth0/config.json の expires_at に 2025-12-04T18:17:33.110929+09:00 のような形式で入っているので、最初はそれを利用しようと考えました。TZ=UTC の環境だと 2025-12-04T09:17:33.110929Z になります。
時刻の比較をするには unixtime にする方が都合が良いので変換したかったんですが、jq も date コマンドもこの形式の timestamp は簡単には処理できません。

jq で timestamp を unixtime に変換することの問題点

まず、fromdateiso8601 がミリ秒をサポートしていません。

$ jq -n '"2025-12-04T18:17:33.110929+09:00" | fromdateiso8601'
jq: error (at <unknown>): date "2021-02-16T15:36:29+0000" does not match format "%Y-%m-%dT%H:%M:%SZ"

cf. Parsing of milliseconds in dates · Issue #1409 · jqlang/jq

次に、timezone offset をサポートしていません。

$ jq -n '"2025-12-04T18:17:33.110929+09:00" | sub("\\.[0-9]+"; "") | fromdateiso8601'
jq: error (at <unknown>): date "2025-12-04T18:17:33+09:00" does not match format "%Y-%m-%dT%H:%M:%SZ"
$ jq -n '"2025-12-04T18:17:33.110929+09:00" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
jq: error (at <unknown>): date "2025-12-04T18:17:33+09:00" does not match format "%Y-%m-%dT%H:%M:%S%z"

cf. fromdate should support timezone offsets · Issue #1053 · jqlang/jq

strptime は timezone offset からコロンを取り除けば Mac ではエラーにはなりません。ただ、TZ=UTC を指定する必要があります。

$ jq -n '"2025-12-04T18:17:33.110929+09:00" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
jq: error (at <unknown>): date "2025-12-04T18:17:33+09:00" does not match format "%Y-%m-%dT%H:%M:%S%z"
$ jq -n '"2025-12-04T18:17:33.110929+0900" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764872253
$ date -r1764872253 +%Y-%m-%dT%H:%M:%S%z
2025-12-05T03:17:33+0900
$ TZ=UTC jq -n '"2025-12-04T18:17:33.110929+0900" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764839853
$ date -r1764839853 +%Y-%m-%dT%H:%M:%S%z
2025-12-04T18:17:33+0900

Linux だとコロンがあってもなくてもエラーにはならないものの offset が無視されます。

$ jq -n '"2025-12-04T18:17:33.110929+0900" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764872253
$ jq -n '"2025-12-04T18:17:33.110929+09:00" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764872253
$ jq -n '"2025-12-04T18:17:33.110929+00:00" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764872253
$ jq -n '"2025-12-04T18:17:33.110929+0000" | sub("\\.[0-9]+"; "") | strptime("%Y-%m-%dT%H:%M:%S%z") | mktime'
1764872253

cf. strptime/1 ignores ISO-8601 TimeZone (format string “%z”) · Issue #2195 · jqlang/jq

というわけで、jq を利用することは諦めました。

date で timestamp を unixtime に変換することの問題点

Linux の date コマンドであれば次のように簡単に処理できます。

$ date -d 2025-12-04T18:17:33.110929+0900 +%s
1764839853

ところが、BSD の date コマンドだと一筋縄ではいきません。ミリ秒情報を削除して、timezone offset からコロンを取り除く必要があります。

$ date -j -f '%FT%T%z' 2025-12-04T18:17:33+0900 +%s
1764839853

timezone 情報が Z の場合も別の処理が必要になります。

$ date -j -f '%FT%T%z' 2025-12-04T18:17:33Z
Failed conversion of ``2025-12-04T18:17:33Z'' using format ``%FT%T%z''
date: illegal time format
usage: date [-jnRu] [-I[date|hours|minutes|seconds]] [-f input_fmt]
            [-r filename|seconds] [-v[+|-]val[y|m|w|d|H|M|S]]
            [[[[mm]dd]HH]MM[[cc]yy][.SS] | new_date] [+output_fmt]
$ date -j -f '%FT%T%Z' 2025-12-04T18:17:33Z
Failed conversion of ``2025-12-04T18:17:33Z'' using format ``%FT%T%Z''
date: illegal time format
usage: date [-jnRu] [-I[date|hours|minutes|seconds]] [-f input_fmt]
            [-r filename|seconds] [-v[+|-]val[y|m|w|d|H|M|S]]
            [[[[mm]dd]HH]MM[[cc]yy][.SS] | new_date] [+output_fmt]

Linux の場合と Mac の場合で分岐をして、Mac の場合はミリ秒やコロンを取り除いて、更に timezone offset か Z かで分岐をして…とするぐらいなら、JWT を decode した方がよっぽど楽ではとなって最終的なコードが完成しました。

AWS ユーザに送る Azure 権限管理 (RBAC) 入門

Tue, 02 Dec 2025 00:00:00 +0900

AWS や Google Cloud にも言えることですが、初めて Azure を利用する際には情報が膨大過ぎてどこからキャッチアップを始めれば良いか戸惑うことでしょう。
自分自身もだいぶ苦労したことから、同じような境遇の方に向けて Azure の入門記事を書くには何が良いだろうかと考えたところ、権限管理についての入門記事を書けば Azure の用語やコンセプトなどの理解も深まるし、どのサービスを使うにしても活きてくるのではと思い立ちました。
というわけで、今回は Azure におけるリソースの権限管理について基本的な内容について説明します。
なお、Azure のリソースの権限管理と Entra ID（旧 Azure Active Directory）の権限管理は別物で、今回焦点を当てるのは前者のみです。読者としては Azure を使い始めて間もない人で、かつある程度 AWS の知識がある人を想定しています。

RBAC による権限管理

AWS では各種リソースに対してどのような操作ができるかを IAM (Identity and Access Management) で管理しますが、Azure では Azure RBAC（アールバック）が使われます。
RBAC は role-based access control のことで、role に permission を付与して、その role をユーザなどに付与する形式の権限管理方法です。Azure に触れたことがない方でも Kubernetes を運用したことがあれば馴染み深い概念でしょう。

例えば、built-in role の Contributor role は次のように定義されています。

$ az role definition list --name "Contributor" | sed "s/$(az account show --query id -o tsv)/{subscriptionId}/g"
[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2015-02-02T21:55:09.880642+00:00",
    "description": "Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC, manage assignments in Azure Blueprints, or share image galleries.",
    "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
    "name": "b24988ac-6180-42a0-ab88-20f7382dd24c",
    "permissions": [
      {
        "actions": [
          "*"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.Authorization/*/Delete",
          "Microsoft.Authorization/*/Write",
          "Microsoft.Authorization/elevateAccess/Action",
          "Microsoft.Blueprint/blueprintAssignments/write",
          "Microsoft.Blueprint/blueprintAssignments/delete",
          "Microsoft.Compute/galleries/share/action",
          "Microsoft.Purview/consents/write",
          "Microsoft.Purview/consents/delete",
          "Microsoft.Resources/deploymentStacks/manageDenySetting/action",
          "Microsoft.Subscription/cancel/action",
          "Microsoft.Subscription/enable/action"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Contributor",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2024-11-18T20:00:23.830435+00:00"
  }
]

notActions で指定されている一部の actions を除いて全ての actions が許可されているのが雰囲気でわかるかと思います。

Azure には AWS IAM の inline policy に相当するものは存在しないので、ユーザ等に権限を付与するには必ず何かしらの role を付与することになります。よって、built-in role に所望の権限を持ったものがない場合は、custom role を定義する必要があります。

例えば、拙作の Azure Key Vault Provider の terraform apply 用の custom role は次のような定義になります。

{
  "Name": "Terraform Provider for Azure Key Vault Applier",
  "Actions": [
    "Microsoft.KeyVault/vaults/read"
  ],
  "DataActions": [
    "Microsoft.KeyVault/vaults/secrets/delete",
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action",
    "Microsoft.KeyVault/vaults/secrets/setSecret/action"
  ],
  "AssignableScopes": [
    "/subscriptions/$subscriptionId"
  ]
}

Azure portal から custom role を作成するにはどの scope（後述）を対象にするかにもよりますが、subscription 全体で利用する場合は subscription の詳細画面の Access control (IAM) から Add custom role をクリックします。

Azure portal 上からだと対象サービス（resource provider）を選択することで permission を付与する action の一覧が出てくるので、付与すべき permission がわからない場合は一度 Azure portal から作成するのが良いでしょう。

Actions と Data actions

Contributor role などの定義や permission の選択画面に data action という言葉が出てきたことに気付いた方も多いかと思います。
次の結果は Owner role の定義ですが、全ての actions が許可されている一方で、data actions は何も許可されていないため、Owner role という何でもできる権限を持っていそうな role にも関わらず、実行できない操作があることを意味します。

$ az role definition list --name "Owner" | sed "s/$(az account show --query id -o tsv)/{subscriptionId}/g"
[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2015-02-02T21:55:09.880642+00:00",
    "description": "Grants full access to manage all resources, including the ability to assign roles in Azure RBAC.",
    "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
    "name": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
    "permissions": [
      {
        "actions": [
          "*"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "Owner",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2021-11-11T20:13:45.897885+00:00"
  }
]

data actions の説明は次のとおりで、data plane に対する actions を意味します。

The DataActions permission specifies the data plane actions that the role allows to be performed to your data within that object. For example, if a user has read blob data access to a storage account, then they can read the blobs within that storage account. Here are some examples of data actions that can be used in DataActions.

cf. DataActions

では data plane とは何なのかというと、Azure control plane and data plane に説明があるんですが、control plane と data plane の違いに関する感覚を掴むのは難しいかと思います。
とりあえず Owner でも権限不足でエラーになることがあることを覚えておくと良いでしょう。

例えば、Azure では秘匿値を管理するのに Key Vault secrets が利用されますが、secret value を取得するには Microsoft.KeyVault/vaults/secrets/getSecret/action の data action が許可されている必要があるので、Owner といえどもこの data action の権限を持った role が付与されていなければ値を参照できません。このことは secret value を取得するための role である Key Vault Secrets User role の定義からもわかります。

$ az role definition list --name "Key Vault Secrets User" | sed "s/$(az account show --query id -o tsv)/{subscriptionId}/g"
[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2020-05-19T17:52:47.204924+00:00",
    "description": "Read secret contents. Only works for key vaults that use the 'Azure role-based access control' permission model.",
    "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6",
    "name": "4633458b-17de-408a-b874-0445c86b69e6",
    "permissions": [
      {
        "actions": [],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [
          "Microsoft.KeyVault/vaults/secrets/getSecret/action",
          "Microsoft.KeyVault/vaults/secrets/readMetadata/action"
        ],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "Key Vault Secrets User",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2021-11-11T20:14:30.954282+00:00"
  }
]

なお、secret value の取得に使われるのが Get Secret API ですが、API のドキュメントからはどの action を許可すべきか想像が付かないため、built-in role に対して許可されている action や custom role 作成時の action の一覧の説明文から必要な権限を想像することになります。

Role assignment の scope

AWS IAM では action の対象として Resource を指定しますが、似たような概念として Azure RBAC では role を付与する際に scope を指定します。

RBAC における scope を理解するには Entra ID, tenant, directory, management group, subscription, resource group という用語を理解しておくと良いです。
management group 以外については Microsoft Azure利用ガイド_2024年1月版の 5 ページ目にこれらの用語について簡潔にまとまっている表があったのでそちらを拝借します。

management group は複数の subscription などを管理するのに使えるもので、初期状態では Tenant Root Group のみが存在します。

図で表現すると次のような階層関係になります。

上位に存在するリソースを scope として role を付与すると、その下位に存在するリソースに対しても role の権限を付与することになります。例えば、subscription リソースを対象に Key Vault Secrets User role を付与した場合、その subscription で管理されている全の secret を取得可能になります。

以下の図は bguqnbvvegkejyoyublnndqf という名前の Key Vault に対する role assignments の一覧ですが、admin group には subscription を scope に、alloy-secret-creator にはこのリソース（bguqnbvvegkejyoyublnndqf）を scope に Key Vault Secrets User role が付与されていることがわかります。

なお、通常のサービスには本番環境以外に開発用の環境など複数の環境が存在することが一般的ですが、このことからも、Azure では環境ごとに subscription を分けることが推奨されています。

Management boundary: Subscriptions provide a management boundary for governance and isolation, which allows a clear separation of concerns. Various environments, such as development, test, and production environments, are often removed from a management perspective.

cf. Organization and governance recommendations

Role assignment

AWS では IAM という 1 つのサービスが存在し、AWS managemnet console 上でユーザ等に権限を付与する際には IAM service にアクセスして操作しますが、Azure portal には RBAC と呼ばれるようなサービスはありません。

ではどうやって role を付与するかというと、role の scope となるリソースの Access control (IAM) メニューから付与します。

前述のとおり、付与できるのは role のみで、AWS IAM の inline policy に相当するものは存在しないので、built-in role に所望の権限を持ったものがない場合は、custom role を定義する必要があります。

各 role の権限は role を付与する際の一覧の Details から確認することができます。

Access control (IAM) の Roles タブからも確認することができます。

なお、付与されている role については、対象リソースの Role assignments で確認できます。

特定のユーザなどに付与されている role を確認するには、確認したいリソースの詳細画面の Azure role assignments にアクセスします。
次の図では aks-example-agentpool という managed identity（後述）の権限を表示しています。

Role assignment の対象 (Identity)

AWS では権限を付与する対象として IAM user、IAM instance profile、ECS task IAM role などがありますが、Azure にも様々な概念があります。
自分が知る限り、大きく分類すると次の 5 種類が存在します。

Entra ID user
Entra ID group
Service principal
Managed identity
Workload identity

Entra ID user/group に関しては IAM user/group のようなもので説明不要かと思いますが、残りの 3 つに関しては初見だとそれっぽい公式ドキュメントを読んでも理解するのが難しいかと思います。少なくとも僕は未だに自信を持って理解できているとは言えません…。
service principal の正確な説明は後回しにして、ひとまずわかりやすさを重視して service principal, managed identity, workload idenity について説明します。

Service principal

認証の文脈で service principal という用語が出てきたら、client secret や certificate によって認証する machine user と理解するのが良いと思います。
例えば次のドキュメントではこの意味で使われています。

Azure CLI でも同様の意味で使われています。

$ az login --help
-- snip --
Arguments
-- snip --
    --service-principal      : Log in with a service principal.

どのような時に利用するかというと、Azure 外から Azure のリソースにアクセスする必要がある時に利用します。具体的には以下のようなケースが挙げられます。

ローカル環境から Entra ID user/group 以外の権限でリソースにアクセスしたい
- 特定のアプリケーションを動かすのに必要な権限が何かを試行錯誤するのに便利
Datadog、Grafana Cloud のような外部サービスと連携したい
OIDC 連携したい ¹
- GitHub Actions の例: Configuring OpenID Connect in Azure - GitHub Docs

service principal を作成するには、Azure portal だと App registrations から New registration をクリックし、Azure CLI だと次のコマンドを実行します。

az ad sp create-for-rbac

Azure portal から作成する場合は自動的には client secret が作成されませんが、Azure CLI から作成する場合は --create-password false を指定しない限り自動的に 1 年間有効な client secret が作成されます。

Azure portal や --create-password false を指定して作成した場合は App registrations から当該 service principal を選択することで client secret を作成できます。

service principal に role を付与するには、role assignment の際に Assign access to で “User, group, or service principal” を選択します。

なお、Azure 内で Azure のリソースにアクセスするケースでは後述する managed identity を利用することが推奨されています。

Managed identity

managed identity は Azure 内でのみ利用可能な machine user と理解するのが良いと思います²。service principal は client secret や certificate が必要でしたが、managed identity ではそのような credential を管理する必要はありません。この観点では AWS の IAM instance profile や ECS task IAM role に近いです。

managed idenitty には system identity という、リソースと不可分な managed identity と、user identity という複数のリソースに紐付けることが可能な managed identity があります。よって、AWS の IAM role に近いのは user identity です。

Managed identity が使われる代表的な例は Azure Virtual Machines (AWS の EC2 に相当) で、Azure portal から Virtual Machine (VM) を作成する際に system assigned managed identity を有効にすることができます。後から user managed identity を紐付けることもできます。

VM に managed identity が紐付いている場合、例えば azure-sdk-for-go の DefaultAzureCredential を使ったアプリケーションを VM 上で動かすと、特別な設定をしなくてもリソースにアクセスする際に Azure Instance Metadata Service から access token を取得するようになっています。

managed identity に role を付与するには、role assignment の際に Assign access to で “Managed identity” を選択します。

なお、後述するように managed identity は厳密には service principal の一種なので、”User, group, or service principal” を選んで managed identity の名前の先頭何文字かを入力することでも role を付与することができます。

Workload identity

Workload identity は What are workiload identities? では次のように定義されています。

In Microsoft Entra, workload identities are applications, service principals, and managed identities.

ところが、実態としては Azure Kubernetes Service (AKS) の Pod で利用する managed identity という意味で使われることがほとんどかと思います。以下は AKS の Pod で利用する managed identity の意味で使われている例です。

ただし、Configuring OpenID Connect in Azure - GitHub Docs のように managed identity に限定しない使い方がされているケースもあるので、文脈で判断する必要があります。

AKS の Pod で managed identity を利用する方法については Use Microsoft Entra Workload ID with Azure Kubernetes Service (AKS) を参照してください。正しく設定することで Pod に次の環境変数が設定されます。

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_FEDERATED_TOKEN_FILE

これらの環境変数のおかげで、例えば azure-sdk-for-go の DefaultAzureCredential を使ったアプリケーションを Pod 上で動かすと、特別な設定をしなくてもリソースにアクセスする際に access token を取得するようになっています。

workload identity に role を付与する方法は managed identity と同様です。

Service principal とは何なのか？

先ほどはわかりやすさを重視して正確な説明を避けましたが、service principal とは Service principal object で説明されているように、application と managed identity の総称のようです。また、前述のとおり、workload identity は application, service principal, managede identity を指すようです。

しかし Azure の公式ドキュメントを含め、多くのドキュメントでは service principal と managed identity は完全に別物として扱われており、workload identity は AKS で利用する managed identity を指していることがほとんどな印象です。

正確な定義と実際の使われ方を図にすると次のようなイメージになります。

service principal の一覧は Enterprise applications で確認することができ、Application type を Enterprise Applications にすると App registrations で application object を作成した時に同時に作成された service principal (local application) が表示され、Applicatin type を Managed Identites にすると managed identity が表示されるようです。role assignment の際に使われている ID が Enterprise applications の object ID であることからも、service principal が application と managed identity の上位概念であることが伺えます。

ただ、前述のとおり、多くのドキュメントにおいて service principal は application のことを指していて、managed identity とは別物として扱われているので、service principal とは「client secret や certificate によって認証する machine user」と理解しておくのが良いと思います。

なお、application（というより application object？）には Entra ID App Registration Auth using OIDC のように OIDC の機能もありますが今回は触れません。

RBAC 以外の認証・認可

RBAC が使える場合は基本的に RBAC の利用が推奨されていますが、例えば次のように各種 Azure サービス固有の認証・認可方法が提供されているものもあります。

Manage storage account access keys
- storage account (S3 みたいなもの) に紐付く admin 権限を持った credential を利用する方法で、access key は無効化することが強く推奨されている
Authenticate to Azure Communication Services - Access Key
- 概念としては storage account の access key と同じ
Assign a Key Vault access policy (legacy)
- Key Vault に対して誰がどの権限を有しているか access policy を定義する

storage account の blob (object) へのアクセスは data action なので、本来であれば Owner role といえども blob にアクセスできませんが、デフォルトの storage account の設定だと data action の権限を付与しなくてもアクセスできてしまいます。これは Owner role に access key の取得権限があり、access key を使って blob にアクセスするからです。

Terraform のドキュメントを読み解く

Azure 関連の Terraform ドキュメントには、認証に関する用語がたくさん出てくるので理解度チェックには持ってこいです。

Azure のリソースを Terraform で管理する場合、state file は storage account (S3 みたいなもの) で管理すると思いますが、その場合に参照すべきドキュメントは以下の 2 つです。

Backend Type: azurerm | Terraform | HashiCorp Developer
Azure Provider - Authenticating to Azure
- Azure Provider: Authenticating using managed identities for Azure Kubernetes Service with Workload Identity はこの一覧に載っていないので注意

前者は Terraform に組み込まれていて、後者は provider の一種なので、微妙に認証方法が異なります。
また、Azure Provider は新しい機能をサポートするのに時間がかかるので、Azure が提供している AzAPI Provider も併用することが多いですが、こちらも認証方法が異なります。
つまり、Azure のリソースを Terraform で管理するには 3 種類の認証実装を意識する必要があり、それぞれが利用している package は次のとおりです。

azurerm backend: http://github.com/hashicorp/go-azure-helpers
Azure Provider: http://github.com/hashicorp/go-azure-sdk
AzAPI Provider: https://github.com/Azure/azure-sdk-for-go

Azure Provider のドキュメントは一覧に載っている Managed Service Identity が Managed Identity の旧称ということさえ知っていれば、これまでの説明から VM の managed identity を利用する場合の方法ということがわかるでしょう。
Azure SDK for Go については度々出てきていますが、基本的に実行環境に合わせてよしなに認証してくれるのであまり意識する必要はありません。
問題は azurerm backend で、初見だとわかりづらいと思うので補足します。

なお、az login によってログイン状態にある環境では特別な設定をしなければ Azure CLI を使った認証が行われます。具体的には access token が az account get-access-token によって取得されます。

azurerm backend の認証に関する主な設定項目

Backend Type: azurerm | Terraform | HashiCorp Developer には次のような言葉が出てきます。

use_azuread_auth - (Optional) Whether Microsoft Entra ID Authentication for storage account data plane authentication. This can also be sourced from the ARM_USE_AZUREAD environment variable.
use_oidc - (Optional) Set to true to use OpenID Connect / Workload identity federation authentication for authentication to the storage account management and data plane. This can also be sourced from the ARM_USE_OIDC environment variable.
oidc_token_file_path - (Optional) The path to a file containing an ID token when authenticating using OpenID Connect. This is only required for advanced scenarios or third party integrations. This can also be sourced from the ARM_OIDC_TOKEN_FILE_PATH environment variable.
use_aks_workload_identity - (Optional) Set to true to use Azure AKS Workload Identity for authentication. This is only required for advanced scenarios or third party integrations. This can also be sourced from the ARM_USE_AKS_WORKLOAD_IDENTITY environment
use_msi - (Optional) Set to true to use a Compute Attached Managed Service Identity for authentication to the storage account management and data planes. This can also be sourced from the ARM_USE_MSI environment variable.

まず、use_azuread_auth は true に指定することで state file を保存している storage account の権限管理に RBAC を利用するようになります。デフォルトだと access key が使われます。前述のとおり、access key は無効化することが強く推奨されているので、true に設定するケースがほとんどでしょう。

use_oidc と oidc_token_file_path は service principal (application) や managed identity で設定した federated credential を利用する場合に true に設定するもので、例えば AKS で workload identity を利用する場合に指定します。
AKS の workload identity 用の設定項目として use_aks_workload_identity がありますが、これは use_oidc を true にして、oidc_token_file_path に AZURE_FEDERATED_TOKEN_FILE 環境変数の値をセットするのと同義です。

use_msi は VM の managed identity を利用する場合に true にします。managed service identity は managed identity の旧称のようです。

Managed identities for Azure are the new name for the service formerly known as Managed Service Identity (MSI).

cf. Use Managed identities for Azure with Azure Monitor SCOM Managed Instance

最後に

以上、Azure 権限管理についてざっくり説明しました。この記事がこれから Azure を使い始める方にとって有益なものになると幸いです。

OIDC を利用するなら managed identity でも可能です ↩
OIDC 連携でも利用できるので、厳密には Azure 外でも利用可能です ↩

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（後編）〜Getting Started Guide の先へ〜

Mon, 06 Oct 2025 00:00:00 +0900

前編では Grafana Cloud の Getting Started Guide に従って Grafana Alloy をインストールする方法や、Kubernetes Monitoring Helm chart の values の読み解き方や、secret を別で管理する方法について説明しました。
今回は設定の変更方法、デバッグ方法、OpenTelemetry との連携方法に焦点を当てます。
前回同様、Kubernetes Monitoring Helm chart で Alloy がインストールされていて、namespace は alloy、release name は grafana-k8s-monitoring であるものとします。

config.alloy の変更方法

Kubernetes Monitoring Helm chart では、values を変更することで各種 Alloy が利用する設定 (config.alloy) を変更することができます。

各種 Alloy の設定は ConfigMap で管理されているため、values の変更によってどのように設定が変わるかは、helm template で出力される結果の前後比較を行うことで確認できます。

helm template grafana-k8s-monitoring grafana/k8s-monitoring -f values.yaml

例えば、次のように Windows exporter を無効化してみます。

clusterMetrics:
  enabled: true
  kube-state-metrics:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
  windows-exporter:
    deploy: false
    enabled: false

すると、grafana-k8s-monitoring-alloy-metrics の config.alloy から Windows exporter に関する設定が消えます。

@@ -540,64 +501,6 @@
         }
         forward_to = argument.metrics_destinations.value
       }
-
-      // Windows Exporter
-      discovery.kubernetes "windows_exporter_pods" {
-        role = "pod"
-        selectors {
-          role = "pod"
-          label = "app.kubernetes.io/name=windows-exporter,release=grafana-k8s-monitoring"
-        }
-        namespaces {
-          names = ["alloy"]
-        }
-      }
-
-      discovery.relabel "windows_exporter" {
-        targets = discovery.kubernetes.windows_exporter_pods.targets
-
-        // keep only the specified metrics port name, and pods that are Running and ready
-        rule {
-          source_labels = [
-            "__meta_kubernetes_pod_container_port_name",
-            "__meta_kubernetes_pod_container_init",
-            "__meta_kubernetes_pod_phase",
-            "__meta_kubernetes_pod_ready",
-          ]
-          separator = "@"
-          regex = "metrics@false@Running@true"
-          action = "keep"
-        }
-
-        // Set the instance label to the node name
-        rule {
-          source_labels = ["__meta_kubernetes_pod_node_name"]
-          target_label = "instance"
-        }
-      }
-
-      prometheus.scrape "windows_exporter" {
-        targets  = discovery.relabel.windows_exporter.output
-        job_name   = "integrations/windows-exporter"
-        scrape_interval = "60s"
-        scrape_timeout = "10s"
-        scrape_protocols = ["OpenMetricsText1.0.0","OpenMetricsText0.0.1","PrometheusText0.0.4"]
-        scrape_classic_histograms = false
-        clustering {
-          enabled = true
-        }
-        forward_to = [prometheus.relabel.windows_exporter.receiver]
-      }
-
-      prometheus.relabel "windows_exporter" {
-        max_cache_size = 100000
-        rule {
-          source_labels = ["__name__"]
-          regex = "up|scrape_samples_scraped|windows_.*|node_cpu_seconds_total|node_filesystem_size_bytes|node_filesystem_avail_bytes|container_cpu_usage_seconds_total"
-          action = "keep"
-        }
-        forward_to = argument.metrics_destinations.value
-      }
     }
     cluster_metrics "feature" {
       metrics_destinations = [
@@ -1220,7 +1123,7 @@
     # HELP grafana_kubernetes_monitoring_feature_info A metric to report the enabled features of the Kubernetes Monitoring Helm chart
     # TYPE grafana_kubernetes_monitoring_feature_info gauge
     grafana_kubernetes_monitoring_feature_info{feature="applicationObservability", protocols="otlpgrpc,otlphttp,zipkin", version="1.0.0"} 1
-    grafana_kubernetes_monitoring_feature_info{deployments="kube-state-metrics,node-exporter,windows-exporter", feature="clusterMetrics", sources="kubelet,kubeletResource,cadvisor,kube-state-metrics,node-exporter,windows-exporter", version="1.0.0"} 1
+    grafana_kubernetes_monitoring_feature_info{deployments="kube-state-metrics,node-exporter", feature="clusterMetrics", sources="kubelet,kubeletResource,cadvisor,kube-state-metrics,node-exporter", version="1.0.0"} 1
     grafana_kubernetes_monitoring_feature_info{feature="clusterEvents", version="1.0.0"} 1
     grafana_kubernetes_monitoring_feature_info{feature="podLogs", method="volumes", version="1.0.0"} 1
     grafana_kubernetes_monitoring_feature_info{feature="integrations", sources="alloy", version="1.0.0"} 1

また、Extra Configuration や Extra Rules で紹介されているように、任意の設定を追加することも可能です。
例えば、次のように podLogs.extraLogProcessingStages と alloy-logs.extraConfig を指定してみます。

podLogs:
  enabled: true
  extraLogProcessingStages: |
    // This is a comment in loki.process.pod_logs
alloy-logs:
  enabled: true
  extraConfig: |
    // This is an extra config

すると、grafana-k8s-monitoring-alloy-logs の config.alloy の内容が次のように変わります。

@@ -1432,6 +1432,7 @@
             "service_instance_id" = "service_instance_id",
           }
         }
+        // This is a comment in loki.process.pod_logs

         // Only keep the labels that are defined in the `keepLabels` list.
         stage.label_keep {
@@ -1449,7 +1450,7 @@



-
+    // This is an extra config
     // Destination: grafana-cloud-logs (loki)
     otelcol.exporter.loki "grafana_cloud_logs" {
       forward_to = [loki.write.grafana_cloud_logs.receiver]

もし直接 config.alloy を記述したい場合、alloy-*.alloy.configMap.content に指定することも可能です。

alloy-logs:
  enabled: true
  alloy:
    configMap:
      create: true
      name: grafana-k8s-monitoring-alloy-logs-custom
      content: |
        // Feature: Pod Logs
        declare "pod_logs" {
          argument "logs_destinations" {
            comment = "Must be a list of log destinations where collected logs should be forwarded to"
          }
        // -- snip --

この場合、name には Helm chart で作られる ConfigMap とは異なるものを指定してください。上記の例では Helm chart で作成される ConfigMap の名前に -custom suffix を付与しています。
もし同じ名前を指定した場合、grafana-k8s-monitoring-alloy-operator で次のようなエラーが出て ConfigMap の内容の更新に失敗します。

$ kubectl logs -n alloy deploy/grafana-k8s-monitoring-alloy-operator
-- snip --
{"level":"error","ts":"2025-09-26T11:30:32Z","logger":"helm.controller","msg":"Failed to sync release","namespace":"alloy","name":"grafana-k8s-monitoring-alloy-logs","apiVersion":"collectors.grafana.com/v1alpha1","kind":"Alloy","release":"grafana-k8s-monitoring-alloy-logs","error":"failed to get candidate release: Unable to continue with update: ConfigMap \"grafana-k8s-monitoring-alloy-logs\" in namespace \"alloy\" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key \"meta.helm.sh/release-name\" must equal \"grafana-k8s-monitoring-alloy-logs\": current value is \"grafana-k8s-monitoring\"","stacktrace":"github.com/operator-framework/operator-sdk/internal/helm/controller.HelmOperatorReconciler.Reconcile\n\t/workspace/internal/helm/controller/reconcile.go:224\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).Reconcile\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:119\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).reconcileHandler\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:340\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).processNextWorkItem\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:300\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).Start.func2.1\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:202"}
{"level":"error","ts":"2025-09-26T11:30:32Z","msg":"Reconciler error","controller":"alloy-controller","object":{"name":"grafana-k8s-monitoring-alloy-logs","namespace":"alloy"},"namespace":"alloy","name":"grafana-k8s-monitoring-alloy-logs","reconcileID":"2e4d2421-24ff-4346-a866-ce37e6c13dab","error":"failed to get candidate release: Unable to continue with update: ConfigMap \"grafana-k8s-monitoring-alloy-logs\" in namespace \"alloy\" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key \"meta.helm.sh/release-name\" must equal \"grafana-k8s-monitoring-alloy-logs\": current value is \"grafana-k8s-monitoring\"","stacktrace":"sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).reconcileHandler\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:353\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).processNextWorkItem\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:300\nsigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller[...]).Start.func2.1\n\t/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.21.0/pkg/internal/controller/controller.go:202"}

これは、Alloy custom resource を処理する alloy-operator の内部で Alloy Helm chart が利用されており、configMap.create が true の場合は Alloy Helm chart によって ConfigMap を作成しようとするからです。もし Kubernetes Monitoring Helm chart で作成される ConfigMap と同じ名前だと、他の Helm chart で作成された ConfigMap を Alloy Helm chart が更新しようとするため、エラーになってしまうのだと思われます。

config.alloy の反映方法

values の変更によって config.alloy が更新されても、Alloy に即時反映されるわけではありません。

Config Reloader で軽く言及されていますが、Helm chart で Alloy をインストールすると、デフォルトで config reloader が sidecar container として定義されます。config reloader は設定の変更を検知すると http://localhost:12345/-/reload に POST リクエストを送るので、設定を反映するために Pod を作り直す必要はありません。むしろ、Kustomize considerations で言及されているように、起動に時間がかかる可能性があるため、設定ファイルの変更を反映するために Pod を作り直すのは避けるべきとされています。

ただし、Mounted ConfigMaps are updated automatically で説明されているように、ConfigMap の更新が Pod に反映されるまでにそれなりのタイムラグがあるので、開発時に即時反映させたい場合は kubectl rollout restart や kubectl delete pod で Pod を再作成するのが良いでしょう。

Pod を再作成しない場合、Alloy collector のログを確認することで設定がリロードされたかどうか判断することができます。設定がリロードされた場合、以下のように “config reloaded” というログが出ます。

$ kubectl -n alloy logs ds/grafana-k8s-monitoring-alloy-logs -f
-- snip --
ts=2025-10-01T17:39:40.345817877Z level=info msg="reload requested via /-/reload endpoint" service=http
-- snip --
ts=2025-10-01T17:39:40.351081419Z level=info msg="config reloaded" service=http

Alloy のデバッグ方法

Debug Grafana Alloy で紹介されているように、Alloy は Web UI を提供しています。
Kubernetes Monitoring Helm chart でインストールすると、各 Alloy collector に対応する Service も作成されるので、Service に対して port forwarding して Web UI にアクセスすると良いでしょう。例えば grafana-k8s-monitoring-alloy-logs の Web UI にアクセスしたい場合は次のコマンドを実行します。

kubectl port-forward -n alloy service/grafana-k8s-monitoring-alloy-logs 12345:12345

port forwarding した上で http://localhost:12345/graph にアクセスすると各コンポーネントの依存関係が可視化されて理解の助けになります。

また、先ほど Alloy collector のログを確認することで設定がリロードされたか判断する方法を紹介しましたが、Alloy の Web UI にアクセスして設定情報を確認するのも良いでしょう。例えば grafana-k8s-monitoring-alloy-logs の loki.process.pod_logs の内容を更新した場合、http://localhost:12345/component/pod_logs.feature/loki.process.pod_logs にアクセスすれば現在利用されている設定情報を確認できます。2 分経っても更新されない場合、config.alloy の内容に問題があって反映されていない可能性があるので Alloy collector のログを確認すると良いでしょう。

更に高度なデバッグ方法として delve を使ったデバッグが考えられますが、この方法については詳説 Alloy loki.process で紹介しているのでそちらを参照してください。

Alloy custom resoure のデバッグ方法

service account や mount する volume など、config.alloy 以外の collector (alloy-*) の設定を変更するには Grafana Alloy collector reference でも言及されているように Alloy Helm chart values の設定項目を各種 collector に設定します。

ところが、values を変更しても、Alloy custom resource の内容が変わるだけで、Alloy custom resource によって生成される manifest がどのように変わるかまではわかりません。

例えば、alloy-metrics に次のような変更を加えたとします。

@@ -1,5 +1,22 @@
 alloy-metrics:
   enabled: true
+  alloy:
+    mounts:
+      extra:
+        - name: secrets
+          mountPath: "/mnt/secrets-store"
+          readOnly: true
   controller:
     podAnnotations:
       kubernetes.azure.com/set-kube-service-host-fqdn: "true"
+    volumes:
+      extra:
+        - name: secrets
+          csi:
+            driver: secrets-store.csi.k8s.io
+            readOnly: true
+            volumeAttributes:
+              secretProviderClass: alloy-secret-provider
+  serviceAccount:
+    annotations:
+      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID

これによって heml template の出力結果で変わるのは Alloy custom resource の定義だけです。

@@ -2703,7 +2692,10 @@
     livenessProbe: {}
     mounts:
       dockercontainers: false
-      extra: []
+      extra:
+      - mountPath: /mnt/secrets-store
+        name: secrets
+        readOnly: true
       varlog: false
     resources: {}
     securityContext:
@@ -2814,7 +2806,13 @@
     updateStrategy: {}
     volumeClaimTemplates: []
     volumes:
-      extra: []
+      extra:
+      - csi:
+          driver: secrets-store.csi.k8s.io
+          readOnly: true
+          volumeAttributes:
+            secretProviderClass: alloy-secret-provider
+        name: secrets
   crds:
     create: false
   extraObjects: []
@@ -2853,7 +2851,8 @@
     type: ClusterIP
   serviceAccount:
     additionalLabels: {}
-    annotations: {}
+    annotations:
+      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
     automountServiceAccountToken: true
     create: true
     name: null

Alloy custom resource は Alloy Helm chart から各種 Kubernetes オブジェクトを作成・更新するだけであるため、詳細な変更内容を確認するには alloy-* に指定する設定項目を Alloy Helm chart に渡して生成される manifest を確認すると良いです。

cat <<'EOF' | helm template grafana-alloy grafana/alloy --namespace alloy -f -
alloy:
  mounts:
    extra:
      - name: secrets
        mountPath: "/mnt/secrets-store"
        readOnly: true
controller:
  podAnnotations:
    kubernetes.azure.com/set-kube-service-host-fqdn: "true"
  volumes:
    extra:
      - name: secrets
        csi:
          driver: secrets-store.csi.k8s.io
          readOnly: true
          volumeAttributes:
            secretProviderClass: alloy-secret-provider
serviceAccount:
  annotations:
    azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
EOF

上記のコマンドを実行することで、Alloy で使われる service account に annotation が付与され、container には volume が mount されるようになっていることがわかります。

出力結果

---
# Source: alloy/templates/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
automountServiceAccountToken: true
metadata:
  name: grafana-alloy
  namespace: alloy
  labels:
    helm.sh/chart: alloy-1.2.1
    app.kubernetes.io/name: alloy
    app.kubernetes.io/instance: grafana-alloy
    app.kubernetes.io/version: "v1.10.1"
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/part-of: alloy
    app.kubernetes.io/component: rbac
  annotations:
    azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
---
# snip
---
# Source: alloy/templates/controllers/daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: grafana-alloy
  namespace: alloy
  labels:
    helm.sh/chart: alloy-1.2.1
    app.kubernetes.io/name: alloy
    app.kubernetes.io/instance: grafana-alloy
    app.kubernetes.io/version: "v1.10.1"
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/part-of: alloy
spec:
  minReadySeconds: 10
  selector:
    matchLabels:
      app.kubernetes.io/name: alloy
      app.kubernetes.io/instance: grafana-alloy
  template:
    metadata:
      annotations:
        kubectl.kubernetes.io/default-container: alloy
        kubernetes.azure.com/set-kube-service-host-fqdn: "true"
      labels:
        app.kubernetes.io/name: alloy
        app.kubernetes.io/instance: grafana-alloy
    spec:
      serviceAccountName: grafana-alloy
      containers:
        - name: alloy
          image: docker.io/grafana/alloy:v1.10.1
          imagePullPolicy: IfNotPresent
          args:
            - run
            - /etc/alloy/config.alloy
            - --storage.path=/tmp/alloy
            - --server.http.listen-addr=0.0.0.0:12345
            - --server.http.ui-path-prefix=/
            - --stability.level=generally-available
          env:
            - name: ALLOY_DEPLOY_MODE
              value: "helm"
            - name: HOSTNAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
          ports:
            - containerPort: 12345
              name: http-metrics
          readinessProbe:
            httpGet:
              path: /-/ready
              port: 12345
              scheme: HTTP
            initialDelaySeconds: 10
            timeoutSeconds: 1
          volumeMounts:
            - name: config
              mountPath: /etc/alloy
            - mountPath: /mnt/secrets-store
              name: secrets
              readOnly: true
        - name: config-reloader
          image: quay.io/prometheus-operator/prometheus-config-reloader:v0.81.0
          args:
            - --watched-dir=/etc/alloy
            - --reload-url=http://localhost:12345/-/reload
          volumeMounts:
            - name: config
              mountPath: /etc/alloy
          resources:
            requests:
              cpu: 10m
              memory: 50Mi
      dnsPolicy: ClusterFirst
      volumes:
        - name: config
          configMap:
            name: grafana-alloy
        - csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: alloy-secret-provider
          name: secrets

OpenTelemetry 連携: Pod のログと OTLP receiver のログの labels を統一する

OpenTelemetry Logging の冒頭でも言及されていますが、ログはメトリクスやトレースデータの収集と違い、既存のシステムがあるので厄介です。

Kubernetes Monitoring Helm chart で Alloy をインストールすると、Pod が stdout/stderr に出力したログは grafana-k8s-monitoring-alloy-logs が収集しますが、OTLP exporter から送信されたログは grafana-k8s-monitoring-alloy-receiver が処理します。OTLP の gRPC エンドポイントは http://grafana-k8s-monitoring-alloy-receiver.alloy.svc.cluster.local:4317 です。

OpenTelemetry としては、New First-Party Application Logs にあるように、これから自分たちで開発するアプリケーションに関しては OTLP でログを送ることを推奨しています。
とはいえ、アプリケーション側で OTLP を使う方針にしたとしても、アプリケーションで利用しているライブラリが stdout にログを出力することもあれば、例外発生時のログが stderr に出力されることもあるので、同じ Pod のログでも OTLP のログと stdout/stderr のログが混ざってしまいます。
Loki 上でログを確認する上で、OTLP のログと stdout/stderr のログで labels や structured metadata が異なっていると、ログを検索する際のフィルタリング条件によっては片方のログしかヒットしないことがあるので困りものです。

ところが、デフォルトの設定だと以下のように labels、structured metadata にけっこうな違いがあります。service_name も値が異なります。

	stdout/stderr	OTLP
labels	cluster container job k8s_cluster_name namespace service_name service_namespace	k8s_cluster_name k8s_namespace_name k8s_pod_name service_name
structured metadata	detected_level pod service_instance_id	cluster detected_level flags host_name k8s_node_name k8s_pod_ip loki_resource_labels namespace observed_timestamp os_type pod scope_name severity_number severity_text span_id telemetry_sdk_language telemetry_sdk_name telemetry_sdk_version trace_id

では、OTLP を使わずに stdout/stderr に寄せれば良いかというと、詳説 Alloy loki.process の「JSON のログをパースして変換する」で説明しているように、アプリケーション側で付与した attribute を structured meatdata として処理するのは難しそうです。

よって、stdout/stderr のログと OTLP のログの labels と structured metadata を極力揃える必要があるわけですが、それには Pod の定義と config.alloy の両方で工夫する必要があります。

重要な label は Pod にアノテーションと環境変数を付与する

grafana-k8s-monitoring-alloy-logs では discovery.kubernetes.pods で検出された Pod に対して discovery.relabel.filtered_pods で relabel します。

discovery.kubernetes "pods" {
  role = "pod"
  selectors {
    role = "pod"
    field = "spec.nodeName=" + sys.env("HOSTNAME")
  }
}

discovery.relabel "filtered_pods" {
  targets = discovery.kubernetes.pods.targets
  rule {
    source_labels = ["__meta_kubernetes_namespace"]
    action = "replace"
    target_label = "namespace"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_name"]
    action = "replace"
    target_label = "pod"
  }
  // -- snip --
}

relabel の rule 中には次のように How service.name should be calculated に従って処理する rule も存在します。

// explicitly set service_name. if not set, loki will automatically try to populate a default.
// see https://grafana.com/docs/loki/latest/get-started/labels/#default-labels-for-all-users
//
// choose the first value found from the following ordered list:
// - pod.annotation[resource.opentelemetry.io/service.name]
// - pod.label[app.kubernetes.io/name]
// - k8s.pod.name
// - k8s.container.name
rule {
  action = "replace"
  source_labels = [
    "__meta_kubernetes_pod_annotation_resource_opentelemetry_io_service_name",
    "__meta_kubernetes_pod_label_app_kubernetes_io_name",
    "__meta_kubernetes_pod_container_name",
  ]
  separator = ";"
  regex = "^(?:;*)?([^;]+).*$"
  replacement = "$1"
  target_label = "service_name"
}

そのため、Pod に resource.opentelemetry.io/service.name annotation を付与することで、stdout/stderr のログに任意の service_name label を付与することができます。

OTLP のログに関しては、OTEL_RESOURCE_ATTRIBUTES 環境変数で service.name を指定することで任意の service_name label を付与することができます。

よって、Pod に resource.opentelemetry.io/service.name annotation と OTEL_RESOURCE_ATTRIBUTES 環境変数の両方を指定することで、それぞれのログの service_name label を統一することができます。

例えば、次の manifest では service_name を hello、deployment_environment_name を staging に統一するために annotation と OTEL_RESOURCE_ATTRIBUTES 環境変数の両方を指定しています。

apiVersion: v1
kind: Pod
metadata:
  generateName: hello-otel-
  annotations:
    resource.opentelemetry.io/service.name: hello
    resource.opentelemetry.io/deployment.environment.name: staging
spec:
  containers:
  - name: hello-otel
    image: ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel:latest
    env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: service.name=hello,deployment.environment.name=staging
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: http://grafana-k8s-monitoring-alloy-receiver.alloy.svc.cluster.local:4317
  restartPolicy: Never

なお、次のように otelcol.processor.k8sattributes の設定を変更すれば OTEL_RESOURCE_ATTRIBUTES が不要になると思われるかもしれませんが、OpenTelemetry Collector の OTLP receiver で受け取ったデータに Kubernetes attributes processor で attribute を付与するで言及しているように、Pod 起動直後のログには attribute が付与されないので、確実に付与したい label は OTEL_RESOURCE_ATTRIBUTES で指定した方が良いでしょう。

applicationObservability:
  enabled: true
  processors:
    k8sattributes:
      annotations:
      - from: pod
        key_regex: ^resource\.opentelemetry\.io/(.+)$
        tag_name: $$1

同様の理由から、OTLP のログの labels、structured metadata のうち、otelcol.processor.k8sattributes が付与している次のものに関しては起動直後のログには付与されない可能性があります。

k8s_namespace_name
k8s_pod_name
k8s_node_name

もし確実に付与したいなら、これらの情報についても次のように OTEL_RESOURCE_ATTRIBUTES に指定すると良いでしょう。

apiVersion: v1
kind: Pod
metadata:
  generateName: hello-otel-
  annotations:
    resource.opentelemetry.io/service.name: hello
    resource.opentelemetry.io/deployment.environment.name: staging
spec:
  containers:
  - name: hello-otel
    image: ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel:latest
    env:
    - name: K8S_NAMESPACE_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: K8S_POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: K8S_NODE_NAME
      valueFrom:
        fieldRef:
          fieldPath: spec.nodeName
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: service.name=hello,deployment.environment.name=staging,k8s.namespace.name=$(K8S_NAMESPACE_NAME),k8s.pod.name=$(K8S_POD_NAME),k8s.node.name=$(K8S_NODE_NAME)
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: http://grafana-k8s-monitoring-alloy-receiver.alloy.svc.cluster.local:4317
  restartPolicy: Never

logs と receiver の config.alloy を変更する

OTLP のログに label を付与するのはなかなか厄介です。というのも、Loki の設定で OpenTelemetry のどの attribute を label とみなすか設定されているようなんですが、Grafana Cloud では現状その設定をカスタマイズできないからです。label とみなされない attribute は全て structured metadata になります。

cf. [Grafana Cloud OTLP Endpoint] Support specifying OTel Resource Attributes promoted as Loki labels #13044

なので、stdout/stderr のログと OTLP のログで labels と structured metadata を揃えようと思うと、stdout/stderr のログで label になっていて Loki が label として処理する OpenTelemetry の attribute は付与しつつ、それが難しくてあまり重要そうでない stdout/stderr の label は structured metadata に変更する方針を取ることになります。

まず、stdout/stderr のログの namespace を label ではなく structured metadata にするには、次のように podLogs.structuredMetadata に namespace を追加します。

podLogs:
  enabled: true
  structuredMetadata:
    namespace: namespace

stdout/stderr のログには k8s_node_name structured metadata が付与されていませんが、便利そうなので付与します。

podLogs:
  enabled: true
  extraDiscoveryRules: |
    rule {
      source_labels = ["__meta_kubernetes_pod_node_name"]
      action = "replace"
      target_label = "k8s_node_name"
    }
  structuredMetadata:
    k8s.node.name: k8s.node.name
    namespace: namespace

また、Default labels for OpenTelemetry の CAUTION にあるように、k8s.pod.name をインデキシングするのは非推奨で、grafana-k8s-monitoring-alloy-receiver の設定では k8s.pod.name の値が pod label にも付与される設定になっているので、冗長な k8s.pod.name は削除するのが良いでしょう。loki.resource.labels も otelcol.exporter.loki のためのもので、デフォルトである otelcol.exporter.otlphttp を使う分には不要なはずなので削除します。

destinations:
- name: gc-otlp-endpoint
  type: otlp
  processors:
    resourceAttributes:
      removeList:
      - k8s.pod.name
      - loki.resource.labels

stdout/stderr の cluster label も冗長なので削除します。

destinations:
- name: grafana-cloud-logs
  type: loki
  clusterLabels:
  - k8s.cluster.name

stdout/stderr のログには service_namespace label があって、OTLP のログには k8s_namespace_name label があるので、service_namespace に統一します。

applicationObservability:
  enabled: true
  logs:
    transforms:
      resource:
      - set(attributes["service.namespace"], attributes["k8s.namespace.name"]) where attributes["service.namespace"] == nil
      - delete_key(attributes, "k8s.namespace.name") where attributes["k8s.namespace.name"] == attributes["service.namespace"]

ここまですると、labels と structured metadata の差異は次のようにだいぶ解消します。

	stdout/stderr	OTLP
labels	container job k8s_cluster_name service_name service_namespace	k8s_cluster_name service_name service_namespace
structured metadata	detected_level k8s_node_name namespace pod service_instance_id	cluster detected_level flags host_name k8s_node_name k8s_pod_ip namespace observed_timestamp os_type pod scope_name severity_number severity_text span_id telemetry_sdk_language telemetry_sdk_name telemetry_sdk_version trace_id

関連する values のみまとめると以下のとおりです。

destinations:
- name: gc-otlp-endpoint
  type: otlp
  processors:
    resourceAttributes:
      removeList:
      - k8s.pod.name
      - loki.resource.labels
- name: grafana-cloud-logs
  type: loki
  clusterLabels:
  - k8s.cluster.name
podLogs:
  enabled: true
  structuredMetadata:
    service.instance.id: service.instance.id
    namespace: namespace
  extraDiscoveryRules: |
    rule {
      source_labels = ["__meta_kubernetes_pod_node_name"]
      action = "replace"
      target_label = "k8s_node_name"
    }
applicationObservability:
  enabled: true
  logs:
    transforms:
      resource:
      - set(attributes["service.namespace"], attributes["k8s.namespace.name"]) where attributes["service.namespace"] == nil
      - delete_key(attributes, "k8s.namespace.name") where attributes["k8s.namespace.name"] == attributes["service.namespace"]

Helm chart の values を理解するで説明したとおり、どの values を変更すれば所望の設定になるか特定するのはなかなか大変です。参考までに各機能のドキュメントのリンクを載せておきます。

おわりに

以上、前編、後編の 2 回に分けて、Kubernetes cluster と Grafana Cloud を Alloy で連携する際の知見について説明してきました。これらの知見がこれから Grafana Cloud を利用する方の参考になれば幸いです。

詳説 Grafana Alloy loki.process

Tue, 30 Sep 2025 00:00:00 +0900

とりあえず Grafana Alloy を使って Loki にログを送ってみるだけなら Use Grafana Alloy to send logs to Loki と Logs and relabeling basics in Grafana Alloy をやれば雰囲気を掴むことができるんですが、ログをフィルタリングしたり加工したりするには loki.process の理解が欠かせません。livedebugging を使えば loki.process の input と output の情報は確認できますが、loki.process 内の各 stage でどのような処理が行われたかは確認することができません。log level を debug にしても同様です。そのこともあって、ドキュメントを読みつつ設定を変更して試行錯誤しても自分には使い方がいまいち理解できず、ソースコードを読んだりしてようやく理解できたので、理解した内容についてまとめました。

loki.process の基礎知識

loki.process については前身である Promtail の pipeline のドキュメントを読むことで理解が深まります。
次の引用はドキュメントの冒頭部分であり、特に重要な内容です。

A pipeline is used to transform a single log line, its labels, and its timestamp. A pipeline is comprised of a set of stages. There are 4 types of stages:

Parsing stages parse the current log line and extract data out of it. The extracted data is then available for use by other stages.

Transform stages transform extracted data from previous stages.

Action stages take extracted data from previous stages and do something with them. Actions can:

Add or modify existing labels to the log line

Change the timestamp of the log line

Change the content of the log line

Create a metric based on the extracted data

Filtering stages optionally apply a subset of stages or drop entries based on some condition.

例えば、stage.json は parsing stage に相当し、データを抽出するだけなので、この stage だけを使っても Loki に取り込まれるデータは変わりません。stage.cri のように、複数の stage をひとまとめにした stage も存在します。このように、利用する stage がどの種類の stage に相当するのか意識することが重要です。

ログには様々なデータが含まれていて、各 stage で特に意識しなければいけないのは次の 3 種類のデータです。

log line
labels
extracted data

これらのデータがあることを意識していなければドキュメントを読んでも内容を理解するのは難しいでしょう。

それでは、それぞれのデータについて説明していきます。

Log line

log line は文字通り 1 行のログを意味します。例えば、Kubernetes の Pod が Hello World! というログを stdout に出力した場合、CRI log format だと次のようなデータが log line になります。

2025-09-26T10:03:07.408766429Z stdout F Hello World!

log line は、例えば stage.json や stage.drop で使われていて、source が指定されていない場合は log line を対象に処理が行われます。
また、transform stage である stage.output で log line を書き換えることもできます。

Labels

labels はいわゆる Loki の labels です。例えば loki.source.file では filename label が付与されます。
discovery.kubernetes の pod role であれば __meta_kubernetes_namespace label などが付与されます。

labels は、loki.process 内において例えば stage.match の selector で処理対象のログをフィルタリングするのに使われます。stage.labels で extracted data の値を labels に追加することもできます。

Extracted data

extracted data は loki.process 内でのみ使われるデータですが、非常に重要な概念です。loki.process のドキュメント内では shared map、extracted values、extracted map 等などと表現されていますが、ここでは extracted data で統一します。

ここでは、extracted data を説明するために、stage.output で使われている次の設定を利用します。

stage.json {
  expressions = { "user" = "user", "message" = "message" }
}

stage.labels {
  values = { "user" = "user" }
}

stage.output {
  source = "message"
}

この設定の下、{"user": "John Doe", "message": "hello, world!"} という log line の入力があったとします。初期状態は次のとおりです。

log_line: {"user": "John Doe", "message": "hello, world!"}
labels: {}
extracted_data: {}

これが stage.json の設定によって log line の JSON に含まれる user フィールドと message フィールドが、それぞれ extracted data の user フィールドと message フィールドに抽出されるので、次のような状態になります。

log_line: {"user": "John Doe", "message": "hello, world!"}
labels: {}
extracted_data: {"user": "John Doe", "message": "hello, world!"}

stage.labels の設定では、extracted data の user フィールドを labels の user フィールドとして付与するので次のような状態になります。

log_line: {"user": "John Doe", "message": "hello, world!"}
labels: {"user": "John Doe"}
extracted_data: {"user": "John Doe", "message": "hello, world!"}

最後に stage.output の設定によって log line が extracted data の message フィールドの値に書き換えられるので次のような状態になります。

log_line: hello, world!
labels: {"user": "John Doe"}
extracted_data: {"user": "John Doe", "message": "hello, world!"}

実践的な例

loki.process の基礎を押さえたところで、実践的な例についていくつか紹介します。

JSON のログに特定のフィールドが含まれていれば drop する

例えば trace データとログを紐付けるために OTLP receiver に TraceID 付きのログを送りつつ、kubectl logs でもログを確認できるようにするために同じログを standard output log exporter を使って stdout に出力するケースを考えます。

stdout に出力されるログの例

{"Timestamp":"2025-09-28T09:03:51.787320833Z","ObservedTimestamp":"2025-09-28T09:03:51.787324124Z","Severity":9,"SeverityText":"INFO","Body":{"Type":"String","Value":"Hello World!"},"Attributes":[{"Key":"key1","Value":{"Type":"String","Value":"value1"}}],"TraceID":"4f4758e0dbacc537e87d9f09c5102d59","SpanID":"0b2f8bd6cadae160","TraceFlags":"01","Resource":[{"Key":"service.name","Value":{"Type":"STRING","Value":"hello"}},{"Key":"service.version","Value":{"Type":"STRING","Value":"0.0.1"}},{"Key":"telemetry.sdk.language","Value":{"Type":"STRING","Value":"go"}},{"Key":"telemetry.sdk.name","Value":{"Type":"STRING","Value":"opentelemetry"}},{"Key":"telemetry.sdk.version","Value":{"Type":"STRING","Value":"1.38.0"}}],"Scope":{"Name":"github.com/abicky/opentelemetry-collector-k8s-example","Version":"","SchemaURL":"","Attributes":{}},"DroppedAttributes":0}

上記のログは次のコマンドを実行した時に stdout に出力されたものです。

kubectl run hello-otel-$(date '+%s') --restart=Never -i \
  --image=ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel@sha256:7428942bb1ad8a9cdc655684554c05e81ddf46ff93a7fe9a2930c4f7eb47603f \
  --env=OTEL_LOGS_EXPORTER=console

この場合、Loki へは OTLP receiver で受け取ったログのみ転送し、stdout に出力されたログは Alloy で drop すると良いでしょう。

OpenTelemetry のログは Log and Event Record Definition に定められたフィールドを含むため、例えば ObservedTimestamp を含むログを drop するとします。これは stage.json と stage.drop を組み合わせることで実現できます。

loki.process "main" {
  stage.json {
    expressions = {observed_timestamp = "ObservedTimestamp"}
  }

  stage.drop {
    source = "observed_timestamp"
  }

  forward_to = [loki.echo.debug.receiver]
}

loki.echo "debug" {}

stage.drop は、source が指定されいて、かつ expression が指定されていない場合、extracted data に source で指定したフィールドが存在すれば drop するようになっています。
cf. loki/process/stages/drop.go#L150-L169

複数行にまたがる JSON のログに特定のフィールドが含まれていれば drop する

実現したいことは「特定のフィールドを含む JSON のログを drop する」と同じですが、stdout に出力されるデータが pretty print されているケースを考えます。

例として、abicky/opentelemetry-collector-k8s-example/hello-otel を次のように実行した場合に stdout に出力されるログが挙げられます。

kubectl run hello-otel-$(date '+%s') --restart=Never -i \
  --image=ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel@sha256:7428942bb1ad8a9cdc655684554c05e81ddf46ff93a7fe9a2930c4f7eb47603f \
  --env=OTEL_LOGS_EXPORTER=console \
  --env=OTEL_EXPORTER_CONSOLE_LOGS_PRETTY_PRINT=true

minikube node に出力されるログの例

{"log":"{\n","stream":"stdout","time":"2025-09-28T09:07:50.902921697Z"}
{"log":"\u0009\"Timestamp\": \"2025-09-28T09:07:50.838311072Z\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902939822Z"}
{"log":"\u0009\"ObservedTimestamp\": \"2025-09-28T09:07:50.838320613Z\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902945363Z"}
{"log":"\u0009\"Severity\": 9,\n","stream":"stdout","time":"2025-09-28T09:07:50.90294653Z"}
{"log":"\u0009\"SeverityText\": \"INFO\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902947488Z"}
{"log":"\u0009\"Body\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.902948405Z"}
{"log":"\u0009\u0009\"Type\": \"String\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902949197Z"}
{"log":"\u0009\u0009\"Value\": \"Hello World!\"\n","stream":"stdout","time":"2025-09-28T09:07:50.902950447Z"}
{"log":"\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.902953197Z"}
{"log":"\u0009\"Attributes\": [\n","stream":"stdout","time":"2025-09-28T09:07:50.90295403Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.902954822Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"key1\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902955572Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.902956488Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"String\",\n","stream":"stdout","time":"2025-09-28T09:07:50.90295728Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"value1\"\n","stream":"stdout","time":"2025-09-28T09:07:50.902958113Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.902958988Z"}
{"log":"\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.902959738Z"}
{"log":"\u0009],\n","stream":"stdout","time":"2025-09-28T09:07:50.902960488Z"}
{"log":"\u0009\"TraceID\": \"d66b7a5221ed43fe20c7febbe85ed99f\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902963363Z"}
{"log":"\u0009\"SpanID\": \"03c04178caaced39\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902964405Z"}
{"log":"\u0009\"TraceFlags\": \"01\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902965238Z"}
{"log":"\u0009\"Resource\": [\n","stream":"stdout","time":"2025-09-28T09:07:50.902966613Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.902970238Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"service.name\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902973072Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.90297603Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"STRING\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902976947Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"hello\"\n","stream":"stdout","time":"2025-09-28T09:07:50.90297778Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.902978613Z"}
{"log":"\u0009\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.902979363Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.902980113Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"service.version\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902980863Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.902981697Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"STRING\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902982488Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"0.0.1\"\n","stream":"stdout","time":"2025-09-28T09:07:50.90298328Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.902984113Z"}
{"log":"\u0009\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.902984822Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.902985613Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"telemetry.sdk.language\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902986322Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.902987197Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"STRING\",\n","stream":"stdout","time":"2025-09-28T09:07:50.902987947Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"go\"\n","stream":"stdout","time":"2025-09-28T09:07:50.903011072Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.903012988Z"}
{"log":"\u0009\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.90301378Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.903014572Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"telemetry.sdk.name\",\n","stream":"stdout","time":"2025-09-28T09:07:50.903015363Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.903016197Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"STRING\",\n","stream":"stdout","time":"2025-09-28T09:07:50.903016947Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"opentelemetry\"\n","stream":"stdout","time":"2025-09-28T09:07:50.903018322Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.903028072Z"}
{"log":"\u0009\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.903029072Z"}
{"log":"\u0009\u0009{\n","stream":"stdout","time":"2025-09-28T09:07:50.903029947Z"}
{"log":"\u0009\u0009\u0009\"Key\": \"telemetry.sdk.version\",\n","stream":"stdout","time":"2025-09-28T09:07:50.903030697Z"}
{"log":"\u0009\u0009\u0009\"Value\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.903031488Z"}
{"log":"\u0009\u0009\u0009\u0009\"Type\": \"STRING\",\n","stream":"stdout","time":"2025-09-28T09:07:50.903032322Z"}
{"log":"\u0009\u0009\u0009\u0009\"Value\": \"1.38.0\"\n","stream":"stdout","time":"2025-09-28T09:07:50.903033113Z"}
{"log":"\u0009\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.903033905Z"}
{"log":"\u0009\u0009}\n","stream":"stdout","time":"2025-09-28T09:07:50.903034655Z"}
{"log":"\u0009],\n","stream":"stdout","time":"2025-09-28T09:07:50.903037572Z"}
{"log":"\u0009\"Scope\": {\n","stream":"stdout","time":"2025-09-28T09:07:50.903038488Z"}
{"log":"\u0009\u0009\"Name\": \"github.com/abicky/opentelemetry-collector-k8s-example\",\n","stream":"stdout","time":"2025-09-28T09:07:50.90303928Z"}
{"log":"\u0009\u0009\"Version\": \"\",\n","stream":"stdout","time":"2025-09-28T09:07:50.903040197Z"}
{"log":"\u0009\u0009\"SchemaURL\": \"\",\n","stream":"stdout","time":"2025-09-28T09:07:50.90304103Z"}
{"log":"\u0009\u0009\"Attributes\": {}\n","stream":"stdout","time":"2025-09-28T09:07:50.903041822Z"}
{"log":"\u0009},\n","stream":"stdout","time":"2025-09-28T09:07:50.903042613Z"}
{"log":"\u0009\"DroppedAttributes\": 0\n","stream":"stdout","time":"2025-09-28T09:07:50.90304353Z"}
{"log":"}\n","stream":"stdout","time":"2025-09-28T09:07:50.903044363Z"}

AKS node に出力されるログの例

2025-09-28T09:15:36.53860237Z stdout F {
2025-09-28T09:15:36.538617329Z stdout F 	"Timestamp": "2025-09-28T09:15:36.525057105Z",
2025-09-28T09:15:36.538620993Z stdout F 	"ObservedTimestamp": "2025-09-28T09:15:36.525061281Z",
2025-09-28T09:15:36.538622777Z stdout F 	"Severity": 9,
2025-09-28T09:15:36.538624689Z stdout F 	"SeverityText": "INFO",
2025-09-28T09:15:36.538626249Z stdout F 	"Body": {
2025-09-28T09:15:36.538627673Z stdout F 		"Type": "String",
2025-09-28T09:15:36.538629257Z stdout F 		"Value": "Hello World!"
2025-09-28T09:15:36.538630681Z stdout F 	},
2025-09-28T09:15:36.538635473Z stdout F 	"Attributes": [
2025-09-28T09:15:36.538636896Z stdout F 		{
2025-09-28T09:15:36.538638232Z stdout F 			"Key": "key1",
2025-09-28T09:15:36.538639528Z stdout F 			"Value": {
2025-09-28T09:15:36.538640856Z stdout F 				"Type": "String",
2025-09-28T09:15:36.538642144Z stdout F 				"Value": "value1"
2025-09-28T09:15:36.538643728Z stdout F 			}
2025-09-28T09:15:36.538645Z stdout F 		}
2025-09-28T09:15:36.53864628Z stdout F 	],
2025-09-28T09:15:36.538647576Z stdout F 	"TraceID": "7ceaa26ff7ac3dfa1e9933d3d0d7222c",
2025-09-28T09:15:36.538648936Z stdout F 	"SpanID": "e984ad987c8f5afa",
2025-09-28T09:15:36.538650208Z stdout F 	"TraceFlags": "01",
2025-09-28T09:15:36.538651512Z stdout F 	"Resource": [
2025-09-28T09:15:36.538652784Z stdout F 		{
2025-09-28T09:15:36.538654056Z stdout F 			"Key": "service.name",
2025-09-28T09:15:36.538655304Z stdout F 			"Value": {
2025-09-28T09:15:36.538656536Z stdout F 				"Type": "STRING",
2025-09-28T09:15:36.538657816Z stdout F 				"Value": "hello"
2025-09-28T09:15:36.538659087Z stdout F 			}
2025-09-28T09:15:36.538660447Z stdout F 		},
2025-09-28T09:15:36.538661703Z stdout F 		{
2025-09-28T09:15:36.538663055Z stdout F 			"Key": "service.version",
2025-09-28T09:15:36.538664335Z stdout F 			"Value": {
2025-09-28T09:15:36.538665591Z stdout F 				"Type": "STRING",
2025-09-28T09:15:36.538666839Z stdout F 				"Value": "0.0.1"
2025-09-28T09:15:36.538668127Z stdout F 			}
2025-09-28T09:15:36.538669351Z stdout F 		},
2025-09-28T09:15:36.538670575Z stdout F 		{
2025-09-28T09:15:36.538671887Z stdout F 			"Key": "telemetry.sdk.language",
2025-09-28T09:15:36.538673135Z stdout F 			"Value": {
2025-09-28T09:15:36.538674623Z stdout F 				"Type": "STRING",
2025-09-28T09:15:36.538675855Z stdout F 				"Value": "go"
2025-09-28T09:15:36.538677103Z stdout F 			}
2025-09-28T09:15:36.538678375Z stdout F 		},
2025-09-28T09:15:36.538679863Z stdout F 		{
2025-09-28T09:15:36.538681334Z stdout F 			"Key": "telemetry.sdk.name",
2025-09-28T09:15:36.538682646Z stdout F 			"Value": {
2025-09-28T09:15:36.538683918Z stdout F 				"Type": "STRING",
2025-09-28T09:15:36.538685166Z stdout F 				"Value": "opentelemetry"
2025-09-28T09:15:36.53868643Z stdout F 			}
2025-09-28T09:15:36.538687702Z stdout F 		},
2025-09-28T09:15:36.538688942Z stdout F 		{
2025-09-28T09:15:36.538690222Z stdout F 			"Key": "telemetry.sdk.version",
2025-09-28T09:15:36.538691502Z stdout F 			"Value": {
2025-09-28T09:15:36.538692798Z stdout F 				"Type": "STRING",
2025-09-28T09:15:36.538694142Z stdout F 				"Value": "1.38.0"
2025-09-28T09:15:36.538695486Z stdout F 			}
2025-09-28T09:15:36.538696902Z stdout F 		}
2025-09-28T09:15:36.538698198Z stdout F 	],
2025-09-28T09:15:36.53869959Z stdout F 	"Scope": {
2025-09-28T09:15:36.53870135Z stdout F 	"Name": "github.com/abicky/opentelemetry-collector-k8s-example",
2025-09-28T09:15:36.538702646Z stdout F 		"Version": "",
2025-09-28T09:15:36.538703917Z stdout F 		"SchemaURL": "",
2025-09-28T09:15:36.538705277Z stdout F 		"Attributes": {}
2025-09-28T09:15:36.538706853Z stdout F 	},
2025-09-28T09:15:36.538708093Z stdout F 	"DroppedAttributes": 0
2025-09-28T09:15:36.538709485Z stdout F }

stage.cri には partial line のログを concat する仕組みがあるので、複数行に渡る JSON に関してもよしなに処理してくれるのかと思ったんですが、AKS node 上の全てのログの第 3 フィールドが F になっていることから、あくまでログの長さが膨大になったがために複数行に出力された時のためのもので、明示的に改行が含まれるメッセージを出力した場合は関係ないみたいですね。

というわけで、JSON が複数行にまたがるケースでは stage.multiline を使って複数行をひとまとめのログにする必要があります。stage.multiline は firstline として 1 行目のログにマッチする正規表現を指定する必要があります。JSON のログのみしか想定しない場合は ^{$ で大丈夫ですが、JSON 以外のログも想定する場合は ^[^\t}]（タブ、} 以外の文字で始まる行）が今回の場合は最も望ましい結果になるでしょう。

loki.process "main" {
  stage.multiline {
    firstline = "^[^\t}]"
  }

  stage.json {
    expressions = {observed_timestamp = "ObservedTimestamp"}
  }

  stage.drop {
    source = "observed_timestamp"
  }

  forward_to = [loki.echo.debug.receiver]
}

loki.echo "debug" {}

JSON のログをパースして変換する

OpenTelemetry の standard output log exporter のログを OTLP receiver に送ったログに似た形式で取り込むことを考えます。
OpenTelemetry Collector の filelog receiver だとこんな感じです。

だいぶ雑な感じですが、loki.process の場合は以下のような設定にすれば良さそうです。

loki.source.file "log_scrape" {
  targets    = local.file_match.local_files.targets
  forward_to = [loki.process.main.receiver]
  tail_from_end = true
}

loki.process "main" {
  stage.json {
    expressions = {
      Timestamp = "",
      ObservedTimestamp = "",
      Severity = "",
      SeverityText = "",
      Body = "Body.Value",
      Attributes = "",
      TraceID = "",
      SpanID = "",
      TraceFlags = "",
      Resource = "",
      DroppedAttributes = "",
    }
  }

  stage.timestamp {
    source = "Timestamp"
    format = "RFC3339"
  }

  stage.output {
    source = "Body"
  }

  stage.structured_metadata {
    values = {
      observed_timestamp = "ObservedTimestamp",
      severity_number = "Severity",
      severity_text = "SeverityText",
      attributes = "Attributes",
      trace_id = "TraceID",
      span_id = "SpanID",
      trace_flags = "TraceFlags",
      resource = "Resource",
      dropped_attributes = "DroppedAttributes",
    }
  }

  forward_to = [loki.echo.debug.receiver]
}

loki.echo "debug" {}

各 stage でやっていることを説明します。例として次のようなログが入力として与えられた場合を考えます。

timestamp: 2025-09-28 22:07:28.190986 +0900 JST
log_line: {"Timestamp":"2025-09-28T09:03:51.787320833Z","ObservedTimestamp":"2025-09-28T09:03:51.787324124Z","Severity":9,"SeverityText":"INFO","Body":{"Type":"String","Value":"Hello World!"},"Attributes":[{"Key":"key1","Value":{"Type":"String","Value":"value1"}}],"TraceID":"4f4758e0dbacc537e87d9f09c5102d59","SpanID":"0b2f8bd6cadae160","TraceFlags":"01","Resource":[{"Key":"service.name","Value":{"Type":"STRING","Value":"hello"}},{"Key":"service.version","Value":{"Type":"STRING","Value":"0.0.1"}},{"Key":"telemetry.sdk.language","Value":{"Type":"STRING","Value":"go"}},{"Key":"telemetry.sdk.name","Value":{"Type":"STRING","Value":"opentelemetry"}},{"Key":"telemetry.sdk.version","Value":{"Type":"STRING","Value":"1.38.0"}}],"Scope":{"Name":"github.com/abicky/opentelemetry-collector-k8s-example","Version":"","SchemaURL":"","Attributes":{}},"DroppedAttributes":0}
labels: {
  "filename": "/tmp/log/a.log"
}
structured_metadata: {}
extracted_data: {}

まず、stage.json によって extracted data にいくつかのフィールドが抽出されます。

timestamp: 2025-09-28 22:07:28.190986 +0900 JST
log_line: {"Timestamp":"2025-09-28T09:03:51.787320833Z","ObservedTimestamp":"2025-09-28T09:03:51.787324124Z","Severity":9,"SeverityText":"INFO","Body":{"Type":"String","Value":"Hello World!"},"Attributes":[{"Key":"key1","Value":{"Type":"String","Value":"value1"}}],"TraceID":"4f4758e0dbacc537e87d9f09c5102d59","SpanID":"0b2f8bd6cadae160","TraceFlags":"01","Resource":[{"Key":"service.name","Value":{"Type":"STRING","Value":"hello"}},{"Key":"service.version","Value":{"Type":"STRING","Value":"0.0.1"}},{"Key":"telemetry.sdk.language","Value":{"Type":"STRING","Value":"go"}},{"Key":"telemetry.sdk.name","Value":{"Type":"STRING","Value":"opentelemetry"}},{"Key":"telemetry.sdk.version","Value":{"Type":"STRING","Value":"1.38.0"}}],"Scope":{"Name":"github.com/abicky/opentelemetry-collector-k8s-example","Version":"","SchemaURL":"","Attributes":{}},"DroppedAttributes":0}
labels: {
  "filename": "/tmp/log/a.log"
}
structured_metadata: {}
extracted_data: {
  "Timestamp": "2025-09-28T09:03:51.787320833Z",
  "ObservedTimestamp": "2025-09-28T09:03:51.787324124Z",
  "Severity": 9,
  "SeverityText": "INFO",
  "Body" = "Body.Value",
  "Attributes": "[{\"Key\":\"key1\",\"Value\":{\"Type\":\"String\",\"Value\":\"value1\"}}]",
  "TraceID": "4f4758e0dbacc537e87d9f09c5102d59",
  "SpanID": "0b2f8bd6cadae160",
  "TraceFlags": "01",
  "Resource": "[{\"Key\":\"service.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"hello\"}},{\"Key\":\"service.version\",\"Value\":{\"Value\":\"0.0.1\",\"Type\":\"STRING\"}},{\"Key\":\"telemetry.sdk.language\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"go\"}},{\"Key\":\"telemetry.sdk.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"opentelemetry\"}},{\"Key\":\"telemetry.sdk.version\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"1.38.0\"}}]",
  "Scope" = "",
  "DroppedAttributes": 0
}

次に、stage.timestamp と stage.output によって timestamp と log line が書き換えられます。

timestamp: 2025-09-28 09:03:51.787320833 +0000 UTC
log_line: Hello World!
labels: {
  "filename": "/tmp/log/a.log"
}
structured_metadata: {}
extracted_data: {
  "Timestamp": "2025-09-28T09:03:51.787320833Z",
  "ObservedTimestamp": "2025-09-28T09:03:51.787324124Z",
  "Severity": 9,
  "SeverityText": "INFO",
  "Body" = "Body.Value",
  "Attributes": "[{\"Key\":\"key1\",\"Value\":{\"Type\":\"String\",\"Value\":\"value1\"}}]",
  "TraceID": "4f4758e0dbacc537e87d9f09c5102d59",
  "SpanID": "0b2f8bd6cadae160",
  "TraceFlags": "01",
  "Resource": "[{\"Key\":\"service.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"hello\"}},{\"Key\":\"service.version\",\"Value\":{\"Value\":\"0.0.1\",\"Type\":\"STRING\"}},{\"Key\":\"telemetry.sdk.language\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"go\"}},{\"Key\":\"telemetry.sdk.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"opentelemetry\"}},{\"Key\":\"telemetry.sdk.version\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"1.38.0\"}}]",
  "Scope" = "",
  "DroppedAttributes": 0
}

最後に、stage.structured_metadata によって指定したデータが structured metadata に付与されます。

timestamp: 2025-09-28 09:03:51.787320833 +0000 UTC
log_line: Hello World!
labels: {
  "filename": "/tmp/log/a.log"
}
structured_metadata: {
  "attributes": "[{\"Key\":\"key1\",\"Value\":{\"Type\":\"String\",\"Value\":\"value1\"}}]",
  "dropped_attributes": "0",
  "observed_timestamp": "2025-09-28T09:03:51.787324124Z",
  "resource": "[{\"Key\":\"service.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"hello\"}},{\"Key\":\"service.version\",\"Value\":{\"Value\":\"0.0.1\",\"Type\":\"STRING\"}},{\"Key\":\"telemetry.sdk.language\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"go\"}},{\"Key\":\"telemetry.sdk.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"opentelemetry\"}},{\"Key\":\"telemetry.sdk.version\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"1.38.0\"}}]",
  "severity_number": "9",
  "severity_text": "INFO",
  "span_id": "0b2f8bd6cadae160",
  "trace_flags": "01",
  "trace_id": "4f4758e0dbacc537e87d9f09c5102d59"
}
extracted_data: {
  "Timestamp": "2025-09-28T09:03:51.787320833Z",
  "ObservedTimestamp": "2025-09-28T09:03:51.787324124Z",
  "Severity": 9,
  "SeverityText": "INFO",
  "Body" = "Body.Value",
  "Attributes": "[{\"Key\":\"key1\",\"Value\":{\"Type\":\"String\",\"Value\":\"value1\"}}]",
  "TraceID": "4f4758e0dbacc537e87d9f09c5102d59",
  "SpanID": "0b2f8bd6cadae160",
  "TraceFlags": "01",
  "Resource": "[{\"Key\":\"service.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"hello\"}},{\"Key\":\"service.version\",\"Value\":{\"Value\":\"0.0.1\",\"Type\":\"STRING\"}},{\"Key\":\"telemetry.sdk.language\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"go\"}},{\"Key\":\"telemetry.sdk.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"opentelemetry\"}},{\"Key\":\"telemetry.sdk.version\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"1.38.0\"}}]",
  "Scope" = "",
  "DroppedAttributes": 0
}

本来であれば Attributes や Resource の各フィールドは structured metadata にマージできれば良いんですが、stage.structured_metadata では明示的に extracted data のフィールドを指定する必要があるため、事前に Attributes や Resource にどのようなフィールドが含まれるのかわかっていないと難しそうです。

デバッグ方法

最後に loki.process のデバッグ方法を紹介します。

Alloy のデバッグビルド

いつ廃止されるかわかりませんが、実は開発者向けには stages.Debug と stages.Inspect が用意されており、これらを手動で true にしてビルドした上で log level を debug にすれば各 stage の詳細なログを確認できます。

これらの変数を true にしつつ自前で Alloy をビルドするには以下のコマンドを実行します。Linux の場合、sed コマンドの -i と '' の間のスペースは削除する必要があります。

git clone https://github.com/grafana/alloy.git
cd alloy
sed -i '' 's/Debug = false/Debug = true/' internal/component/loki/process/stages/util.go
sed -i '' 's/Inspect = false/Inspect = true/' internal/component/loki/process/stages/util.go
make generate-ui
make alloy

上記のコマンドによって build/alloy が作成されます。make generate-ui を実行しないと、build/alloy が作成されても Web UI (デフォルトで localhost:12345) が Not found になるので注意してください。

なお、grafana/alloy#503 で inspect stage が導入されることが提案され、debug.variables の導入も提案されましたが、後者に関しては棄却されたようです。

もし IDE と連携したい場合は make alloy で実行されるコマンドを参考に IDE の設定をすると良いです。以下のスクリーンショットは GoLand の例です。

デバッグログの確認

前工程で作成された build/alloy を使ってみます。
今回は config.alloy として次のファイルを利用します。

logging {
  level  = "debug"
}

local.file_match "local_files" {
  path_targets = [{"__path__" = "/tmp/log/*.log"}]
  sync_period = "5s"
}

loki.source.file "log_scrape" {
  targets    = local.file_match.local_files.targets
  forward_to = [loki.process.main.receiver]
  tail_from_end = true
}

loki.process "main" {
  stage.json {
    expressions = {
      Timestamp = "",
      ObservedTimestamp = "",
      Severity = "",
      SeverityText = "",
      Body = "Body.Value",
      Attributes = "",
      TraceID = "",
      SpanID = "",
      TraceFlags = "",
      Resource = "",
      Scope = "",
      DroppedAttributes = "",
    }
  }

  stage.timestamp {
    source = "Timestamp"
    format = "RFC3339"
  }

  stage.output {
    source = "Body"
  }

  stage.structured_metadata {
    values = {
      observed_timestamp = "ObservedTimestamp",
      severity_number = "Severity",
      severity_text = "SeverityText",
      attributes = "Attributes",
      trace_id = "TraceID",
      span_id = "SpanID",
      trace_flags = "TraceFlags",
      resource = "Resource",
      dropped_attributes = "DroppedAttributes",
    }
  }

  forward_to = [loki.echo.debug.receiver]
}

loki.echo "debug" {}

これは「JSON のログをパースして変換する」で利用したものに少しの設定を加えたものです。

それでは起動してみます。

build/alloy run config.alloy

入力データとして /tmp/log/a.log に JSON を書き込みます。

echo '{"Timestamp":"2025-09-28T09:03:51.787320833Z","ObservedTimestamp":"2025-09-28T09:03:51.787324124Z","Severity":9,"SeverityText":"INFO","Body":{"Type":"String","Value":"Hello World!"},"Attributes":[{"Key":"key1","Value":{"Type":"String","Value":"value1"}}],"TraceID":"4f4758e0dbacc537e87d9f09c5102d59","SpanID":"0b2f8bd6cadae160","TraceFlags":"01","Resource":[{"Key":"service.name","Value":{"Type":"STRING","Value":"hello"}},{"Key":"service.version","Value":{"Type":"STRING","Value":"0.0.1"}},{"Key":"telemetry.sdk.language","Value":{"Type":"STRING","Value":"go"}},{"Key":"telemetry.sdk.name","Value":{"Type":"STRING","Value":"opentelemetry"}},{"Key":"telemetry.sdk.version","Value":{"Type":"STRING","Value":"1.38.0"}}],"Scope":{"Name":"github.com/abicky/opentelemetry-collector-k8s-example","Version":"","SchemaURL":"","Attributes":{}},"DroppedAttributes":0}' >> /tmp/log/a.log

すると、Alloy から以下のようなログが出力されます。

ts=2025-09-28T13:07:28.192684Z level=debug msg="extracted data debug in json stage" component_path=/ component_id=loki.process.main component=stage type=json extracted_data="map[Attributes:[{\"Key\":\"key1\",\"Value\":{\"Type\":\"String\",\"Value\":\"value1\"}}] Body:Hello World! DroppedAttributes:0 ObservedTimestamp:2025-09-28T09:03:51.787324124Z Resource:[{\"Key\":\"service.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"hello\"}},{\"Key\":\"service.version\",\"Value\":{\"Value\":\"0.0.1\",\"Type\":\"STRING\"}},{\"Key\":\"telemetry.sdk.language\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"go\"}},{\"Key\":\"telemetry.sdk.name\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"opentelemetry\"}},{\"Key\":\"telemetry.sdk.version\",\"Value\":{\"Type\":\"STRING\",\"Value\":\"1.38.0\"}}] Scope:{\"SchemaURL\":\"\",\"Attributes\":{},\"Name\":\"github.com/abicky/opentelemetry-collector-k8s-example\",\"Version\":\"\"} Severity:9 SeverityText:INFO SpanID:0b2f8bd6cadae160 Timestamp:2025-09-28T09:03:51.787320833Z TraceFlags:01 TraceID:4f4758e0dbacc537e87d9f09c5102d59 filename:/tmp/log/a.log]"
[inspect: timestamp stage]: 
{stages.Entry}.Entry.Entry.Timestamp:
	-: 2025-09-28 22:07:28.190986 +0900 JST
	+: 2025-09-28 09:03:51.787320833 +0000 UTC
[inspect: output stage]: 
{stages.Entry}.Entry.Entry.Line:
	-: {"Timestamp":"2025-09-28T09:03:51.787320833Z","ObservedTimestamp":"2025-09-28T09:03:51.787324124Z","Severity":9,"SeverityText":"INFO","Body":{"Type":"String","Value":"Hello World!"},"Attributes":[{"Key":"key1","Value":{"Type":"String","Value":"value1"}}],"TraceID":"4f4758e0dbacc537e87d9f09c5102d59","SpanID":"0b2f8bd6cadae160","TraceFlags":"01","Resource":[{"Key":"service.name","Value":{"Type":"STRING","Value":"hello"}},{"Key":"service.version","Value":{"Type":"STRING","Value":"0.0.1"}},{"Key":"telemetry.sdk.language","Value":{"Type":"STRING","Value":"go"}},{"Key":"telemetry.sdk.name","Value":{"Type":"STRING","Value":"opentelemetry"}},{"Key":"telemetry.sdk.version","Value":{"Type":"STRING","Value":"1.38.0"}}],"Scope":{"Name":"github.com/abicky/opentelemetry-collector-k8s-example","Version":"","SchemaURL":"","Attributes":{}},"DroppedAttributes":0}
	+: Hello World!
ts=2025-09-28T13:07:28.196264Z level=info component_path=/ component_id=loki.echo.debug receiver=loki.echo.debug entry="Hello World!" entry_timestamp=2025-09-28T09:03:51.787Z labels="{filename=\"/tmp/log/a.log\"}" structured_metadata="{\"attributes\":\"[{\\\"Key\\\":\\\"key1\\\",\\\"Value\\\":{\\\"Type\\\":\\\"String\\\",\\\"Value\\\":\\\"value1\\\"}}]\",\"dropped_attributes\":\"0\",\"observed_timestamp\":\"2025-09-28T09:03:51.787324124Z\",\"resource\":\"[{\\\"Key\\\":\\\"service.name\\\",\\\"Value\\\":{\\\"Type\\\":\\\"STRING\\\",\\\"Value\\\":\\\"hello\\\"}},{\\\"Key\\\":\\\"service.version\\\",\\\"Value\\\":{\\\"Value\\\":\\\"0.0.1\\\",\\\"Type\\\":\\\"STRING\\\"}},{\\\"Key\\\":\\\"telemetry.sdk.language\\\",\\\"Value\\\":{\\\"Type\\\":\\\"STRING\\\",\\\"Value\\\":\\\"go\\\"}},{\\\"Key\\\":\\\"telemetry.sdk.name\\\",\\\"Value\\\":{\\\"Type\\\":\\\"STRING\\\",\\\"Value\\\":\\\"opentelemetry\\\"}},{\\\"Key\\\":\\\"telemetry.sdk.version\\\",\\\"Value\\\":{\\\"Type\\\":\\\"STRING\\\",\\\"Value\\\":\\\"1.38.0\\\"}}]\",\"severity_number\":\"9\",\"severity_text\":\"INFO\",\"span_id\":\"0b2f8bd6cadae160\",\"trace_flags\":\"01\",\"trace_id\":\"4f4758e0dbacc537e87d9f09c5102d59\"}"

stage.json で抽出されたデータ、stage.timestamp による変更内容、stage.output による変更内容が表示されていることがわかるかと思います。stage.json に関するログは level を debug にして stages.Debug を true にしないと表示されず、inspect のログは stages.Inspect を true にしないと表示されません。

Kubernetes 上の Alloy をリモートデバッグする

Kubernetes 上で動いている Alloy をデバッグしようと思うとひと手間かかります。基本的に delve を使うことになるので、container image に同梱するようにします。
例えば Dockerfile や Makefile に以下のような変更を加えると良いでしょう。

diff --git a/Dockerfile b/Dockerfile
index 3051d524c..12bf1f523 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -36,6 +36,9 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
     GOEXPERIMENT=${GOEXPERIMENT} \
     make alloy
 
+FROM golang:1.25 AS dlv
+RUN go install github.com/go-delve/delve/cmd/dlv@latest
+
 ###
 
 FROM public.ecr.aws/ubuntu/ubuntu:noble
@@ -59,6 +62,7 @@ RUN apt-get update \
 
 
 COPY --from=build --chown=${UID}:${UID} /src/alloy/build/alloy /bin/alloy
+COPY --from=dlv --chown=${UID}:${UID} /go/bin/dlv /bin/dlv
 COPY --chown=${UID}:${UID} example-config.alloy /etc/alloy/config.alloy
 
 # Create alloy user in container, but do not set it as default
@@ -71,6 +75,6 @@ RUN groupadd --gid $UID $USERNAME \
     && chown -R $USERNAME:$USERNAME /var/lib/alloy \
     && chmod -R 770 /var/lib/alloy
 
-ENTRYPOINT ["/bin/alloy"]
+ENTRYPOINT ["dlv", "--listen=:2345", "--headless=true", "--api-version=2", "--accept-multiclient", "exec", "/bin/alloy", "--"]
 ENV ALLOY_DEPLOY_MODE=docker
 CMD ["run", "/etc/alloy/config.alloy", "--storage.path=/var/lib/alloy/data"]
diff --git a/Makefile b/Makefile
index ec2de618b..c17f6bcc6 100644
--- a/Makefile
+++ b/Makefile
@@ -128,7 +128,7 @@ GO_LDFLAGS   := -X $(VPREFIX).Branch=$(GIT_BRANCH)                        \
                 -X $(VPREFIX).BuildDate=$(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 DEFAULT_FLAGS    := $(GO_FLAGS)
-DEBUG_GO_FLAGS   := -ldflags "$(GO_LDFLAGS)" -tags "$(GO_TAGS)"
+DEBUG_GO_FLAGS   := -ldflags "$(GO_LDFLAGS)" -tags "$(GO_TAGS)" -gcflags "all=-N -l"
 RELEASE_GO_FLAGS := -ldflags "-s -w $(GO_LDFLAGS)" -tags "$(GO_TAGS)"
 
 ifeq ($(RELEASE_BUILD),1)
diff --git a/internal/component/loki/process/stages/util.go b/internal/component/loki/process/stages/util.go
index 3825186ed..90af7a419 100644
--- a/internal/component/loki/process/stages/util.go
+++ b/internal/component/loki/process/stages/util.go
@@ -15,10 +15,10 @@ var (
 	// so this global is used for that purpose. This allows us to skip allocations of log messages at the
 	// debug level when debug level logging is not enabled. Log level allocations can become very expensive
 	// as we log numerous log entries per log line at debug level.
-	Debug = false
+	Debug = true
 
 	// Inspect is used to debug promtail pipelines by showing diffs between pipeline stages
-	Inspect = false
+	Inspect = true
 )
 
 const (

上記の変更を加えた上で container image をビルドします。

make alloy-image

ビルドできたら Kubernetes cluster が pull できる場所に配置します。minikube で手軽に試すなら、public repository に push するか、次のようにビルドされた image を load すると良いでしょう。

minikube image load grafana/alloy

動作確認には Deploy Grafana Alloy on Kubernetes で使われている Alloy Helm chart を使います。Configure Kubernetes Monitoring で紹介されている Kubernetes Monitoring Helm chart の方が洗練されていますが、テスト用途では Alloy Helm chart の方が手軽で良いでしょう。

今回利用する values.yaml は次のとおりです。

values.yaml

image:
  repository: grafana/alloy
  tag: latest
alloy:
  mounts:
    dockercontainers: true
    varlog: true
  extraPorts:
  - name: delve
    port: 2345
    targetPort: 2345
    protocol: TCP
  configMap:
    content: |
      logging {
        level  = "debug"
      }

      // Feature: Pod Logs
      declare "pod_logs" {
        argument "logs_destinations" {
          comment = "Must be a list of log destinations where collected logs should be forwarded to"
        }

        discovery.relabel "filtered_pods" {
          targets = discovery.kubernetes.pods.targets
          rule {
            source_labels = ["__meta_kubernetes_namespace"]
            action = "replace"
            target_label = "namespace"
          }
          rule {
            source_labels = ["__meta_kubernetes_pod_name"]
            action = "replace"
            target_label = "pod"
          }
          rule {
            source_labels = ["__meta_kubernetes_pod_container_name"]
            action = "replace"
            target_label = "container"
          }
          rule {
            source_labels = ["__meta_kubernetes_namespace", "__meta_kubernetes_pod_container_name"]
            separator = "/"
            action = "replace"
            replacement = "$1"
            target_label = "job"
          }

          // set the container runtime as a label
          rule {
            action = "replace"
            source_labels = ["__meta_kubernetes_pod_container_id"]
            regex = "^(\\S+):\\/\\/.+$"
            replacement = "$1"
            target_label = "tmp_container_runtime"
          }

          // make all labels on the pod available to the pipeline as labels,
          // they are omitted before write to loki via stage.label_keep unless explicitly set
          rule {
            action = "labelmap"
            regex = "__meta_kubernetes_pod_label_(.+)"
          }

          // make all annotations on the pod available to the pipeline as labels,
          // they are omitted before write to loki via stage.label_keep unless explicitly set
          rule {
            action = "labelmap"
            regex = "__meta_kubernetes_pod_annotation_(.+)"
          }

          // explicitly set service_name. if not set, loki will automatically try to populate a default.
          // see https://grafana.com/docs/loki/latest/get-started/labels/#default-labels-for-all-users
          //
          // choose the first value found from the following ordered list:
          // - pod.annotation[resource.opentelemetry.io/service.name]
          // - pod.label[app.kubernetes.io/name]
          // - k8s.pod.name
          // - k8s.container.name
          rule {
            action = "replace"
            source_labels = [
              "__meta_kubernetes_pod_annotation_resource_opentelemetry_io_service_name",
              "__meta_kubernetes_pod_label_app_kubernetes_io_name",
              "__meta_kubernetes_pod_container_name",
            ]
            separator = ";"
            regex = "^(?:;*)?([^;]+).*$"
            replacement = "$1"
            target_label = "service_name"
          }

          // explicitly set service_namespace.
          //
          // choose the first value found from the following ordered list:
          // - pod.annotation[resource.opentelemetry.io/service.namespace]
          // - pod.namespace
          rule {
            action = "replace"
            source_labels = [
              "__meta_kubernetes_pod_annotation_resource_opentelemetry_io_service_namespace",
              "namespace",
            ]
            separator = ";"
            regex = "^(?:;*)?([^;]+).*$"
            replacement = "$1"
            target_label = "service_namespace"
          }

          // explicitly set service_instance_id.
          //
          // choose the first value found from the following ordered list:
          // - pod.annotation[resource.opentelemetry.io/service.instance.id]
          // - concat([k8s.namespace.name, k8s.pod.name, k8s.container.name], '.')
          rule {
            source_labels = ["__meta_kubernetes_pod_annotation_resource_opentelemetry_io_service_instance_id"]
            target_label = "service_instance_id"
          }
          rule {
            source_labels = ["service_instance_id", "namespace", "pod", "container"]
            separator = "."
            regex = "^\\.([^.]+\\.[^.]+\\.[^.]+)$"
            target_label = "service_instance_id"
          }

          // set resource attributes
          rule {
            action = "labelmap"
            regex = "__meta_kubernetes_pod_annotation_resource_opentelemetry_io_(.+)"
          }
          rule {
            source_labels = ["__meta_kubernetes_pod_annotation_k8s_grafana_com_logs_job"]
            regex = "(.+)"
            target_label = "job"
          }
          rule {
            source_labels = ["__meta_kubernetes_pod_label_app_kubernetes_io_name"]
            regex = "(.+)"
            target_label = "app_kubernetes_io_name"
          }
        }

        discovery.kubernetes "pods" {
          role = "pod"
          selectors {
            role = "pod"
            field = "spec.nodeName=" + sys.env("HOSTNAME")
            label = "run"
          }
        }

        discovery.relabel "filtered_pods_with_paths" {
          targets = discovery.relabel.filtered_pods.output

          rule {
            source_labels = ["__meta_kubernetes_pod_uid", "__meta_kubernetes_pod_container_name"]
            separator = "/"
            action = "replace"
            replacement = "/var/log/pods/*$1/*.log"
            target_label = "__path__"
          }
        }

        local.file_match "pod_logs" {
          path_targets = discovery.relabel.filtered_pods_with_paths.output
        }

        loki.source.file "pod_logs" {
          targets    = local.file_match.pod_logs.targets
          forward_to = [loki.process.pod_logs.receiver]
        }

        loki.process "pod_logs" {
          stage.match {
            selector = "{tmp_container_runtime=~\"containerd|cri-o\"}"
            // the cri processing stage extracts the following k/v pairs: log, stream, time, flags
            stage.cri {}

            // Set the extract flags and stream values as labels
            stage.labels {
              values = {
                flags  = "",
                stream  = "",
              }
            }
          }

          stage.match {
            selector = "{tmp_container_runtime=\"docker\"}"
            // the docker processing stage extracts the following k/v pairs: log, stream, time
            stage.docker {}

            // Set the extract stream value as a label
            stage.labels {
              values = {
                stream  = "",
              }
            }
          }

          // Drop the filename label, since it's not really useful in the context of Kubernetes, where we already have cluster,
          // namespace, pod, and container labels. Drop any structured metadata. Also drop the temporary
          // container runtime label as it is no longer needed.
          stage.label_drop {
            values = [
              "filename",
              "tmp_container_runtime",
            ]
          }
          stage.structured_metadata {
            values = {
              "k8s_pod_name" = "k8s_pod_name",
              "pod" = "pod",
              "service_instance_id" = "service_instance_id",
            }
          }

          // Only keep the labels that are defined in the `keepLabels` list.
          stage.label_keep {
            values = ["__tenant_id__","app_kubernetes_io_name","container","instance","job","level","namespace","service_name","service_namespace","deployment_environment","deployment_environment_name","k8s_namespace_name","k8s_deployment_name","k8s_statefulset_name","k8s_daemonset_name","k8s_cronjob_name","k8s_job_name","k8s_node_name"]
          }

          forward_to = argument.logs_destinations.value
        }
      }
      pod_logs "feature" {
        logs_destinations = [
          loki.echo.debug.receiver,
        ]
      }

      loki.echo "debug" {}

config.alloy の内容は Kubernetes Monitoring Helm chart で Pod のログ収集用に生成される内容に次の変更を加えたものです。

--- config.alloy.orig   2025-09-29 22:49:10
+++ config.alloy        2025-09-29 22:50:13
@@ -1,3 +1,7 @@
+logging {
+  level  = "debug"
+}
+
 // Feature: Pod Logs
 declare "pod_logs" {
   argument "logs_destinations" {
@@ -128,6 +132,7 @@
     selectors {
       role = "pod"
       field = "spec.nodeName=" + sys.env("HOSTNAME")
+      label = "run"
     }
   }

@@ -207,39 +212,8 @@
 }
 pod_logs "feature" {
   logs_destinations = [
-    loki.write.grafana_cloud_logs.receiver,
+    loki.echo.debug.receiver,
   ]
 }

-
-
-
-// Destination: grafana-cloud-logs (loki)
-otelcol.exporter.loki "grafana_cloud_logs" {
-  forward_to = [loki.write.grafana_cloud_logs.receiver]
-}
-
-loki.write "grafana_cloud_logs" {
-  endpoint {
-    url = "https://logs-prod-030.grafana.net/loki/api/v1/push"
-    basic_auth {
-      username = convert.nonsensitive(remote.kubernetes.secret.grafana_cloud_logs.data["username"])
-      password = remote.kubernetes.secret.grafana_cloud_logs.data["password"]
-    }
-    tls_config {
-      insecure_skip_verify = false
-    }
-    min_backoff_period = "500ms"
-    max_backoff_period = "5m"
-    max_backoff_retries = "10"
-  }
-  external_labels = {
-    "cluster" = "my-cluster",
-    "k8s_cluster_name" = "my-cluster",
-  }
-}
-
-remote.kubernetes.secret "grafana_cloud_logs" {
-  name      = "grafana-cloud-logs-grafana-k8s-monitoring"
-  namespace = "monitoring"
-}
+loki.echo "debug" {}

要は以下のような変更を加えています。

log level を debug に設定
discovery.kubernetes.pods に label を追加して kubectl run で起動した Pod のみを対象に限定
- 他の Pod も対象にするとおぞましい量のログが流れるため
出力先を loki.echo に変更

それでは Alloy をインストールします。

helm upgrade --install grafana-alloy grafana/alloy \
    --namespace alloy --create-namespace -f values.yaml

次に、ローカルホストから Alloy の 2345 番ポートにアクセスできるようにします。

kubectl port-forward -n alloy ds/grafana-alloy 2345:2345

最後に、GoLand なり VS Code なりから接続すれば設定したブレークポントで処理を止めることができます。

動作確認してみます。

kubectl run hello-$(date '+%s') --restart=Never -i --image=alpine \
  --annotations="resource.opentelemetry.io/service.name=hello" \
  --annotations="resource.opentelemetry.io/service.version=0.0.1" \
  -- echo 'Hello World!'

上記のコマンドを実行することで、Alloy のログには次のような内容が出力されます。

ts=2025-09-29T23:33:11.565280472Z level=debug msg="extracted data debug in json stage" component_path=/pod_logs.feature component_id=loki.process.pod_logs component=stage type=json extracted_data="map[container:hello-1759188771 filename:/var/log/pods/default_hello-1759188771_6f088a07-7c1d-45b2-b21a-f590ff22ba2d/hello-1759188771/0.log job:default/hello-1759188771 namespace:default output:Hello World!\n pod:hello-1759188771 resource_opentelemetry_io_service_name:hello resource_opentelemetry_io_service_version:0.0.1 run:hello-1759188771 service_instance_id:default.hello-1759188771.hello-1759188771 service_name:hello service_namespace:default service_version:0.0.1 stream:stdout timestamp:2025-09-29T23:32:56.37882809Z tmp_container_runtime:docker]"
[inspect: labels stage]:
{stages.Entry}.Entry.Labels:
        -: {container="hello-1759188771", filename="/var/log/pods/default_hello-1759188771_6f088a07-7c1d-45b2-b21a-f590ff22ba2d/hello-1759188771/0.log", job="default/hello-1759188771", namespace="default", pod="hello-1759188771", resource_opentelemetry_io_service_name="hello", resource_opentelemetry_io_service_version="0.0.1", run="hello-1759188771", service_instance_id="default.hello-1759188771.hello-1759188771", service_name="hello", service_namespace="default", service_version="0.0.1", tmp_container_runtime="docker"}
        +: {container="hello-1759188771", filename="/var/log/pods/default_hello-1759188771_6f088a07-7c1d-45b2-b21a-f590ff22ba2d/hello-1759188771/0.log", job="default/hello-1759188771", namespace="default", pod="hello-1759188771", resource_opentelemetry_io_service_name="hello", resource_opentelemetry_io_service_version="0.0.1", run="hello-1759188771", service_instance_id="default.hello-1759188771.hello-1759188771", service_name="hello", service_namespace="default", service_version="0.0.1", stream="stdout", tmp_container_runtime="docker"}
[inspect: timestamp stage]:
{stages.Entry}.Entry.Entry.Timestamp:
        -: 2025-09-29 23:33:11.564708638 +0000 UTC
        +: 2025-09-29 23:32:56.37882809 +0000 UTC
[inspect: output stage]:
{stages.Entry}.Entry.Entry.Line:
        -: {"log":"Hello World!\n","stream":"stdout","time":"2025-09-29T23:32:56.37882809Z"}
        +: Hello World!

[inspect: labels stage]: none
[inspect: labeldrop stage]:
{stages.Entry}.Entry.Labels:
        -: {container="hello-1759188771", filename="/var/log/pods/default_hello-1759188771_6f088a07-7c1d-45b2-b21a-f590ff22ba2d/hello-1759188771/0.log", job="default/hello-1759188771", namespace="default", pod="hello-1759188771", resource_opentelemetry_io_service_name="hello", resource_opentelemetry_io_service_version="0.0.1", run="hello-1759188771", service_instance_id="default.hello-1759188771.hello-1759188771", service_name="hello", service_namespace="default", service_version="0.0.1", stream="stdout", tmp_container_runtime="docker"}
        +: {container="hello-1759188771", job="default/hello-1759188771", namespace="default", pod="hello-1759188771", resource_opentelemetry_io_service_name="hello", resource_opentelemetry_io_service_version="0.0.1", run="hello-1759188771", service_instance_id="default.hello-1759188771.hello-1759188771", service_name="hello", service_namespace="default", service_version="0.0.1", stream="stdout"}
[inspect: labelallow stage]:
{stages.Entry}.Entry.Labels:
        -: {container="hello-1759188771", job="default/hello-1759188771", namespace="default", resource_opentelemetry_io_service_name="hello", resource_opentelemetry_io_service_version="0.0.1", run="hello-1759188771", service_name="hello", service_namespace="default", service_version="0.0.1", stream="stdout"}
        +: {container="hello-1759188771", job="default/hello-1759188771", namespace="default", service_name="hello", service_namespace="default"}
ts=2025-09-29T23:33:11.56969018Z level=info component_path=/ component_id=loki.echo.debug receiver=loki.echo.debug entry="Hello World!\n" entry_timestamp=2025-09-29T23:32:56.378Z labels="{container=\"hello-1759188771\", job=\"default/hello-1759188771\", namespace=\"default\", service_name=\"hello\", service_namespace=\"default\"}" structured_metadata="{\"pod\":\"hello-1759188771\",\"service_instance_id\":\"default.hello-1759188771.hello-1759188771\"}"

なお、上記のコマンドに --rm を付けてしまうと、ログが収集されることなく Pod が削除されてしまうので注意してください。

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（前編）〜Getting Started Guide の先へ〜

Wed, 24 Sep 2025 00:00:00 +0900

最近 Grafana Cloud を試したんですが、Getting Started Guide に従って Kuberneters cluster に Grafana Alloy をインストールするだけで様々なログやメトリクスが取れるようになるし、メトリクスの取得も高速でとても感動しました。
ただ、Grafana、Prometheus、OpenTelmetry Collector を浅く使ったことがあるだけの自分にとって、ブラックボックス過ぎてわからないことが多く、どこの設定をどう修正すれば好みの内容になるのかわかりづらかったので、備忘録がてら知見についてまとめます。

1 エントリーにまとめようと思ったんですが力尽きたので、前編と後編に分けようと思います。

Getting Started Guide に従って連携してみる

Getting Started Guide にはいくつか選択肢があるんですが、Kubernetes 上で使うなら Kubernetes を選択するのが最も良いです。OpenTelemetry の手順に従うと Fleet Management の設定が追加されるのに、生成される token には fleet-management:read の権限が付与されておらず起動に失敗します。

最近は Kubernetes を選択すると「利用状況に応じて料金がかかるけど有効化しますか？」みたいなことが聞かれるようになったんですが、動作確認のために使う分にはよっぽどヘマをしない限り無料枠に収まるので気にせず Activate ボタンを押すと良いと思います。

このガイドでは、回答する内容にしたがって Alloy をインストールするためのコマンドや Terraform ファイルの内容が表示されるようになっています。

まずは alert rule と recording rule をインストールします。インストールされた rule は Grafana の Web UI の /alerting/list から確認できます。

Namespace には Alloy のインストール先の namespace 名を指定します。今回は alloy とします。そして Kubernetes サービスとして自身の利用しているサービスを選択します。自分の場合は AKS で使いたかったので AKS を選択しています。

利用する機能についてはデフォルトで Cost metrics (OpenCost) と Energy metrics (Keplr) が有効になっていますが、個人的には必要性を感じなかったので無効にしています。

今回は初めての利用なので新規作成します。これによって access policy とそれに紐付く token が作成されます。access policy の scope は自動で設定されますが、後ほど変更可能です。token の expiration date は後から変更できないようなので、変更したくなったら既存の token を削除して新規作成することになります。

Fleet Management はデフォルトで有効化されているんですが、とりあえず 1 クラスタで利用する分には不要そうなので無効化します。複数クラスタを管理する場合に重宝するかもしれません。

あとは表示されたコマンドを実行するだけで Alloy がインストールされ、クラスタのログやメトリクスが収集されて Grafana 上で見れるようになります。
2025-09-24 時点だと values の内容のみを抜粋すると次のような内容になりました。url, username, password はプレースホルダーにしてあります。

cluster:
  name: my-cluster
destinations:
  - name: grafana-cloud-metrics
    type: prometheus
    url: $PROMETHEUS_REMOTE_WRITE_ENDPOINT
    auth:
      type: basic
      username: "$PROMETHEUS_USERNAME"
      password: $GRAFANA_CLOUD_TOKEN
  - name: grafana-cloud-logs
    type: loki
    url: $LOKI_ENDPOINT
    auth:
      type: basic
      username: "$LOKI_USERNAME"
      password: $GRAFANA_CLOUD_TOKEN
  - name: gc-otlp-endpoint
    type: otlp
    url: $OTLP_ENDPOINT
    protocol: http
    auth:
      type: basic
      username: "$GRAFANA_INSTANCE_ID"
      password: $GRAFANA_CLOUD_TOKEN
    metrics:
      enabled: true
    logs:
      enabled: true
    traces:
      enabled: true
clusterMetrics:
  enabled: true
  kube-state-metrics:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
clusterEvents:
  enabled: true
podLogs:
  enabled: true
applicationObservability:
  enabled: true
  receivers:
    otlp:
      grpc:
        enabled: true
        port: 4317
      http:
        enabled: true
        port: 4318
    zipkin:
      enabled: true
      port: 9411
integrations:
  alloy:
    instances:
      - name: alloy
        labelSelectors:
          app.kubernetes.io/name:
            - alloy-metrics
            - alloy-singleton
            - alloy-logs
            - alloy-receiver
alloy-metrics:
  enabled: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
alloy-singleton:
  enabled: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
alloy-logs:
  enabled: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
alloy-receiver:
  enabled: true
  alloy:
    extraPorts:
      - name: otlp-grpc
        port: 4317
        targetPort: 4317
        protocol: TCP
      - name: otlp-http
        port: 4318
        targetPort: 4318
        protocol: TCP
      - name: zipkin
        port: 9411
        targetPort: 9411
        protocol: TCP
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"

もし kustomize を使ってインストールする場合は includeCRDs と skipHooks に true を指定する必要があることに注意してください。

helmCharts:
- name: k8s-monitoring
  repo: https://grafana.github.io/helm-charts
  version: 3.5.1
  namespace: alloy
  releaseName: grafana-k8s-monitoring
  valuesFile: values.yaml
  includeCRDs: true
  skipHooks: true

includeCRDs を指定しないと次のようなエラーになります。

resource mapping not found for name: "release-name-alloy-logs" namespace: "alloy" from "STDIN": no matches for kind "Alloy" in version "collectors.grafana.com/v1alpha1"
ensure CRDs are installed first
resource mapping not found for name: "release-name-alloy-metrics" namespace: "alloy" from "STDIN": no matches for kind "Alloy" in version "collectors.grafana.com/v1alpha1"
ensure CRDs are installed first
resource mapping not found for name: "release-name-alloy-receiver" namespace: "alloy" from "STDIN": no matches for kind "Alloy" in version "collectors.grafana.com/v1alpha1"
ensure CRDs are installed first
resource mapping not found for name: "release-name-alloy-singleton" namespace: "alloy" from "STDIN": no matches for kind "Alloy" in version "collectors.grafana.com/v1alpha1"
ensure CRDs are installed first

skipHooks を指定しないと、Helm chart の pre-delete hook として登録されている Job が普通の Job とみなされて即実行されます。その結果、2 回目の kubectl apply 時に Alloy custom resource (alloys.collectors.grafana.com) が全て削除されます。hook がないことで、kubectl delete の際に次のようにして finalizer を削除する必要がありますが、削除時以外には影響がないので大きな問題にはならないでしょう。

for name in $(kubectl get -n alloy alloys.collectors.grafana.com -o 'jsonpath={.items[*].metadata.name}'); do
  kubectl patch \
    --namespace=alloy \
    --type json \
    --patch='[{"op": "remove", "path": "/metadata/finalizers"}]' \
    alloy.collectors.grafana.com/$name
done

以降、Getting Started Guide のインストールコマンドに従って Helm chart の release name を grafana-k8s-monitoring にしたものとします。

Alloy とは何か？

Getting Started Guide ではしれっと Alloy が出てきましたが、Alloy は OpenTelemetry Collector みたいなものです。
Introductoin to Grafana Alloy には “Alloy is a flexible, high performance, vendor-neutral distribution of the OpenTelemetry Collector.” とありますが、ソースコードから設定ファイルの構文まで OpenTelemetry Collector とは全く異なるものなので、Grafana Labs 製独自 OpenTelemetry Collector と考えると良いでしょう。

元々 Grafana Agent の Flow mode というものがあり、Alloy はこれの後継にあたるようです。GitHub のスター数では Grafana Agent は OpenTelemetry に対して差が開く一方でしたが、Alloy は平衡状態にあるようです。

Alloy と OpenTelemetry Collector の違いは grafana/agent#642 (comment) がよく説明してそうで、Alloy は Prometheus のエコシステムにフォーカスしているのに対して、OpenTelemetry Collector はスコープがもっと広くなっています。また、OpenTelemetry Collector は独自のコンポーネント含め、必要なコンポーネントのみから collector をビルドする仕組みを提供していますが¹、Alloy で同様のことをしようと思うと fork するしかなさそうです。

とはいえ、Configure Kubernetes Monitoring にも次のように書いてあるように、特別な事情がなければ Grafana Cloud を利用する分には OpenTelemetry Collector ではなく Alloy を利用するのが無難でしょう。

Configuration with Grafana Kubernetes Monitoring Helm chart is recommended.

設定ファイルの構文が特殊ですが、Terraform に似た構文なので、Terraform に慣れている人であれば Alloy configuration syntax を読んで Grafana Alloy tutorials をやれば、Helm chart でインストールされた設定ファイルを読み解くことは可能かと思います。

Helm chart の values を理解する

Helm chart を使って Alloy をインストールすると様々なコンポーネントがインストールされるんですが、何がインストールされるか理解するには Overview of Grafana Kubernetes Monitoring Helm chart を一読するのが良いです。記事中の overview の図からもわかるように、Grafana Kubernetes Monitoring Helm chart を使うと少なくとも次の 4 種類の collector がインストールされます。

alloy-logs: Pod などのログ収集用
alloy-metrics: メトリクス収集用
alloy-receiver: OTLP receiver で受け取るデータ用
alloy-singleton: Kubernetes event 等 cluster レベルのデータ収集用

Getting Started Guide で生成された values のトップレベルにも上記のフィールドが定義されているため、それらが collector の定義に関係していることは想像が付くかと思います。values によってどのようなカスタマイズができるかは Customize the Kubernetes Monitoring Helm chart を読むとイメージが掴めるでしょう。

また、次のコマンドの出力結果には要所要所に README へのリンクが記載されているので、values に記載されている内容の意味を知りたい場合に重宝します。colloector (alloy-*) の設定値に関してはリンク先が間違っていて Grafana Alloy collector reference が正しいので注意が必要ですが。

helm show values grafana/k8s-monitoring

このように、ドキュメントはそれなりに充実しているわけですが、config.alloy の内容を変更したい場合にどの値を変更すれば良いか初見で理解するのはなかなか大変です。運良くドキュメントや examples から求めている内容が見つかれば良いですが、そうでなければ template を読み解く必要があります。例えば、以下は grafana-k8s-monitoring-alloy-logs ConfigMap の定義ですが、loki.process.pod_logs に処理を追加したい場合にどのように values を変更すべきか特定するのは至難の業です。

# Source: k8s-monitoring/templates/alloy-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: grafana-k8s-monitoring-alloy-logs
  namespace: alloy
data:
  config.alloy: |
    // Feature: Pod Logs
    declare "pod_logs" {
      argument "logs_destinations" {
        comment = "Must be a list of log destinations where collected logs should be forwarded to"
      }

      // -- snip --

      loki.process "pod_logs" {
        stage.match {
          selector = "{tmp_container_runtime=~\"containerd|cri-o\"}"
          // the cri processing stage extracts the following k/v pairs: log, stream, time, flags
          stage.cri {}

          // Set the extract flags and stream values as labels
          stage.labels {
            values = {
              flags  = "",
              stream  = "",
            }
          }
        }

        stage.match {
          selector = "{tmp_container_runtime=\"docker\"}"
          // the docker processing stage extracts the following k/v pairs: log, stream, time
          stage.docker {}

          // Set the extract stream value as a label
          stage.labels {
            values = {
              stream  = "",
            }
          }
        }

        // Drop the filename label, since it's not really useful in the context of Kubernetes, where we already have cluster,
        // namespace, pod, and container labels. Drop any structured metadata. Also drop the temporary
        // container runtime label as it is no longer needed.
        stage.label_drop {
          values = [
            "filename",
            "tmp_container_runtime",
          ]
        }
        stage.structured_metadata {
          values = {
            "k8s_pod_name" = "k8s_pod_name",
            "pod" = "pod",
            "service_instance_id" = "service_instance_id",
          }
        }

        // Only keep the labels that are defined in the `keepLabels` list.
        stage.label_keep {
          values = ["__tenant_id__","app_kubernetes_io_name","container","instance","job","level","namespace","service_name","service_namespace","deployment_environment","deployment_environment_name","k8s_namespace_name","k8s_deployment_name","k8s_statefulset_name","k8s_daemonset_name","k8s_cronjob_name","k8s_job_name","k8s_node_name"]
        }

        forward_to = argument.logs_destinations.value
      }
    }
    pod_logs "feature" {
      logs_destinations = [
        loki.write.grafana_cloud_logs.receiver,
      ]
    }

    // -- snip --

Pod のログを収集している Alloy の設定だからと Grafana Alloy collector reference を確認してもそれらしい設定値は見つかりません。

“Source: k8s-monitoring/templates/alloy-config.yaml” と記載されていることから k8s-monitoring/templates/alloy-config.yaml から生成されていることは容易に想像が付くのですが、これを読み解くのはなかなか大変です。JetBrains 製の IDE であれば include 対象の定義にジャンプできるので、IDE を使って処理を追いかければ理解が捗るかもしれません。このご時世だと AI も駆使できるかもしれません。

他の手段としては愚直に grep ですね。今回の場合、loki.process "pod_logs" で grep すればテンプレートファイルがすぐ見つかり、このファイルの中で extraLogProcessingStages という value が使われていることがわかります。

$ git grep 'loki.process "pod_logs"' charts/k8s-monitoring ':!*/docs/*' ':!*/tests/*'
charts/k8s-monitoring/charts/feature-pod-logs/templates/_common_log_processing.alloy.tpl:2:loki.process "pod_logs" {

あとは extraLogProcessingStages でドキュメントを漁れば使用例が出てきます。

$ git grep extraLogProcessingStages charts/k8s-monitoring/docs/examples
charts/k8s-monitoring/docs/examples/extra-rules/README.md:16:*   `extraLogProcessingStages` - Rules that control log processing, such as modifying labels or modifying content.
charts/k8s-monitoring/docs/examples/extra-rules/README.md:98:  extraLogProcessingStages: |-
charts/k8s-monitoring/docs/examples/extra-rules/description.txt:12:*   `extraLogProcessingStages` - Rules that control log processing, such as modifying labels or modifying content.
charts/k8s-monitoring/docs/examples/extra-rules/values.yaml:77:  extraLogProcessingStages: |-
charts/k8s-monitoring/docs/examples/log-metrics/README.md:32:  extraLogProcessingStages: |-
charts/k8s-monitoring/docs/examples/log-metrics/values.yaml:17:  extraLogProcessingStages: |-

なお、loki.process.pod_logs に設定を追加する方法に関しては Customize the Kubernetes Monitoring Helm chart をよく読めば答えにたどり着くことはできて、Processing and labeling の Additional processing で紹介されています。

loki.process.pod_logs に設定を追加する方法がわかっても、どのような設定を追加すれば意図したとおりにログを処理できるかという新たな問題が出てきますが、それについてはこの記事の範疇を超えるので、別途詳説 Alloy loki.processにまとめています。

今回は values の各設定項目のドキュメントや変更すべき設定項目の探し方について説明しましたが、設定項目を変更した際の差分の確認方法や反映方法にはついては後編で扱います。

Grafana Cloud の token 管理

Helm chart のインストール時には Grafana Cloud の token を指定する必要があります。この情報から Kubernetes 上に Secret が作成され、config.alloy ではこの Secret を利用するようになっています。
ところが、Alloy の管理を Argo CD などで行おうと思うと、token 情報を直接 values に指定することは避けたいものです。

Destinations のドキュメントには各 type のドキュメントへのリンクがあり、どの type も secret.create に false を指定することで Helm chart の Secret 作成処理をスキップできることがわかります。

destinations:
  - name: grafana-cloud-metrics
    type: prometheus
    url: $PROMETHEUS_REMOTE_WRITE_ENDPOINT
    auth:
      type: basic
    secret:
      create: false
  - name: grafana-cloud-logs
    type: loki
    url: $LOKI_ENDPOINT
    auth:
      type: basic
    secret:
      create: false
  - name: gc-otlp-endpoint
    type: otlp
    url: $OTLP_ENDPOINT
    protocol: http
    auth:
      type: basic
    secret:
      create: false
    metrics:
      enabled: true
    logs:
      enabled: true
    traces:
      enabled: true

examples/auth/external-secrets も参考になるかと思います。

あとは各組織の Secret の管理方法に従うと良いでしょう。

AKS における Secret 管理の例: Kubernetes Secret を作成する Deployment の導入

例えば、AKS (Azure Kubernetes Service) の場合、Key Vault の secret と Kubernetes の Secret を連携させることができます。
cf. Connect your Azure identity provider to the Azure Key Vault Secrets Store CSI Driver in Azure Kubernetes Service (AKS)

以下の Terraform ファイルはそのために必要な managed identity や federated identity credential を作成する例です。

terraform {
  required_version = ">=1.11"
  required_providers {
    azurekv = {
      source = "abicky/azurekv"
    }
  }
}

data "azurerm_subscription" "default" {}

resource "azurerm_key_vault" "this" {
  name                = random_string.name.result
  location            = var.location
  resource_group_name = var.resource_group_name
  tenant_id           = data.azurerm_subscription.default.tenant_id
  sku_name            = "standard"

  enable_rbac_authorization = true
}

resource "azurekv_secret" "this" {
  for_each = toset([
    "prometheus-username",
    "loki-username",
    "grafana-instance-id",
    "grafana-cloud-token",
  ])

  name             = each.key
  key_vault_id     = azurerm_key_vault.this.id
  value_wo         = "This value is manged outside of Terraform"
  value_wo_version = 1
}

resource "azurerm_user_assigned_identity" "alloy_secret_creator" {
  name                = "alloy-secret-creator"
  location            = var.location
  resource_group_name = var.resource_group_name
}

resource "azurerm_role_assignment" "alloy_secret_creator" {
  principal_id         = azurerm_user_assigned_identity.alloy_secret_creator.principal_id
  role_definition_name = "Key Vault Secrets User"
  scope                = azurerm_key_vault.this.id
}

resource "azurerm_federated_identity_credential" "alloy_secret_creator" {
  name                = "aks"
  resource_group_name = var.resource_group_name
  audience            = ["api://AzureADTokenExchange"]
  issuer              = var.kubernetes_cluster_oidc_issuer_url
  parent_id           = azurerm_user_assigned_identity.alloy_secret_creator.id
  subject             = "system:serviceaccount:alloy:${azurerm_user_assigned_identity.alloy_secret_creator.name}"
}

Key Vault の secret を Kubernetes の Secret として作成するには Key Vault の secret を mount する container が最低 1 つは存在していないといけないので、例えば次のように sleep infinity する Pod の Deployment を作成すると Kuberntes の Secret を維持できます。

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: alloy-secret-provider
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    clientID: "$USER_ASSIGNED_CLIENT_ID"
    keyvaultName: $KEYVAULT_NAME
    objects:  |
      array:
        - |
          objectName: prometheus-username
          objectType: secret
        - |
          objectName: loki-username
          objectType: secret
        - |
          objectName: grafana-instance-id
          objectType: secret
        - |
          objectName: grafana-cloud-token
          objectType: secret
    tenantId: "$TENANT_ID"
  # cf. https://learn.microsoft.com/en-us/azure/aks/csi-secrets-store-configuration-options#sync-mounted-content-with-a-kubernetes-secret
  secretObjects:
  - data:
    - key: username
      objectName: prometheus-username
    - key: password
      objectName: grafana-cloud-token
    secretName: grafana-cloud-metrics-grafana-k8s-monitoring
    type: Opaque
  - data:
    - key: username
      objectName: loki-username
    - key: password
      objectName: grafana-cloud-token
    secretName: grafana-cloud-logs-grafana-k8s-monitoring
    type: Opaque
  - data:
    - key: username
      objectName: grafana-instance-id
    - key: password
      objectName: grafana-cloud-token
    secretName: gc-otlp-endpoint-grafana-k8s-monitoring
    type: Opaque
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: alloy-secret-creator
  annotations:
    azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
automountServiceAccountToken: false
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: alloy-secret-creator
  labels:
    app: alloy-secret-creator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: alloy-secret-creator
  template:
    metadata:
      labels:
        app: alloy-secret-creator
        azure.workload.identity/use: "true"
    spec:
      containers:
      - name: main
        image: alpine
        command:
        - sleep
        - infinity
        volumeMounts:
        - name: secrets
          mountPath: "/mnt/secrets-store"
          readOnly: true
      terminationGracePeriodSeconds: 0
      serviceAccountName: alloy-secret-creator
      volumes:
      - name: secrets
        csi:
          driver: secrets-store.csi.k8s.io
          readOnly: true
          volumeAttributes:
            secretProviderClass: alloy-secret-provider

AKS における Secret 管理の例: 各 Alloy が Kubernetes Secret を作成

先ほどは、Key Vault の secret を Kubernetes の Secret として作成するには Key Vault の secret を mount する container が最低 1 つは存在していないといけないという特性を考慮し、sleep infinity する Pod の Deployment を作成しました。
この方法は Helm chart とは独立に導入できる一方で、無駄な Deployment を導入することになります。
AKS の SecretProviderClass を使うことを前提とするなら、各 Alloy の container が secret を mount するように Helm chart の values を修正する方が自然でしょう。

各 Alloy の container が secret を mount するには、Alloy で使われている全ての service account 用の federated identity credential を作成するように Terraform ファイルを変更する必要があります。

resource "azurerm_user_assigned_identity" "alloy" {
  name                = "alloy"
  location            = var.location
  resource_group_name = var.resource_group_name
}

resource "azurerm_role_assignment" "alloy" {
  principal_id         = azurerm_user_assigned_identity.alloy.principal_id
  role_definition_name = "Key Vault Secrets User"
  scope                = azurerm_key_vault.this.id
}

resource "azurerm_federated_identity_credential" "alloy" {
  for_each = { for name in [
    "grafana-k8s-monitoring-alloy-metrics",
    "grafana-k8s-monitoring-alloy-logs",
    "grafana-k8s-monitoring-alloy-receiver",
    "grafana-k8s-monitoring-alloy-singleton",
  ] : name => name }

  name                = each.key
  resource_group_name = var.resource_group_name
  audience            = ["api://AzureADTokenExchange"]
  issuer              = var.kubernetes_cluster_oidc_issuer_url
  parent_id           = azurerm_user_assigned_identity.alloy.id
  subject             = "system:serviceaccount:alloy:${each.key}"
}

その上で、各 Alloy の設定で secret を mount するようにします。具体的には Helm chart の values を以下のように設定します。SecretProviderClass は先ほど作成したものを流用しています。

alloy-metrics:
  enabled: true
  alloy:
    mounts:
      extra:
        - name: secrets
          mountPath: "/mnt/secrets-store"
          readOnly: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
    volumes:
      extra:
        - name: secrets
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: alloy-secret-provider
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
alloy-singleton:
  enabled: true
  alloy:
    mounts:
      extra:
        - name: secrets
          mountPath: "/mnt/secrets-store"
          readOnly: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
    volumes:
      extra:
        - name: secrets
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: alloy-secret-provider
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
alloy-logs:
  enabled: true
  alloy:
    mounts:
      extra:
        - name: secrets
          mountPath: "/mnt/secrets-store"
          readOnly: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
    volumes:
      extra:
        - name: secrets
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: alloy-secret-provider
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID
alloy-receiver:
  enabled: true
  alloy:
    extraPorts:
      - name: otlp-grpc
        port: 4317
        targetPort: 4317
        protocol: TCP
      - name: otlp-http
        port: 4318
        targetPort: 4318
        protocol: TCP
    mounts:
      extra:
        - name: secrets
          mountPath: "/mnt/secrets-store"
          readOnly: true
  controller:
    podAnnotations:
      kubernetes.azure.com/set-kube-service-host-fqdn: "true"
    volumes:
      extra:
        - name: secrets
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: alloy-secret-provider
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: $USER_ASSIGNED_CLIENT_ID

Building a custom collector ↩

OpenTelemetry Collector の OTLP receiver で受け取ったデータに Kubernetes attributes processor で attribute を付与する

Sun, 21 Sep 2025 00:00:00 +0900

OpenTelemetry Collector の Kubernates attribute processor は、Kubernetes cluster 上で動いている Pod の情報を保持し、それらの Pod から telemetry data が送られてきたら Pod に関連する metadata を attribute として付与する processor です。

README にも “By default, it associates the incoming connection IP to the Pod IP.” とあるように、Pod から OTLP receiver に送信したログなどに対しても attribute が付与されそうですが、DaemonSet で OpenTelemetry Collector を動かすと stdout に出力されたログにしか attribute が付与されなかったので、原因を調査して、OTLP receiver で受け取ったデータにも付与されるようにしてみました。

簡単のため、OpenTelemetry Collecotr の helm chart を使い、daemonset mode でインストールするものとします。
検証のために使ったコードや設定ファイルは github.com/abicky/opentelemetry-collector-k8s-example に置いてあります。

attribute が付与されない例

Kubernates attribute processor の動作確認に必要そうな最低限の設定として、次のような values.yaml を定義します。

mode: daemonset

image:
  repository: otel/opentelemetry-collector-k8s

presets:
  kubernetesAttributes:
    enabled: true
  logsCollection:
    enabled: true

config:
  exporters:
    debug:
      verbosity: detailed
  processors:
    k8sattributes:
      extract:
        annotations:
        - from: pod
          key_regex: ^resource\.opentelemetry\.io/(.+)$
          tag_name: $$1

上記の values.yaml を使って OpenTelemetry Collector をインストールします。

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm upgrade --install opentelemetry-collector open-telemetry/opentelemetry-collector \
  --version 0.134.0 \
  -f values.yaml \
  --namespace opentelemetry-collector \
  --create-namespace

Collector configuration best practices を踏襲すると、次のように OTLP receiver を利用する Pod には OTEL_EXPORTER_OTLP_ENDPOINT=http://$(MY_HOST_IP):4317 を指定することになりますが、これだと Kubernates attribute processor は attribute を付与しません。

apiVersion: v1
kind: Pod
metadata:
  generateName: hello-otel-
  annotations:
    resource.opentelemetry.io/service.name: hello
    resource.opentelemetry.io/service.version: 0.0.1
spec:
  containers:
  - name: hello-otel
    image: ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel:latest
    env:
    - name: MY_HOST_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: service.name=hello,service.version=0.0.1
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: http://$(MY_HOST_IP):4317
  restartPolicy: Never

Pod を作成してみます。

kubectl create -f pod.yaml

OpenTelemetry Collector のログは以下のとおりです。

OTLP receiver 関連のログ

2025-09-21T06:58:09.900Z        info    ResourceLog #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.37.0
Resource attributes:
     -> service.name: Str(hello)
     -> service.version: Str(0.0.1)
     -> telemetry.sdk.language: Str(go)
     -> telemetry.sdk.name: Str(opentelemetry)
     -> telemetry.sdk.version: Str(1.38.0)
     -> k8s.pod.ip: Str(10.244.0.1)
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope github.com/abicky/opentelemetry-collector-k8s-example
LogRecord #0
ObservedTimestamp: 2025-09-21 06:58:09.674347885 +0000 UTC
Timestamp: 2025-09-21 06:58:09.674336635 +0000 UTC
SeverityText: INFO
SeverityNumber: Info(9)
Body: Str(Hello World!)
Attributes:
     -> key1: Str(value1)
Trace ID: 259de42ec10699e1c67bc3ebd635840d
Span ID: b61cc14f6a1d0798
Flags: 1

Filelog receiver 関連のログ

2025-09-21T06:58:10.101Z        info    ResourceLog #0
Resource SchemaURL:
Resource attributes:
     -> k8s.pod.uid: Str(66af25e1-da87-487e-9c31-79c2ddfd6e9f)
     -> k8s.container.name: Str(hello-otel)
     -> k8s.namespace.name: Str(default)
     -> k8s.pod.name: Str(hello-otel-zpnsn)
     -> k8s.container.restart_count: Str(0)
     -> k8s.pod.start_time: Str(2025-09-21T06:58:07Z)
     -> k8s.node.name: Str(minikube)
     -> service.name: Str(hello)
     -> service.version: Str(0.0.1)
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope
LogRecord #0
ObservedTimestamp: 2025-09-21 06:58:09.894962843 +0000 UTC
Timestamp: 2025-09-21 06:58:09.674437885 +0000 UTC
SeverityText:
SeverityNumber: Unspecified(0)
Body: Str([INFO] Hello World!]
)
Attributes:
     -> log.file.path: Str(/var/log/pods/default_hello-otel-zpnsn_66af25e1-da87-487e-9c31-79c2ddfd6e9f/hello-otel/0.log)
     -> log.iostream: Str(stdout)
Trace ID:
Span ID:
Flags: 0

OTLP receiver 関連のログには k8s.pod.name などの attribute が付与されていないことがわかります。また、k8s.pod.ip の値が 10.244.0.1 となっており、Pod の IP らしからぬものとなっています。

attribute が付与される例

次のように service.enabled: true を values.yaml に追加します。これによって internalTrafficPolicy: Local な Service が作成されます。

mode: daemonset

image:
  repository: otel/opentelemetry-collector-k8s

presets:
  kubernetesAttributes:
    enabled: true
  logsCollection:
    enabled: true

service:
  enabled: true

config:
  processors:
    k8sattributes:
      extract:
        annotations:
        - from: pod
          key_regex: ^resource\.opentelemetry\.io/(.+)$
          tag_name: $$1

上記の values.yaml を使って OpenTelemetry Collector をインストールします。

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm upgrade --install opentelemetry-collector open-telemetry/opentelemetry-collector \
  --version 0.134.0 \
  -f values.yaml \
  --namespace opentelemetry-collector \
  --create-namespace

「attribute が付与される例」とは違い、OTLP receiver を利用する Pod では作成された Service の endpoint を使うよう OTEL_EXPORTER_OTLP_ENDPOINT=http://opentelemetry-collector.opentelemetry-collector.svc.cluster.local:4317 を指定します。

apiVersion: v1
kind: Pod
metadata:
  generateName: hello-otel-
  annotations:
    resource.opentelemetry.io/service.name: hello
    resource.opentelemetry.io/service.version: 0.0.1
spec:
  containers:
  - name: hello-otel
    image: ghcr.io/abicky/opentelemetry-collector-k8s-example/hello-otel:latest
    env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: service.name=hello,service.version=0.0.1
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: http://opentelemetry-collector.opentelemetry-collector.svc.cluster.local:4317
  restartPolicy: Never

Pod を作成してみます。

kubectl create -f pod.yaml

OpenTelemetry Collector のログは以下のとおりです。

OTLP receiver 関連のログ

2025-09-21T07:05:00.917Z        info    ResourceLog #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.37.0
Resource attributes:
     -> service.name: Str(hello)
     -> service.version: Str(0.0.1)
     -> telemetry.sdk.language: Str(go)
     -> telemetry.sdk.name: Str(opentelemetry)
     -> telemetry.sdk.version: Str(1.38.0)
     -> k8s.pod.ip: Str(10.244.0.12)
     -> k8s.pod.name: Str(hello-otel-mbzd9)
     -> k8s.namespace.name: Str(default)
     -> k8s.pod.start_time: Str(2025-09-21T07:04:58Z)
     -> k8s.pod.uid: Str(787de00a-454a-448f-9ce2-5b800018e32e)
     -> k8s.node.name: Str(minikube)
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope github.com/abicky/opentelemetry-collector-k8s-example
LogRecord #0
ObservedTimestamp: 2025-09-21 07:05:00.779964622 +0000 UTC
Timestamp: 2025-09-21 07:05:00.779955706 +0000 UTC
SeverityText: INFO
SeverityNumber: Info(9)
Body: Str(Hello World!)
Attributes:
     -> key1: Str(value1)
Trace ID: f1667fc768434960f328a2cce545398d
Span ID: 9dc540ac9bdc4354
Flags: 1

Filelog receiver 関連のログ

2025-09-21T07:05:01.117Z        info    Logs    {"resource": {"service.instance.id": "dd6dc1f8-7952-4bba-97cc-b3531c553d63", "service.name": "otelcol-k8s", "service.version": "0.135.0"}, "otelcol.component.id": "debug", "otelcol.component.kind": "exporter", "otelcol.signal": "logs", "resource logs": 2, "log records": 37}
2025-09-21T07:05:01.118Z        info    ResourceLog #0
Resource SchemaURL:
Resource attributes:
     -> k8s.pod.name: Str(hello-otel-mbzd9)
     -> k8s.container.restart_count: Str(0)
     -> k8s.pod.uid: Str(787de00a-454a-448f-9ce2-5b800018e32e)
     -> k8s.container.name: Str(hello-otel)
     -> k8s.namespace.name: Str(default)
     -> service.version: Str(0.0.1)
     -> service.name: Str(hello)
     -> k8s.pod.start_time: Str(2025-09-21T07:04:58Z)
     -> k8s.node.name: Str(minikube)
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope
LogRecord #0
ObservedTimestamp: 2025-09-21 07:05:00.859715664 +0000 UTC
Timestamp: 2025-09-21 07:05:00.780197414 +0000 UTC
SeverityText:
SeverityNumber: Unspecified(0)
Body: Str([INFO] Hello World!]
)
Attributes:
     -> log.file.path: Str(/var/log/pods/default_hello-otel-mbzd9_787de00a-454a-448f-9ce2-5b800018e32e/hello-otel/0.log)
     -> log.iostream: Str(stdout)
Trace ID:
Span ID:
Flags: 0

OTLP receiver 関連のログにも k8s.pod.name などの attribute が付与されていることがわかります。また、k8s.pod.ip の値が 10.244.0.12 という Pod の IP っぽいものになりました。
なお、trace や metrics にも同様の attribute が付与されます。

どうして host IP を使うと attribute が付与されないのか？

まず、helm chart の daemonset mode で OpenTelemetry Collector をインストールすると、次のような DaemonSet が定義されます。

apiVersion: apps/v1
kind: DaemonSet
spec:
  template:
    spec:
      containers:
        - name: opentelemetry-collector
          args:
            - --config=/conf/relay.yaml
          securityContext:
            {}
          image: "otel/opentelemetry-collector-k8s:0.135.0"
          imagePullPolicy: IfNotPresent
          ports:
            - name: otlp
              containerPort: 4317
              protocol: TCP
              hostPort: 4317
-- snip --

host の 4317 port と container の 4317 port が mapping されているため、http://$(MY_HOST_IP):4317 で OTLP receiver が利用可能になっています。
この port mapping は iptables の NAT テーブルによって実現されます。minikube の場合、次のコマンドで定義を確認することができます。

minikube ssh 'sudo iptables -L -t nat -n'

OpenTelemetry Collector の Pod IP が 10.244.0.3 の場合、出力結果は次のようになります。

出力結果

Chain PREROUTING (policy ACCEPT)
target     prot opt source               destination         
KUBE-SERVICES  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service portals */
DOCKER_OUTPUT  all  --  0.0.0.0/0            192.168.5.2         
DOCKER     all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain INPUT (policy ACCEPT)
target     prot opt source               destination         

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         
KUBE-SERVICES  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service portals */
DOCKER_OUTPUT  all  --  0.0.0.0/0            192.168.5.2         
DOCKER     all  --  0.0.0.0/0           !127.0.0.0/8          ADDRTYPE match dst-type LOCAL
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         
CNI-HOSTPORT-MASQ  all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd requiring masquerade */
KUBE-POSTROUTING  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes postrouting rules */
MASQUERADE  all  --  172.17.0.0/16        0.0.0.0/0           
DOCKER_POSTROUTING  all  --  0.0.0.0/0            192.168.5.2         
CNI-63ca6a5e53e580099e762a37  all  --  10.244.0.2           0.0.0.0/0            /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */
CNI-49b91e9558fcd61a2007a64a  all  --  10.244.0.3           0.0.0.0/0            /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-49b91e9558fcd61a2007a64a (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            10.244.0.0/16        /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */
MASQUERADE  all  --  0.0.0.0/0           !224.0.0.0/4          /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-63ca6a5e53e580099e762a37 (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            10.244.0.0/16        /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */
MASQUERADE  all  --  0.0.0.0/0           !224.0.0.0/4          /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */

Chain CNI-DN-49b91e9558fcd61a2007a (2 references)
target     prot opt source               destination         
CNI-HOSTPORT-SETMARK  udp  --  10.244.0.0/16        0.0.0.0/0            udp dpt:6831
CNI-HOSTPORT-SETMARK  udp  --  127.0.0.1            0.0.0.0/0            udp dpt:6831
DNAT       udp  --  0.0.0.0/0            0.0.0.0/0            udp dpt:6831 to:10.244.0.3:6831
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:14250
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:14250
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:14250 to:10.244.0.3:14250
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:14268
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:14268
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:14268 to:10.244.0.3:14268
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:4317
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:4317
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:4317 to:10.244.0.3:4317
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:4318
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:4318
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:4318 to:10.244.0.3:4318
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:9411
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:9411
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:9411 to:10.244.0.3:9411

Chain CNI-HOSTPORT-DNAT (2 references)
target     prot opt source               destination         
CNI-DN-49b91e9558fcd61a2007a  tcp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 14250,14268,4317,4318,9411
CNI-DN-49b91e9558fcd61a2007a  udp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 6831

Chain CNI-HOSTPORT-MASQ (1 references)
target     prot opt source               destination         
MASQUERADE  all  --  0.0.0.0/0            0.0.0.0/0            mark match 0x2000/0x2000

Chain CNI-HOSTPORT-SETMARK (12 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd masquerade mark */ MARK or 0x2000

Chain DOCKER (2 references)
target     prot opt source               destination         
RETURN     all  --  0.0.0.0/0            0.0.0.0/0           

Chain DOCKER_OUTPUT (2 references)
target     prot opt source               destination         
DNAT       tcp  --  0.0.0.0/0            192.168.5.2          tcp dpt:53 to:127.0.0.11:39019
DNAT       udp  --  0.0.0.0/0            192.168.5.2          udp dpt:53 to:127.0.0.11:34808

Chain DOCKER_POSTROUTING (1 references)
target     prot opt source               destination         
SNAT       tcp  --  127.0.0.11           0.0.0.0/0            to:192.168.5.2:53
SNAT       udp  --  127.0.0.11           0.0.0.0/0            to:192.168.5.2:53

Chain KUBE-KUBELET-CANARY (0 references)
target     prot opt source               destination         

Chain KUBE-MARK-MASQ (8 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            MARK or 0x4000

Chain KUBE-NODEPORTS (1 references)
target     prot opt source               destination         

Chain KUBE-POSTROUTING (1 references)
target     prot opt source               destination         
RETURN     all  --  0.0.0.0/0            0.0.0.0/0           
MARK       all  --  0.0.0.0/0            0.0.0.0/0            MARK xor 0x4000
MASQUERADE  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service traffic requiring SNAT */ random-fully

Chain KUBE-PROXY-CANARY (0 references)
target     prot opt source               destination         

Chain KUBE-SEP-IT2ZTR26TO4XFPTO (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:dns-tcp */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns-tcp */ tcp to:10.244.0.2:53

Chain KUBE-SEP-N4G2XR5TDX7PQE7P (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:metrics */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:metrics */ tcp to:10.244.0.2:9153

Chain KUBE-SEP-VPILYQBSPPXYB66K (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  192.168.49.2         0.0.0.0/0            /* default/kubernetes:https */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* default/kubernetes:https */ tcp to:192.168.49.2:8443

Chain KUBE-SEP-YIL6JZP7A3QYXJU2 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:dns */
DNAT       udp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns */ udp to:10.244.0.2:53

Chain KUBE-SERVICES (2 references)
target     prot opt source               destination         
KUBE-SVC-NPX46M4PTMTKRN6Y  tcp  --  0.0.0.0/0            10.96.0.1            /* default/kubernetes:https cluster IP */
KUBE-SVC-TCOU7JCQXEZGVUNU  udp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:dns cluster IP */
KUBE-SVC-ERIFXISQEP7F7OF4  tcp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:dns-tcp cluster IP */
KUBE-SVC-JD5MR3NA4I4DYORP  tcp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:metrics cluster IP */
KUBE-NODEPORTS  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service nodeports; NOTE: this must be the last rule in this chain */ ADDRTYPE match dst-type LOCAL

Chain KUBE-SVC-ERIFXISQEP7F7OF4 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:dns-tcp cluster IP */
KUBE-SEP-IT2ZTR26TO4XFPTO  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns-tcp -> 10.244.0.2:53 */

Chain KUBE-SVC-JD5MR3NA4I4DYORP (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:metrics cluster IP */
KUBE-SEP-N4G2XR5TDX7PQE7P  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:metrics -> 10.244.0.2:9153 */

Chain KUBE-SVC-NPX46M4PTMTKRN6Y (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.1            /* default/kubernetes:https cluster IP */
KUBE-SEP-VPILYQBSPPXYB66K  all  --  0.0.0.0/0            0.0.0.0/0            /* default/kubernetes:https -> 192.168.49.2:8443 */

Chain KUBE-SVC-TCOU7JCQXEZGVUNU (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  udp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:dns cluster IP */
KUBE-SEP-YIL6JZP7A3QYXJU2  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns -> 10.244.0.2:53 */

関連しそうなもののみピックアップすると次のようになります。

Chain PREROUTING (policy ACCEPT)
target     prot opt source               destination         
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         
CNI-HOSTPORT-MASQ  all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd requiring masquerade */
CNI-49b91e9558fcd61a2007a64a  all  --  10.244.0.3           0.0.0.0/0            /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-49b91e9558fcd61a2007a64a (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            10.244.0.0/16        /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */
MASQUERADE  all  --  0.0.0.0/0           !224.0.0.0/4          /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-DN-49b91e9558fcd61a2007a (2 references)
target     prot opt source               destination         
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:4317
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:4317
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:4317 to:10.244.0.3:4317

Chain CNI-HOSTPORT-DNAT (2 references)
target     prot opt source               destination         
CNI-DN-49b91e9558fcd61a2007a  tcp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 14250,14268,4317,4318,9411
CNI-DN-49b91e9558fcd61a2007a  udp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 6831

Chain CNI-HOSTPORT-MASQ (1 references)
target     prot opt source               destination         
MASQUERADE  all  --  0.0.0.0/0            0.0.0.0/0            mark match 0x2000/0x2000

Chain CNI-HOSTPORT-SETMARK (12 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd masquerade mark */ MARK or 0x2000

host の 4317 port へのリクエストは CNI-DN-49b91e9558fcd61a2007a の DNAT によって 10.244.0.3:4317 へのリクエストに変換され、10.244.0.3:4317 へのリクエストは CNI-49b91e9558fcd61a2007a64a の MASQUERADE によって送信元（Pod）のアドレスが変換されることがわかります。

よって、本来であれば Kubernates attribute processor は connection IP に対応する Pod に関連する attribute を付与するわけですが、この connection IP がリクエスト元の Pod と異なるため、対応する Pod を見つけることができないわけです。

なお、上記の例では minikube を利用していますが、Azure Kubernetes Service でも CNI-HOSTPORT-DNAT や CNI-HOSTPORT-MASQ などが定義されます。次のようなコマンドで確認できます。

kubectl debug $(kubectl get nodes --output name) -i \
  --image=mcr.microsoft.com/cbl-mariner/busybox:2.0 \
  --profile=sysadmin \
  -- chroot /host iptables -L -t nat -n

どうして Service を使うと attribute が付与されるのか？

前述のとおり、values.yaml で service.enabled: true を指定することで internalTrafficPolicy: Local な Service が作成されます。
Service の定義を一部抜粋すると以下のとおりです。

apiVersion: v1
kind: Service
metadata:
  name: opentelemetry-collector
  namespace: opentelemetry-collector
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: opentelemetry-collector
    app.kubernetes.io/instance: opentelemetry-collector
    component: agent-collector
  internalTrafficPolicy: Local
  ports:
    - name: otlp
      port: 4317
      targetPort: 4317
      protocol: TCP
      appProtocol: grpc

internalTrafficPolicy が Local の場合、同一 node に対してしかリクエストを送れなくなってしまいますが、その代わり送信元 Pod の IP アドレスは維持されます。¹

よって、connection IP の情報から対応する Pod の情報を取得することができるというわけです。

参考までに iptables -L -t nat -n の出力結果は次のとおりです。

出力結果

Chain PREROUTING (policy ACCEPT)
target     prot opt source               destination         
KUBE-SERVICES  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service portals */
DOCKER_OUTPUT  all  --  0.0.0.0/0            192.168.5.2         
DOCKER     all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain INPUT (policy ACCEPT)
target     prot opt source               destination         

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         
KUBE-SERVICES  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service portals */
DOCKER_OUTPUT  all  --  0.0.0.0/0            192.168.5.2         
DOCKER     all  --  0.0.0.0/0           !127.0.0.0/8          ADDRTYPE match dst-type LOCAL
CNI-HOSTPORT-DNAT  all  --  0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         
CNI-HOSTPORT-MASQ  all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd requiring masquerade */
KUBE-POSTROUTING  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes postrouting rules */
MASQUERADE  all  --  172.17.0.0/16        0.0.0.0/0           
DOCKER_POSTROUTING  all  --  0.0.0.0/0            192.168.5.2         
CNI-63ca6a5e53e580099e762a37  all  --  10.244.0.2           0.0.0.0/0            /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */
CNI-49b91e9558fcd61a2007a64a  all  --  10.244.0.3           0.0.0.0/0            /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-49b91e9558fcd61a2007a64a (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            10.244.0.0/16        /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */
MASQUERADE  all  --  0.0.0.0/0           !224.0.0.0/4          /* name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */

Chain CNI-63ca6a5e53e580099e762a37 (1 references)
target     prot opt source               destination         
ACCEPT     all  --  0.0.0.0/0            10.244.0.0/16        /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */
MASQUERADE  all  --  0.0.0.0/0           !224.0.0.0/4          /* name: "bridge" id: "91c4bb4e8c3975c045ab9b40179a31b673c18adeed0261e72a93480a852deb63" */

Chain CNI-DN-49b91e9558fcd61a2007a (2 references)
target     prot opt source               destination         
CNI-HOSTPORT-SETMARK  udp  --  10.244.0.0/16        0.0.0.0/0            udp dpt:6831
CNI-HOSTPORT-SETMARK  udp  --  127.0.0.1            0.0.0.0/0            udp dpt:6831
DNAT       udp  --  0.0.0.0/0            0.0.0.0/0            udp dpt:6831 to:10.244.0.3:6831
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:14250
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:14250
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:14250 to:10.244.0.3:14250
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:14268
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:14268
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:14268 to:10.244.0.3:14268
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:4317
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:4317
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:4317 to:10.244.0.3:4317
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:4318
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:4318
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:4318 to:10.244.0.3:4318
CNI-HOSTPORT-SETMARK  tcp  --  10.244.0.0/16        0.0.0.0/0            tcp dpt:9411
CNI-HOSTPORT-SETMARK  tcp  --  127.0.0.1            0.0.0.0/0            tcp dpt:9411
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:9411 to:10.244.0.3:9411

Chain CNI-HOSTPORT-DNAT (2 references)
target     prot opt source               destination         
CNI-DN-49b91e9558fcd61a2007a  tcp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 14250,14268,4317,4318,9411
CNI-DN-49b91e9558fcd61a2007a  udp  --  0.0.0.0/0            0.0.0.0/0            /* dnat name: "bridge" id: "f74edbf5656551c51b28f524a13fbca17bfd0577d0faf1f561932a090f99255f" */ multiport dports 6831

Chain CNI-HOSTPORT-MASQ (1 references)
target     prot opt source               destination         
MASQUERADE  all  --  0.0.0.0/0            0.0.0.0/0            mark match 0x2000/0x2000

Chain CNI-HOSTPORT-SETMARK (12 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            /* CNI portfwd masquerade mark */ MARK or 0x2000

Chain DOCKER (2 references)
target     prot opt source               destination         
RETURN     all  --  0.0.0.0/0            0.0.0.0/0           

Chain DOCKER_OUTPUT (2 references)
target     prot opt source               destination         
DNAT       tcp  --  0.0.0.0/0            192.168.5.2          tcp dpt:53 to:127.0.0.11:39019
DNAT       udp  --  0.0.0.0/0            192.168.5.2          udp dpt:53 to:127.0.0.11:34808

Chain DOCKER_POSTROUTING (1 references)
target     prot opt source               destination         
SNAT       tcp  --  127.0.0.11           0.0.0.0/0            to:192.168.5.2:53
SNAT       udp  --  127.0.0.11           0.0.0.0/0            to:192.168.5.2:53

Chain KUBE-KUBELET-CANARY (0 references)
target     prot opt source               destination         

Chain KUBE-MARK-MASQ (20 references)
target     prot opt source               destination         
MARK       all  --  0.0.0.0/0            0.0.0.0/0            MARK or 0x4000

Chain KUBE-NODEPORTS (1 references)
target     prot opt source               destination         

Chain KUBE-POSTROUTING (1 references)
target     prot opt source               destination         
RETURN     all  --  0.0.0.0/0            0.0.0.0/0           
MARK       all  --  0.0.0.0/0            0.0.0.0/0            MARK xor 0x4000
MASQUERADE  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service traffic requiring SNAT */ random-fully

Chain KUBE-PROXY-CANARY (0 references)
target     prot opt source               destination         

Chain KUBE-SEP-4LPIWUPUF5AGFYOT (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp-http */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp-http */ tcp to:10.244.0.3:4318

Chain KUBE-SEP-7OD2PDG3PD7J2VZ7 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-grpc */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-grpc */ tcp to:10.244.0.3:14250

Chain KUBE-SEP-CQ3FDE7FTJ5XNAXT (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-thrift */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-thrift */ tcp to:10.244.0.3:14268

Chain KUBE-SEP-CRMKBXNSVTMUHCM2 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp */ tcp to:10.244.0.3:4317

Chain KUBE-SEP-DEN5DS53K2NB2AKB (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:zipkin */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:zipkin */ tcp to:10.244.0.3:9411

Chain KUBE-SEP-IT2ZTR26TO4XFPTO (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:dns-tcp */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns-tcp */ tcp to:10.244.0.2:53

Chain KUBE-SEP-N4G2XR5TDX7PQE7P (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:metrics */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:metrics */ tcp to:10.244.0.2:9153

Chain KUBE-SEP-QAAOH7NY3YNSNY24 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.3           0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-compact */
DNAT       udp  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-compact */ udp to:10.244.0.3:6831

Chain KUBE-SEP-VPILYQBSPPXYB66K (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  192.168.49.2         0.0.0.0/0            /* default/kubernetes:https */
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            /* default/kubernetes:https */ tcp to:192.168.49.2:8443

Chain KUBE-SEP-YIL6JZP7A3QYXJU2 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  all  --  10.244.0.2           0.0.0.0/0            /* kube-system/kube-dns:dns */
DNAT       udp  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns */ udp to:10.244.0.2:53

Chain KUBE-SERVICES (2 references)
target     prot opt source               destination         
KUBE-SVC-TCOU7JCQXEZGVUNU  udp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:dns cluster IP */
KUBE-SVC-ERIFXISQEP7F7OF4  tcp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:dns-tcp cluster IP */
KUBE-SVC-JD5MR3NA4I4DYORP  tcp  --  0.0.0.0/0            10.96.0.10           /* kube-system/kube-dns:metrics cluster IP */
KUBE-SVC-NPX46M4PTMTKRN6Y  tcp  --  0.0.0.0/0            10.96.0.1            /* default/kubernetes:https cluster IP */
KUBE-SVL-VX6IA5VL6FLYVBXT  tcp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:otlp-http cluster IP */
KUBE-SVL-WQZRZBSAAJJ5ENNE  tcp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:zipkin cluster IP */
KUBE-SVL-AR7YBPPNY2K6GKT3  udp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-compact cluster IP */
KUBE-SVL-7S5WBWADAYVHRMPZ  tcp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-grpc cluster IP */
KUBE-SVL-GQJJUNO6YZCBZIVL  tcp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-thrift cluster IP */
KUBE-SVL-7E5QNFKIEQM22BF2  tcp  --  0.0.0.0/0            10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:otlp cluster IP */
KUBE-NODEPORTS  all  --  0.0.0.0/0            0.0.0.0/0            /* kubernetes service nodeports; NOTE: this must be the last rule in this chain */ ADDRTYPE match dst-type LOCAL

Chain KUBE-SVC-ERIFXISQEP7F7OF4 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:dns-tcp cluster IP */
KUBE-SEP-IT2ZTR26TO4XFPTO  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns-tcp -> 10.244.0.2:53 */

Chain KUBE-SVC-JD5MR3NA4I4DYORP (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:metrics cluster IP */
KUBE-SEP-N4G2XR5TDX7PQE7P  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:metrics -> 10.244.0.2:9153 */

Chain KUBE-SVC-NPX46M4PTMTKRN6Y (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.96.0.1            /* default/kubernetes:https cluster IP */
KUBE-SEP-VPILYQBSPPXYB66K  all  --  0.0.0.0/0            0.0.0.0/0            /* default/kubernetes:https -> 192.168.49.2:8443 */

Chain KUBE-SVC-TCOU7JCQXEZGVUNU (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  udp  -- !10.244.0.0/16        10.96.0.10           /* kube-system/kube-dns:dns cluster IP */
KUBE-SEP-YIL6JZP7A3QYXJU2  all  --  0.0.0.0/0            0.0.0.0/0            /* kube-system/kube-dns:dns -> 10.244.0.2:53 */

Chain KUBE-SVL-7E5QNFKIEQM22BF2 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:otlp cluster IP */
KUBE-SEP-CRMKBXNSVTMUHCM2  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp -> 10.244.0.3:4317 */

Chain KUBE-SVL-7S5WBWADAYVHRMPZ (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-grpc cluster IP */
KUBE-SEP-7OD2PDG3PD7J2VZ7  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-grpc -> 10.244.0.3:14250 */

Chain KUBE-SVL-AR7YBPPNY2K6GKT3 (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  udp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-compact cluster IP */
KUBE-SEP-QAAOH7NY3YNSNY24  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-compact -> 10.244.0.3:6831 */

Chain KUBE-SVL-GQJJUNO6YZCBZIVL (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:jaeger-thrift cluster IP */
KUBE-SEP-CQ3FDE7FTJ5XNAXT  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:jaeger-thrift -> 10.244.0.3:14268 */

Chain KUBE-SVL-VX6IA5VL6FLYVBXT (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:otlp-http cluster IP */
KUBE-SEP-4LPIWUPUF5AGFYOT  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:otlp-http -> 10.244.0.3:4318 */

Chain KUBE-SVL-WQZRZBSAAJJ5ENNE (1 references)
target     prot opt source               destination         
KUBE-MARK-MASQ  tcp  -- !10.244.0.0/16        10.105.249.160       /* opentelemetry-collector/opentelemetry-collector:zipkin cluster IP */
KUBE-SEP-DEN5DS53K2NB2AKB  all  --  0.0.0.0/0            0.0.0.0/0            /* opentelemetry-collector/opentelemetry-collector:zipkin -> 10.244.0.3:9411 */

なお、Pod の起動直後のログだと、Kubernates attribute processor が telemetry data を受けった時点でまだ Kubernates attribute processor が Pod を検知できていないことがあり、その場合は attribute が付与されません。サンプルコードでは起動直後に 1 秒 sleep しています。

Kubernates attribute processor が付与し損なうと困る attribute に関しては OTEL_RESOURCE_ATTRIBUTES で指定するのが良いでしょう。
Pod の定義で resource.opentelemetry.io/* annotation と OTEL_RESOURCE_ATTRIBUTES に同じ値を指定しているのはそのためです。前者が Filelog receiver 用、後者が OTLP receiver 用で、起動直後のログなどに service.name などが付与されないことを許容できるなら OTEL_RESOURCE_ATTRIBUTES は不要です。

minikube と Azure Kubernetes Service (v1.33.3) で試したところ、どうも iptables の定義的にも、動作確認結果的にも、同じネットワーク内に存在する Pod 同士の通信であれば internalTrafficPolicy が Cluster でも Pod の IP は変換されないようで、違いはリクエスト先が固定になるかランダムになるかだけみたいです ↩

Terraform Provider for Azure Key Vault を作った〜Azure の Key Vault secret を Terraform で安全に管理したい〜

Wed, 27 Aug 2025 00:00:00 +0900

Azure の Key Vault secret (AWS でいう paramete store) を Terraform で管理できると次のようなメリットがあります。

secret の作成・変更を pull request のレビューフローに乗せることができる
- ただし secret value は apply 時に指定したり、Terraform では仮の値を指定して別途本当の値で更新したりする想定
CI 等で terraform plan/apply するようにしていれば secret の操作に関する権限がない人でも作成・変更できる
- secret value の更新に関しては同上
Terraform file を見るだけでどのような secret があるか確認できる
- 謎に作成された secret の存在に気付ける
権限のスコープを設定する際に特定の secret に対する read 権限を手軽に付与できる
- resource ID を手軽に取得できる

ところが、Terraform で Key Vault secret を普通に管理すると、state file に secret value が保存されるという問題があります。
Terraform の state file に一部の attribute を保存しないようにしたいという話は 10 年以上も前から話題になっています。¹

その対策として、Terraform 1.11 では write-only arguments が導入され、Terraform Provider for Azure の azurerm_key_vault_secret リソースでも write-only argument である value_wo が導入されました。²

ここで、write-only arguments を使わなくても ignore_changes を使えば良いじゃないかと思った方もいるでしょうが、ignore_changes だと state file に実際の値が保存されます。詳細は [Terraform] 誤解されがちなignore_changesの動き・機密情報はstateに保持されるのか？ | DevelopersIO を読んでみてください。

azurerm_key_vault_secret で value_wo を使えば問題ないかというとそうでもなく、value_wo を使ったとしても Microsoft.KeyVault/vaults/secrets/getSecret/action の権限が必要で、terraform plan を実行できる権限を付与するには secret value を取得する権限を付与することになり使い勝手が悪いです。

というわけで、value_wo を使っている場合に secret value の取得を不要にする PR を 3 ヶ月前に出したんですが、いつまで経ってもレビューされる気配はなく、半年以上前に出した簡単な bugfix PR も同様で、Slack も閑散としていて、レビューしてくれとたまにメッセージを投稿する人がいてもスルーという状態で、マージされるにはまだまだ時間がかかりそうです。

そんなわけで、Microsoft.KeyVault/vaults/secrets/getSecret/action の権限なしで secret を管理できる terraform-provider-azurekv を作りました。

使い方

基本的な使い方はドキュメントを参照してください。
基本的に azurerm_key_vault_secret と同じ使い方ができますが、soft delete 済みの secret を復活させたり、purge させる機能はサポートしていません。

azurerm_key_vault_secret からのマイグレーション

例えば次のようなリソースが定義されていたとします。

resource "azurerm_key_vault_secret" "example" {
  name         = "example"
  key_vault_id = var.key_vault_id

  value_wo         = "This value is manged outside of Terraform"
  value_wo_version = 1
}

この場合、まずは azurerm_key_vault_secret の内容をコピペして、コピーした内容の azurerm_key_vault_secret を azurekv_secret に変更し、import ブロックでインポートします。

resource "azurerm_key_vault_secret" "example" {
  name         = "example"
  key_vault_id = var.key_vault_id

  value_wo         = "This value is manged outside of Terraform"
  value_wo_version = 1
}

resource "azurekv_secret" "example" {
  name         = "example"
  key_vault_id = var.key_vault_id

  value_wo         = "This value is manged outside of Terraform"
  value_wo_version = 1
}

import {
  id = azurerm_key_vault_secret.example.id
  to = azurekv_secret.example
}

これで一度 terraform apply を実行し、次に azurerm_key_vault_secret.example を削除します。

resource "azurekv_secret" "example" {
  name         = "example"
  key_vault_id = var.key_vault_id

  value_wo         = "This value is manged outside of Terraform"
  value_wo_version = 1
}

removed {
  from = azurerm_key_vault_secret.example

  lifecycle {
    destroy = false
  }
}

最後に不要になった removed ブロックを削除すれば移行完了です。

その他の選択肢

Azure provider

Microsoft.KeyVault/vaults/secrets/getSecret/action の権限が必要な時点で選択肢にはないんですが、ignore_changes の意味がないことを確認します。

terraform {
  required_version = ">=1.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "=4.41.0"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_key_vault_secret" "example" {
  name         = "example"
  key_vault_id = var.key_vault_id

  value = "This value is manged outside of Terraform"

  lifecycle {
    ignore_changes = [value]
  }
}

terraform apply 後の状態は次のとおりです。

$ jq -r '.resources[] | select(.name == "example").instances[].attributes.value' terraform.tfstate
This value is manged outside of Terraform

secret value を更新します。

az keyvault secret set \
  --vault-name $KEY_VAULT_NAME \
  --name example \
  --value 'This is the actual secret!'

terraform refresh の後に state file を確認してみると、Terraform 外で更新した値が保存されていることがわかります。

$ jq -r '.resources[] | select(.name == "example").instances[].attributes.value' terraform.tfstate
This is the actual secret!

AzAPI provider

AzAPI provider を使うと、secret value が state file に保存されても Terraform 外で更新された値には追従しないので、ignore_changes を使った時のような問題は起きません。

terraform {
  required_version = ">=1.0"
  required_providers {
    azapi = {
      source  = "azure/azapi"
      version = "=2.6.1"
    }
  }
}

resource "azapi_resource" "example" {
  name      = "example"
  type      = "Microsoft.KeyVault/vaults/secrets@2024-11-01"
  parent_id = "/subscriptions/f48afe64-0e0a-4ce8-b0bd-21eecb6b9ad1/resourceGroups/terraform-provider-azurekv/providers/Microsoft.KeyVault/vaults/avnjctgtwrxesljlzowkbdlr"

  body = {
    properties = {
      value = "This value is manged outside of Terraform"
    }
  }
}

ただ、次のようにタグを追加するだけでも新しいバージョンの secret が作成され、value も Terraform file で指定しているものに戻ってしまうので使い勝手が悪いです。

resource "azapi_resource" "example" {
  name      = "example"
  type      = "Microsoft.KeyVault/vaults/secrets@2024-11-01"
  parent_id = "/subscriptions/f48afe64-0e0a-4ce8-b0bd-21eecb6b9ad1/resourceGroups/terraform-provider-azurekv/providers/Microsoft.KeyVault/vaults/avnjctgtwrxesljlzowkbdlr"

  body = {
    properties = {
      value = "This value is manged outside of Terraform"
    }

    tags = {
      Environment = "Production"
    }
  }
}

おまけ〜動作確認用 service principal の作成方法〜

開発方法についてはだいたい https://github.com/abicky/terraform-provider-azurekv の README に書いてあるんですが、動作確認用の service principal の作成について紹介します。

テスト用 service principal

make testacc の実行に使うやつです。

まず、次のような JSON を作成します。

{
  "Name": "Terraform Provider for Azure Key Vault Tester",
  "Actions": [
    "Microsoft.Resources/subscriptions/resourceGroups/delete",
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Resources/subscriptions/resourceGroups/write",
    "Microsoft.KeyVault/locations/deletedVaults/purge/action",
    "Microsoft.KeyVault/locations/operationResults/read",
    "Microsoft.KeyVault/vaults/delete",
    "Microsoft.KeyVault/vaults/read",
    "Microsoft.KeyVault/vaults/write"
  ],
  "DataActions": [
    "Microsoft.KeyVault/vaults/secrets/delete",
    "Microsoft.KeyVault/vaults/secrets/getSecret/action",
    "Microsoft.KeyVault/vaults/secrets/purge/action",
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action",
    "Microsoft.KeyVault/vaults/secrets/setSecret/action"
  ],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}

上記の JSON を使って custom role を作成します。

az role definition create --role-definition terraform-provider-for-azure-key-vault-tester.json

作成された custom role を付与しつつ service principal を作成します。

az ad sp create-for-rbac \
  --name terraform-provider-azurekv-tester \
  --role 'Terraform Provider for Azure Key Vault Tester' \
  --scopes /subscriptions/$YOUR_SUBSCRIPTION_ID

出力された appId が client ID、password が client secret になります。secret の期限はデフォルトで 1 年間です。

なお、CI では managed identity を作成し、同じ role を付与した上で OIDC を利用しています。

terraform plan 用 service principal

次のような JSON を用意します。あとはテスト用 service principal と同様です。

{
  "Name": "Terraform Provider for Azure Key Vault Planner",
  "Actions": [
    "Microsoft.KeyVault/vaults/read"
  ],
  "DataActions": [
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action"
  ],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}

terraform plan 用 service principal

次のような JSON を用意します。あとはテスト用 service principal と同様です。

{
  "Name": "Terraform Provider for Azure Key Vault Applier",
  "Actions": [
    "Microsoft.KeyVault/vaults/read"
  ],
  "DataActions": [
    "Microsoft.KeyVault/vaults/secrets/delete",
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action",
    "Microsoft.KeyVault/vaults/secrets/setSecret/action"
  ],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}

PagerDuty のシフト回数を数える pd-shift というツールを作成した〜オンコール待機手当の計算を効率化する〜

Mon, 30 Jun 2025 00:00:00 +0900

24/365 で運用しているサービスであれば、オンコール体制を整備するために PagerDuty を利用しているサービスも多いことでしょう。また、業務時間外に待機することに対して、待機手当なるものが支給されることもあるでしょう。
待機手当が待機回数に応じて支給される場合、人手で待機回数を数えるのは地味に大変だったりします。そんなわけで、pd-shift というツールを作成しました。
現状はシフト回数を数える機能しかありませんが、将来的に pd よりも手軽に override を作成する機能も提供したいと思っていて、少し抽象的な名前になっています。

使用例

インストール方法は README の Installation、一般的な使い方は README の Usage を読んでいただくとして、README でも利用している次のスケジュール (ID: P4DRALL) を使っていくつかの使用例を見ていきます。

設定は次のとおりで、handoff time を月曜日の 05:00 としています。

集計対象期間は 2025-07-01 05:00 〜 2025-07-08 05:00 とします。

なお、PagerDuty の API key が PD_SHIFT_API_KEY 環境変数にセットされているものとします。API key がなければ PagerDuty のドキュメントに従って発行してください。

平日・土日関係なく待機日数をカウントしたい場合

とてもシンプルな例で、次のように実行すれば良いです。

pd-shift count \
  --time-zone Asia/Tokyo \
  --schedule-ids P4DRALL \
  --handoff-times 05:00 \
  --since 2025-07-01 \
  --until 2025-07-08

結果は次のとおりです。

# Summary

- John Smith: 5.75
- Takeshi Arabiki: 1.25
- Total: 7.00
- Expected total: 7

# Details

- Tue, 2025-07-01 05:00+0900 - Wed, 2025-07-02 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Wed, 2025-07-02 05:00+0900 - Thu, 2025-07-03 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Thu, 2025-07-03 05:00+0900 - Fri, 2025-07-04 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Fri, 2025-07-04 05:00+0900 - Sat, 2025-07-05 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Sat, 2025-07-05 05:00+0900 - Sun, 2025-07-06 05:00+0900
    - Weekly Rotation
        - John Smith: 0.17 (05:00 - 09:00)
        - Takeshi Arabiki: 0.25 (09:00 - 15:00)
        - John Smith: 0.58 (15:00 - 05:00)
- Sun, 2025-07-06 05:00+0900 - Mon, 2025-07-07 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Mon, 2025-07-07 05:00+0900 - Tue, 2025-07-08 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)

# PagerDuty schedules

## Weekly Rotation

- 2025-07-01T05:00:00+09:00 - 2025-07-05T09:00:00+09:00: John Smith
- 2025-07-05T09:00:00+09:00 - 2025-07-05T15:00:00+09:00: Takeshi Arabiki
- 2025-07-05T15:00:00+09:00 - 2025-07-07T05:00:00+09:00: John Smith
- 2025-07-07T05:00:00+09:00 - 2025-07-08T05:00:00+09:00: Takeshi Arabiki

平日は夜間のみ、休日は日中と夜間別々にカウントしたい場合

業務時間外のみが待機手当の対象で、平日は夜間のみ、休日は日中と夜間それぞれでカウントされるものとします。休日丸々待機していれば 2 とカウントされる感じですね。
このような集計をしたい場合、--non-working-days で休日を定義し、--include で working-days のカウント対象を夜間に限定する必要があります。
例えば、土日・祝日が休日で、夜間を 17:00 から翌朝 05:00 とした場合、次のように実行します。

pd-shift count \
  --time-zone Asia/Tokyo \
  --schedule-ids P4DRALL \
  --handoff-times 05:00,17:00 \
  --include working-days:17:00-05:00,non-working-days \
  --non-working-days 'JP holidays,Sat,Sun,Dec 29,Dec 30,Dec 31,Jan 1,Jan 2,Jan 3' \
  --since 2025-07-01 \
  --until 2025-07-08

結果は次のとおりで、土日に関しては日中と夜間で別々にカウントされていることがわかるかと思います。

# Summary

- John Smith: 7.50
- Takeshi Arabiki: 1.50
- Total: 9.00
- Expected total: 9

# Details

- Tue, 2025-07-01 17:00+0900 - Wed, 2025-07-02 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Wed, 2025-07-02 17:00+0900 - Thu, 2025-07-03 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Thu, 2025-07-03 17:00+0900 - Fri, 2025-07-04 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Fri, 2025-07-04 17:00+0900 - Sat, 2025-07-05 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Sat, 2025-07-05 05:00+0900 - Sat, 2025-07-05 17:00+0900
    - Weekly Rotation
        - John Smith: 0.33 (05:00 - 09:00)
        - Takeshi Arabiki: 0.50 (09:00 - 15:00)
        - John Smith: 0.17 (15:00 - 17:00)
- Sat, 2025-07-05 17:00+0900 - Sun, 2025-07-06 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Sun, 2025-07-06 05:00+0900 - Sun, 2025-07-06 17:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 17:00)
- Sun, 2025-07-06 17:00+0900 - Mon, 2025-07-07 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Mon, 2025-07-07 17:00+0900 - Tue, 2025-07-08 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (17:00 - 05:00)

# PagerDuty schedules

## Weekly Rotation

- 2025-07-01T05:00:00+09:00 - 2025-07-05T09:00:00+09:00: John Smith
- 2025-07-05T09:00:00+09:00 - 2025-07-05T15:00:00+09:00: Takeshi Arabiki
- 2025-07-05T15:00:00+09:00 - 2025-07-07T05:00:00+09:00: John Smith
- 2025-07-07T05:00:00+09:00 - 2025-07-08T05:00:00+09:00: Takeshi Arabiki

なお、集計対象期間が 2025-07-01 〜 2025-07-08 であれば --non-working-days 'Sat,Sun' で十分なんですが、日本の祝日や年末年始休暇が集計期間になるケースも考慮して --non-working-days 'JP holidays,Sat,Sun,Dec 29,Dec 30,Dec 31,Jan 1,Jan 2,Jan 3' としています。

もし土日と水曜日が休みの週休 3 日制の会社だと --non-working-days 'JP holidays,Wed,Sat,Sun,Dec 29,Dec 30,Dec 31,Jan 1,Jan 2,Jan 3' です。
その場合、出力結果は水曜日の日中もカウントされるので次のようになります。

# Summary

- John Smith: 8.50
- Takeshi Arabiki: 1.50
- Total: 10.00
- Expected total: 10

# Details

- Tue, 2025-07-01 17:00+0900 - Wed, 2025-07-02 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Wed, 2025-07-02 05:00+0900 - Wed, 2025-07-02 17:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 17:00)
- Wed, 2025-07-02 17:00+0900 - Thu, 2025-07-03 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Thu, 2025-07-03 17:00+0900 - Fri, 2025-07-04 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Fri, 2025-07-04 17:00+0900 - Sat, 2025-07-05 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Sat, 2025-07-05 05:00+0900 - Sat, 2025-07-05 17:00+0900
    - Weekly Rotation
        - John Smith: 0.33 (05:00 - 09:00)
        - Takeshi Arabiki: 0.50 (09:00 - 15:00)
        - John Smith: 0.17 (15:00 - 17:00)
- Sat, 2025-07-05 17:00+0900 - Sun, 2025-07-06 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Sun, 2025-07-06 05:00+0900 - Sun, 2025-07-06 17:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 17:00)
- Sun, 2025-07-06 17:00+0900 - Mon, 2025-07-07 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (17:00 - 05:00)
- Mon, 2025-07-07 17:00+0900 - Tue, 2025-07-08 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (17:00 - 05:00)

# PagerDuty schedules

## Weekly Rotation

- 2025-07-01T05:00:00+09:00 - 2025-07-05T09:00:00+09:00: John Smith
- 2025-07-05T09:00:00+09:00 - 2025-07-05T15:00:00+09:00: Takeshi Arabiki
- 2025-07-05T15:00:00+09:00 - 2025-07-07T05:00:00+09:00: John Smith
- 2025-07-07T05:00:00+09:00 - 2025-07-08T05:00:00+09:00: Takeshi Arabiki

休日のみ待機回数をカウントしたい場合

グローバルな会社で、follo-the-sun schedule になっている場合、休日のみカウントすることになるでしょう。
05:00, 13:00, 22:00 でシフトが変わる場合、次のように実行します。

pd-shift count \
  --time-zone Asia/Tokyo \
  --schedule-ids P4DRALL \
  --handoff-times 05:00,13:00,22:00 \
  --include non-working-days \
  --non-working-days 'JP holidays,Sat,Sun,Dec 29,Dec 30,Dec 31,Jan 1,Jan 2,Jan 3' \
  --since 2025-07-01 \
  --until 2025-07-08

結果は次のとおりです。

# Summary

- John Smith: 5.28
- Takeshi Arabiki: 0.72
- Total: 6.00
- Expected total: 6

# Details

- Sat, 2025-07-05 05:00+0900 - Sat, 2025-07-05 13:00+0900
    - Weekly Rotation
        - John Smith: 0.50 (05:00 - 09:00)
        - Takeshi Arabiki: 0.50 (09:00 - 13:00)
- Sat, 2025-07-05 13:00+0900 - Sat, 2025-07-05 22:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 0.22 (13:00 - 15:00)
        - John Smith: 0.78 (15:00 - 22:00)
- Sat, 2025-07-05 22:00+0900 - Sun, 2025-07-06 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (22:00 - 05:00)
- Sun, 2025-07-06 05:00+0900 - Sun, 2025-07-06 13:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 13:00)
- Sun, 2025-07-06 13:00+0900 - Sun, 2025-07-06 22:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (13:00 - 22:00)
- Sun, 2025-07-06 22:00+0900 - Mon, 2025-07-07 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (22:00 - 05:00)

# PagerDuty schedules

## Weekly Rotation

- 2025-07-01T05:00:00+09:00 - 2025-07-05T09:00:00+09:00: John Smith
- 2025-07-05T09:00:00+09:00 - 2025-07-05T15:00:00+09:00: Takeshi Arabiki
- 2025-07-05T15:00:00+09:00 - 2025-07-07T05:00:00+09:00: John Smith
- 2025-07-07T05:00:00+09:00 - 2025-07-08T05:00:00+09:00: Takeshi Arabiki

なお、拠点ごとに休日が異なるケースには対応していません。

Primary/secondary 合わせた待機回数をカウントしたい場合

次のように --scheduled-ids に複数のスケジュールを指定すると、primary と secondary 両方の待機回数をカウントできます。

pd-shift count \
  --time-zone Asia/Tokyo \
  --schedule-ids P4DRALL,P5ESBMM \
  --handoff-times 05:00 \
  --since 2025-07-01 \
  --until 2025-07-08

特定の時間帯だけ secondary の schedule を primary の人で override することで、一時的に primary 一人体制になる時間帯もあるかと思いますが、現状は同一人物の待機回数がダブルカウントされるようになっています。

前月の待機回数をカウントしたい場合

集計対象期間は 2025-07-01 〜 2025-07-08 の固定としていましたが、待機手当の支給を目的とする場合、今月や前月の待機回数をカウントしたいことが多いでしょう。pd-shift にそのような指定ができるようにしようかとも思ったんですが、date コマンドと併用することで実現できるのでサポートしていません。
例えば前月の月初は BSD date であれば date -v -1m -jf %F $(date +%Y-%m-01) +%F、GNU date であれば date -d $(date '+%Y-%m-01')-1month +%F で出力することができます。月初に実行するのであればシンプルに date -v -1m +%Y-%m-01、date -d -1month +%Y-%m-01 で大丈夫です。翌月月初は -1m となっている箇所を +1m に変えるだけです。

よって、Mac で前月の待機回数をカウントするには次のように実行します。

pd-shift count \
  --time-zone Asia/Tokyo \
  --schedule-ids P4DRALL \
  --handoff-times 05:00 \
  --since $(date -v -1m -jf %F $(date +%Y-%m-01) +%F) \
  --until $(date '+%Y-%m-01')

結果は次のとおりです。

# Summary

- John Smith: 14.00
- Takeshi Arabiki: 17.00
- Total: 31.00
- Expected total: 31

# Details

- Thu, 2025-05-01 05:00+0900 - Fri, 2025-05-02 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Fri, 2025-05-02 05:00+0900 - Sat, 2025-05-03 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Sat, 2025-05-03 05:00+0900 - Sun, 2025-05-04 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Sun, 2025-05-04 05:00+0900 - Mon, 2025-05-05 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Mon, 2025-05-05 05:00+0900 - Tue, 2025-05-06 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Tue, 2025-05-06 05:00+0900 - Wed, 2025-05-07 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Wed, 2025-05-07 05:00+0900 - Thu, 2025-05-08 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 0.62 (05:00 - 20:00)
        - John Smith: 0.38 (20:00 - 05:00)
- Thu, 2025-05-08 05:00+0900 - Fri, 2025-05-09 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Fri, 2025-05-09 05:00+0900 - Sat, 2025-05-10 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Sat, 2025-05-10 05:00+0900 - Sun, 2025-05-11 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Sun, 2025-05-11 05:00+0900 - Mon, 2025-05-12 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Mon, 2025-05-12 05:00+0900 - Tue, 2025-05-13 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Tue, 2025-05-13 05:00+0900 - Wed, 2025-05-14 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Wed, 2025-05-14 05:00+0900 - Thu, 2025-05-15 05:00+0900
    - Weekly Rotation
        - John Smith: 0.62 (05:00 - 20:00)
        - Takeshi Arabiki: 0.38 (20:00 - 05:00)
- Thu, 2025-05-15 05:00+0900 - Fri, 2025-05-16 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Fri, 2025-05-16 05:00+0900 - Sat, 2025-05-17 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Sat, 2025-05-17 05:00+0900 - Sun, 2025-05-18 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Sun, 2025-05-18 05:00+0900 - Mon, 2025-05-19 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Mon, 2025-05-19 05:00+0900 - Tue, 2025-05-20 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Tue, 2025-05-20 05:00+0900 - Wed, 2025-05-21 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Wed, 2025-05-21 05:00+0900 - Thu, 2025-05-22 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 0.62 (05:00 - 20:00)
        - John Smith: 0.38 (20:00 - 05:00)
- Thu, 2025-05-22 05:00+0900 - Fri, 2025-05-23 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Fri, 2025-05-23 05:00+0900 - Sat, 2025-05-24 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Sat, 2025-05-24 05:00+0900 - Sun, 2025-05-25 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Sun, 2025-05-25 05:00+0900 - Mon, 2025-05-26 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Mon, 2025-05-26 05:00+0900 - Tue, 2025-05-27 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Tue, 2025-05-27 05:00+0900 - Wed, 2025-05-28 05:00+0900
    - Weekly Rotation
        - John Smith: 1.00 (05:00 - 05:00)
- Wed, 2025-05-28 05:00+0900 - Thu, 2025-05-29 05:00+0900
    - Weekly Rotation
        - John Smith: 0.62 (05:00 - 20:00)
        - Takeshi Arabiki: 0.38 (20:00 - 05:00)
- Thu, 2025-05-29 05:00+0900 - Fri, 2025-05-30 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Fri, 2025-05-30 05:00+0900 - Sat, 2025-05-31 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)
- Sat, 2025-05-31 05:00+0900 - Sun, 2025-06-01 05:00+0900
    - Weekly Rotation
        - Takeshi Arabiki: 1.00 (05:00 - 05:00)

# PagerDuty schedules

## Weekly Rotation

- 2025-05-01T05:00:00+09:00 - 2025-05-07T20:00:00+09:00: Takeshi Arabiki
- 2025-05-07T20:00:00+09:00 - 2025-05-14T20:00:00+09:00: John Smith
- 2025-05-14T20:00:00+09:00 - 2025-05-21T20:00:00+09:00: Takeshi Arabiki
- 2025-05-21T20:00:00+09:00 - 2025-05-28T20:00:00+09:00: John Smith
- 2025-05-28T20:00:00+09:00 - 2025-06-01T05:00:00+09:00: Takeshi Arabiki

おわりに

以上、pd-shift の紹介でした。このツールが事務作業の負担軽減に繋がると幸いです。

Kubernetes で sleep infinity しつつ SIGTERM を受け取ったらすぐ終了させたい

Fri, 20 Jun 2025 00:00:00 +0900

Introducing dumb-init, an init system for Docker containers で説明されているように、PID 1 のプロセスは特殊な扱いになるため、そのプロセスにシグナルハンドラーがなければ、シグナルは無視されます。

例えば Docker の場合、次のように --init オプションなしで実行すると、PID 1 のプロセスは sleep になるため、docker stop を実行してもデフォルトタイムアウトの 10 秒が経過して強制終了させられるまで動き続きます。

$ docker run --rm --name sleep -d ubuntu sleep infinity
0fef58eb514808d77dc26edccb2e56b55268425dae2a299c21b23a1b661b1d84
$ time docker stop sleep
sleep
docker stop sleep  0.01s user 0.02s system 0% cpu 10.381 total

--init オプション付きで実行すると、PID 1 は init プロセスになり、SIGTERM を受け取ると子プロセスである sleep に SIGTERM を送り、sleep はカーネルによって殺されるため、即座に終了します。

$ docker run --init --rm --name sleep -d ubuntu sleep infinity
623807fc3bb9f052c1a001c0ee69db2255356ed6edff42af02dd1fdf14a1c905
$ time docker stop sleep
sleep
docker stop sleep  0.01s user 0.01s system 9% cpu 0.245 total

これと同じようなことを Kubernetes でもやりたかったんですが、Support adding an init process to containers という issue が 6 年前に作成されて今も open であることから、おそらく同様の機能が追加されることはないでしょう。

というわけで、shell script を何行も書かずに手軽に実現する方法がないかと考えたところ、そういえば timeout というコマンドがあったなと思い出したわけです。
こいつを使うと次のようにすぐに pod を終了させることができます。

$ kubectl run sleep --restart=Never --image=ubuntu -- timeout infinity sleep infinity
pod/sleep created
$ time kubectl delete pod sleep
pod "sleep" deleted
kubectl delete pod sleep  0.07s user 0.04s system 5% cpu 2.106 total

timeout なしで実行した場合と雲泥の差ですね。

$ kubectl run sleep --restart=Never --image=ubuntu -- sleep infinity
pod/sleep created
$ time kubectl delete pod sleep
pod "sleep" deleted
kubectl delete pod sleep  0.10s user 0.05s system 0% cpu 32.795 total

なお、sh -c などで複数のコマンドを実行する場合は PID 1 が sh になってしまうので、次のように exec を使う必要があります。

$ kubectl run sleep --restart=Never --image=ubuntu -- sh -c 'echo "do something"; exec timeout infinity sleep infinity'
pod/sleep created
$ time kubectl delete pod sleep
pod "sleep" deleted
kubectl delete pod sleep  0.06s user 0.03s system 5% cpu 1.680 total

以上、ちょっとした小ネタでした。

akv:/// 形式の文字列を Azure Key Vault secrets で差し替えるツールを作った

Mon, 06 Jan 2025 00:00:00 +0900

akv というツールを作りました。次のように標準入力に含まれる akv://<vault-name>/<secret-name> 形式の文字列や、同形式の環境変数を Azure Key Vault secret（AWS だと parameter store に相当）の値で差し替えることができます。

$ az keyvault secret set --vault-name example --name password --value 'C@6LWQnuKDjQYHNE'
$ echo 'password: akv://example/password' | akv inject
password: C@6LWQnuKDjQYHNE
$ env PASSWORD=akv://example/password akv exec -- printenv PASSWORD
C@6LWQnuKDjQYHNE

inject subcommand は 1Password CLI の inject subcommand みたいなもので、exec subcommand は berglas の exec subcommand が begras:// や sm:// で始まる環境変数を差し替えたり、1Password CLI の run subcommand が op:// で始まる環境変数を差し替えるのと同じような感じです。

背景

Argo Workflows の events API では、GitHub の webhook のように Authorization ヘッダをリクエストに含めることができないケースのための仕組みがあります。
cf. Webhooks - Argo Workflows - The workflow engine for Kubernetes

これは、予め argo-workflows-webhook-clients という名前で service account ごとに type, secret 情報を Secret オブジェクトに保存しておけば、Authorization ヘッダがないリクエストを受け取った場合にそれらの情報を使ってリクエストの signature を検証し、検証に成功した service account の token を Authorization ヘッダに付与してくれるというものです。
cf. addWebhookAuthorization

なので、Kubernetes manifest で Secret オブジェクトを管理しつつ、webhook secret の値は manifest を見ただけではわからない形にしたいという思いがありました。
次の記事ややり取りを見ても色んな人が Secret オブジェクトの管理には頭を悩ませている印象です。

どちらでも言及されている external-secrets や sealed-secrets が広く使われてそうですが、今回は手軽に実現したかったのでどちらも大仰に感じました。
また、秘匿情報の管理は Azure Key Vault secrets に集約したいという思いもありました。Azure Kubernetes Service では Azure Key Vault secrets を CSI volume として利用できるんですが、前述のとおり events API で利用するには Secret オブジェクトでなければいけません。¹

というわけで、akv://<vault-name>/<secret-name> といった形式の文字列を Azure Key Vault secret の値で差し替えるツールを作って、Kustomize の exec KRM function から利用するのが手軽と考えました。
Kustomize のプラグイン機能はアルファのまま何年も進展がないのが気になるところではありますが…

Kustomize の exec KRM function による secret の差し替え

exec KRM function の詳細についてはドキュメントに譲りますが、最低限次のようなファイルが必要です。ファイル名は kustomization.yaml 以外は好きな名前で大丈夫です。

$ tree .
.
├── key-vault-secrets.yaml
├── kustomization.yaml
├── plugins
│   └── inject-key-vault-secrets.sh
└── secret.yaml

2 directories, 4 files

それぞれのファイルの内容は以下のとおりで、secret.yaml が差し替え対象の Secret オブジェクト、key-vault-secrets.yaml が KRM function の定義です。

resources:
- secret.yaml

transformers:
- key-vault-secrets.yaml

apiVersion: v1
kind: Secret
metadata:
  name: some-secret
stringData:
  # This secret is replaced by KeyVaultSecretsTransformer
  password: akv://example/password

apiVersion: abicky.net/v1alpha1 # どんな値でも OK
kind: KeyVaultSecretsTransformer # どんな値でも OK
metadata:
  name: key-vault-secrets # どんな値でも OK
  annotations:
    config.kubernetes.io/function: |
      exec:
        # kustomization.yaml からの相対パス
        path: ./plugins/inject-key-vault-secrets.sh

#!/bin/bash
akv inject --quote

このディレクトリに対して --enable-alpha-plugins --enable-exec オプションを付けて実行すると secret の内容が差し替わります。

$ kustomize build --enable-alpha-plugins --enable-exec .
apiVersion: v1
kind: Secret
metadata:
  name: some-secret
stringData:
  password: C@6LWQnuKDjQYHNE

なお、akv inject に --quote オプションを付けているのは secret に改行が含まれるケースのためです。例えば SSH の private key を Secret オブジェクトで管理するケースが当てはまります。²

もし --quote オプションがないと、YAML が壊れてしまうので次のようなエラーになります。

$ kustomize build --enable-alpha-plugins --enable-exec .
Error: couldn't execute function: MalformedYAMLError: yaml: line 20: could not find expected ':'

既にダブルクォートで囲まれているケースのために --escape オプションもあるんですが、仮に次のように Secret オブジェクトの定義の方でダブルクォートで囲っていたとしても Kustomize が不要なダブルクォートとみなして KRM function を実行するまでに取り除いてしまうので、Kustomize で利用する際には --quote オプションにする必要があります。

apiVersion: v1
kind: Secret
metadata:
  name: some-secret
stringData:
  password: "akv://example/password"

2024-01-13 追記: SecretProviderClass の定義に secretObjects を指定すれば、volume を mount する際に Secret オブジェクトを作成することができるので、それで対応できるケースもありそうです cf. Sync mounted content with a Kubernetes secret ↩
Argo Workflows の git artifact で GitHub App の private key から token を生成して checkout できると良いんですが、現状は artifact を利用せずに自前で checkout するか、deploy key または machine user の private key を使うしかなさそうです cf. Git artifact using GitHub App Credentials · argoproj/argo-workflows · Discussion #11028 ↩

前方互換性・後方互換性とは何なのか？〜Schema Registry における例〜

Sun, 28 Jan 2024 00:00:00 +0900

Schema evolution において前方互換性・後方互換性を意識することは重要ですが、どっちがどっちか混乱することがあるのでメモとして残しておきます。

一般的な説明

Wikipedia の互換性の説明がとても簡潔に表現されていると思うので引用します。

前方互換性（英語: Forward compatibility）

新しいシステム向けのデータなどが古いシステムでも使用できること1。

後方互換性（英語: Backward compatibility）

古いシステム向けのデータなどが新しいシステムでも全て使用できること2。

前方互換性の例として、よく白黒テレビがカラーテレビ放送を受信して白黒で表示できることが挙げられますが、ポイントとしては、前方互換性を考慮して白黒テレビが作られているわけではなく、前方互換性を考慮してカラーテレビ放送規格 (NTSC) が定められていることです。初めて「前方互換性」という言葉を知った時は「将来のカラーテレビ放送規格のことも見据えて白黒テレビを作るのは無理では？」と思ったものです。
一方、後方互換性に関してもテレビを例にすると、カラーテレビが白黒テレビ放送を受信して白黒で表示できることが挙げられ、この場合は後方互換性を考慮してカラーテレビを作ることになるのかなと思います。

このように、前方互換性を保つために工夫しなければいけないのはデータで、後方互換性を保つために工夫しなければいけないのはシステムであることが個人的に混乱する理由でした。

Schema Registry における例

Kafka のデータの schema を管理するのに Schema Registry というミドルウェアがあり、schema のバージョン管理ができます。
新しい schema バージョンを登録する際の制約として compatibility を設定することができ、それぞれの compatibility に対してどのような schema の変更が許容され、どのようなオペレーションが必要かが定められています。例えば BACKWARD（1 つ前のバージョンとの後方互換性）、FORWARD（1 つ前のバージョンとの前方互換性）は次のようになっています。

Compatibility Type	Changes allowed	Check against which schemas	Upgrade first
BACKWARD	Delete fields Add optional fields	Last version	Consumers
FORWARD	Add fields Delete optional fields	Last version	Producers

cf. https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html#summary

“Delete fields” は optional fields も required fields も削除でき、”Add fields” は optional fields も required fields も削除できます。

BACKWARD

後方互換性とは「古いシステム向けのデータなどが新しいシステムでも全て使用できること」でした。Kafka の文脈において、古いシステム向けのデータとは、古い schema で生成されたデータで、データを処理する「新しいシステム」とは consumer です。全く新しい consumer の追加かもしれませんし、consumer のバージョンアップかもしれません。
つまり、新しい実装の cosumer が 1 つ前の schema バージョンで生成されたデータも最新バージョンで生成されたデータも処理できる必要があるのがこの設定です。

最新の schema バージョンで追加されたフィールドが必ず存在する前提で consumer が実装されていた場合、1 つ前の schema バージョンで生成されたデータは処理できません。よって、フィールドの追加に関してはオプショナルなフィールドしか追加できません。
一方で、最新バージョンで削除されるフィールドがあるなら、それに依存しないように consumer を実装すれば良いので、フィールドの削除に関する条件は存在しません。ただし、現行の consumer が削除されるフィールドに依存していると問題になるので、新しい schema のデータが生成される前に consumer を更新しなければいけません。Upgrade first の項目が Consumers になっているのはこれが理由です。オプショナルなフィールドの追加であれば consumer から更新しても producer から更新しても大丈夫です。

なお、Avro においてオプショナルなフィールドというのは default 属性を持ったフィールドであり、値が nullable なフィールドではありません。例えば、int のオプショナルなフィールドを default 0 で追加した場合、consumer は古い schema バージョンで生成されたデータを読み込む際に 0 という値がセットされているものとして処理します。

FORWARD

前方互換性とは「新しいシステム向けのデータなどが古いシステムでも使用できること」でした。Kafka の文脈において、新しいシステム向けのデータとは、新しい schema で生成されたデータで、データを処理する「古いシステム」とは既に存在する consumer であり、consumer に変更を加えないことを意味します。
つまり、新しい schema バージョンで生成されたデータであっても既存の consumer が意図した処理を行える必要があるのがこの設定です。

最新のバージョンで何かしらのフィールドが追加されたとしても、古い consumer はそれを無視すれば良いだけなので、フィールドは自由に追加できます。一方で、古い consumer が利用しているフィールドが削除されると問題が発生するので、オプショナルなフィールドしか削除できません。なお、オプショナルなフィールドだとしても実は特定のオプション機能を提供するには必要なフィールドである可能性があるため、オプショナルなフィールドの削除は「consumer が正しく実装されていれば削除してもエラーが起きないことが期待される」ぐらいの意味になるかと思います。

新しいフィールドを追加するということは、そのフィールドに依存した consumer を追加・修正するケースでしょうから、そのフィールドが追加されたデータを処理することを保証するため Upgrade first の項目は Producers になっています。
ただし、producer を先に更新しても、consumer の commit offset が古過ぎると古い schema のデータを処理してしまうかもしれないので注意が必要です。

型の変更はどう解釈されるか？

後述する WikipediaFeedAvroLambdaExample で利用されるデータの schema を見てみます。

$ curl -s localhost:8081/subjects/WikipediaFeed-value/versions/latest/schema | jq .
{
  "type": "record",
  "name": "WikiFeed",
  "namespace": "io.confluent.examples.streams.avro",
  "fields": [
    {
      "name": "user",
      "type": {
        "type": "string",
        "avro.java.string": "String"
      }
    },
    {
      "name": "is_new",
      "type": "boolean"
    },
    {
      "name": "content",
      "type": [
        {
          "type": "string",
          "avro.java.string": "String"
        },
        "null"
      ]
    }
  ]
}

compatibility は BACKWARD です。

$ curl -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/config/WikipediaFeed-value -w "\n"
{"error_code":40401,"message":"Subject 'WikipediaFeed-value' not found."}
$ curl -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/config -w "\n"
{"compatibilityLevel":"BACKWARD"}

例えば user を string または int の union type の場合に compatibility を満たすか確認してみます。

$ cat <<JSON | curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/compatibility/subjects/WikipediaFeed-value/versions/latest -d @- -w "\n"
{
  "schema": "{
    \"namespace\": \"io.confluent.examples.streams.avro\",
    \"type\": \"record\",
    \"name\": \"WikiFeed\",
    \"fields\":[
      {\"name\": \"user\", \"type\": [\"string\", \"int\"]},
      {\"name\": \"is_new\", \"type\": \"boolean\"},
      {\"name\": \"content\", \"type\": [\"string\", \"null\"]}
    ]
  }"
}
JSON
{"is_compatible":true}

backward compatible みたいです。古い schema のデータであれば user は string であり、新しい schema のデータであれば string か int なので、新しい consumer は string と int 両方の user を処理することが想定されていると考えられるので新旧両方の schema のデータに対応していると言えます。よって後方互換性の条件を満たしていると言えるでしょう。

compatibility を forward にした上で再度確認します。

$ curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/config/WikipediaFeed-value -d '{"compatibility":"FORWARD"}' -w "\n"
{"compatibility":"FORWARD"}
$ cat <<JSON | curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/compatibility/subjects/WikipediaFeed-value/versions/latest -d @- -w "\n"
{
  "schema": "{
    \"namespace\": \"io.confluent.examples.streams.avro\",
    \"type\": \"record\",
    \"name\": \"WikiFeed\",
    \"fields\":[
      {\"name\": \"user\", \"type\": [\"string\", \"int\"]},
      {\"name\": \"is_new\", \"type\": \"boolean\"},
      {\"name\": \"content\", \"type\": [\"string\", \"null\"]}
    ]
  }"
}
JSON
{"is_compatible":false}

forward compatible ではないと判定されました。古い consumer では int の user を処理できないので当然でしょう。

では、user を int に変更するとどうなるか確認してみます。

$ curl -X DELETE -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/config/WikipediaFeed-value -w "\n"
{"compatibilityLevel":"FORWARD"}
$ cat <<JSON | curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" localhost:8081/compatibility/subjects/WikipediaFeed-value/versions/latest -d @- -w "\n"
{
  "schema": "{
    \"namespace\": \"io.confluent.examples.streams.avro\",
    \"type\": \"record\",
    \"name\": \"WikiFeed\",
    \"fields\":[
      {\"name\": \"user\", \"type\": \"int\"},
      {\"name\": \"is_new\", \"type\": \"boolean\"},
      {\"name\": \"content\", \"type\": [\"string\", \"null\"]}
    ]
  }"
}
JSON

backward compatible ではないと判定されました。string から string, int の union type への変更だと backward compatible でしたが、int への変更だと backward compatible ではないようです。これは新しい consumer が string の user ではなく int の user に依存しているとみなされるからでしょう。古い schema のデータは string の user なので処理できません。よって後方互換性の定義を満たしません。

このように、type の変更はどのような type に変更するかで結果が変わるのが compatibility を理解する上で難しいところです。

おまけ〜Kafka Streams アプリケーションでデータの Schema が変わった時の挙動を確認する〜

Kafka Streams アプリケーションでデータの schema が変わった時の挙動をサクッと確認したい場合、kafka-streams-examples の WikipediaFeedAvroLambdaExample を動かしてみるのが手軽です。

最初に次のようなコマンドで必要なトピックを作成します。

kafka-topics --create --topic WikipediaFeed --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
kafka-topics --create --topic WikipediaStats --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1

次に、jar ファイルを作成します。

./mvnw -Dmaven.test.skip=true package

IDE で気になる処理にブレークポイントを設定した上で、次コマンドで WikipediaFeed にデータを投入すればデバッグし放題です。

java -cp target/kafka-streams-examples-7.5.3-standalone.jar io.confluent.examples.streams.WikipediaFeedAvroExampleDriver

WikipediaFeedAvroExampleDriver は schema registry でエラーになっていると stuck するので、WikipediaFeedAvroLambdaExample を動かしているのに何も出力されない場合は schema registry のログを確認してみると良いです。

Java のような静的型付き言語でどのようにデータから特定のクラスのインスタンスを生成しているかというと、SpecificData#newRecord で Avro schema の情報からクラスを特定してインスタンスを生成し、SpecificRecordBase#put でフィールドをセットするみたいですね。

WikipediaFeed だと #put は次のような定義になっています。

// Used by DatumReader.  Applications should not call.
@SuppressWarnings(value="unchecked")
public void put(int field$, java.lang.Object value$) {
  switch (field$) {
  case 0: user = value$ != null ? value$.toString() : null; break;
  case 1: is_new = (java.lang.Boolean)value$; break;
  case 2: content = value$ != null ? value$.toString() : null; break;
  default: throw new IndexOutOfBoundsException("Invalid index: " + field$);
  }
}

上記の実装を見ると、フィールドの順番が変わるとまずいように見えますが、SpecificDatumReader で consumer の保持している schema 情報を使ってよしなに処理するようにしているみたいです。

DataGrip などの JetBrains 製 IDE から IAM データベース認証を使って RDS インスタンスに接続する

Sun, 17 Sep 2023 00:00:00 +0900

今までデータベースにアクセスする際には GUI ツールとして Sequel Ace を使っていたんですが、諸事情から IAM データベース認証に対応したツールを利用する必要が出てきました。残念ながら Sequel Ace は IAM データベース認証に対応していません。
cf. Cannot connect to AWS RDS using IAM Authentication · Issue #202 · Sequel-Ace/Sequel-Ace

そこで、代替手段として RubyMine、DataGrip 等 JetBrains 製の IDE を使おうとしたんですが、~/.aws/credentials にクレデンシャルを保存していない自分の使い方だと一苦労したので、接続方法についてまとめてみました。

IAM データベース認証とは？

詳細は IAM database authentication for MariaDB, MySQL, and PostgreSQL に譲るとして、物凄くざっくり説明すると、パスワードとして AWS SDK で発行した token を使ってデータベースに接続する方法です。
データベースに作成するユーザは認証方式以外は通常のユーザと同じですが、パスワードとして利用する token は IAM ユーザに紐付いているので、接続可否を IAM に任せることができます。

なお、token の有効期限は 15 分ですが、ドキュメントで次のように述べられているとおり、一度コネクションを確立すれば token の期限が切れてもクエリを投げることができるようです。

The token is only used for authentication and doesn’t affect the session after it is established.

Recommendations for IAM database authentication でも言及されていますが、アプリケーションで利用する際には次の点を特に気を付けた方が良さそうです。

秒間 200 コネクションが確立される場合は利用すべきじゃない
- ドキュメントからは token を生成するための API の rate limit の都合と読めるので、コネクションの確立数が多い場合は rate limit が IAM ユーザ単位なのかリージョン単位なのか AWS アカウント単位なのか検証した方が良さそう（Quotas and constraints for Amazon RDS には言及がない）
アプリケーション起動時に token を生成するだけだと、15 分経った後に何かしらの理由で新しいコネクションを作成しようとしても失敗する
- 認証に失敗した場合に再度 token を生成して接続を試みるような処理が必要

検証環境

次のような環境を用意して検証しました

データベースエンジンは Amazon Aurora MySQL 3.04.0
IAM データベース認証用のユーザ名は iam_db_auth_test
データベースクラスタの識別子は iam-db-auth-example-rds
データベースには VPC 内からしかアクセスできない
VPC 内に踏み台用の EC2 インスタンスがある

「おまけ」に上記の環境を構築するのに使った tf ファイルを載せているので、検証環境を構築したい方はそちらを参照してください。

IAM データベース認証を実現する 3 つの方法

調べた限り、次の 3 つの方法がありました。

AWS Toolkit Plugin を使う方法
AWS 製の JDBC Driver を使う方法
MysqlClearPasswordPlugin を使う方法

以下、それぞれについて説明していきます。

AWS Toolkit Plugin を使う方法

~/.aws/credentials でクレデンシャルを管理している人にとって最も簡単な方法です。

基本的には Connecting to an Amazon RDS database に従って設定すれば接続できると思います。JetBrains DataGrip でのみ利用できるような書きっぷりですが、Database Tools and SQL plugin がプリインストールされている IntelliJ IDEA Ultimate, RubyMine 等でも同様に設定できたので、おそらく IntelliJ IDEA Community Edition を除く全ての JetBrains 製 IDE で同様に接続できます。

もし IAM ユーザがデータベースに接続するための権限しかない場合、ドキュメントの手順では設定できないので、手動で設定する必要あります。
まず、Database ツールウィンドウから Driver and Data Source を選択します。

AWS Toolkit plugin をインストールすると、下図のように Data Sources and Drivers で Data Source を追加する際に Authentication で AWS IAM を選択できるようになります。

User にはデータベースユーザの名前を入力するので、今回は iam_db_auth_test になります。
また、AWS IAM を選択すると Credentials に profile を指定する必要があるので、IAM データベース認証で使う IAM ユーザのクレデンシャルを管理している profile を指定すれば良いです。ここでは iam-db-auth-test という profile を指定しています。

なお、~/.aws/credentials が存在しなければ、たとえ環境変数に AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY がセットされていても登録できません。

IAM データベース認証を利用する場合は TLS を有効にする必要があるのと、今回はデータベースにアクセスするには踏み台を経由しなければいけないので、次のように SSH/SSL の設定も必要です。

SSH configuration に指定している設定は次のとおりで、Host には踏み台サーバの public IP を指定しています。

SSH tunnel の設定をすると、IDE の方でよしなに接続先をローカルホストに変更してくれるようで、General の項目は一切変更する必要がありません。

CA file を指定しなければいけないケースがあるようですが、自分の環境では不要でした。必要な場合は Using SSL/TLS to encrypt a connection to a DB instance の手順に従って CA file をダウンロードした上で指定する必要があります。

AWS 製の JDBC Driver を使う方法

MySQL に使える IAM データベース認証に対応した JDBC driver として、AWS は次の 2 つの driver を提供しています。

データベースに直接アクセスできる場合はどちらも使えると思われますが、踏み台を経由する場合のように、JDBC driver の実際の接続先と RDS ホストが異なる場合はおそらく後者しか使えないので、ここでは後者を利用する方法について説明します。

aws-advanced-jdbc-wrapper は様々な機能を plugin として提供しており、 IAM データベース認証機能も plugin の 1 つです。plugin の使い方については AWS IAM Authentication Plugin に書いてあるので、IDE で利用する際もこれに従って設定します。

JetBrains 製の IDE でカスタム driver を利用するには、Data Sources and Drivers の Drivers タブで + ボタンを押して driver を追加します。Driver Files には custom driver の含まれた jar や、その jar が依存している jar を登録します。

これが少し厄介で、aws-advanced-jdbc-wrapper を含めた一般的な JDBC driver は DriverManager が ServiceLoader を使ってクラスパスに存在する driver を全てロードするようになっているようなんですが（この辺あまり詳しくない）、JetBrains 製の IDE ではロードするクラスを 1 つだけ明示的に指定する必要があるようで、aws-advanced-jdbc-wrapper が提供している driver である software.amazon.jdbc.Driver を指定すると、MySQL driver である com.mysql.cj.jdbc.Driver 等、他の driver がロードされません。また、IAM データベース認証を利用するためには token を発行するために AWS Java SDK RDS v2.x や、それが依存しているパッケージまで必要ですが、それらの jar をダウンロードして適当な位置に配置するのは少し手間です。

そこで、software.amazon.jdbc.Driver がロードされると com.mysql.cj.jdbc.Driver もロードされるように改造した上で、依存するパッケージが全て含まれた fat jar を作成するようにしました。

cf. https://github.com/abicky/aws-advanced-jdbc-wrapper/commit/f7f34fdd0b494025d2e59c10d9938d98993a0de5

fat jar は aws-advanced-jdbc-wrapper-2.2.5-SNAPSHOT-all.jar からダウンロードできるようにしてあります。

URL templates には他の driver を参考に次の値を入れました。

jdbc:aws-wrapper:mysql://{host::localhost}?[:{port::3306}][/{database}?][\?<&,user={user},password={password},{:identifier}={:param}>]

また、Options タブで Dialect に MySQL を指定しておくと、MySQL driver を使った他の data source でも利用可能になります。

最後に、プロパティの wrapperPlugins を iam に、iamDefaultPort をデータベースサーバのポート番号に設定してカスタム driver の登録は完了です。

iamDefaultPort はデータベースサーバのポート番号で、踏み台を利用する場合は設定が必要です。というのも、踏み台を利用すると IDE が裏側で data source の URL を書き換えるため、aws-advanced-jdbc-wrapper がその URL をパースして得たポート番号を使って token を生成しても認証に失敗するからです。iamDefaultPort を設定することで、このポート番号を使って token を生成するようになります。

新しく登録したカスタム driver を使うには、data source の Driver を変更します。IAM データベース認証はパスワード認証と同じように利用可能なので、Authentication は User & Password にします。ここで入力した Password は利用されないので、空文字列を入力して Save: Forever にすると良いです。

SSH/SSL の設定は「AWS Toolkit Plugin を使う方法」と同様です。

Advanced タブでは iamHost を設定します。理由は iamDefaultPort と同様で、指定しないと localhost 用の token を発行しようとしてエラーになります。

最後に、IAM ユーザのクレデンシャルを渡す方法ですが、ローカル開発環境で ~/.aws/credentials を利用していない場合は環境変数で渡すことになります。
Advanced タブの VM environment で渡すこともできますが、僕の場合は DataGrip を起動する際に渡しています。普段 envchain を使って環境変数を管理しているんですが、例えば aws という namespace に AWS 関係のクレデンシャルが保存されている場合、macOS では次のコマンドで起動すると IAM ユーザのクレデンシャルが環境変数として引き継がれます。

envchain aws open -a DataGrip

上記のやり方の注意点として、もしアプリケーションの起動時に利用した IAM ユーザが AWS の様々なリソースを操作できる強力な権限を持っている場合、IDE 上で AWS にアクセスするスクリプトなどを実行した時に意図せず本番環境に影響を与える可能性があります。データベースにアクセスするだけの権限を持った IAM ユーザを使うか、データベースへのアクセス以外の用途で IDE を使わないようにした方が良いでしょう。

MysqlClearPasswordPlugin を使う方法

DataGrip でクリアテキスト認証を使う #DataGrip - ジムには乗りたいに書いてあるとおりです。
ただ、今回の検証環境だと Advanced タブの項目を修正する必要はなく、パスワードの欄に aws rds generate-db-auth-token で生成した token を入力するだけで大丈夫でした。

初めて IAM データベース認証を利用して接続した時には必要な設定だった気がするので、Aurora のバージョンや driver のバージョンの組み合わせによっては不要なのかもしれません。

設定は「AWS 製の JDBC Driver を使う方法」に比べて簡単であり、誤って AWS リソースを操作してしまうリスクもないですが、頻繁に複数のデータベースにアクセスしては接続を切る必要がある場合は割りと手間に感じるかもしれません。

おまけ〜検証環境の構築〜

今回は次の tf ファイルを使って検証環境を構築しました。

provider "aws" {
  region = var.aws_region
}

variable "aws_region" {
  default = "ap-northeast-1"
}

variable "db_username" {
  default = "iam_db_auth_test"
}


locals {
  name_prefix = "iam-db-auth-example-"
}

resource "random_string" "password" {
  length           = 16
  override_special = "!#$%&*()-_=+[]{}<>:?"
}

resource "aws_rds_cluster" "default" {
  cluster_identifier     = "${local.name_prefix}rds"
  engine                 = "aurora-mysql"
  engine_version         = "8.0.mysql_aurora.3.04.0"
  master_username        = "admin"
  master_password        = random_string.password.result
  skip_final_snapshot    = true
  vpc_security_group_ids = [aws_security_group.rds.id]

  iam_database_authentication_enabled = true
}

resource "aws_rds_cluster_instance" "default" {
  count = 2

  identifier         = "${local.name_prefix}rds-${count.index}"
  cluster_identifier = aws_rds_cluster.default.id
  instance_class     = "db.t4g.medium"
  engine             = aws_rds_cluster.default.engine
  engine_version     = aws_rds_cluster.default.engine_version
}

resource "aws_security_group" "rds" {
  name = "${local.name_prefix}rds"
}

variable "key_name" {}

data "aws_availability_zones" "available" {
  state = "available"
}

data "aws_subnet" "default" {
  default_for_az    = true
  availability_zone = data.aws_availability_zones.available.names[0]
}

data "aws_ami" "most_recent_amazon_linux_2023" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["al2023-ami-2023*-arm64"]
  }
}


resource "aws_security_group" "ec2" {
  name = "${local.name_prefix}ec2"
}

resource "aws_security_group_rule" "ec2_ingress" {
  security_group_id = aws_security_group.ec2.id
  type              = "ingress"
  from_port         = 22
  to_port           = 22
  protocol          = "tcp"
  cidr_blocks       = ["0.0.0.0/0"]
}

resource "aws_security_group_rule" "ec2_egress" {
  security_group_id = aws_security_group.ec2.id
  type              = "egress"
  from_port         = 0
  to_port           = 0
  protocol          = "-1"
  cidr_blocks       = ["0.0.0.0/0"]
}

resource "aws_security_group_rule" "rds_ingress" {
  security_group_id = aws_security_group.rds.id
  type              = "ingress"
  from_port         = 3306
  to_port           = 3306
  protocol          = "tcp"

  source_security_group_id = aws_security_group.ec2.id
}

resource "aws_security_group_rule" "rds_egress" {
  security_group_id = aws_security_group.rds.id
  type              = "egress"
  from_port         = 0
  to_port           = 0
  protocol          = "-1"

  source_security_group_id = aws_security_group.ec2.id
}

resource "aws_instance" "bastion" {
  ami           = data.aws_ami.most_recent_amazon_linux_2023.image_id
  instance_type = "t4g.nano"
  key_name      = var.key_name

  #subnet_id              = aws_subnet.subnet_az1.id
  vpc_security_group_ids = [aws_security_group.ec2.id]

  associate_public_ip_address = true
}

resource "aws_iam_user" "test" {
  name = "${local.name_prefix}test"
}

resource "aws_iam_access_key" "test" {
  user = aws_iam_user.test.name
}

data "aws_caller_identity" "current" {}

resource "aws_iam_user_policy" "test" {
  name = "iam-db-auth"
  user = aws_iam_user.test.name

  policy = <<-JSON
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "rds-db:connect"
        ],
        "Resource": [
          "arn:aws:rds-db:${var.aws_region}:${data.aws_caller_identity.current.account_id}:dbuser:${aws_rds_cluster.default.cluster_resource_id}/${var.db_username}"
        ]
      }
   ]
  }
  JSON
}

output "ami_id" {
  value = aws_instance.bastion.ami
}

output "bastion_public_ip" {
  value = aws_instance.bastion.public_ip
}

output "rds_endpoint" {
  value = aws_rds_cluster.default.endpoint
}

output "rds_reader_endpoint" {
  value = aws_rds_cluster.default.reader_endpoint
}

output "rds_password" {
  value     = aws_rds_cluster.default.master_password
  sensitive = true
}

output "aws_access_key_id" {
  value = aws_iam_access_key.test.id
}

output "aws_secret_access_key" {
  value     = aws_iam_access_key.test.secret
  sensitive = true
}

aws_secret_access_key, rds_password の値は terraform apply や terraform output だと <sensitive> という表示になりますが、terraform output --json だと実際の値を確認することができます。

値を確認したら、踏み台にポートフォワーディングをします。

ssh -fNL \
  13306:iam-db-auth-example-rds.cluster-xxxxxxxxxxxx.ap-northeast-1.rds.amazonaws.com:3306 \
  <bastion_public_ip> \
  -l ec2-user \
  -i /path/to/key

ポートフォワーディングしたら、そのポートに対して admin ユーザでアクセスします。パスワードは rds_password の値を入力します。

mysql -u admin -h 127.0.0.1 -P 13306 -p

データベースに接続できたら、次のクエリを実行することで IAM データベース認証で接続できるユーザが作成されます。

CREATE USER iam_db_auth_test IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS' REQUIRE SSL;

もし作成したユーザに強力な権限を付与したい場合は次のようにして権限を付与します（どういうわけか *.* だと Access denied になります）

GRANT ALL ON `%`.* TO iam_db_auth_test;

IAM ユーザのプロファイル名が iam-db-auth-test の場合、次のコマンドで接続可否を確認できます。

token=$(aws rds generate-db-auth-token \
  --profile iam-db-auth-test \
  --hostname iam-db-auth-example-rds.cluster-ro-cv0e2etijwco.ap-northeast-1.rds.amazonaws.com \
  --port 3306 \
  --username iam_db_auth_test)

mysql \
  --protocol tcp \
  -u iam_db_auth_test \
  -h 127.0.0.1 \
  -P 13306 \
  -p${token} \
  --enable-cleartext-plugin

Ruby で SOCKS Proxy を利用する

Wed, 30 Aug 2023 00:00:00 +0900

ローカル環境から直接アクセスできない Web ページにアクセスするために、そのページにアクセスできるサーバに SSH dynamic port forwarding をして、ブラウザに SOSCKS proxy の設定することでアクセスするのはよくある話だと思います。
例えば Amazon EMR で各種 Web UI にアクセスするための方法として、SSH dynamic port forwarding を使った方法が次のドキュメントで紹介されています。

Option 2, part 1: Set up an SSH tunnel to the primary node using dynamic port forwarding - Amazon EMR

ブラウザで SOCKS proxy を利用する際にはブラウザでプロキシの設定をする必要があったわけですが、Ruby で SOCKS proxy を利用するにはどうしたら良いのでしょう？
というわけで、RFC 1928 や既存ソフトウェアを見つつ socks_handler という gem を作ったので、SOCKS についての簡単な解説と gem の紹介をしていきます。

そもそも SOCKS Proxy とは何か？

SOCKS とは RFC 1928 で定められているプロトコルで、SOCKS proxy はそのプロトコルを扱えるサーバです。
プロキシといえば HTTP プロキシが有名ですが、HTTP プロキシは HTTP しか扱えないのに対して、SOCKS プロキシは HTTP を含めた任意の TCP 通信に加え、UDP 通信も扱えます。

SOCKS proxy としては SSH dynamic port forwarding が最も有名じゃないかと思いますが、次のように -D オプションに SOCKS proxy サーバが listen するポート番号を指定して、SSH サーバにログインすると、SOCKS proxy として localhost:1080 を利用した通信は SSH サーバ経由で通信することができます。

$ ssh -D 1080 <ssh-server>

localhost:1080 に SOCKS proxy が立っている場合、curl では次のように --proxy オプションに socks5h://localhost:1080 を指定することで SOCKS proxy 経由で通信できます。

$ curl --proxy socks5h://localhost:1080 -I http://nginx
HTTP/1.1 200 OK
Server: nginx/1.25.1
Date: Wed, 30 Aug 2023 13:30:17 GMT
Content-Type: text/html
Content-Length: 615
Last-Modified: Tue, 13 Jun 2023 15:08:10 GMT
Connection: keep-alive
ETag: "6488865a-267"
Accept-Ranges: bytes

上記の例では http://nginx に対して SOCKS proxy 経由で HTTP リクエストを送っています。nginx というホスト名は SOCKS proxy が解決できる名前であれば、curl を実行する環境で名前解決できなくても問題ありません。例えば AWS VPC 内に SSH サーバがあれば、AWS VPC 外の環境から AWS VPC 内の private DNS name を使って HTTP リクエストを送ることも可能ということです。

なお、RFC は SOCKS versoin 5 についての仕様で、その前身である version 4 も存在しますが、version 4 の説明は割愛します。

SOCKS Proxy を利用するには何が必要か？

SOCKS proxy が必要なのは言うまでもないですが、proxy を利用するアプリケーション側でも SOCKS プロトコルを使って proxy サーバと通信する必要があります。
TCP 通信に関しては接続を確立するまでにちょっとした手順を踏めば、その後は通常の TCP 通信と同様に処理できます。UDP 通信に関してはリクエストを送る度にリモートホストの情報を追加したり、レスポンスから余計な情報を取り除いたりする必要があります。

詳細は RFC 1928 に譲りますが、RFC 自体シンプルな内容なので、動作確認できる環境と、自分の慣れた言語で書かれた既存コードがあればすんなり理解できると思います。
動作確認環境についてはこの後言及します。

socks_handler gem の紹介

前置きが長くなりましたがようやく gem の紹介です。使い方については README を読んでもらえば十分だとは思いますが、ちょっと補足します。動作確認には dokcer-compose.yml が使えて、docker compose up すると次のような構成でコンテナが起動します。

sockd-auth-none: 認証なしの SOCKS server（1080 番ポート）
- Docker host の 1080 番ポートでアクセス可能
sockd-auth-username-password: username/password 認証ありの SOCKS server（1080 番ポート）
- Docker host の 1081 番ポートでアクセス可能
- username: user, passsword: pass というユーザーが作成されている
nginx: HTTP サーバ（80 番ポート）
- Docker host からは直接アクセス不可だが、SOCKS server 経由でアクセス可能
echo: UDP echo サーバ（7 番ポート）
- Docker host からは直接アクセス不可だが、SOCKS server 経由でアクセス可能

以降、上記の構成を前提として説明します。

TCP 通信で SOCKS Proxy を利用する

例えば nginx にアクセスするには次のような手順を踏みます

SOCKS server との接続を確立
SOCKS server と SOCKS5 プロトコルでやり取りして nginx との接続を確立
通常の TCP socket と同じように操作

上記の手順を行っているのが README に載っている最初のサンプルコードです

require "socks_handler"

# 1. SOCKS server との接続を確立
socket = TCPSocket.new("127.0.0.1", 1080)
# 2. SOCKS server と SOCKS5 プロトコルでやり取りして nginx との接続を確立
SocksHandler::TCP.establish_connection(socket, "nginx", 80)

# 3. 通常の TCP socket と同じように操作
socket.write(<<~REQUEST.gsub("\n", "\r\n"))
  HEAD / HTTP/1.1
  Host: nginx

REQUEST
puts socket.gets #=> HTTP/1.1 200 OK

これでめでたく SOCKS proxy を利用できますね！

…とはいきませんよね。
普段の開発で直接 TCP socket を作成するような人は稀だと思うので、正直上記の手順を踏む必要があるのは使えないも同然です。

というわけで、次のように書けば、TCPSocket と Socket にモンキーパッチが適用されるので、おそらく Ruby レイヤーで作成する TCP socket は全て SOCKS proxy を経由させることができます。

require "net/http"
require "socks_handler"

SocksHandler::TCP.socksify([
  # 最初に host_patterns にマッチしたルールが適用される
  SocksHandler::DirectAccessRule.new(
    host_patterns: ["localhost", "127.0.0.1", "::1"],
  ),
  # // は全ての文字列にマッチする正規表現
  SocksHandler::ProxyAccessRule.new(
    host_patterns: [//],
    socks_server: "127.0.0.1:1080",
  ),
])

Net::HTTP.start("nginx", 80) do |http|
  pp http.head("/") #=> #<Net::HTTPOK 200 OK readbody=true>
end

nginx だけ SOCKS proxy を経由したい場合は次のように ProxyAccessRule を 1 つ指定すれば良いです。

require "net/http"
require "socks_handler"

SocksHandler::TCP.socksify([
  # host_patterns にマッチするルールがなければ直接アクセスになる
  SocksHandler::ProxyAccessRule.new(
    host_patterns: ["nginx"],
    socks_server: "127.0.0.1:1080",
  ),
])

Net::HTTP.start("nginx", 80) do |http|
  pp http.head("/") #=> #<Net::HTTPOK 200 OK readbody=true>
end

UDP 通信で SOCKS Proxy を利用する

UDP に関してはもう少し複雑で、次のような手順を踏みます

SOCKS server との接続を確立（TCP と同じ）
SOCKS server と SOCKS5 プロトコルでやり取りして UDP で通信することを通知
SOCKS server が用意したポートに対して UDP の接続を確立（という表現で良いんだろうか？）
通常の UDP socket と同じように操作して、レスポンスから SOCKS 用のヘッダを除去

上記の手順を行っているのが README に載っているサンプルコードです

require "socks_handler"

# 1. SOCKS server との接続を確立（TCP と同じ）
tcp_socket = TCPSocket.new("127.0.0.1", 1080) # or Socket.tcp("127.0.0.1", 1080)

# 2. SOCKS server と SOCKS5 プロトコルでやり取りして UDP で通信することを通知
# 3. SOCKS server が用意したポートに対して UDP の接続を確立（という表現で良いんだろうか？）
udp_socket = SocksHandler::UDP.associate_udp(tcp_socket, "0.0.0.0", 0)

# 4. 通常の UDP socket と同じように操作して、レスポンスから SOCKS 用のヘッダを除去
udp_socket.send("hello", 0, "echo", 7)
puts udp_socket.gets #=> hello

サンプルコードだと通常の UDP 通信とほとんど変わらないように見えますが、SocksHandelr::UDPSocket というクラスが涙ぐましい処理をしています。

SocksHandler::UDP.socksify というメソッドも用意しようかと思ったんですが力尽きました。気が向いたら実装するかもしれません。

利用上の注意

Limitation に書いてあるとおり、native extension で行っている TCP 通信には対応できないので、mysql2 等には使えません。

何故一から gem を作ったのか？

README の冒頭や Related Work にある程度書いてあるとおりですが、少し補足します。
同じようなことをしている gem として ruby-proxifier と socksify-ruby があるんですが、SOCKS proxy を通すかどうか柔軟に指定することができません。
じゃあプルリクエストを出して機能拡張すればと思うわけですが、ruby-proxifier は次のような一瞬でマージできるようなプルリクエストすらマージされていない状況です。

socksify-ruby に関しては一応メンテされているんですが、とにかく読み辛いです。Net::HTTP のモンキーパッチ部分は実際にコードを動かしてみないと理解できないです。更には、Ruby 3.1 に対応させるために、Ruby 3.0 の Net::HTTP#connect の実装をコピペしてきていて、これを恒久対応としています。
cf. patch Net::HTTP for Ruby 3.1 by MatzFan · Pull Request #51 · astro/socksify-ruby

以上から、そんなに実装も大変じゃないので自分が自由にメンテできる gem を一から開発した方が良いのでは？と思って自作するに至りました。

ProxyChains-NG で柔軟にルールが指定できて、macOS でも SIP の影響を受けずに利用できればベストなんですけどね…。

おまけ

curl で SOCKS proxy を利用する

冒頭でも軽く言及しましたが、curl だと --proxy に socks5h scheme を指定すれば名前解決も SOCKS server に任せることができます。

$ curl --proxy socks5h://localhost:1080/ -I http://nginx
HTTP/1.1 200 OK
Server: nginx/1.25.1
Date: Wed, 30 Aug 2023 10:40:50 GMT
Content-Type: text/html
Content-Length: 615
Last-Modified: Tue, 13 Jun 2023 15:08:10 GMT
Connection: keep-alive
ETag: "6488865a-267"
Accept-Ranges: bytes

h を付けないと名前解決できないので注意が必要です。

proxychains4 を使う場合、macOS では組み込みのものではなく Homebrew 等でインストールしたものを使わないと preload が期待どおりに動かないことに注意です

$ proxychains4 /usr/local/opt/curl/bin/curl -I http://nginx
[proxychains] config file found: /usr/local/etc/proxychains.conf
[proxychains] preloading /usr/local/Cellar/proxychains-ng/4.16/lib/libproxychains4.dylib
[proxychains] DLL init: proxychains-ng 4.16
[proxychains] Strict chain  ...  127.0.0.1:1080  ...  nginx:80  ...  OK
HTTP/1.1 200 OK
Server: nginx/1.25.1
Date: Wed, 30 Aug 2023 10:40:38 GMT
Content-Type: text/html
Content-Length: 615
Last-Modified: Tue, 13 Jun 2023 15:08:10 GMT
Connection: keep-alive
ETag: "6488865a-267"
Accept-Ranges: bytes

do you use system curl or homebrew curl ? the former is known to not work with hooking (any system binaries, that is).

cf. https://github.com/rofl0r/proxychains-ng/issues/409#issuecomment-1002771526

OpenSSH で SOCKS Proxy を立てて動作確認する

次のような docker-compose.yml を用意して

version: "2.4"
services:
  put-custom-file:
    image: lscr.io/linuxserver/openssh-server:latest
    entrypoint: ""
    command:
      # Resolve the error like "channel 4: open failed: administratively prohibited: open failed"
      # cf. https://unix.stackexchange.com/questions/14160/ssh-tunneling-error-channel-1-open-failed-administratively-prohibited-open
      /bin/sh -c "echo \"sed -i 's/AllowTcpForwarding no/AllowTcpForwarding yes/' /etc/ssh/sshd_config\" >/work/allow-tcp-forwarding"
    volumes:
      - type: volume
        source: custom-files
        target: /work

  openssh-server:
    image: lscr.io/linuxserver/openssh-server:latest
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Etc/UTC
      PUBLIC_KEY_URL: https://github.com/abicky.keys
    ports:
      - 2222:2222
    volumes:
      - type: volume
        source: custom-files
        target: /custom-cont-init.d
        read_only: true
    depends_on:
      put-custom-file:
        condition: service_completed_successfully

  nginx:
    image: nginx:latest

volumes:
  custom-files:

次のような感じでポートフォワーディングすれば、dante と同じように SOCKS proxy として動作させることができます。

$ ssh -fND 1080 -p 2222 localhost -l linuxserver.io \
  -o UserKnownHostsFile=/dev/null \
  -o StrictHostKeyChecking=no \
  -o ExitOnForwardFailure=yes

docker-compose.yml の PUBLIC_KEY_URL はご自身のものに変更してください。
また、コンテナを立ち上げ直すと何度もホスト情報が変わったと警告が出るので ssh コマンドには上記のオプションも合わせて指定すると便利です。

ECS の Daemon サービスで動かしている Fluentd を Logging Driver の接続先にすると Draining 時にコンテナが終了しないことがある問題とその対策

Thu, 24 Nov 2022 00:00:00 +0900

標題のとおり、ECS の daemon サービスで動かしている Fluentd を logging driver の接続先にすると、draining 時に Docker container with fluentd logging driver never stops if it can’t connect to fluentd · Issue #44511 · moby/moby で言及している問題が起きて、Fluentd が復活しない限り、logging driver で Fluentd を利用しているコンテナが無限に生き続けることになります。
本エントリーでは問題の再現方法と対策について解説します。

Issue についての解説

どうしてコンテナが終了しないかについての自分なりの仮説はコメントに書いたとおりです。
次のように 3 つの goroutine が関係していそうです。

goroutine 1: Fluentd のコネクションにログを書き込む際にロガーのロックを取るが、Fluentd が起動していないためロックを抱えたまま何億回も接続を確立しようとリトライする
goroutine 2: コンテナを終了するためにコンテナのロックを取ってから logging driver を close しようとするが、ロガーのロックが取れず待機
goroutine 3: コンテナを強制終了するために PID を取得しようとするが、その際にコンテナのロックが取れず待機

上記の仮説が正しければ、fluentd-async に "true" を指定したり、fluentd-max-retries に小さな値を指定したりすれば、一応コンテナを終了させることはできるんじゃないかと思います。

再現手順

次の設定ファイルを使って terraform apply し、ECS インスタンスに 2 つのタスクが配置された後にこのインスタンスを draining すると再現します。

provider "aws" {
  region = "ap-northeast-1"
}


locals {
  namespace = "moby-issue-44511"
}

variable "key_name" {}

data "aws_vpc" "default" {
  default = true
}


#--------------#
# ECS instance #
#--------------#

resource "aws_ecs_cluster" "main" {
  name = local.namespace
}

resource "aws_iam_instance_profile" "AmazonEC2ContainerServiceforEC2Role" {
  name = "AmazonEC2ContainerServiceforEC2Role"
  role = aws_iam_role.AmazonEC2ContainerServiceforEC2Role.name
}

resource "aws_iam_role" "AmazonEC2ContainerServiceforEC2Role" {
  name = "AmazonEC2ContainerServiceforEC2Role"

  assume_role_policy = <<-EOF
  {
    "Version":"2012-10-17",
    "Statement":[
      {
        "Effect":"Allow",
        "Principal": {
          "Service": [
            "ec2.amazonaws.com"
          ]
        },
        "Action":"sts:AssumeRole"
      }
    ]
  }
  EOF
}

resource "aws_iam_role_policy_attachment" "AmazonEC2ContainerServiceforEC2Role" {
  role       = aws_iam_role.AmazonEC2ContainerServiceforEC2Role.id
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role"
}


resource "aws_security_group" "allow_ssh" {
  name   = "${local.namespace}-allow-ssh"
  vpc_id = data.aws_vpc.default.id

  ingress {
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_launch_template" "main" {
  name = local.namespace

  image_id = "ami-0fcfb0266308303f6"

  instance_type = "t3.micro"

  iam_instance_profile {
    name = aws_iam_instance_profile.AmazonEC2ContainerServiceforEC2Role.name
  }

  key_name = var.key_name

  network_interfaces {
    associate_public_ip_address = true
    security_groups             = [aws_security_group.allow_ssh.id]
  }

  instance_market_options {
    market_type = "spot"
  }

  user_data = base64encode(<<-DATA
  #!/bin/bash

  cat <<'EOF' >> /etc/ecs/ecs.config
  ECS_CLUSTER=${aws_ecs_cluster.main.name}
  ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","syslog","awslogs","fluentd"]
  ECS_LOGLEVEL=debug
  EOF

  echo '{"debug": true}' >/etc/docker/daemon.json
  systemctl restart docker --no-block
  DATA
  )
}

resource "aws_instance" "main" {
  launch_template {
    id      = aws_launch_template.main.id
    version = "$Latest"
  }

  # Set iam_instance_profile explicitly to avoid the bug that will be fixed
  # by https://github.com/hashicorp/terraform-provider-aws/pull/27972.
  iam_instance_profile = aws_iam_instance_profile.AmazonEC2ContainerServiceforEC2Role.name

  tags = {
    Name = local.namespace
  }

  lifecycle {
    ignore_changes = [
      # Although the user data of the launch template is base64-encoded,
      # terraform-provider-aws cannot know that.
      user_data,
      # The latest version at the time the instance is created, not "$Latest" is set
      launch_template["version"],
    ]
  }
}


#---------#
# fluentd #
#---------#

resource "aws_ecs_task_definition" "fluentd" {
  family                = "${local.namespace}-fluentd"
  container_definitions = <<-JSON
  [
    {
      "name": "fluentd",
      "image": "fluent/fluentd:v1.15.3-1.0",
      "essential": true,
      "memoryReservation": 50,
      "portMappings": [
        { "containerPort": 24224, "hostPort": 24224 }
      ]
    }
  ]
  JSON
}

resource "aws_ecs_service" "fluentd" {
  name                = aws_ecs_task_definition.fluentd.family
  cluster             = aws_ecs_cluster.main.name
  task_definition     = aws_ecs_task_definition.fluentd.arn
  scheduling_strategy = "DAEMON"
}


#-------------#
# application #
#-------------#

resource "aws_ecs_task_definition" "hello" {
  family                = "${local.namespace}-application"
  container_definitions = <<-JSON
  [
    {
      "name": "hello",
      "image": "ubuntu",
      "essential": true,
      "command": ["sh", "-c", "while :; do echo \"$(date +%FT%T): hello\"; sleep 1; done"],
      "stopTimeout": 30,
      "logConfiguration": {
        "logDriver": "fluentd",
        "options": {
          "fluentd-address": "${aws_instance.main.private_ip}"
        }
      },
      "memoryReservation": 50
    }
  ]
  JSON
}

resource "aws_ecs_service" "hello" {
  name            = aws_ecs_task_definition.hello.family
  cluster         = aws_ecs_cluster.main.name
  task_definition = aws_ecs_task_definition.hello.arn
  desired_count   = 1

  deployment_minimum_healthy_percent = 0
}

上記の hello コンテナではシグナルハンドリングをしていないので、少なくとも stopTimeout の 30 秒が経つまでコンテナは終了しません。30 秒経つと docker は強制的にコンテナを終了しようとします。
その様子はログからも確認できます。

$ journalctl -u docker -o json | jq -r .MESSAGE
-- snip --
time="2022-11-23T11:02:52.029418846Z" level=debug msg="Calling POST /v1.21/containers/d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15/stop?t=30"
time="2022-11-23T11:02:52.029494540Z" level=debug msg="Sending kill signal 15 to container d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15"
time="2022-11-23T11:02:59.372092034Z" level=debug msg="Running health check for container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd ..."
time="2022-11-23T11:02:59.372551803Z" level=debug msg="starting exec command 888c6ff102d55ba1b8ce00464569eeb670d418c9d14a27fad966fb381ed78de1 in container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd"
time="2022-11-23T11:02:59.374900092Z" level=debug msg="attach: stdout: begin"
time="2022-11-23T11:02:59.374939402Z" level=debug msg="attach: stderr: begin"
time="2022-11-23T11:02:59.378410573Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exec-added
time="2022-11-23T11:02:59.729173160Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exec-started
time="2022-11-23T11:02:59.758665471Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T11:02:59.758851692Z" level=debug msg="attach: stdout: end"
time="2022-11-23T11:02:59.758874503Z" level=debug msg="attach: stderr: end"
time="2022-11-23T11:02:59.758902425Z" level=debug msg="attach done"
time="2022-11-23T11:02:59.758927682Z" level=debug msg="Health check for container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd done (exitCode=0)"
time="2022-11-23T11:03:00.189947282Z" level=debug msg="Calling POST /v1.21/containers/e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb/stop?t=30"
time="2022-11-23T11:03:00.190024918Z" level=debug msg="Sending kill signal 15 to container e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb"
time="2022-11-23T11:03:01.541963842Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T11:03:01.562363324Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/delete
time="2022-11-23T11:03:01.562396747Z" level=info msg="ignoring event" container=e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb module=libcontainerd namespace=moby topic=/tasks/delete type="*events.TaskDelete"
time="2022-11-23T11:03:01.574352549Z" level=debug msg="Revoking external connectivity on endpoint ecs-moby-issue-44511-fluentd-5-fluentd-8490d7a8bce5fac7dd01 (d03613098372f77002e9c8f4c972358e227f03fa4e0875288e2a7fd2c6344e5a)"
time="2022-11-23T11:03:01.574995334Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -C DOCKER -p tcp -d 0/0 --dport 24224 -j DNAT --to-destination 172.17.0.2:24224 ! -i docker0]"
time="2022-11-23T11:03:01.575847232Z" level=debug msg="Calling GET /v1.21/containers/e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb/json"
time="2022-11-23T11:03:01.577553743Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -D DOCKER -p tcp -d 0/0 --dport 24224 -j DNAT --to-destination 172.17.0.2:24224 ! -i docker0]"
time="2022-11-23T11:03:01.581373824Z" level=debug msg="/usr/sbin/iptables, [--wait -t filter -C DOCKER ! -i docker0 -o docker0 -p tcp -d 172.17.0.2 --dport 24224 -j ACCEPT]"
time="2022-11-23T11:03:01.588964441Z" level=debug msg="/usr/sbin/iptables, [--wait -t filter -D DOCKER ! -i docker0 -o docker0 -p tcp -d 172.17.0.2 --dport 24224 -j ACCEPT]"
time="2022-11-23T11:03:01.598819481Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -C POSTROUTING -p tcp -s 172.17.0.2 -d 172.17.0.2 --dport 24224 -j MASQUERADE]"
time="2022-11-23T11:03:01.602651989Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -D POSTROUTING -p tcp -s 172.17.0.2 -d 172.17.0.2 --dport 24224 -j MASQUERADE]"
time="2022-11-23T11:03:01.606894842Z" level=debug msg="DeleteConntrackEntries purged ipv4:1, ipv6:0"
time="2022-11-23T11:03:01.689072479Z" level=debug msg="Releasing addresses for endpoint ecs-moby-issue-44511-fluentd-5-fluentd-8490d7a8bce5fac7dd01's interface on network bridge"
time="2022-11-23T11:03:01.689111084Z" level=debug msg="ReleaseAddress(LocalDefault/172.17.0.0/16, 172.17.0.2)"
time="2022-11-23T11:03:01.689137776Z" level=debug msg="Released address PoolID:LocalDefault/172.17.0.0/16, Address:172.17.0.2 Sequence:App: ipam/default/data, ID: LocalDefault/172.17.0.0/16, DBIndex: 0x0, Bits: 65536, Unselected: 65531, Sequence: (0xe8000000, 1)->(0x0, 2046)->(0x1, 1)->end Curr:5"
time="2022-11-23T11:03:01.796276657Z" level=debug msg="Calling GET /v1.21/containers/e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb/json"
time="2022-11-23T11:03:01.797123648Z" level=debug msg="Calling GET /v1.21/containers/e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb/json"
time="2022-11-23T11:03:22.052640413Z" level=info msg="Container failed to exit within 30s of signal 15 - using the force" container=d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15
time="2022-11-23T11:03:22.052683086Z" level=debug msg="Sending kill signal 9 to container d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15"
time="2022-11-23T11:03:22.125742131Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T11:03:22.160118590Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/delete
time="2022-11-23T11:03:22.160152542Z" level=info msg="ignoring event" container=d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15 module=libcontainerd namespace=moby topic=/tasks/delete type="*events.TaskDelete"
-- snip --

上記のログでは、コンテナ ID = d3030f944843 が hello コンテナで、e6cec48166c6 が fluentd コンテナです。ログから docker が次のように動作したことがわかります。

2022-11-23T11:02:52.029494540Z: hello コンテナに SIGTERM (signal 15) を送る
2022-11-23T11:03:00.190024918Z: fluentd コンテナに SIGTERM (signal 15) を送る
2022-11-23T11:03:22.052683086Z: hello コンテナに SIGKILL (signal 9) を送る

各タスクの詳細は次のとおりです。

% TZ=UTC aws ecs describe-tasks --cluster moby-issue-44511 \
  --tasks ecb4495fd45343e88e5649a9d2f4eac6 f64e3d5e2f654fbeaac060acf07f7871 \
  | jq '[.tasks[] | { group, containerId: .containers[0].runtimeId, desiredStatus, lastStatus, createdAt, stoppingAt, stoppedAt, stoppedReason, containerStoppedReason: .containers[0].reason }]'
[
  {
    "group": "service:moby-issue-44511-application",
    "containerId": "d3030f9448430fc0be31d74cb4651b0f723043b6645ebc53ae0f84345adfaa15",
    "desiredStatus": "STOPPED",
    "lastStatus": "STOPPED",
    "createdAt": "2022-11-23T11:01:43.145000+00:00",
    "stoppingAt": "2022-11-23T11:02:51.646000+00:00",
    "stoppedAt": "2022-11-23T11:15:28.866000+00:00",
    "stoppedReason": "Service moby-issue-44511-application: container instance is in DRAINING state",
    "containerStoppedReason": "DockerTimeoutError: Could not transition to stopped; timed out after waiting 2m30s"
  },
  {
    "group": "service:moby-issue-44511-fluentd",
    "containerId": "e6cec48166c665fe4bffb9dceac44595953afc7fcd5bb727588ba62ff451bbbb",
    "desiredStatus": "STOPPED",
    "lastStatus": "STOPPED",
    "createdAt": "2022-11-23T11:00:49.831000+00:00",
    "stoppingAt": "2022-11-23T11:02:58.827000+00:00",
    "stoppedAt": "2022-11-23T11:03:01.819000+00:00",
    "stoppedReason": "Servicemoby-issue-44511-fluentd: container instance is in DRAINING state",
    "containerStoppedReason": null
  }
]

上記の結果を見ると、fluentd タスクの方が先に終了していることがわかります。また、application タスクの方も無事停止しているように見えますが、実際はコンテナは生きたままです。

[ec2-user@ip-172-31-16-91 ~]$ date
Wed Nov 23 11:48:08 UTC 2022
[ec2-user@ip-172-31-16-91 ~]$ docker container ls
CONTAINER ID   IMAGE                            COMMAND                  CREATED             STATUS                       PORTS     NAMES
d3030f944843   ubuntu                           "sh -c 'while :; do …"   46 minutes ago      Up 46 minutes                          ecs-moby-issue-44511-application-7-hello-8adde2899ef48c97b401
be5a2c16b818   amazon/amazon-ecs-agent:latest   "/agent"                 About an hour ago   Up About an hour (healthy)             ecs-agent

対策

ECS インスタンスを draining した場合に fluentd 以外のタスクが全て終了してから fluentd を停止させれば良いです。
最初は wrapper program を書こうかと思ったんですが、同じ悩みを抱えている方が別の解決策を取っていたのでそのやり方を採用してみます。

ECSのDAEMONをDRAININGで直ぐに停止しないようにした - Sansan Tech Blog

元々の fluentd のタスク定義は次のようになっていましたが

resource "aws_ecs_task_definition" "fluentd" {
  family                = "${local.namespace}-fluentd"
  container_definitions = <<-JSON
  [
    {
      "name": "fluentd",
      "image": "fluent/fluentd:v1.15.3-1.0",
      "essential": true,
      "memoryReservation": 50,
      "portMappings": [
        { "containerPort": 24224, "hostPort": 24224 }
      ]
    }
  ]
  JSON
}

次のように変更します。

resource "aws_ecs_task_definition" "fluentd" {
  family                = "${local.namespace}-fluentd"
  container_definitions = <<-JSON
  [
    {
      "name": "fluentd",
      "image": "fluent/fluentd:v1.15.3-1.0",
      "essential": true,
      "memoryReservation": 50,
      "portMappings": [
        { "containerPort": 24224, "hostPort": 24224 }
      ]
    },
    {
      "name": "ecs-daemon-protector",
      "image": "iamwaneal/ecs-daemon-protector@sha256:6da000b4bf5e6878dfbad80b8cb82f05a514ff7751f3291841568078df247a7c",
      "dependsOn": [
        {
          "containerName": "fluentd",
          "condition": "START"
        }
      ]
    }
  ]
  JSON
}

また、必要な権限を追加します。ロール名が AmazonEC2ContainerServiceforEC2Role のままなのは気持ち悪いですが、検証用途なので気にしないことにします。

resource "aws_iam_role_policy" "ecs_daemon_protector" {
  name = "ecs-daemon-protector"
  role = aws_iam_role.AmazonEC2ContainerServiceforEC2Role.id

  policy = <<-EOF
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "ecs:DescribeContainerInstances",
          "ecs:DescribeServices",
          "ecs:DescribeTasks",
          "ecs:ListContainerInstances",
          "ecs:ListServices",
          "ecs:ListTasks"
        ],
        "Resource": "*"
      }
    ]
  }
  EOF
}

次のログは ECS インスタンスを draining にした時のログです。

% journalctl -u docker -o json | jq -r .MESSAGE
-- snip --
time="2022-11-23T16:32:58.600810655Z" level=debug msg="Calling POST /v1.21/containers/55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3/stop?t=30"
time="2022-11-23T16:32:58.600881633Z" level=debug msg="Sending kill signal 15 to container 55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3"
time="2022-11-23T16:33:00.594474625Z" level=debug msg="Calling POST /v1.21/containers/e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5/stop?t=60"
time="2022-11-23T16:33:00.594537016Z" level=debug msg="Sending kill signal 15 to container e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5"
time="2022-11-23T16:33:02.385822631Z" level=debug msg="Calling GET /v1.21/containers/7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef/stats?stream=1"
time="2022-11-23T16:33:03.454707939Z" level=debug msg="Calling GET /v1.21/containers/e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5/stats?stream=1"
time="2022-11-23T16:33:03.990980151Z" level=debug msg="Calling GET /v1.21/containers/55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3/stats?stream=1"
time="2022-11-23T16:33:11.160810958Z" level=debug msg="Running health check for container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd ..."
time="2022-11-23T16:33:11.160942303Z" level=debug msg="starting exec command ed20873b8284e03235eaed7b82810943e9fc27a07574d48a2c314dc1a038a104 in container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd"
time="2022-11-23T16:33:11.163104354Z" level=debug msg="attach: stdout: begin"
time="2022-11-23T16:33:11.163127192Z" level=debug msg="attach: stderr: begin"
time="2022-11-23T16:33:11.179469927Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exec-added
time="2022-11-23T16:33:11.656820563Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exec-started
time="2022-11-23T16:33:11.689799328Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T16:33:11.689982652Z" level=debug msg="attach: stdout: end"
time="2022-11-23T16:33:11.689999787Z" level=debug msg="attach: stderr: end"
time="2022-11-23T16:33:11.690028133Z" level=debug msg="attach done"
time="2022-11-23T16:33:11.690054723Z" level=debug msg="Health check for container be5a2c16b818ecd5893d810710cf94c6cc24e15b14ac8966f9d8eb401d12d1fd done (exitCode=0)"
time="2022-11-23T16:33:25.581998420Z" level=debug msg="Calling HEAD /_ping"
time="2022-11-23T16:33:28.624113389Z" level=info msg="Container failed to exit within 30s of signal 15 - using the force" container=55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3
time="2022-11-23T16:33:28.624600967Z" level=debug msg="Sending kill signal 9 to container 55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3"
time="2022-11-23T16:33:28.669807373Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T16:33:28.691661030Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/delete
time="2022-11-23T16:33:28.691693014Z" level=info msg="ignoring event" container=55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3 module=libcontainerd namespace=moby topic=/tasks/delete type="*events.TaskDelete"
time="2022-11-23T16:33:28.710003493Z" level=debug msg="Calling GET /v1.21/containers/55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3/json"
time="2022-11-23T16:33:28.710214466Z" level=debug msg="Revoking external connectivity on endpoint ecs-moby-issue-44511-application-7-hello-8ef4ebb89fb8ddabe801 (af30a24de76c98f322b732eb8f0607fd3e7dbc1081965d77aa596d4033fa6b67)"
time="2022-11-23T16:33:28.710989827Z" level=debug msg="DeleteConntrackEntries purged ipv4:0, ipv6:0"
time="2022-11-23T16:33:28.801219714Z" level=debug msg="Releasing addresses for endpoint ecs-moby-issue-44511-application-7-hello-8ef4ebb89fb8ddabe801's interface on network bridge"
time="2022-11-23T16:33:28.801255110Z" level=debug msg="ReleaseAddress(LocalDefault/172.17.0.0/16, 172.17.0.5)"
time="2022-11-23T16:33:28.801281090Z" level=debug msg="Released address PoolID:LocalDefault/172.17.0.0/16, Address:172.17.0.5 Sequence:App: ipam/default/data, ID: LocalDefault/172.17.0.0/16, DBIndex: 0x0, Bits: 65536, Unselected: 65529, Sequence: (0xfc000000, 1)->(0x0, 2046)->(0x1, 1)->end Curr:6"
time="2022-11-23T16:33:28.869477226Z" level=debug msg="Calling GET /v1.21/containers/55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3/json"
time="2022-11-23T16:33:28.872855536Z" level=debug msg="Calling GET /v1.21/containers/55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3/json"
time="2022-11-23T16:33:31.394374108Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T16:33:31.407158227Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/delete
time="2022-11-23T16:33:31.407270649Z" level=info msg="ignoring event" container=e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5 module=libcontainerd namespace=moby topic=/tasks/delete type="*events.TaskDelete"
time="2022-11-23T16:33:31.462495321Z" level=debug msg="Calling GET /v1.21/containers/e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5/json"
time="2022-11-23T16:33:31.462960602Z" level=debug msg="Revoking external connectivity on endpoint ecs-moby-issue-44511-fluentd-9-ecs-daemon-protector-8082e0b9e3a0d8890d00 (fdfa544690ae43c81b0d272b36b61fc2a3e84cde6af79cb567b19d552fe5bc4a)"
time="2022-11-23T16:33:31.464711815Z" level=debug msg="DeleteConntrackEntries purged ipv4:1, ipv6:0"
time="2022-11-23T16:33:31.580839512Z" level=debug msg="Releasing addresses for endpoint ecs-moby-issue-44511-fluentd-9-ecs-daemon-protector-8082e0b9e3a0d8890d00's interface on network bridge"
time="2022-11-23T16:33:31.580878245Z" level=debug msg="ReleaseAddress(LocalDefault/172.17.0.0/16, 172.17.0.3)"
time="2022-11-23T16:33:31.580905793Z" level=debug msg="Released address PoolID:LocalDefault/172.17.0.0/16, Address:172.17.0.3 Sequence:App: ipam/default/data, ID: LocalDefault/172.17.0.0/16, DBIndex: 0x0, Bits: 65536, Unselected: 65530, Sequence: (0xf8000000, 1)->(0x0, 2046)->(0x1, 1)->end Curr:6"
time="2022-11-23T16:33:31.671308358Z" level=debug msg="Calling GET /v1.21/containers/e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5/json"
time="2022-11-23T16:33:31.676579087Z" level=debug msg="Calling GET /v1.21/containers/e08afe646cb171a4366381ae7273e8fd13537f1d2a3677bbf0f8c574a9f4f2a5/json"
time="2022-11-23T16:33:31.685018931Z" level=debug msg="Calling POST /v1.21/containers/7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef/stop?t=30"
time="2022-11-23T16:33:31.685095206Z" level=debug msg="Sending kill signal 15 to container 7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef"
time="2022-11-23T16:33:32.837157890Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/exit
time="2022-11-23T16:33:32.863129855Z" level=debug msg=event module=libcontainerd namespace=moby topic=/tasks/delete
time="2022-11-23T16:33:32.863166595Z" level=info msg="ignoring event" container=7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef module=libcontainerd namespace=moby topic=/tasks/delete type="*events.TaskDelete"
time="2022-11-23T16:33:32.895880772Z" level=debug msg="Revoking external connectivity on endpoint ecs-moby-issue-44511-fluentd-9-fluentd-d8fafae7fab5a6f85200 (f202415ea19ff26a858bd28f24d9536837c4283dd7dd7c33ea828cfa3df9e01a)"
time="2022-11-23T16:33:32.901781381Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -C DOCKER -p tcp -d 0/0 --dport 24224 -j DNAT --to-destination 172.17.0.2:24224 ! -i docker0]"
time="2022-11-23T16:33:32.901855554Z" level=debug msg="Calling GET /v1.21/containers/7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef/json"
time="2022-11-23T16:33:32.904022305Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -D DOCKER -p tcp -d 0/0 --dport 24224 -j DNAT --to-destination 172.17.0.2:24224 ! -i docker0]"
time="2022-11-23T16:33:32.907646778Z" level=debug msg="/usr/sbin/iptables, [--wait -t filter -C DOCKER ! -i docker0 -o docker0 -p tcp -d 172.17.0.2 --dport 24224 -j ACCEPT]"
time="2022-11-23T16:33:32.911546064Z" level=debug msg="/usr/sbin/iptables, [--wait -t filter -D DOCKER ! -i docker0 -o docker0 -p tcp -d 172.17.0.2 --dport 24224 -j ACCEPT]"
time="2022-11-23T16:33:32.918312060Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -C POSTROUTING -p tcp -s 172.17.0.2 -d 172.17.0.2 --dport 24224 -j MASQUERADE]"
time="2022-11-23T16:33:32.919867917Z" level=debug msg="/usr/sbin/iptables, [--wait -t nat -D POSTROUTING -p tcp -s 172.17.0.2 -d 172.17.0.2 --dport 24224 -j MASQUERADE]"
time="2022-11-23T16:33:32.922380159Z" level=debug msg="DeleteConntrackEntries purged ipv4:1, ipv6:0"
time="2022-11-23T16:33:33.036928666Z" level=debug msg="Releasing addresses for endpoint ecs-moby-issue-44511-fluentd-9-fluentd-d8fafae7fab5a6f85200's interface on network bridge"
time="2022-11-23T16:33:33.036969823Z" level=debug msg="ReleaseAddress(LocalDefault/172.17.0.0/16, 172.17.0.2)"
time="2022-11-23T16:33:33.036995247Z" level=debug msg="Released address PoolID:LocalDefault/172.17.0.0/16, Address:172.17.0.2 Sequence:App: ipam/default/data, ID: LocalDefault/172.17.0.0/16, DBIndex: 0x0, Bits: 65536, Unselected: 65531, Sequence: (0xe8000000, 1)->(0x0, 2046)->(0x1, 1)->end Curr:6"
time="2022-11-23T16:33:33.118298509Z" level=debug msg="Calling GET /v1.21/containers/7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef/json"
time="2022-11-23T16:33:33.118306244Z" level=debug msg="Calling GET /v1.21/containers/7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef/json"

上記のログでは、コンテナ ID = 55add885ec06 が hello コンテナで、7d8cbbe6f7e0 が fluentd コンテナ、e08afe646cb1 が ecs-daemon-protector です。ログから docker が次のように動作したことがわかります。

2022-11-23T16:32:58.600881633Z: hello コンテナに SIGTERM (signal 15) を送る
2022-11-23T16:33:00.594537016Z: ecs-daemon-protector コンテナに SIGTERM (signal 15) を送る
2022-11-23T16:33:28.624600967Z: hello コンテナに SIGKILL (signal 9) を送る
2022-11-23T16:33:31.685095206Z: fluentd コンテナに SIGTERM (signal 15) を送る

各タスクの詳細は次のとおりです。application タスクの後に fluentd タスクが終了しているので期待どおりですね。

% TZ=UTC aws ecs describe-tasks --cluster moby-issue-44511 \
  --tasks 3c9d1bfca2a04095bfc58f52f5154955 45e8d21609834e2da2d6ad0a22d51de3 \
  | jq '[.tasks[] | { group, containerId: .containers[0].runtimeId, desiredStatus, lastStatus, createdAt, stoppingAt, stoppedAt, stoppedReason, containerStoppedReason: .containers[0].reason }]'
[
  {
    "group": "service:moby-issue-44511-application",
    "containerId": "55add885ec06b5da86e1a01302bee4b1c95bdc53a74e5fe268b30a05c86462a3",
    "desiredStatus": "STOPPED",
    "lastStatus": "STOPPED",
    "createdAt": "2022-11-23T16:31:45.322000+00:00",
    "stoppingAt": "2022-11-23T16:32:57.071000+00:00",
    "stoppedAt": "2022-11-23T16:33:28.885000+00:00",
    "stoppedReason": "Service moby-issue-44511-application: container instance is in DRAINING state",
    "containerStoppedReason": null
  },
  {
    "group": "service:moby-issue-44511-fluentd",
    "containerId": "7d8cbbe6f7e056f4fb677633c10d3bfed31749f7563006b7fe5100ece2bf51ef",
    "desiredStatus": "STOPPED",
    "lastStatus": "STOPPED",
    "createdAt": "2022-11-23T16:31:43.798000+00:00",
    "stoppingAt": "2022-11-23T16:32:59.612000+00:00",
    "stoppedAt": "2022-11-23T16:33:33.122000+00:00",
    "stoppedReason": "Servicemoby-issue-44511-fluentd: container instance is in DRAINING state",
    "containerStoppedReason": null
  }
]

補足

前述の対策は [ECS] [request]: Tasks scheduled with the DAEMON strategy should not be stopped when container instance is placed into DRAINING · Issue #128 · aws/containers-roadmap が解消することで不要になる予定だったと思われます。

Improving daemon services in Amazon ECS にも次のように、daemon タスクは最後に終了するようにしたと言及されています。

In November of 2020, we added an update to the ECS scheduler to drain daemon tasks last on a host. This ensures that when an instance is set to drain, ECS will terminate all other tasks before terminating the daemon task.

ところが、どうも次のようなことが今でも起きるようです。

ECS サービスのタスクが DEACTIVATING になる
ECS サービスのタスクが STOPPING になる
- この時点で stopsignal が送られ、ECS サービスに属していたタスクはサービスから外れたものと認識されるのかもしれない
- タスク自体はまだ終了したわけではない
Daemon サービスのタスクが STOPPING になる
- この時点で stopsignal が送られる
- ECS サービスに属している running タスクがある間は終了しないが、ECS サービスに属していない running タスクのことは考慮しないらしい
Daemon サービスのタスクが STOPPED になる
ECS サービスに属していたタスクが STOPPED になる

DEACTIVATING, STOPPING 等の state については Task lifecycle を参照してください。

regression が起きているのでは？と投げかけている issue があるので、もしかしたらどこかのタイミングで regression があったのかもしれません。
cf. [ECS] [bug]: daemon task should be last to be stopped when instance is draining · Issue #1700 · aws/containers-roadmap

Datadog メトリクスモニター作成入門

Tue, 08 Nov 2022 00:00:00 +0900

Datadog はモニタリング関連の SaaS ではおそらく最も利用されているサービスでしょうが、公式ドキュメントが豊富にある割には何から読み始めれば良いかわかりにくく、慣れるまでの道が険しい印象です。
本エントリーでは、Datadog が既に導入されている組織で、Datadog モニターを使って監視をしたいけど、モニターの設定方法がよくわからないといった方を対象に、メトリクスモニターの作成に焦点を絞って解説していきます。なお、あくまで Datadog の使い方についての解説であり、どのようなモニターを設定すべきかについては触れません。

メトリクスの収集についても触れたかったんですが、力尽きたので、メトリクスの収集については気が向いたら別エントリーを書きます。

メトリクスモニターの作成方法の基本

モニターは Terraform などで管理している組織も多いかと思いますが、慣れないうちは Web UI で項目を埋めて確認するのが良いです。下部に “Export Monitor” というボタンがあり、これをクリックすることでモニターの JSON 表現を確認できます。Terraform などでモニターを作成する際は、JSON の内容を参考にそれぞれのフィールドの値を指定すると良いでしょう。

Web UI からもわかるとおり、モニターを作成するには最低限次のことを行わなければなりません。

検知方法の選択
クエリの定義・評価期間と評価方法の指定
アラート条件の指定
通知方法の指定

以降、検知方法は Threshold Alert を選択するものとして、残りの作業を滞りなく行えるようになるのに必要な知識について次の順で解説します。

クエリの定義
クエリの評価期間・評価方法・アラート条件の指定
通知方法の指定

なお、本文で言及するものもありますが、それぞれの作業について読むべき公式ドキュメントはおそらく次の辺りです。本エントリーと合わせて読むことで理解が深まると思います。

メトリクスモニター作成の Getting Started
- Getting Started with Monitors
  - メトリクスモニター作成の一連の流れはわかるが、それぞれの作業の詳細を理解するのは難しいかも
クエリの定義について
- Metrics
  - クエリの定義をしっかり理解するには必読
- Advanced Filtering
  - メトリクスのスコープを指定する方法についての説明
  - Advanced と言いつつ、かなり基本的な内容かつ量も少ないので、クエリの定義を理解するのに合わせて読むべき
クエリの評価期間・評価方法・アラート条件の指定について
- Configure Monitors
  - クエリの評価期間、評価方法、アラート条件の指定方法についての説明
  - Configure Monitors で触れられていない full window の概念については Data Window 参照
通知方法の指定について
- Notifications
  - モニターの Notification の指定方法についての説明
- Variables
  - 通知メッセージで使える変数についての説明

クエリの定義について

モニターで使うクエリの指定方法については Querying metrics に書かれています。本項を読んだ後に一読すると理解が深まるかもしれません。

上記のドキュメントに載っている用語を使うと、Web UI 上のクエリの各項目の意味は次のようになります。

上図には Time Aggregation は載っていませんが、Time Aggregation で使われている rollup は関数であり、Σを押さないと指定できません。次のとおり、通常の用途では rollup 関数をモニターのクエリに指定することはないので、ここでは説明を割愛します。

Rollups should usually be avoided in monitor queries, because of the possibility of misalignment between the rollup interval and the evaluation window of the monitor.

cf. Rollups in monitors

各項目の詳細はドキュメントを読んでもらうとして、理解を深めてもらうために具体例を出します。例えば次のクエリを考えます。

式で表現すると avg:system.load.1{*} です。

system.load.1 の部分はメトリクス名で、過去 1 分間のロードアベレージです。uptime で確認できるやつですね。

[ec2-user@ip-172-31-4-62 ~]$ uptime
 15:53:16 up  1:15,  1 user,  load average: 1.27, 0.54, 0.42

上記の出力結果だと過去 1 分間のロードアベレージは 1.27 で、過去 5 分が 0.54、過去 15 分が 0.42 です。

* の部分はスコープ（フィルター条件）で、* は全てのメトリクスを対象にすることを意味します。例えば本番で稼働しているサーバのメトリクスに env:production というタグが付与されている場合、env:production を指定することで本番のメトリクスに限定することができます。複雑なスコープの指定方法については Advanced Filtering を一読すると良いでしょう。分量も少ないのでサクッと読めるはずです。

avg の部分は同時刻のメトリクスをどのように集約するかを意味し、他に min, max, sum があります。

例えば、3 つのホストがあり、それぞれのメトリクスの値が次のようになっていたとします。

datetime	i-0ba82eddc862f3795	i-0da62b250aad43710	i-0f05b9b48bcbba766
2022-11-06T14:52:36Z	0.000	1.350	0.463
2022-11-06T14:52:50Z	0.000	1.070	0.790
2022-11-06T14:52:51Z	0.000	1.050	0.808
2022-11-06T14:53:05Z	0.000	0.835	1.060
2022-11-06T14:53:06Z	0.000	0.820	1.074
2022-11-06T14:53:20Z	0.000	0.643	1.270
2022-11-06T14:53:21Z	0.000	0.630	1.281
2022-11-06T14:53:35Z	0.000	0.499	1.430
2022-11-06T14:53:36Z	0.000	0.490	1.439
2022-11-06T14:53:50Z	0.000	0.387	1.560
2022-11-06T14:53:51Z	0.000	0.380	1.567
2022-11-06T14:54:05Z	0.000	0.305	1.660
2022-11-06T14:54:06Z	0.000	0.300	1.665
2022-11-06T14:54:20Z	0.000	0.235	1.730
2022-11-06T14:54:21Z	0.029	0.230	1.705
2022-11-06T14:54:35Z	0.440	0.183	1.350
2022-11-06T14:54:36Z	0.463	0.180	1.339
2022-11-06T14:54:50Z	0.790	0.143	1.180

min:system.load.1{*}, avg:system.load.1{*}, max:system.load.1{*} は、これら 3 ホストのメトリクスの最小値、平均値、最大値を取って次のようになります。

datetime	min	avg	max
2022-11-06T14:52:36Z	0.000	0.604	1.350
2022-11-06T14:52:50Z	0.000	0.620	1.070
2022-11-06T14:52:51Z	0.000	0.619	1.050
2022-11-06T14:53:05Z	0.000	0.632	1.060
2022-11-06T14:53:06Z	0.000	0.631	1.074
2022-11-06T14:53:20Z	0.000	0.638	1.270
2022-11-06T14:53:21Z	0.000	0.637	1.281
2022-11-06T14:53:35Z	0.000	0.643	1.430
2022-11-06T14:53:36Z	0.000	0.643	1.439
2022-11-06T14:53:50Z	0.000	0.649	1.560
2022-11-06T14:53:51Z	0.000	0.649	1.567
2022-11-06T14:54:05Z	0.000	0.655	1.660
2022-11-06T14:54:06Z	0.000	0.655	1.665
2022-11-06T14:54:20Z	0.000	0.655	1.730
2022-11-06T14:54:21Z	0.029	0.655	1.705
2022-11-06T14:54:35Z	0.183	0.658	1.350
2022-11-06T14:54:36Z	0.180	0.661	1.339
2022-11-06T14:54:50Z	0.143	0.704	1.180

次に、grouping by tag が指定されているケースを考えます。ここでは、指定するタグは host とします。

式で表現すると avg:system.load.1{*} by {host} です。

avg は host タグが同じメトリクスごとに適用されます。system.load.1 の場合、ホストごとに同時刻のメトリクスは 1 つしかないので、avg, min, max, sum のいずれを指定しても結果は同じになります。万が一同時刻に同じメトリクスが複数送られてきた場合、後の値が採用されます。同じメトリクスとは、メトリクス名とタグの値が全て同じメトリクスのことです。

Any metrics with fractions of a second timestamps are rounded to the nearest second. If any points have the same timestamp, the latest point overwrites the previous ones.

cf. What are metrics?

一方で、avg:system.load.1{*} by {availability-zone} のように grouping by tag が availability-zone で、各 availability zone に複数のホストが存在すれば、同時刻に複数のメトリクスが存在するので、avg, min 等で結果が異なります。また、grouping by tag が host でも、system.core.user のように、同一ホストから同時刻にコアの数だけメトリクスが送られてくる場合も結果が異なります。

なお、モニターを作成する際に grouping by tag を指定すると、そのグループごとにアラートを受け取ることになります。よって、grouping by tag として host を指定した上でシステム全体が高負荷になると、ホストの数だけアラートを受け取ることになります。

クエリの評価期間・評価方法・アラート条件の指定

モニタリングすべきクエリを決めたら、次は評価期間、評価方法、アラートの条件を指定する必要があります。
これらについては、まずは Configure Monitors を一読してください。

以下、ドキュメントの内容に対する補足です。

クエリの結果はどう処理されるのか？

クエリにも avg 等の集約関数が出てきましたが、モニターを作成する際にはクエリの結果の評価方法でも avg などが出てくるのが初心者にとってわかりにくい内容かと思います。

例えば、avg:system.load.1{*} というクエリの結果が 2 分間ずっと 1 を超えていたらアラートを受け取りたいとします。つまり、2 分間の最小値が 1 を超えた場合ですね。

Web UI 上だと次のように指定します。

式で表現すると min(last_2m):avg:system.load.1{*} > 1 です。

例えば、3 つのホストが存在し、それぞれのホストのメトリクスが次のようになっていたとします。

datetime	i-0ba82eddc862f3795	i-0da62b250aad43710	i-0f05b9b48bcbba766
2022-11-06T14:52:36Z	0.000	1.350	0.463
2022-11-06T14:52:50Z	0.000	1.070	0.790
2022-11-06T14:52:51Z	0.000	1.050	0.808
2022-11-06T14:53:05Z	0.000	0.835	1.060
2022-11-06T14:53:06Z	0.000	0.820	1.074
2022-11-06T14:53:20Z	0.000	0.643	1.270
2022-11-06T14:53:21Z	0.000	0.630	1.281
2022-11-06T14:53:35Z	0.000	0.499	1.430
2022-11-06T14:53:36Z	0.000	0.490	1.439
2022-11-06T14:53:50Z	0.000	0.387	1.560
2022-11-06T14:53:51Z	0.000	0.380	1.567
2022-11-06T14:54:05Z	0.000	0.305	1.660
2022-11-06T14:54:06Z	0.000	0.300	1.665
2022-11-06T14:54:20Z	0.000	0.235	1.730
2022-11-06T14:54:21Z	0.029	0.230	1.705
2022-11-06T14:54:35Z	0.440	0.183	1.350
2022-11-06T14:54:36Z	0.463	0.180	1.339
2022-11-06T14:54:50Z	0.790	0.143	1.180

すると、クエリの結果（平均値）は次のとおりです。

datetime	avg
2022-11-06T14:52:36Z	0.604
2022-11-06T14:52:50Z	0.620
2022-11-06T14:52:51Z	0.619
2022-11-06T14:53:05Z	0.632
2022-11-06T14:53:06Z	0.631
2022-11-06T14:53:20Z	0.638
2022-11-06T14:53:21Z	0.637
2022-11-06T14:53:35Z	0.643
2022-11-06T14:53:36Z	0.643
2022-11-06T14:53:50Z	0.649
2022-11-06T14:53:51Z	0.649
2022-11-06T14:54:05Z	0.655
2022-11-06T14:54:06Z	0.655
2022-11-06T14:54:20Z	0.655
2022-11-06T14:54:21Z	0.655
2022-11-06T14:54:35Z	0.658
2022-11-06T14:54:36Z	0.661
2022-11-06T14:54:50Z	0.704

そして、このクエリの結果の 2 分間の最小値は 0.604 です。これが 1 分ごとに評価されて、その時に 2 を超えていたらアラートを受け取ることになります。あくまで、先にクエリの結果を計算することに注意してください。
1 分ごとに評価されるという話については Evaluation frequency を参照してください。

Notify No Data

Configure Monitors - NO DATA でも言及されているように、notify no data を有効にすることで、モニタリング対象のメトリクスが届かなくなった時にアラートを受け取ることができるので、メトリクスを収集する仕組みが動いてなくて監視できていなかったといった事態を防ぐことができます。grouping by tag を指定している場合はグループごとに no data アラートを受け取ることができます。

どれだけの期間メトリクスが届かなかったらアラートを受け取るようにするかの期間は no_data_timeframe と呼ばれ、評価期間の 2 倍以上を指定することが推奨されています。
次の内容はドキュメントからの引用です。

Note: It is recommended that you set the missing data window to at least two times the evaluation period.

これに従うと評価期間が 1 時間の場合は no_data_timeframe に 2 時間を指定することになるわけですが、流石に長過ぎると思い、2020 年 9 月に問い合わせたところ、次のような回答をもらいました。2 倍を推奨しているのは誤検知防止のためで、評価期間が長い場合は必ずしも 2 倍じゃなくて良さそうです。

It is a general rule of thumb, especially with shorter evaluation windows, as a way to account for any delays or latencies that may not actually mean data is truly missing.

For instance, if you are using a 1 minute evaluation it’s better to have a 2 minute no data window. If you have an hour eval window, having a no data window of 1.5 hours is probably enough

What we really don’t want is to see customers set the same No Data period as the Evaluation Window. This will definitely lead to unwanted behaviour.

なお、no_data_timeframe は大きすぎる値もダメです。次の内容はドキュメントからの引用です。

This option does not work if it is enabled at a time when data has not been reporting for a long period.

Web UI 上では 1440 分より大きな値を指定すると warning が出ます。無視して作成することはできますが…。

1440 分より大きな値を指定した場合の挙動については不明ですが、今の挙動が将来も保証されるとは限らないので 1440 分以下にした方が良いでしょう。

なお、Datadog の AWS 連携には EC2 automuting という機能があり、これを有効にすることで、EC2 インスタンスが terminate する時にそのホストに関するモニターを自動で mute することができます。つまり、auto-scaling するようなクラスタのサーバのメトリクスモニターに対して notify no data を有効にしても、terminate したインスタンスから no data アラートを受け取らずに済むということですね。
もし grouping by tag にホストごとに値が異なるようなタグ（e.g. IP アドレス）を指定した場合、通常であればインスタンスが terminate した後に no data アラートを受け取ることになります。このような場合、冗長ではありますが、grouping by tag に host タグも追加すれば EC2 automuting が効いてアラートを受け取らずに済みます。

ただ、EC2 automuting は時々 mute されるまでに数十分かかることがあったりと、それなりに誤検知があるので、個人的には Event Bridge と Lambda でインスタンスが terminate した時に自前で mute するのが良いと思います。

なお、EC2 automuting があるなら container automuting もあることを期待するかもしれませんが、2018 年 8 月に問い合わせた時点では存在しませんでした。問い合わせた当時は backlog にはあると回答がありましたが、今も存在しない気がします。

The feature you’ve described is currently one that we have in our backlog. I don’t know if it’s scheduled for delivery short-term however, I will follow-up after reviewing with product management.

アラートのメッセージの設定

アラートのメッセージや通知先の設定方法については Notifications のうち、Title、Message、Notifications は最低限読むべき内容です。メッセージの内容に変数を埋め込みたい場合や、alert、warn、no data 等モニターの状態の変化に応じてメッセージの内容や通知先を変えたい場合は Variables も読むと良いでしょう。
Web UI 上だと補完が効くので、慣れるまでは Web UI を使うことを推奨します。

ここではよく連携されているであろう Slack と PagerDuty について注意点を補足します。

Slack

Slack では @slack-<channel-name> をメッセージに含めることで、指定した Slack チャンネルにメッセージを流すことができますが、Slack 連携でチャンネルを追加しない限り通知されません。既存のモニターの設定をコピペして雰囲気で修正するとハマるので注意してください。

次の例では Slack 連携として notification チャンネルしか追加されていないので、他のチャンネルの名前を指定すると warning が表示されています。

こういったミスに気付けるのも Web UI の良いところです。

なお、追加されているチャンネルであれば、次のように variable が展開された内容を受け取ることができます。

Slack 連携のページでは、メッセージに含まれる内容をチャンネルごとに選択できます。Message、Snapshot、Tags、Notified、Muting のうち、Tags、Notified は一目瞭然だと思うので、残りの項目がどの内容に対応するかを下図に示します。

PagerDuty

PagerDuty も PagerDuty 連携で service を追加しないといけません。
service を追加すると、@pagerduty-<service-name> に通知することで incident が作成され、@pagerduty-resolve に通知することで incident が resolve されます。
よって、メッセージの基本形は次のようになるでしょう。

{{#is_alert}} @pagerduty-<service-name> {{/is_alert}}
{{#is_recovery}} @pagerduty-resolve {{/is_recovery}}

incident を作成する際にはサービスごとに通知先を変える必要がありますが、resolve する際には @pagerduty-resolve だけで大丈夫なことに注意してください。

ただし、次のように alert と warn で別々の incident が作成されるようにした場合、@pagerduty-resolve で resolve されるのは最後に作成された incident だけで、最初に作成された incident は resolve されません。

{{#is_alert}} @pagerduty-<service-name> {{/is_alert}}
{{#is_warn}} @pagerduty-<another-service-name> {{/is_warn}}
{{#is_recovery}} @pagerduty-resolve {{/is_recovery}}

Terraform で Datadog モニターを管理する際の注意点

Terraform で Datadog のモニターを管理する場合は datadog_monitor resource を使います。
Web UI による補助がなかったり、terraform-provider-datadog 特有の設定があったりするので、次のことに注意してください。

no_data_timeframe のデフォルトが評価期間に関係なく 10 で固定になる
- Web UI や API では評価期間の 2 倍 (cf. Monitor API Options)
no_data_timeframe に 1440 より大きな値を指定してもモニターを作成できてしまう
- Web UI からも 1440 より大きな値でモニターを作成できるが、warning が表示されるので気付くことができる
require_full_window のデフォルト値が true
- cf. datadog/resource_datadog_monitor.go#L263-L268
  - フィールドの description には評価方法によってデフォルト値が代わるようなことが書いてあるが、無条件でデフォルト true であることに注意
- Web UI や API では false (cf. Monitor API Options)
- full window の概念については Data Window 参照
Slack 等のメンションで存在しないメンションを指定できてしまう
- 指定したメンションが本当に存在するか確認すべき
クエリの閾値と monitor_thresholds の critical は同じ値にしなければならない
- monitor_thresholds.critical だけ変更してクエリの修正を忘れがち
datadog_downtime resource で recurrence を指定すると、繰り返す度に新しい ID の downtime が作成されるので terraform でまともに管理できない

知っておくと良いかもしれない豆知識

最後に、自分が今までにモニターを作成する際に役に立った知識やハマった内容などを共有します。

メトリクスの定義の調べ方

メトリクスの意味について知りたい場合、まずは Datadog のドキュメントを参照すると思うんですが、メトリクスの定義を読んでもよく理解できないことがあると思います。そんな時は次のリポジトリを覗いてみると良いです。

例えば、MySQL integration を有効にすると Data Collected に載っているようなメトリクスが収集されるわけですが、InnoDB 関係のメトリクスは innodb_metrics.py で取得していることが雰囲気でわかると思います。

ところで、会社名やサービス名は Datadog なのにリポジトリの organization が DataDog なのは紛らわしいですね…

クエリの結果はメトリクスが届かなくなった場合に 5 分間最後の値が外挿される

Datadog はデータが届かなくても、デフォルトで 5 分間最後の値を外挿します。
cf. Interpolation and the Fill Modifier

例えば、高負荷な状態で EC2 インスタンスが terminate すると、高負荷な状態が 5 分間続いているように見えるわけです。これが原因で、terminate した後のインスタンスのアラートを受け取ってしまうかもしれません。
これを避けるには fill(null) を指定したり、fill(last, 60) 等、デフォルトの 5 分より短い間補完するようにしたりすると良いでしょう。

Datadog のグラフはデフォルトで平均値が表示される

例えば system.load.1 のモニターの閾値を決めるために、直近 1 週間の最大値を確認するとします。その場合、まずは notebook 等で max:system.load.1{*} のグラフを作成して、直近 1 週間のグラフを確認するかもしれませんが、それでは最大値を確認することはできません。Datadog は長期間のメトリクスを表示する際にデータポイントを間引くからです。その際にデフォルトで平均値が使われます。

When graphing, Datadog imposes a limit on the number of points per graph. To respect this limit, Datadog rolls up data points automatically with the avg method, effectively displaying the average of all data points within a time interval for a given metric.

cf. Rollup interval: enforced vs custom

もし最大値を確認したいなら max:system.load.1{*}.rollup(max) とする必要があります。

次のグラフは上が max:system.load.1{*} で、下が max:system.load.1{*}.rollup(max) で、グラフの形はほぼ同じですが、上記の理由から縦軸が異なります。

CloudWatch から取得しているメトリクスの評価期間の推奨値は 1 時間以上

Datadog では AWS の連携を有効にすると、CloudWatch のメトリクスを取り込むことができます。このメトリクスに対して 1 時間未満の評価期間を指定すると次のような warning が出ます。

Note: The selected metric provides data at low frequencies. We strongly recommend alerting on at least a 1 hour time frame.

CloudWatch のメトリクス自体は解像度が 1 分なので疑問に思い問い合わせたところ、これは Datadog が CloudWatch のメトリクスを 10 分間隔で取得していることから、そのタイムラグを考慮しての推奨値みたいです。2018 年 7 月に問い合わせた時の回答は次のとおり。

This is related to the delay from the AWS integration.

If you receive 5-minute metrics from CloudWatch, there can be up to ~15-20 min delay in receiving your metrics. This is because CloudWatch makes your data available with a 5-10 minute latency, and we run the crawler every 10 minutes. More information related to this can also be found here https://docs.datadoghq.com/integrations/faq/are-my-aws-cloudwatch-metrics-delayed/

評価期間を 1 時間にすることが許容できない場合は、誤検知を覚悟の上で評価期間を短くするか、AWS CloudWatch Metric Streams with Kinesis Data Firehose を検討すると良いかもしれません（未検証）。

なお、クローリング間隔はサポートにお願いすれば短くしてもらえるかもしれません。短くすることで CloudWatch のコストはかかるようになりますが。

モニターで使われているクエリの結果と評価値がずれることがある

モニターには History という項目と、EVALUATION GRAPGH という項目がありますが、History がクエリの結果で、枠で囲まれた範囲の評価値が EVALUATION GRAPGH に表示されています。

つまり、評価値がアラートの条件に引っかかった場合に、History の内容から原因を調査できるんですが、過去に、History の内容的にあり得ない EVALUATION GRAPGH になることがありました。サポートに問い合わせたところ、このクエリは 4 つのクエリの結果を組み合わせたものであったこともあり、クエリの結果が出揃う前に評価してしまうことがあったようです。この時はサポートのアドバイスに従って、Evaluation options でモニターの評価を遅らせたことで意図した結果が得られるようになりました。

質問内容

I have a monitor to detect the increase of a certain ratio.

It monitors “min(last_10m): ( the current ratio / the ratio 1 hour before )”.
Its historical values displayed in the graph are usually less than 2.0, but the evaluated value, in other words, the minimum value for 10 minutes, is sometimes greater than 4.0.

Why do evaluated values significantly differ from historical values?

回答

Thanks for your patience on this! After digging into the issue you’re experiencing and running some commands in our backend, I believe these random spikes that are happening are due to the size of the query. The full query has four sets of metrics and a formula which can take an extra bit of time to fully query and compute this request and then have the monitor evaluate.

To avoid these unintended spikes, I suggest delaying the evaluation by 30-60 seconds to provide adequate time for the data to be computed before the evaluation happens.

Docker コンテナの CPU 使用率のモニタリングは難しい

ECS などを利用している場合、タスクやコンテナの負荷を見るのに docker.cpu.usage を使っている方もいるでしょう。このメトリクスが少しわかりにくいので補足します。

注意点は次の 2 点です。

docker.cpu.usage の最大値はコア数 x 100
- system.cpu.user はコア数が何個でも最大値は 100 だが、docker.cpu.usage はコア数によって変わることに注意
ECS タスク等で各コンテナへの CPU の割当が少なかったとしても、最大値はコア数 x 100 になり得る
- ECS の task definition の cpu は docker コマンドの --cpu-shares に相当し、cgroup の cpu.shares に相当するので、CPU が空いていれば無制限に使用する

例えば、ある ECS タスクに A, B, C の 3 つのコンテナが存在し、それぞれ CPU の割当が 1024、512、512 だったとします。この ECS タスクが 2 コアの ECS インスタンスで動いていて、コンテナ A がマルチスレッドで動くことができる場合、docker.cpu.usage は 100 を超えて 200 になる可能性があります。仮にコンテナ A、B、C の docker.cpu.usage がそれぞれ 150、0、0 だった場合、コンテナインスタンスの CPU 使用率は 75% です。一方で、全コンテナが全力で CPU を使うと、コンテナインスタンスの CPU 使用率は 100% になり、cpu.shares が効いてくるので、A、B、C の docker.cpu.usage はそれぞれ 100、50、50 になります。
コンテナ A だけの docker.cpu.usage に着目した場合、150 の時の方が高負荷に見えますが、ECS タスク全体として見た場合、実は 100 の時の方が高負荷なわけです。

じゃあ、sum:docker.cpu.usage{*} by {host,task_name} をモニタリングすれば良いと思うかもしれませんが、これも複数のタスクが同じコンテナインスタンスに同居する場合に上手く行きません。
また、Docker のメトリクスにはロードアベレージに相当するものがないので、docker.cpu.usage が高いのは 1 プロセスが CPU を専有しているのか、run queue が詰まっているのか判断が付きません。

というわけで、個人的に負荷をモニタリングしたいのであれば、100 - system.cpu.idle や system.load.norm.1 をモニタリングしつつ、問題が起きた時の調査に docker.cpu.usage を使うだけにとどめて、docker.cpu.usage をメトリクスモニターに使うのはやめた方が良いんじゃないかと思います。

おまけ〜定期的に負荷のかかるサーバのメトリクスを収集する〜

今回例に出したメトリクスの値は、次の tf ファイルでリソースを作成することで収集しました。3 つの EC2 インスタンスを起動し、Datadog agent をインストールし、maintenance window で 10 分に 1 回順番に 2 分間 stress コマンドで負荷をかけています。

provider "aws" {
  region = "ap-northeast-1"
}

variable "datadog_api_key" {}
variable "key_name" {}
variable "security_group_id" {}

resource "aws_iam_role" "StressTest" {
  name = "StressTest"

  assume_role_policy = <<-EOF
  {
    "Version":"2012-10-17",
    "Statement":[
      {
        "Effect":"Allow",
        "Principal": {
          "Service": [
            "ec2.amazonaws.com"
          ]
        },
        "Action":"sts:AssumeRole"
      }
    ]
  }
  EOF
}

resource "aws_iam_role_policy" "datadog" {
  name = "Datadog"
  role = aws_iam_role.StressTest.id

  policy = <<-EOF
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeInstances",
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeTags"
        ],
        "Resource": "*"
      }
    ]
  }
  EOF
}

resource "aws_iam_role_policy_attachment" "AmazonSSMManagedInstanceCore" {
  role       = aws_iam_role.StressTest.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
}

resource "aws_iam_instance_profile" "StressTest" {
  name = "StressTest"
  role = aws_iam_role.StressTest.id
}

data "aws_ami" "amazon_linux_2" {
  most_recent = true

  filter {
    name   = "name"
    values = ["amzn2-ami-kernel-5.10-hvm-2.0.*-x86_64-gp2"]
  }

  owners = ["amazon"]
}

resource "aws_launch_template" "stress" {
  image_id = data.aws_ami.amazon_linux_2.id

  instance_type = "t3.micro"

  iam_instance_profile {
    name = aws_iam_instance_profile.StressTest.id
  }

  key_name = var.key_name

  vpc_security_group_ids = [var.security_group_id]

  instance_market_options {
    market_type = "spot"
  }

  user_data = base64encode(<<-EOF
  #!/bin/bash

  DD_AGENT_MAJOR_VERSION=7 DD_API_KEY=${var.datadog_api_key} DD_SITE="datadoghq.com" bash -c "$(curl -L https://s3.amazonaws.com/dd-agent/scripts/install_script.sh)"
  sed -i 's/^# collect_ec2_tags: false/collect_ec2_tags: true/' datadog.yaml
  systemctl restart datadog-agent

  yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
  yum install -y stress
  EOF
  )
}

data "aws_subnet" "subnet_1a" {
  filter {
    name   = "default-for-az"
    values = ["true"]
  }

  filter {
    name   = "availability-zone"
    values = ["ap-northeast-1a"]
  }
}

data "aws_subnet" "subnet_1c" {
  filter {
    name   = "default-for-az"
    values = ["true"]
  }

  filter {
    name   = "availability-zone"
    values = ["ap-northeast-1c"]
  }
}

data "aws_subnet" "subnet_1d" {
  filter {
    name   = "default-for-az"
    values = ["true"]
  }

  filter {
    name   = "availability-zone"
    values = ["ap-northeast-1d"]
  }
}

resource "aws_autoscaling_group" "stress" {
  name = "stress"

  desired_capacity = 3
  min_size         = 3
  max_size         = 3

  vpc_zone_identifier = [data.aws_subnet.subnet_1a.id, data.aws_subnet.subnet_1c.id, data.aws_subnet.subnet_1d.id]

  tag {
    key                 = "MaintenanceTarget"
    value               = "true"
    propagate_at_launch = true
  }

  launch_template {
    id      = aws_launch_template.stress.id
    version = "$Latest"
  }
}

resource "aws_iam_role" "AmazonSSMMaintenanceWindowRole" {
  name = "AmazonSSMMaintenanceWindowRole"

  assume_role_policy = <<-EOF
  {
    "Version":"2012-10-17",
    "Statement":[
      {
        "Effect":"Allow",
        "Principal": {
          "Service": [
            "ssm.amazonaws.com"
          ]
        },
        "Action":"sts:AssumeRole"
      }
    ]
  }
  EOF
}

resource "aws_iam_role_policy_attachment" "AmazonSSMMaintenanceWindowRole" {
  role       = aws_iam_role.AmazonSSMMaintenanceWindowRole.id
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonSSMMaintenanceWindowRole"
}

resource "aws_ssm_maintenance_window" "mw_stress" {
  name              = "mw-stress"
  schedule          = "cron(0 */10 * * * ? *)"
  schedule_timezone = "Etc/UTC"
  duration          = 2
  cutoff            = 1
}

resource "aws_ssm_maintenance_window_task" "mw_stress" {
  window_id        = aws_ssm_maintenance_window.mw_stress.id
  name             = "mw_stress"
  task_type        = "RUN_COMMAND"
  task_arn         = "AWS-RunShellScript"
  priority         = 1
  service_role_arn = aws_iam_role.AmazonSSMMaintenanceWindowRole.arn
  max_concurrency  = 1
  max_errors       = "100%"

  targets {
    key    = "WindowTargetIds"
    values = ["${aws_ssm_maintenance_window_target.mw_stress.id}"]
  }

  task_invocation_parameters {
    run_command_parameters {
      parameter {
        name = "commands"
        values = [
          "stress -c 2 -t 120"
        ]
      }
    }
  }
}

resource "aws_ssm_maintenance_window_target" "mw_stress" {
  window_id     = aws_ssm_maintenance_window.mw_stress.id
  resource_type = "INSTANCE"

  targets {
    key    = "tag:MaintenanceTarget"
    values = ["true"]
  }
}

なお、本文中のテーブルは次のようなスクリプトで生成しています。

# https://docs.datadoghq.com/api/latest/metrics/
require 'datadog_api_client'
%w[DD_API_KEY DD_APP_KEY].each do |env|
  ENV.fetch(env) { raise %Q{"#{env} is required} }
end

AGGS = %w[min avg max]

api_instance = DatadogAPIClient::V1::MetricsAPI.new
from = Time.parse('2022-11-06T14:52:36Z').to_i
to = from + 135

AGGS.each do |agg|
  resp = api_instance.query_metrics(from, to, "#{agg}:system.load.1{*} by {host}.rollup(max, 20)")

  time_to_values = Hash.new { |h, v| h[v] = {} }

  resp.series.each do |series|
    host = series.scope.split(':').last
    series.pointlist.each do |t, v|
      time_to_values[t][host] = '%.3f' % v
    end
  end

  puts agg
  puts ''


  hosts = %w[i-0ba82eddc862f3795 i-0da62b250aad43710 i-0f05b9b48bcbba766]
  puts "datetime | #{hosts.join(' | ')}"
  puts "--------|--------|--------|--------"
  time_to_values.sort_by(&:first).each do |t, values|
    puts [Time.at(t / 1_000).utc.iso8601, *values.values_at(*hosts)].join(' | ')
  end

  puts ''
end

time_to_values = Hash.new { |h, v| h[v] = {} }

AGGS.each do |agg|
  resp = api_instance.query_metrics(from, to, "#{agg}:system.load.1{*}.rollup(max, 20)")
  resp.series[0].pointlist.each do |t, v|
    time_to_values[t][agg] = '%.3f' % v
  end
end

puts "datetime | #{AGGS.join(' | ')}"
puts "--------|--------|--------|--------"
time_to_values.sort_by(&:first).each do |t, values|
  puts [Time.at(t / 1_000).utc.iso8601, *values.values_at(*AGGS)].join(' | ')
end

Fluentd 終了時に起きる "[!] There was an error parsing `Gemfile`: SIGTERM. Bundler cannot continue." を握り潰す

Fri, 04 Nov 2022 00:00:00 +0900

Fluentd が終了する時に次のようなエラーに遭遇することがあります。

/private/tmp/fluentd/Gemfile:13:in `sleep':  (Bundler::Dsl::DSLError)
[!] There was an error parsing `Gemfile`: SIGTERM. Bundler cannot continue.

 #  from /private/tmp/fluentd/Gemfile:13
 #  -------------------------------------------
 #  $stderr.puts "#{File.basename($PROGRAM_NAME)}: sleep 1"
 >  sleep 1
 #  -------------------------------------------
        from /private/tmp/fluentd/Gemfile:13:in `eval_gemfile'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:47:in `instance_eval'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:47:in `eval_gemfile'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:12:in `evaluate'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/definition.rb:33:in `build'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler.rb:195:in `definition'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler.rb:143:in `setup'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/setup.rb:20:in `block in <top (required)>'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/ui/shell.rb:136:in `with_level'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/ui/shell.rb:88:in `silence'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/setup.rb:20:in `<top (required)>'
        from <internal:/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/rubygems/core_ext/kernel_require.rb>:85:in `require'
        from <internal:/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/rubygems/core_ext/kernel_require.rb>:85:in `require'
/private/tmp/fluentd/Gemfile:13:in `sleep': SIGTERM (SignalException)
        from /private/tmp/fluentd/Gemfile:13:in `eval_gemfile'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:47:in `instance_eval'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:47:in `eval_gemfile'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:12:in `evaluate'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/definition.rb:33:in `build'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler.rb:195:in `definition'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler.rb:143:in `setup'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/setup.rb:20:in `block in <top (required)>'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/ui/shell.rb:136:in `with_level'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/ui/shell.rb:88:in `silence'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/setup.rb:20:in `<top (required)>'
        from <internal:/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/rubygems/core_ext/kernel_require.rb>:85:in `require'
        from <internal:/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/rubygems/core_ext/kernel_require.rb>:85:in `require'

stacktrace を見ると Fluentd が起動せずに Gemfile を処理するところで stuck してしまっているのではないかと不安になりますよね！このエラーがどういう時に起きるエラーで、どうすれば無視できるかについて解説します。

どういう時に起きるエラーなのか？

exec output plugin 等、外部プログラムを呼び出す plugin で、Ruby のスクリプトを処理している最中、中でも Gemfile を処理している最中に Fluentd が終了すると起きるエラーです。exec output plugin に関して言えば、プログラムがエラー終了した場合は rollback するようになっているので、file buffer で管理していれば Fluentd が再度起動した後に再処理されます。memory buffer を使っていたり、Fluentd が起動することがなかったりすれば、flush できなかったデータは消失することになります。
なので、問題があるかどうかはデータの性質や Fluentd の運用方法次第ですが、Fluentd 本体のエラーではありません。

再現手順

次の設定ファイルで再現できます。

fluent.conf

<source>
  @type sample
  tag test
</source>

<match>
  @type exec
  command "ruby main.rb" # main.rb の内容は何でも良い
  <format>
    @type json
  </format>
  <buffer>
    flush_interval 2s
  </buffer>
</match>

Gemfile

# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

gem "fluentd"

if File.basename($PROGRAM_NAME) == "main.rb"
  Thread.start { Process.kill(:TERM, Process.ppid) }
end
$stderr.puts "#{File.basename($PROGRAM_NAME)}: sleep 1"
sleep 1

実行してみます。

% fluentd -c fluent.conf --gemfile Gemfile
bundle: sleep 1
bundle: sleep 1
Using bundler 2.2.22
Using concurrent-ruby 1.1.10
Using cool.io 1.7.1
Using http_parser.rb 0.8.0
Using msgpack 1.6.0
Using sigdump 0.2.4
Using serverengine 2.3.0
Using strptime 0.2.5
Using tzinfo 2.0.5
Using tzinfo-data 1.2022.6
Using webrick 1.7.0
Using yajl-ruby 1.4.3
Using fluentd 1.15.3
Bundle complete! 1 Gemfile dependency, 13 gems now installed.
Bundled gems are installed into `./vendor/bundle`
fluentd.rb: sleep 1
2022-11-04 02:30:54 +0900 [info]: init supervisor logger path=nil rotate_age=nil rotate_size=nil
2022-11-04 02:30:54 +0900 [info]: parsing config file is succeeded path="fluent.conf"
2022-11-04 02:30:54 +0900 [info]: gem 'fluentd' version '1.15.3'
2022-11-04 02:30:54 +0900 [info]: Oj isn't installed, fallback to Yajl as json parser
2022-11-04 02:30:54 +0900 [warn]: both of Plugin @id and path for <storage> are not specified. Using on-memory store.
2022-11-04 02:30:54 +0900 [warn]: both of Plugin @id and path for <storage> are not specified. Using on-memory store.
2022-11-04 02:30:54 +0900 [warn]: define <match fluent.**> to capture fluentd logs in top level is deprecated. Use <label @FLUENT_LOG> instead
2022-11-04 02:30:54 +0900 [info]: using configuration file: <ROOT>
  <source>
    @type sample
    tag "test"
  </source>
  <match>
    @type exec
    command "ruby main.rb"
    <format>
      @type "json"
    </format>
    <buffer>
      flush_interval 2s
    </buffer>
  </match>
</ROOT>
2022-11-04 02:30:54 +0900 [info]: starting fluentd-1.15.3 pid=79643 ruby="3.0.2"
2022-11-04 02:30:54 +0900 [info]: spawn command to main:  cmdline=["/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/bin/ruby", "-r/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/setup", "-Eascii-8bit:ascii-8bit", "/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/fluentd-1.15.3/lib/fluent/command/fluentd.rb", "-c", "fluent.conf", "--gemfile", "Gemfile", "--under-supervisor"]
2022-11-04 02:30:54 +0900 [info]: init supervisor logger path=nil rotate_age=nil rotate_size=nil
fluentd.rb: sleep 1
2022-11-04 02:30:56 +0900 [info]: #0 init worker0 logger path=nil rotate_age=nil rotate_size=nil
2022-11-04 02:30:56 +0900 [info]: adding match pattern="**" type="exec"
2022-11-04 02:30:56 +0900 [info]: #0 Oj isn't installed, fallback to Yajl as json parser
2022-11-04 02:30:56 +0900 [info]: adding source type="sample"
2022-11-04 02:30:56 +0900 [warn]: #0 both of Plugin @id and path for <storage> are not specified. Using on-memory store.
2022-11-04 02:30:56 +0900 [warn]: #0 both of Plugin @id and path for <storage> are not specified. Using on-memory store.
2022-11-04 02:30:56 +0900 [warn]: #0 define <match fluent.**> to capture fluentd logs in top level is deprecated. Use <label @FLUENT_LOG> instead
2022-11-04 02:30:56 +0900 [info]: #0 starting fluentd worker pid=79678 ppid=79643 worker=0
2022-11-04 02:30:56 +0900 [info]: #0 fluentd worker is now running worker=0
main.rb: sleep 1
2022-11-04 02:30:59 +0900 [info]: #0 fluentd worker is now stopping worker=0
2022-11-04 02:30:59 +0900 [info]: #0 shutting down fluentd worker worker=0
2022-11-04 02:30:59 +0900 [info]: #0 shutting down input plugin type=:sample plugin_id="object:960"
main.rb: sleep 1
2022-11-04 02:31:00 +0900 [info]: #0 shutting down output plugin type=:exec plugin_id="object:938"
/private/tmp/fluentd/Gemfile:13:in `sleep':  (Bundler::Dsl::DSLError)
[!] There was an error parsing `Gemfile`: SIGTERM. Bundler cannot continue.

 #  from /private/tmp/fluentd/Gemfile:13
 #  -------------------------------------------
 #  $stderr.puts "#{File.basename($PROGRAM_NAME)}: sleep 1"
 >  sleep 1
 #  -------------------------------------------
        from /private/tmp/fluentd/Gemfile:13:in `eval_gemfile'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/3.0.0/bundler/dsl.rb:47:in `instance_eval'
-- snip --

ruby main.rb は bundle exec 経由で呼び出されていないから Gemfile が処理されているのはおかしいと思う方もいるかもしれませんが、fluentd は --gemfile が指定されていると、起動時に BUNDLE_GEMFILE をセットし、bundle exec 経由で再度プロセスを起動します。そうすると、起動したプロセスには依然として BUNDLE_GEMFILE がセットされた状態だし、RUBYOPT に -r/path/to/bundler/setup のような値がセットされるので、そのプロセスが起動した子プロセスや孫プロセスも bundle exec 経由で実行するのと同じ効果が得られます。
よって、もし bundler を経由したくなければ RUBYOPT='' ruby main.rb とすることで回避できます。

エラーメッセージを握り潰す

Gemfile を次のように begin で囲んで SignalException を rescue し、$stderr を $stdout に差し替えるのが一番無難なんじゃないかと思います。握り潰すというよりは、不安を煽る仰々しい stacktrace の代わりに 1 行シグナルを受け取った旨を出す感じですね。

# frozen_string_literal: true

begin
  source "https://rubygems.org"

  git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

  ...
rescue SignalException => e
  $stderr.puts "#{File.basename($PROGRAM_NAME)}: Received SIG#{Signal.signame(e.signo)} while parsing Gemfile"
  # Suppress the error "There was an error ..." from Bundler::Dsl
  $stderr = $stdout
  raise e
end

どうしてわざわざ $stderr を $stdout にしているかというと、exec output plugin に関して言えば、標準エラー出力をハンドリングしておらず、子プロセスが標準エラー出力に吐いた内容がそのまま表示されてしまうからです。内容を握り潰せれば良いので、File.open(File::NULL, 'w') や StringIO.new でも良いとは思います。

なお、exit も試してみたんですが、依然終了時にエラーメッセージが出てしまいました。bundler は一般的には rescue しない Exception を rescue しているからみたいですね。
cf. bundler/dsl.rb#L41-L56

以上、同じ不安を抱えている人の不安解消になれば幸いです。

MySQL で複合インデックスを作成する際には必ず Explain の key_len を確認すべきという話

Fri, 03 Jun 2022 00:00:00 +0900

「Rails Developers Meetup 2018 で「MySQL/InnoDB の裏側」を発表しました」でちゃんと触れられてないので今更ながら key_len について補足します。発表で触れた内容については言及しないので、storage engine や B+ tree といった用語がよくわからない方は発表内容を参照してください。
なお、MySQL のバージョンは 5.7.38 です。

mysql> SELECT @@version;
+-----------+
| @@version |
+-----------+
| 5.7.38    |
+-----------+
1 row in set (0.00 sec)

事前準備

sample-data-railsdm-2018 の orders テーブルを少しいじって、キャンセル時刻（canceled_at）、配送予定時刻（delivered_at）カラムを追加してみます。また、同じ商品に対する注文の数を増やしてみます。
具体的には次のような変更を加えます。

diff --git a/Rakefile b/Rakefile
index 6d1d89d..01df6dd 100644
--- a/Rakefile
+++ b/Rakefile
@@ -35,8 +35,8 @@ namespace :db do
 
     user_count    = 100
     shop_count    = 10
-    product_count = 5_000
-    order_count   = 10_000
+    product_count = 10
+    order_count   = 200_000
 
     prng = Random.new(42)
     Faker::Config.random = prng
@@ -71,11 +71,13 @@ namespace :db do
       product_id = prng.rand(product_count) + 1
       count = (prng.rand(5) + 1)
       product = id_to_product[product_id]
+      created_at = Faker::Time.between_dates(from: product.started_at, to: product.ended_at)
       orders << {
         user_id: user_id,
         product_id: product_id,
         count: count,
-        created_at: Faker::Time.between_dates(from: product.started_at, to: product.ended_at),
+        created_at: created_at,
+        delivered_at: created_at + 86400 * (prng.rand(7) + 1),
       }
       if orders.size == 1_000
         Order.insert_all!(orders)
diff --git a/Schemafile b/Schemafile
index b40e65f..1327c6d 100644
--- a/Schemafile
+++ b/Schemafile
@@ -19,9 +19,12 @@ add_foreign_key 'products', 'shops',           name: 'fk_products_shops'
 
 create_table 'orders', unsigned: true, force: :cascade do |t|
   t.references 'user',       unsigned: true, null: false
-  t.references 'product',    unsigned: true, null: false
+  t.references 'product',    unsigned: true, null: false, index: false
   t.integer    'count',      unsigned: true, null: false
-  t.datetime   'created_at', precision: 0,   null: false
+  t.datetime   'created_at',   precision: 0, null: false
+  t.datetime   'canceled_at',  precision: 0
+  t.datetime   'delivered_at', precision: 0, null: false
 end
+add_index 'orders', ['product_id', 'canceled_at', 'delivered_at'], name: 'ix_product_id_canceled_at_delivered_at'
 add_foreign_key 'orders', 'users',    name: 'fk_orders_users'
 add_foreign_key 'orders', 'products', name: 'fk_orders_products'

最終的なテーブルの定義は次のとおりです。

CREATE TABLE `orders` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `user_id` bigint(8) unsigned NOT NULL,
  `product_id` bigint(8) unsigned NOT NULL,
  `count` int(10) unsigned NOT NULL,
  `created_at` datetime NOT NULL,
  `canceled_at` datetime DEFAULT NULL,
  `delivered_at` datetime NOT NULL,
  PRIMARY KEY (`id`),
  KEY `ix_product_id_canceled_at_delivered_at` (`product_id`,`canceled_at`,`delivered_at`),
  KEY `index_orders_on_user_id` (`user_id`),
  CONSTRAINT `fk_orders_products` FOREIGN KEY (`product_id`) REFERENCES `products` (`id`),
  CONSTRAINT `fk_orders_users` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=200001 DEFAULT CHARSET=utf8;

key_len とは何か

key_len は explain に表示される情報の 1 項目で、storage engine が B+ tree を辿る際にインデックスの先頭何バイトを使ったかを意味します。
例えば、explain の結果が次のようになったとします。

*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: orders
   partitions: NULL
         type: range
possible_keys: ix_product_id_canceled_at_delivered_at
          key: ix_product_id_canceled_at_delivered_at
      key_len: 19
          ref: NULL
         rows: 17190
     filtered: 100.00
        Extra: Using index condition
1 row in set, 1 warning (0.00 sec)

ix_product_id_canceled_at_delivered_at は (product_id, canceled_at, delivered_at) から成る複合インデックスで、product_id は非 null な bigint なので 8 バイト、canceled_at は nullable な datetime なので 6 バイト、delivered_at は非 null な datetime なので 5 バイトであるため、合計 19 バイトです。
つまり、上記の explain の結果から、この SQL はインデックスを構成する 3 カラム全ての情報が使われていることがわかります。もし他の SQL で key_len が 8 になったら、それは 1 カラムの情報しか使われていないことを意味します。同様に、key_len が 14 なら 2 カラムです。

なお、各型のサイズは MySQL :: MySQL 5.7 Reference Manual :: 11.7 Data Type Storage Requirements に記載されています。
nullable なカラムは通常の型のサイズに加えて 1 バイトか 2 バイト必要です。

An SQL NULL value reserves one or two bytes in the record directory. An SQL NULL value reserves zero bytes in the data part of the record if stored in a variable-length column. For a fixed-length column, the fixed length of the column is reserved in the data part of the record. Reserving fixed space for NULL values permits columns to be updated in place from NULL to non-NULL values without causing index page fragmentation.

cf. MySQL :: MySQL 5.7 Reference Manual :: 14.11 InnoDB Row Formats

key_len の例

例えば、次の商品を取得するのに必要な SQL を考えます。

商品 ID が 1
キャンセルされていない
配送予定時刻が 2018-04-01 00:00:00 以降

SELECT
  *
FROM
  orders
WHERE
  product_id = 1
  AND canceled_at IS NULL
  AND delivered_at >= '2018-04-01 00:00:00'
;

この SQL の explain 結果は次のとおりです。

*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: orders
   partitions: NULL
         type: range
possible_keys: ix_product_id_canceled_at_delivered_at
          key: ix_product_id_canceled_at_delivered_at
      key_len: 19
          ref: NULL
         rows: 17190
     filtered: 100.00
        Extra: Using index condition
1 row in set, 1 warning (0.00 sec)

これは key_len の説明で使用した explain 結果で、前述のとおり、この SQL ではインデックスを構成する 3 カラム全ての情報が使われていることがわかります。

ここで、元の SQL から canceled_at の条件を外してみます。

SELECT
  *
FROM
  orders
WHERE
  product_id = 1
  AND delivered_at >= '2018-04-01 00:00:00'
;

すると、explain の結果は次のように変わります。

*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: orders
   partitions: NULL
         type: ref
possible_keys: ix_product_id_canceled_at_delivered_at
          key: ix_product_id_canceled_at_delivered_at
      key_len: 8
          ref: const
         rows: 42826
     filtered: 33.33
        Extra: Using index condition
1 row in set, 1 warning (0.01 sec)

key_len が 8 になったので、product_id の情報のみが使われていることがわかります。canceled_at が NULL のレコードも非 NULL のレコードも全て取得する必要があるので当然ですね。ICP で delivered_at の条件が使われるので、クラスタインデックスへのアクセスは減らせますが、key_len が 19 の場合に比べると B+ tree から受けられる恩恵は少ないです。
もしインデックスを最大限利用したい場合は (product_id, delivered_at) の複合インデックスを別途作成する必要があります。

今度は次のような SQL を考えます。

SELECT
  *
FROM
  orders
  INNER JOIN
    products
  ON
    orders.product_id = products.id
WHERE
  canceled_at IS NULL
  AND delivered_at <= '2017-01-01 00:00:00'
  AND shop_id = 3
;

この SQL の explain 結果は次のとおりです。

*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: products
   partitions: NULL
         type: ref
possible_keys: PRIMARY,ix_shop_id_ended_at
          key: ix_shop_id_ended_at
      key_len: 8
          ref: const
         rows: 3
     filtered: 100.00
        Extra: NULL
*************************** 2. row ***************************
           id: 1
  select_type: SIMPLE
        table: orders
   partitions: NULL
         type: ref
possible_keys: ix_product_id_canceled_at_delivered_at
          key: ix_product_id_canceled_at_delivered_at
      key_len: 14
          ref: railsdm2018.products.id,const
         rows: 22179
     filtered: 33.33
        Extra: Using index condition
2 rows in set, 1 warning (0.00 sec)

まず最初に、products テーブルから shop_id = 3 にマッチするレコードを取得しており、rows の情報からマッチしたレコードは 3 レコードです。
次に、取得した product レコードごとに、orders テーブルから条件を満たすレコードを取得しています。ところが、ix_product_id_canceled_at_delivered_at の key_len は 14 であり、delivered_at の情報が使われないことがわかります。実は delivered_at <= '2017-01-01 00:00:00' の条件を満たすレコードは存在しないのですが、delivered_at の情報が使われないこともあって rows は 22179 と大きな数字になっています。

shop_id = 3 にマッチするレコードは次のとおりです。

mysql> SELECT id, name FROM products WHERE shop_id = 3;
+----+------------------------------+
| id | name                         |
+----+------------------------------+
| 10 | Eyeless in Gaza              |
|  6 | The Soldier's Art            |
|  2 | Let Us Now Praise Famous Men |
+----+------------------------------+
3 rows in set (0.00 sec)

MySQL の join は nested loop join であることから、orders テーブルからレコードを取得する処理は、上記の products.id を指定した次の SQL と等価と言えます。

SELECT
  *
FROM
  orders
WHERE
  product_id IN (10, 6, 2)
  AND canceled_at IS NULL
  AND delivered_at <= '2017-01-01 00:00:00'
;

こちらの SQL の explain 結果は次のとおりです。

*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: orders
   partitions: NULL
         type: range
possible_keys: ix_product_id_canceled_at_delivered_at
          key: ix_product_id_canceled_at_delivered_at
      key_len: 19
          ref: NULL
         rows: 3
     filtered: 100.00
        Extra: Using index condition
1 row in set, 1 warning (0.00 sec)

key_len が 19 なので、インデックスを構成する全てのカラムの情報が使われています。rows も 3 に減りました。

JOIN が絡むと key_len が 14 になってしまう理由はよくわかっていないですが、key_len を意識することの重要性がよくわかる例じゃないでしょうか。

なお、上記のようなケースでは、クライアント側で最初に shop_id = 3 にマッチする products.id を取得し、その情報を使って SQL を組み立てる必要があるんじゃないかと思います。key_len を指定するためのヒントがあれば良いんですが…

まとめ

key_len は storage engine が B+ tree を辿る際にインデックスの先頭何バイトを使ったかを意味する
複合インデックスを作成しても、一部のカラムの情報しか使われないことがある
複合インデックスが意図したとおりに使われているか explain で確認することが重要

Stateful Kafka Streams アプリケーションで consumer が増減すると意図しない偏りが発生する理由〜 StreamsPartitionAssignor はいかにタスクを割り当てるのか〜

Mon, 11 Apr 2022 00:00:00 +0900

Stateful Kafka Streams アプリケーション、つまり state store を使った Kafka Streams アプリケーションでは consumer が増減するとタスクの割当が極端に偏ることがあります。その理由について、WordCount の例を使って解説し、運用上の注意点についてまとめます。
なお、Kafka Streams のバージョンは 2.7.2 です。

サンプルアプリケーション

WordCount は次のように入力値を単語に分割し、単語ごとに処理した回数を数えるシンプルなアプリケーションです。

KStream<String, String> source = builder.stream("streams-plaintext-input");
source.flatMapValues(value -> Arrays.asList(value.toLowerCase(Locale.getDefault()).split("\\W+")))
      .groupBy((key, value) -> value)
      .count(Materialized.as("counts-store"))
      .toStream()
      .to("streams-wordcount-output", Produced.with(Serdes.String(), Serdes.Long()));

言葉で説明するのは簡単ではありますが、単語ごとに数を数えるために repartition 用の topic に書き出したり、数えた結果を state store に保存したりしています。

これは topology.describe() で内容を確認するとよくわかります。

Topologies:
   Sub-topology: 0
    Source: KSTREAM-SOURCE-0000000000 (topics: [streams-plaintext-input])
      --> KSTREAM-FLATMAPVALUES-0000000001
    Processor: KSTREAM-FLATMAPVALUES-0000000001 (stores: [])
      --> KSTREAM-KEY-SELECT-0000000002
      <-- KSTREAM-SOURCE-0000000000
    Processor: KSTREAM-KEY-SELECT-0000000002 (stores: [])
      --> counts-store-repartition-filter
      <-- KSTREAM-FLATMAPVALUES-0000000001
    Processor: counts-store-repartition-filter (stores: [])
      --> counts-store-repartition-sink
      <-- KSTREAM-KEY-SELECT-0000000002
    Sink: counts-store-repartition-sink (topic: counts-store-repartition)
      <-- counts-store-repartition-filter

  Sub-topology: 1
    Source: counts-store-repartition-source (topics: [counts-store-repartition])
      --> KSTREAM-AGGREGATE-0000000003
    Processor: KSTREAM-AGGREGATE-0000000003 (stores: [counts-store])
      --> KTABLE-TOSTREAM-0000000007
      <-- counts-store-repartition-source
    Processor: KTABLE-TOSTREAM-0000000007 (stores: [])
      --> KSTREAM-SINK-0000000008
      <-- KSTREAM-AGGREGATE-0000000003
    Sink: KSTREAM-SINK-0000000008 (topic: streams-wordcount-output)
      <-- KTABLE-TOSTREAM-0000000007

これを Kafka Streams Topology Visualizer で可視化すると次のようになります。

WordCount では state store に今までの結果を保存することで、新しい値が来た時にこれまでの結果を取り出し、カウントアップすることができています。このように、state store を使ったアプリケーションは stateful アプリケーションと呼ばれます。

Rebalance

Kafka topic を複数の consumer で処理する場合（グループを形成する場合）、1 partition を 1 consumer だけが処理するよう partition が割り当てられます。よって、consumer が増減すると partition の割り当ても変わります。これを rebalance と呼びます。
rebalance については丁寧な説明がいくらでも見つかると思いますが、例えば Static Membership: Rebalance Strategy Designed for the Cloud - Confluent を参照してもらうとイメージが付きやすいと良いと思います。

なお、この発表で説明されている static membership は、consumer のプロセスを再起動した場合などに rebalance が行われないよう、割り当てる partition を固定する機能です。後述する stateful アプリケーションの問題とも関連する話ですが、consumer が増減した場合とは別の話なので今回は詳しく触れません。

Stateful なアプリケーションの問題

state store は consumer がローカルに持つデータストアで、他の consumer からはアクセスできません。よって、rebalance が行われると state store を復元する必要があります。そのために使われるのが changelog topic と呼ばれる Kafka topic です。これは state store の redo ログみたいなもので、state store に書き込んだ内容を Kafka topic にも書き込むためのものです。
よって、大量のデータが state store に書き込まれると、復元にはそれに応じた時間がかかってしまいます。例えば 1 partition の state store の復元に 1 時間かかるとして、1 consumer が増減しただけで全 partition のアサインが変わると全ての処理が 1 時間止まることになります。

なお、WordCount では次のように streams-wordcount-counts-store-changelog という changelog topic が自動的に作成されます。

% kafka-topics --bootstrap-server localhost:9092 --list
__consumer_offsets
streams-plaintext-input
streams-wordcount-counts-store-changelog
streams-wordcount-counts-store-repartition
streams-wordcount-output

StreamsPartitionAssignor

StreamsPartitionAssignor は現在 Kafka Streams で利用されている partition assignor です。この partition assignor は前述の問題を軽減するために、state store を所有している consumer に partition を割り当てるようになっています。
このロジックを理解するには StreamsPartitionAssignor#subscriptionUserData, StreamsPartitionAssignor#assign を起点に読むと良いですが、中でも特に重要なメソッドは次の 2 つです。

TaskManager#getTaskOffsetSums は consumer が group に join する際に coordinator (Kafka broker の 1 台) に送る userdata の生成に使われるメソッドです。この userdata には changelog の offset 情報が含まれているんですが、現在自分が処理している task に関しては changelog offset は全て Task.LATEST_OFFSET とし、処理していない task に関しては state store の checkpoint ファイルの offset 情報を使うようになっています。なお、task というのは sub-topology 番号と partition 番号の組み合わせで、例えば sub-topology 0 の partition 1 だと 0_1 になります。WordCount の例だと source topic が 1 つなのでわかりにくいですが、task 0_1 を処理する consumer は、sub-topology 0 に複数の source topic があっても、それらの topic の partition 1 だけを consume します。

HighAvailabilityTaskAssignor#assign は各 task を consumer にアサインするのに StreamsPartitionAssignor で使われているメソッドです。

簡単のため、standby replica は 0 であるものとして説明します。そうすると、メソッドの内容は次のように単純になります。

public boolean assign(final Map<UUID, ClientState> clients,
                      final Set<TaskId> allTaskIds,
                      final Set<TaskId> statefulTaskIds,
                      final AssignmentConfigs configs) {
    final SortedSet<TaskId> statefulTasks = new TreeSet<>(statefulTaskIds);
    final TreeMap<UUID, ClientState> clientStates = new TreeMap<>(clients);

    assignActiveStatefulTasks(clientStates, statefulTasks);

    final AtomicInteger remainingWarmupReplicas = new AtomicInteger(configs.maxWarmupReplicas);

    final Map<TaskId, SortedSet<UUID>> tasksToCaughtUpClients = tasksToCaughtUpClients(
        statefulTasks,
        clientStates,
        configs.acceptableRecoveryLag
    );

    final Map<UUID, Set<TaskId>> warmups = new TreeMap<>();

    final int neededActiveTaskMovements = assignActiveTaskMovements(
        tasksToCaughtUpClients,
        clientStates,
        warmups,
        remainingWarmupReplicas
    );

    assignStatelessActiveTasks(clientStates, diff(TreeSet::new, allTaskIds, statefulTasks));

    final boolean probingRebalanceNeeded = neededActiveTaskMovements > 0;

    return probingRebalanceNeeded;
}

assignActiveStatefulTasks では最初に stateful task を round-robin 方式で process ID 順に client に割り振ります。client というのは userdata に含まれる process ID が同じ consumer を 1 つのグループにしたものです。TaskManager#initializeProcessId で付与されるもので、プロセスごとにユニークな ID となっています。stream thread の数 (num.stream.threads) が 2 であれば 1 client に 2 consumer が属することになります。stateful task というのは state store に依存している task で、WordCount の場合 sub-topology 1 に属する task です。
なお、client が state store を所有している場合は、state store directory 配下の kafka-streams-process-metadata というファイルに process ID が保存されているので、再起動しても process ID は変わりません。

例えば parition の数が 6、client が A, B, C の 3 の場合、過去に各 client が処理していた task とは関係なしに次のように割り当てます。なお、process ID は簡単のため単純な文字列にしていますが、実際は java.util.UUID です。

Task	Client
1_0	A
1_1	B
1_2	C
1_3	A
1_4	B
1_5	C

もし client ごとに stream thread の数が異なる場合、stream thread の数が多い client により多くの partition が割り当てられるよう、round-robin 方式で割り当てた後に割り当てが調整されますが、ここでは簡単のため stream thread の数は全て同じとします。

次に、tasksToCaughtUpClients では consumer が送ってきた changelog offset 情報を使って task ごとに caught-up client の一覧を作ります。caught-up client とは、現在その task を処理している client か changelog topic の最新の latest offset と state store offset が acceptable.recovery.lag 以下である client です。例えば WordCount の例で、client A が 1_0, 1_2, 1_4 を処理していて、B が残りを処理している状態であれば、caught-up client は次のようになります。

Task	Caught-up Clients
1_0	[A]
1_1	[B]
1_2	[A]
1_3	[B]
1_4	[A]
1_5	[B]

これがもし、A が B の join 前に全ての task を処理していて、state store がまだ残っていて changelog offset も acceptable.recovery.lag 以下であれば次のようになります。

Task	Caught-up Clients
1_0	[A]
1_1	[A, B]
1_2	[A]
1_3	[A, B]
1_4	[A]
1_5	[A, B]

最後に assignActiveTaskMovements で、round-robin 方式で割り当てられた stateful task が caught-up client に割り当てられていなかった場合に、caught-up client のいずれかに割り当てられるように調整されます。caught-up client でなかったがために stateful task が別の client に移った client には standby task が割り当てられます。standby task は state store の復元を行う task で、standby task が動くことで caught-up client でなかった client はそのうち caught-up client になります。一定時間経つと consumer が join/leave しなくても rebalance が行われ（probing rebalance）、その時に standby task を割り当てられていた client が caught-up client になっていれば調整が不要になります。つまり、最終的には round-robin 方式の割り当てに収束します。standby task を生成できる最大数は max.warmup.replicas で制御され、デフォルトは 2 です。standby task の数が max.warmup.replicas に達すると、task が caught-up client のいずれかに移るだけで、standby task は生成されません。
なお、どの task に standby task を割り当てるかの優先順位は決まっていません。もし Assign warmups to tasks in priority order by abicky · Pull Request #697 · confluentinc/kafka がマージされれば、caught-up client の数の少ない task から順に standby task が割り当てられ、もし caught-up client の数が同じであれば task ID 順で割り当てられるようになります。

ここで、round-robin 方式で割り当てた task と caught-up client が次のようになっている状態で client C が join した場合を考えます。

Task	Client
1_0	A
1_1	B
1_2	C
1_3	A
1_4	B
1_5	C

Task	Caught-up Clients
1_0	[A]
1_1	[B]
1_2	[A]
1_3	[B]
1_4	[A]
1_5	[B]

task 1_2 は client C に割り当てられていますが、C は caught-up client ではないので、この task 1_2 は A に割り当てられ、C には 1_2 の standby task が割り当てられます。同様に、task 1_5 は B に割り当てられ、C には 1_5 の standby task が割り当てられます。task 1_3, 1_4 も同様です。ただし、standby task を 4 つ割り当てるには max.warmup.replicas を 4 にしなければなりません。デフォルトだと 2 つしか standby task が作成されません。

下表の Source Client は round-robin 方式で各 task に割り当てられた client で、Destination Client は caught-up client を考慮した最終的な割り当てです。

Task	Source Client	Destination Client
1_0	A	A
1_1	B	B
1_2	C	A
1_3	A	B
1_4	B	A
1_5	C	B

Standby Task	Client
1_2	C
1_3	A
1_4	B
1_5	C

あとはステートレスな task を割り当てたり、client に割り当てられた task を consumer に割り当てたり、再度 rebalance を行うべき時間を計算したりするだけです。

過去に使われていた assignor や StreamsPartitionAssignfor で使われている HighAvailabilityTaskAssignor の導入経緯などについては Kafka Streamsのタスク割り当てアルゴリズム - shinichy’s blog で触れられているので、興味のある方はそちらを参照してください。当該記事でも触れられていますが（というか一連のコードを読み終わってから知ったんですが）、KIP-441: Smooth Scaling Out for Kafka Streams は今回触れた仕組みのコンセプトが書かれているので、一読してからコードを読むと捗るかもしれません。

実験

WordCount のプロパティに次のような設定を追加します。

props.put(StreamsConfig.ACCEPTABLE_RECOVERY_LAG_CONFIG, 0);
props.put(StreamsConfig.PROBING_REBALANCE_INTERVAL_MS_CONFIG, 60_000);
props.put(StreamsConfig.STATE_DIR_CONFIG, System.getenv().getOrDefault("STATE_DIR", "/tmp/kafka-streams"));
props.put(StreamsConfig.NUM_STREAM_THREADS_CONFIG, 2);

partition 数は 6 で topic を作成します。

for topic in streams-plaintext-input streams-wordcount-output; do
  kafka-topics --bootstrap-server localhost:9092 --create --topic $topic --partitions 6
done

これで環境変数 STATE_DIR=/tmp/kafka-streams-0 と STATE_DIR=/tmp/kafka-streams-1 をそれぞれ指定して 2 つの client を起動すると、stateful task の source topic となっている streams-wordcount-counts-store-repartition の partition の割当は次のようになります。

% kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group streams-wordcount | grep repartition | sort | cut -c19-189
streams-wordcount-counts-store-repartition 0          -               0               -               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 1          -               0               -               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2
streams-wordcount-counts-store-repartition 2          -               0               -               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-2
streams-wordcount-counts-store-repartition 3          -               0               -               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 4          -               0               -               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 5          -               0               -               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2

上記の情報から stateful task の割り当ても把握することができます。

Task	Client	Thread
1_0	4b61083e-57d0-457d-951f-d06556c148ca	1
1_1	7156cef1-307e-49c0-a5bb-0f11d26a4933	2
1_2	4b61083e-57d0-457d-951f-d06556c148ca	2
1_3	7156cef1-307e-49c0-a5bb-0f11d26a4933	1
1_4	4b61083e-57d0-457d-951f-d06556c148ca	1
1_5	7156cef1-307e-49c0-a5bb-0f11d26a4933	2

次に、適当な内容を topic に produce します。

echo 'a b c d e f g h i j k l m n o p q r s t u v w x y z' | kafka-console-producer --bootstrap-server localhost:9092 --topic streams-plaintext-input

offset が commit されるまで待つと offset の情報は次のようになりました。

% kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group streams-wordcount | grep repartition | sort | cut -c19-189
streams-wordcount-counts-store-repartition 0          2               2               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 1          2               2               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2
streams-wordcount-counts-store-repartition 2          8               8               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-2
streams-wordcount-counts-store-repartition 3          6               6               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 4          4               4               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 5          4               4               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2

ちなみにこの時の checkpoint ファイルの内容は次のようになっています。

% cat /tmp/kafka-streams-0/streams-wordcount/1_*/.checkpoint
0
1
streams-wordcount-counts-store-changelog 0 1
0
1
streams-wordcount-counts-store-changelog 2 7
0
1
streams-wordcount-counts-store-changelog 3 5
0
1
streams-wordcount-counts-store-changelog 4 3

checkpoint ファイルの内容は上から version（現状 0 のみ）, expectedSize, topic partition offset です。
cf. OffsetCheckpoint

次に、環境変数 STATE_DIR=/tmp/kafka-streams-2 で別の client を起動します。この client ID は bbb83e43-b1af-4b2d-a60a-94a7091684d0 になりました。task は client ID をソートした上で round-robin 方式で割り当てるので、caught-up client を考慮しなければ次のような割り当てになります。¹

Task	Client
1_0	bbb83e43-b1af-4b2d-a60a-94a7091684d0
1_1	4b61083e-57d0-457d-951f-d06556c148ca
1_2	7156cef1-307e-49c0-a5bb-0f11d26a4933
1_3	bbb83e43-b1af-4b2d-a60a-94a7091684d0
1_4	4b61083e-57d0-457d-951f-d06556c148ca
1_5	7156cef1-307e-49c0-a5bb-0f11d26a4933

ところが、1_0, 1_1, 1_2, 1_3 が割り当てられる client はそれらの state store を所有していない、つまり caught-up client じゃないので、1_0, 1_1, 1_2, 1_3 に関しては既に state store を所有している client に task を割り当てます。
最終的な割り当ては次のような leader のログから把握することができます。max.warmup.replicas が 2 なので、standby task は 1_0 と 1_2 だけです。

13:48:02.571 [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1] INFO  o.a.k.s.p.i.StreamsPartitionAssignor - stream-thread [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer] Assigned tasks [0_0, 0_1, 1_0, 0_2, 1_1, 0_3, 1_2, 0_4, 1_3, 0_5, 1_4, 1_5] including stateful [1_0, 1_1, 1_2, 1_3, 1_4, 1_5] to clients as: 
bbb83e43-b1af-4b2d-a60a-94a7091684d0=[activeTasks: ([0_0, 0_1, 0_2, 0_3]) standbyTasks: ([1_0])]
4b61083e-57d0-457d-951f-d06556c148ca=[activeTasks: ([0_4, 1_0, 1_2, 1_4]) standbyTasks: ([])]
7156cef1-307e-49c0-a5bb-0f11d26a4933=[activeTasks: ([0_5, 1_1, 1_3, 1_5]) standbyTasks: ([1_2])].
13:48:02.571 [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1] INFO  o.a.k.s.p.i.StreamsPartitionAssignor - stream-thread [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer] Requesting followup rebalance be scheduled by streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer-47d53591-da40-49ff-9c3c-b3054cf71902 for 1649652542571 ms to probe for caught-up replica tasks.

ログからも、probing.rebalance.interval.ms だけ経過した後（13:49:02）に rebalance するようスケジューリングされたことがわかります。この時点ではまだ割り当ては変わっていません。

% kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group streams-wordcount | grep repartition | sort | cut -c19-189
streams-wordcount-counts-store-repartition 0          2               2               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 1          2               2               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2
streams-wordcount-counts-store-repartition 2          8               8               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-2
streams-wordcount-counts-store-repartition 3          6               6               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 4          4               4               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 5          4               4               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2

1 分後のログは次のようになっていました。次のログから、1_3, 1_1 が standby task になっていることがわかります。

13:49:02.654 [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1] INFO  o.a.k.s.p.i.StreamsPartitionAssignor - stream-thread [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer] Assigned tasks [0_0, 0_1, 1_0, 0_2, 1_1, 0_3, 1_2, 0_4, 1_3, 0_5, 1_4, 1_5] including stateful [1_0, 1_1, 1_2, 1_3, 1_4, 1_5] to clients as: 
bbb83e43-b1af-4b2d-a60a-94a7091684d0=[activeTasks: ([0_0, 0_2, 0_4, 1_0]) standbyTasks: ([1_3])]
4b61083e-57d0-457d-951f-d06556c148ca=[activeTasks: ([0_1, 0_3, 0_5, 1_4]) standbyTasks: ([1_1])]
7156cef1-307e-49c0-a5bb-0f11d26a4933=[activeTasks: ([1_1, 1_2, 1_3, 1_5]) standbyTasks: ([])].

ログからもわかるとおり、元々 bbb83e43-b1af-4b2d-a60a-94a7091684d0 が 1_0 を処理するはずだったので、state store が復元されたことでそのまま処理するようになりました。同様に、1_2 は 7156cef1-307e-49c0-a5bb-0f11d26a4933 が処理するようになりました。一方で、7156cef1-307e-49c0-a5bb-0f11d26a4933 に stateful task が集中してしまったことがわかります。state store を既に 3 つ所有していた 7156cef1-307e-49c0-a5bb-0f11d26a4933 に 1_2 standby task が割り当てられたことで、7156cef1-307e-49c0-a5bb-0f11d26a4933 が 4 つの state store を所有するようになったのが原因です。

% kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group streams-wordcount | grep repartition | sort | cut -c19-189
streams-wordcount-counts-store-repartition 0          2               2               0               streams-wordcount-bbb83e43-b1af-4b2d-a60a-94a7091684d0-StreamThread-1
streams-wordcount-counts-store-repartition 1          2               2               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2
streams-wordcount-counts-store-repartition 2          8               8               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 3          6               6               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 4          4               4               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 5          4               4               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2

この後、probing.rebalance.interval.ms だけ経過した後、rebalance が起こり、round-robin 方式の割り当てどおりになったため、standby task もなくなり、この状態に収束しました。

13:50:05.739 [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1] INFO  o.a.k.s.p.i.StreamsPartitionAssignor - stream-thread [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer] Assigned tasks [0_0, 0_1, 1_0, 0_2, 1_1, 0_3, 1_2, 0_4, 1_3, 0_5, 1_4, 1_5] including stateful [1_0, 1_1, 1_2, 1_3, 1_4, 1_5] to clients as: 
bbb83e43-b1af-4b2d-a60a-94a7091684d0=[activeTasks: ([0_0, 0_3, 1_0, 1_3]) standbyTasks: ([])]
4b61083e-57d0-457d-951f-d06556c148ca=[activeTasks: ([0_1, 0_4, 1_1, 1_4]) standbyTasks: ([])]
7156cef1-307e-49c0-a5bb-0f11d26a4933=[activeTasks: ([0_2, 0_5, 1_2, 1_5]) standbyTasks: ([])].
-- snip --
13:50:05.800 [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1] INFO  o.a.k.s.p.i.StreamsPartitionAssignor - stream-thread [streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1-consumer] Finished stable assignment of tasks, no followup rebalances required.

consumer の割り当ては次のとおりです。

% kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group streams-wordcount | grep repartition | sort | cut -c19-189
streams-wordcount-counts-store-repartition 0          2               2               0               streams-wordcount-bbb83e43-b1af-4b2d-a60a-94a7091684d0-StreamThread-1
streams-wordcount-counts-store-repartition 1          2               2               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-2
streams-wordcount-counts-store-repartition 2          8               8               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-1
streams-wordcount-counts-store-repartition 3          6               6               0               streams-wordcount-bbb83e43-b1af-4b2d-a60a-94a7091684d0-StreamThread-2
streams-wordcount-counts-store-repartition 4          4               4               0               streams-wordcount-4b61083e-57d0-457d-951f-d06556c148ca-StreamThread-1
streams-wordcount-counts-store-repartition 5          4               4               0               streams-wordcount-7156cef1-307e-49c0-a5bb-0f11d26a4933-StreamThread-2

なお、別の consumer が処理していた task が割り当てられた場合、いきなり active task になるのではなく standby task として登録され、すぐに rebalance を行うようになっているようです。どうも [KAFKA-10078] Partition may skip assignment with static members and incremental rebalances - ASF JIRA が関係しているようですが、詳細は追っていません。

Stateful Kafka Streams アプリケーションの運用上の注意点

これまで見てきた内容から次のようなことが言えます。

client を増やしてもすぐには新しい client に stateful task が割り当てられない
1 client だけ別 process ID の client に変えると stateful task の割り当てがコロコロ変わる可能性がある
Changelog topic の代わりに source topic を使っている場合はアプリケーションを止めている間に caught-up client が減る可能性がある

それぞれ解説していきます。

client を増やしてもすぐには新しい client に stateful task が割り当てられない

stateful Kafka Streams アプリケーションでは、client が増減しても、その直後は state store を所有している client（caught-up client）に stateful task を割り当てるようになっています。その際、最大 max.warmup.replicas だけ standby task が作られます。最終的には round-robin 方式の割り当てに収束していきますが、一度の rebalance で移る task は最大で max.warmup.replicas だけと言えます。また、実験で 7156cef1-307e-49c0-a5bb-0f11d26a4933 に 6 つ中 4 つの stateful task が集中したように、その過程で偏りが悪化することもあります。

できるだけ早く新しい clinet に stateful task を割り当てたい時にできることは次のどれかと言えます。

起動時に KafkaStreams#cleanUp で state store のデータをクリアするようにして再起動する
max.warmup.replicas を増やして再起動する
- 復元中の state store があると最初からやり直しになるので注意
probing.rebalance.interval.ms を短くして再起動する
- デフォルトだと standby task によって caught-up client が増えても 10 分経たないと rebalance が起きない

state store を復元している間処理が止まることを許容できるなら state store のクリア、許容できないなら残りの選択肢の組み合わせになるでしょう。一方で、max.warmup.replicas を増やすと standby task が増え、Kafka broker や consumer の負荷が増えるので、良い塩梅にする必要があります。

1 client だけ別 process ID の client に変えると stateful task の割り当てがコロコロ変わる可能性がある

StreamsPartitionAssignor（というより HighAvailabilityTaskAssignor）は stateful task を round-robin 方式で process ID 順に client に割り当てることについて言及しました。例えば round-robin 方式による割り当て結果が次のようになっている状態で client C を client D に置き換えれば、process ID のソート順が変わらないので C に割り当てられていた stateful task が D に移るだけです。

Task	Client
1_0	A
1_1	B
1_2	C
1_3	A
1_4	B
1_5	C

つまり、次のような割り当てに収束します。

Task	Client
1_0	A
1_1	B
1_2	D
1_3	A
1_4	B
1_5	D

ところが、A を D に置き換えると、最終的には次の割り当てに収束します。

Task	Client
1_0	B
1_1	C
1_2	D
1_3	B
1_4	C
1_5	D

全ての stateful task が別の client に移動することになるので、それまで standby task が動き続けることになります。

これを防ぐには、置き換え前の client の state store directory に存在する kafka-streams-process-metadata を置き換え後の client の state store directory に配置した状態で置き換えると良いはずです（未検証）

Changelog topic の代わりに source topic を使っている場合はアプリケーションを止めている間に caught-up client が減る可能性がある

Topology optimization を有効にすると、source topic を changelog topic の代わりに使うことができます。

Right now there are two possible optimizations, reusing the source topic as a changelog topic for a KTable created directly from an input topic.

通常、changelog topic は state store を使っている Kafka Streams アプリケーションからしか利用されないので、そのアプリケーションを動かしていない限りレコードも produce されず、どれだけ止めていても latest offset と state store offset の差は変わりません。一方で、source topic を state store に紐付けている場合、他のアプリケーションがその topic にレコードを produce する可能性があります。その結果、acceptable.recovery.lag を超えた lag が生じ、stateful task の割り当てに変化が生じる可能性があります。stateful task の割り当てが round-robin 方式の割り当てに収束していれば caught-up client が 0 になっても同じ割り当てになって、state store を一から復元することは避けられるはずですが（未検証）、もし収束していない状態で（standby task が動いている状態）で caught-up client が 0 になると、state store の有無を考慮せず round-robin 方式で task が割り当てられるため、復元が終わるまで処理が止まる task が出てきます。

process ID は java.util.UUID なので、文字列のソート順ではありません。最初の 3 つの要素から構成される 16 進数の 64 bit signed int（mostSigBits）と最後の 2 つの要素から構成される 64 bit signed int (leastSigBits) を基にソートされるので、先頭の文字だけ見ると 8 〜 f（mostSigBits がマイナス）, 0 〜 7（mostSigBits がプラス）の順になります ↩

Cassandra C/C++ Driver を使うと Cassandra で Connection reset by peer という INFO ログが出る

Sun, 03 Apr 2022 00:00:00 +0900

Cassandra C/C++ driver を使うと次のようなログが出るので調査したという話です。

INFO  [epollEventLoopGroup-2-30] 2022-04-02 02:38:49,314 Message.java:623 - Unexpected exception during request; channel = [id: 0x632f6343, L:/172.31.84.31:9042 - R:/172.31.87.113:60864]
io.netty.channel.unix.Errors$NativeIoException: syscall:read(...)() failed: Connection reset by peer
	at io.netty.channel.unix.FileDescriptor.readAddress(...)(Unknown Source) ~[netty-all-4.0.44.Final.jar:4.0.44.Final]

以下、Cassandra 3.11、Cassandra C/C++ driver 2.16 に対して macOS 上で調査した話です。

そもそも Connection reset by peer とは何なのか？

sockets - What does “connection reset by peer” mean? - Stack Overflow 辺りで説明されています。要は、片方が接続を閉じたのにもう片方が依然として通信しようとした場合に起きるエラーですね。
例えば次のコードを実行すると、client が接続を閉じた後に server が client にメッセージを送り、その後引き続きメッセージを受け取ろうとするので Connection reset by peer になります。

require 'logger'
require 'socket'

HOST = '127.0.0.1'
PORT = 8080

logger = Logger.new($stdout)
server_sock = TCPServer.new(HOST, PORT)
client_sock = TCPSocket.new(HOST, PORT)

th = Thread.new do
  sock = server_sock.accept
  logger.info("Server: Try to get a message")
  msg = sock.gets
  logger.info("Server: Received: #{msg}")
  sleep 0.1
  logger.info("Server: Send: #{msg}")
  sock.puts(msg)
  logger.info("Server: Try to get a message")
  10.times { sock.gets } # 何故か 1, 2 回だとエラーにならないこともある
end
th.report_on_exception = false

logger.info('Client: Send hello')
client_sock.write('hello')
client_sock.close

th.join

実行すると次のようなログが出ます。

I, [2022-04-02T20:40:17.857053 #49528]  INFO -- : Client: Send hello
I, [2022-04-02T20:40:17.857314 #49528]  INFO -- : Server: Try to get a message
I, [2022-04-02T20:40:17.857360 #49528]  INFO -- : Server: Received: hello
I, [2022-04-02T20:40:17.961273 #49528]  INFO -- : Server: Send: hello
I, [2022-04-02T20:40:17.961421 #49528]  INFO -- : Server: Try to get a message
/tmp/script.rb:20:in `gets': Connection reset by peer @ io_fillbuf - fd:10  (Errno::ECONNRESET)
        from /tmp/script.rb:20:in `block (2 levels) in <main>'
        from /tmp/script.rb:20:in `times'
        from /tmp/script.rb:20:in `block in <main>'

tcpdump の結果は次のとおりです。

% sudo tcpdump -i lo0 -n tcp port 8080
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on lo0, link-type NULL (BSD loopback), capture size 262144 bytes
40:17.856691 IP 127.0.0.1.50115 > 127.0.0.1.8080: Flags [S], seq 3704873561, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 882104961 ecr 0,sackOK,eol], length 0
40:17.856785 IP 127.0.0.1.8080 > 127.0.0.1.50115: Flags [S.], seq 894336615, ack 3704873562, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 1111480137 ecr 882104961,sackOK,eol], length 0
40:17.856796 IP 127.0.0.1.50115 > 127.0.0.1.8080: Flags [.], ack 1, win 6379, options [nop,nop,TS val 882104961 ecr 1111480137], length 0
40:17.856800 IP 127.0.0.1.8080 > 127.0.0.1.50115: Flags [.], ack 1, win 6379, options [nop,nop,TS val 1111480137 ecr 882104961], length 0
40:17.857200 IP 127.0.0.1.50115 > 127.0.0.1.8080: Flags [P.], seq 1:6, ack 1, win 6379, options [nop,nop,TS val 882104961 ecr 1111480137], length 5: HTTP
40:17.857216 IP 127.0.0.1.50115 > 127.0.0.1.8080: Flags [F.], seq 6, ack 1, win 6379, options [nop,nop,TS val 882104961 ecr 1111480137], length 0
40:17.857220 IP 127.0.0.1.8080 > 127.0.0.1.50115: Flags [.], ack 6, win 6379, options [nop,nop,TS val 1111480137 ecr 882104961], length 0
40:17.857228 IP 127.0.0.1.8080 > 127.0.0.1.50115: Flags [.], ack 7, win 6379, options [nop,nop,TS val 1111480137 ecr 882104961], length 0
40:17.961403 IP 127.0.0.1.8080 > 127.0.0.1.50115: Flags [P.], seq 1:7, ack 7, win 6379, options [nop,nop,TS val 1111480241 ecr 882104961], length 6: HTTP
40:17.961464 IP 127.0.0.1.50115 > 127.0.0.1.8080: Flags [R], seq 3704873568, win 0, length 0

client が FIN パケットを送ったにも関わらず、server がメッセージを送ったからか、RST パケットが返ってきています。別途 lsof で確認したところ、client が FIN パケットを送って、server が ACK を返した時点で CLOSE-WAIT になり、RST パケットを送った時点で CLOSED になっているので、仕様的には次の箇所が関連してそうです（仕様というか実装例のセクションですが）

CLOSE-WAIT STATE

Send a reset segment:

<SEQ=SND.NXT><CTL=RST>

All queued SENDs and RECEIVEs should be given “connection reset” notification; all segments queued for transmission (except for the RST formed above) or retransmission should be flushed, delete the TCB, enter CLOSED state, and return.

というわけで、Cassandra で Connection reset by peer のログが出るということは、何らかの理由で client が接続を閉じたにも関わらず server からメッセージを送ることで RST パケットが返ってきて、その後も client からメッセージを読み取ろうとした場合に起きると言えそうです。要は server の意図しない形で client の方から接続を閉じた場合ですね。

ちなみに CASSANDRA-7849 では client の実装がまずいことを検知するには有用かもしれないけど、server のエラーじゃないから log level を DEBUG にしようみたいなやり取りがされています。かなり前にこの変更が取り込まれていて、その後 TRACE にまでなってるんですが、実は Native transports が使われた時のことが考慮されていなくて、この変更で正真正銘 TRACE ログになってます。なので、macOS 等 EpollEventLoopGroup をサポートしてないプラットフォームや Cassandra 3.11.4 以降で再現確認しても Connection reset by peer の INFO ログは出ないことに注意です。

再現確認

まず、client が異常終了した時に当該ログが出ることを確認します。次の docker-compose.yml を使って docker-compose up すると再現します。

version: "3.8"

services:
  cassandra:
    image: cassandra:3.11.3
    environment:
      CASSANDRA_SEEDS: 127.0.0.1
      CASSANDRA_LISTEN_ADDRESS: 127.0.0.1
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M

  app:
    image: ruby:2.7
    command: sh -c 'gem install cassandra-driver && ruby main.rb'
    working_dir: /app
    volumes:
      - type: bind
        source: .
        target: /app

main.rb は次のようなコードです。もっとシンプルにできるかもしれないですが。

require 'cassandra'

logger = Logger.new($stdout)
cluster = nil
begin
  cluster = Cassandra.cluster(hosts: %w[cassandra], logger: logger)
rescue Cassandra::Errors::NoHostsAvailable
  sleep 1
  retry
end
session  = cluster.connect
session.execute(<<~CQL)
  CREATE KEYSPACE IF NOT EXISTS store
    WITH REPLICATION = {
      'class': 'SimpleStrategy',
      'replication_factor' : 1
    };
CQL
session.execute(<<~CQL)
  CREATE TABLE IF NOT EXISTS store.shopping_cart (
    partitionid int,
    userid text,
    item_count int,
    last_update_timestamp timestamp,
    PRIMARY KEY (partitionid, userid)
  );
CQL

1000.times do |i|
  session.execute(<<~CQL % i, idempotent: true)
  INSERT INTO
    store.shopping_cart (partitionid, userid, item_count, last_update_timestamp)
  VALUES
    (2, '1234%04d', 3, toTimeStamp(now()));
  CQL
end

Thread.new do
  sleep 1
  Process.kill(:KILL, Process.pid)
end

Array.new(4) do
  Thread.new do
    loop do
      session  = cluster.connect
      session.execute_async('SELECT * FROM store.shopping_cart')
      sleep 0.001
      session.close
    end
  end
end.each(&:join)

次のような感じでログが出ることがわかります。

-- snip --
app_1        | D, [2022-04-02T14:56:23.150517 #38] DEBUG -- : Creating 1 request connections to 192.168.32.3
cassandra_1  | INFO  [epollEventLoopGroup-2-7] 2022-04-02 14:56:23,163 Message.java:623 - Unexpected exception during request; channel = [id: 0x4be59dde, L:/192.168.32.3:9042 - R:/192.168.32.2:57716]
cassandra_1  | io.netty.channel.unix.Errors$NativeIoException: syscall:read(...)() failed: Connection reset by peer
cassandra_1  |  at io.netty.channel.unix.FileDescriptor.readAddress(...)(Unknown Source) ~[netty-all-4.0.44.Final.jar:4.0.44.Final]
app_1        | Killed
cassandra_1  | INFO  [epollEventLoopGroup-2-3] 2022-04-02 14:56:23,234 Message.java:623 - Unexpected exception during request; channel = [id: 0x834c6e96, L:/192.168.32.3:9042 - R:/192.168.32.2:57724]
cassandra_1  | io.netty.channel.unix.Errors$NativeIoException: syscall:read(...)() failed: Connection reset by peer
cassandra_1  |  at io.netty.channel.unix.FileDescriptor.readAddress(...)(Unknown Source) ~[netty-all-4.0.44.Final.jar:4.0.44.Final]
cassandra_app_1 exited with code 137

ちなみに、Docker Desktop for Mac を使っている場合、次のような docker-compose.yml を使って、Cassandra Ruby driver の contact point を 172.16.0.2 にすれば app container は不要なんですが、Connection reset by peer は再現できないので気を付けてください。Linux でどうなるかは検証していません。

version: "3.8"

services:
  cassandra:
    image: cassandra:3.11.3
    networks:
      cassandra:
        ipv4_address: 172.16.0.2
    ports:
      # ifconfig lo0 alias 172.16.0.2 (To delete the alias: ifconfig lo0 -alias 172.16.0.2)
      - 172.16.0.2:9042:9042
    environment:
      CASSANDRA_SEEDS: 172.16.0.2
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M

networks:
  cassandra:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.16.0.0/24

慣れてる Ruby のコードですら問題のログを出すのにめちゃくちゃ苦労したことや、C/C++ driver は最初に接続を確立しているところでログが出てそうという話があったので、RST パケットが送られてないかを確認しました。
最終的に次のコードで RST パケットが送られていることを確認しました。

#include <cassandra.h>

int main(int argc, char* argv[]) {
  CassCluster* cluster = cass_cluster_new();
  cass_cluster_set_contact_points(cluster, "127.0.0.1");

  CassSession* session = cass_session_new();
  CassFuture* future = cass_session_connect(session, cluster);

  cass_future_wait(future);

  return 0;
}

% gcc -o main main.c -lcassandra
% ./main

% sudo tcpdump -i lo0 -n tcp port 9042
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on lo0, link-type NULL (BSD loopback), capture size 262144 bytes
01:51.901853 IP 127.0.0.1.60298 > 127.0.0.1.9042: Flags [S], seq 3790279341, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 3269705598 ecr 0,sackOK,eol], length 0
01:51.901932 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [S.], seq 3495878965, ack 3790279342, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 3990721673 ecr 3269705598,sackOK,eol], length 0
01:51.901940 IP 127.0.0.1.60298 > 127.0.0.1.9042: Flags [.], ack 1, win 6379, options [nop,nop,TS val 3269705598 ecr 3990721673], length 0
01:51.901946 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [.], ack 1, win 6379, options [nop,nop,TS val 3990721673 ecr 3269705598], length 0
01:51.902051 IP 127.0.0.1.60298 > 127.0.0.1.9042: Flags [P.], seq 1:10, ack 1, win 6379, options [nop,nop,TS val 3269705598 ecr 3990721673], length 9
01:51.902069 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [.], ack 10, win 6379, options [nop,nop,TS val 3990721673 ecr 3269705598], length 0
01:51.904650 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [P.], seq 1:108, ack 10, win 6379, options [nop,nop,TS val 3990721675 ecr 3269705598], length 107
01:51.904688 IP 127.0.0.1.60298 > 127.0.0.1.9042: Flags [.], ack 108, win 6378, options [nop,nop,TS val 3269705600 ecr 3990721675], length 0
01:51.904921 IP 127.0.0.1.60298 > 127.0.0.1.9042: Flags [F.], seq 10, ack 108, win 6378, options [nop,nop,TS val 3269705600 ecr 3990721675], length 0
01:51.904949 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [.], ack 11, win 6379, options [nop,nop,TS val 3990721675 ecr 3269705600], length 0
01:51.905086 IP 127.0.0.1.60299 > 127.0.0.1.9042: Flags [S], seq 1512530264, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 1342414003 ecr 0,sackOK,eol], length 0
01:51.905177 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [S.], seq 421117837, ack 1512530265, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 764993117 ecr 1342414003,sackOK,eol], length 0
01:51.905184 IP 127.0.0.1.60299 > 127.0.0.1.9042: Flags [.], ack 1, win 6379, options [nop,nop,TS val 1342414003 ecr 764993117], length 0
01:51.905190 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [.], ack 1, win 6379, options [nop,nop,TS val 764993117 ecr 1342414003], length 0
01:51.905302 IP 127.0.0.1.60299 > 127.0.0.1.9042: Flags [P.], seq 1:10, ack 1, win 6379, options [nop,nop,TS val 1342414003 ecr 764993117], length 9
01:51.905325 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [.], ack 10, win 6379, options [nop,nop,TS val 764993117 ecr 1342414003], length 0
01:51.905594 IP 127.0.0.1.9042 > 127.0.0.1.60298: Flags [R.], seq 108, ack 11, win 6379, length 0
01:51.908357 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [P.], seq 1:108, ack 10, win 6379, options [nop,nop,TS val 764993119 ecr 1342414003], length 107
01:51.908395 IP 127.0.0.1.60299 > 127.0.0.1.9042: Flags [.], ack 108, win 6378, options [nop,nop,TS val 1342414005 ecr 764993119], length 0
01:51.908557 IP 127.0.0.1.60299 > 127.0.0.1.9042: Flags [F.], seq 10, ack 108, win 6378, options [nop,nop,TS val 1342414005 ecr 764993119], length 0
01:51.908576 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [.], ack 11, win 6379, options [nop,nop,TS val 764993119 ecr 1342414005], length 0
01:51.908713 IP 127.0.0.1.60300 > 127.0.0.1.9042: Flags [S], seq 3213156330, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 3594102261 ecr 0,sackOK,eol], length 0
01:51.908773 IP 127.0.0.1.9042 > 127.0.0.1.60299: Flags [R.], seq 108, ack 11, win 6379, length 0
01:51.908841 IP 127.0.0.1.9042 > 127.0.0.1.60300: Flags [S.], seq 2612148364, ack 3213156331, win 65535, options [mss 16344,nop,wscale 6,nop,nop,TS val 2461264152 ecr 3594102261,sackOK,eol], length 0
01:51.908858 IP 127.0.0.1.60300 > 127.0.0.1.9042: Flags [.], ack 1, win 6379, options [nop,nop,TS val 3594102261 ecr 2461264152], length 0
01:51.908865 IP 127.0.0.1.9042 > 127.0.0.1.60300: Flags [.], ack 1, win 6379, options [nop,nop,TS val 2461264152 ecr 3594102261], length 0
-- snip --

この結果から、後述するようにどこで接続を閉じているのか調査したんですが、結局再現確認できないと直ったかわからないので C/C++ driver でも再現環境を作るよう試行錯誤してみました。
最終的に次の設定で再現させることができました。複数の Cassandra ノードが必要なのがポイントです。

version: "3.8"

services:
  cassandra-1:
    image: cassandra:3.11.3
    networks:
      cassandra:
        ipv4_address: 172.16.0.2
    environment:
      CASSANDRA_SEEDS: 172.16.0.2,172.16.0.3
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M
    healthcheck:
        test: ["CMD", "cqlsh", "-e", "quit"]
        interval: 5s
        timeout: 5s
        retries: 60

  cassandra-2:
    image: cassandra:3.11.3
    networks:
      cassandra:
        ipv4_address: 172.16.0.3
    environment:
      CASSANDRA_SEEDS: 172.16.0.2,172.16.0.3
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M
    healthcheck:
        test: ["CMD", "cqlsh", "-e", "quit"]
        interval: 5s
        timeout: 5s
        retries: 60

  app:
    build: .
    command: sh -c 'gcc -o main main.c -lcassandra && ./main'
    working_dir: /app
    volumes:
      - type: bind
        source: .
        target: /app
    networks:
      cassandra:
        ipv4_address: 172.16.0.4
    depends_on:
      cassandra-1:
        condition: service_healthy
      cassandra-2:
        condition: service_healthy

networks:
  cassandra:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.16.0.0/24

Dockerfile

FROM ubuntu:18.04

# cf. https://docs.datastax.com/en/developer/cpp-driver/2.16/topics/installation/
RUN apt-get update && \
  apt-get install -y \
    build-essential \
    curl \
    multiarch-support \
    libkrb5-3 \
    libssl1.1 \
    zlib1g

RUN curl -O https://downloads.datastax.com/cpp-driver/ubuntu/18.04/cassandra/v2.16.0/cassandra-cpp-driver_2.16.0-1_amd64.deb && \
  curl -O https://downloads.datastax.com/cpp-driver/ubuntu/18.04/cassandra/v2.16.0/cassandra-cpp-driver-dev_2.16.0-1_amd64.deb && \
  curl -O https://downloads.datastax.com/cpp-driver/ubuntu/18.04/dependencies/libuv/v1.35.0/libuv1_1.35.0-1_amd64.deb && \
  dpkg -i libuv1_1.35.0-1_amd64.deb && \
  dpkg -i cassandra-cpp-driver_2.16.0-1_amd64.deb && \
  dpkg -i cassandra-cpp-driver-dev_2.16.0-1_amd64.deb

main.c

#include <stdio.h>
#include <stdlib.h>
#include <cassandra.h>

int main(int argc, char* argv[]) {
  CassCluster* cluster = cass_cluster_new();
  cass_cluster_set_contact_points(cluster, "cassandra-1,cassandra-2");

  CassError rc = CASS_OK;
  CassSession* session = cass_session_new();
  CassFuture* future = cass_session_connect(session, cluster);

  cass_future_wait(future);
  rc = cass_future_error_code(future);
  if (rc != CASS_OK) {
    fprintf(stderr, "failed to connect\n");
    exit(1);
  }
  cass_future_free(future);

  return 0;
}

次のようなログが出ます。

-- snip --
app_1          | 1648917845.145 [WARN] (host.cpp:155:void datastax::internal::core::Host::set(const datastax::internal::core::Row*, bool)): Found host with 'bind any' for rpc_address; using listen_address (172.16.0.3) to contact instead. If this is incorrect you should configure a specific interface for rpc_address on the server.
app_1          | 1648917845.174 [WARN] (host.cpp:155:void datastax::internal::core::Host::set(const datastax::internal::core::Row*, bool)): Found host with 'bind any' for rpc_address; using listen_address (172.16.0.2) to contact instead. If this is incorrect you should configure a specific interface for rpc_address on the server.
cassandra-1_1  | INFO  [epollEventLoopGroup-2-6] 2022-04-02 16:44:05,284 Message.java:623 - Unexpected exception during request; channel = [id: 0x1145f794, L:/172.16.0.2:9042 - R:/172.16.0.4:60700]
cassandra-1_1  | io.netty.channel.unix.Errors$NativeIoException: syscall:read(...)() failed: Connection reset by peer
cassandra-1_1  |        at io.netty.channel.unix.FileDescriptor.readAddress(...)(Unknown Source) ~[netty-all-4.0.44.Final.jar:4.0.44.Final]
cassandra_app_1 exited with code 0

原因調査

connect する時に接続が閉じられていることが原因っぽいということがわかったので、あとはブレークポイントを仕込んで地道にデバッグすれば良いだけです。自分の場合は CLion を使ってデバッグしました。
C/C++ driver は examples が豊富で、CMake options に -DCASS_BUILD_EXAMPLES=ON を付ければ CLion から手軽に試せて便利です。

とはいえ、C/C++ driver は callback だらけで地道にステップ実行してもなかなか骨の折れる作業だったので、TRACE ログを有効にしました。

cass_log_set_level(CASS_LOG_TRACE);

これで実行してみると、次のような怪しいログが出ました。

1648918232.789 [DEBUG] (socket.cpp:377:void datastax::internal::core::Socket::handle_close()): Socket(0x7f5e280047a0) to host 172.16.0.2 closed
1648918232.789 [DEBUG] (socket.cpp:377:void datastax::internal::core::Socket::handle_close()): Socket(0x7f5e28004510) to host 172.16.0.3 closed

この Socket::handle_close() にブレークポイントを仕込んで、どこから呼ばれているのかを調べてみてもたしかよくわからなかったんですが、Socket::close という、接続を閉じる際に確実に呼ばれているであろうメソッドを見つけたのでここにブレークポイントを仕込むと Connector::on_error から呼ばれていることがわかりました。

つまり、何かしらのエラーが原因で接続を閉じているということになります。このメソッドの中では “Unable to connect to host …” というログを出すようになっているので、それを調べてみました（Socket::handle_close() にブレークポイントを設定したのはログを有効にする前で、この時にようやく有効にした気もしてきた）

そうすると、次のように Invalid or unsupported protocol version (66) とありました。

1648918232.786 [TRACE] (connection.cpp:254:void datastax::internal::core::Connection::on_read(const char*, size_t)): Consumed message type CQL_OPCODE_ERROR with stream 0, input 107, remaining 107 on host 172.16.0.3
1648918232.786 [DEBUG] (connector.cpp:251:void datastax::internal::core::Connector::on_error(datastax::internal::core::Connector::ConnectionError, const String&)): Unable to connect to host 172.16.0.3 because of the following error: Received error response 'Invalid or unsupported protocol version (66); supported versions are (3/v3, 4/v4, 5/v5-beta)' (0x0200000A)
1648918232.788 [INFO] (cluster_connector.cpp:290:void datastax::internal::core::ClusterConnector::on_connect(datastax::internal::core::ControlConnector*)): Host 172.16.0.3 does not support protocol version DSEv2. Trying protocol version DSEv1...
1648918232.789 [TRACE] (connection.cpp:254:void datastax::internal::core::Connection::on_read(const char*, size_t)): Consumed message type CQL_OPCODE_ERROR with stream 0, input 107, remaining 107 on host 172.16.0.2
1648918232.789 [DEBUG] (connector.cpp:251:void datastax::internal::core::Connector::on_error(datastax::internal::core::Connector::ConnectionError, const String&)): Unable to connect to host 172.16.0.2 because of the following error: Received error response 'Invalid or unsupported protocol version (66); supported versions are (3/v3, 4/v4, 5/v5-beta)' (0x0200000A)
1648918232.789 [INFO] (cluster_connector.cpp:290:void datastax::internal::core::ClusterConnector::on_connect(datastax::internal::core::ControlConnector*)): Host 172.16.0.2 does not support protocol version DSEv2. Trying protocol version DSEv1...
1648918232.789 [DEBUG] (socket.cpp:377:void datastax::internal::core::Socket::handle_close()): Socket(0x7f5e280047a0) to host 172.16.0.2 closed
1648918232.789 [DEBUG] (socket.cpp:377:void datastax::internal::core::Socket::handle_close()): Socket(0x7f5e28004510) to host 172.16.0.3 closed

66、つまり 0x42 で grep してみると、CASS_PROTOCOL_VERSION_DSEV2 という enum の要素が見つかったので、これを使っている箇所が怪しいということになります。これを使っているのは ProtocolVersion::highest_supported で、Config の protocol version の初期値として CASS_PROTOCOL_VERSION_DSEV2 が使われているのがわかります。よって、これを CASS_PROTOCOL_VERSION_V4 に変更すれば良さそうです。

というわけで、main.c を次のように変更すれば解消すると思うじゃないですか。

#include <stdio.h>
#include <stdlib.h>
#include <cassandra.h>

int main(int argc, char* argv[]) {
  CassCluster* cluster = cass_cluster_new();
  cass_cluster_set_contact_points(cluster, "cassandra-1,cassandra-2");
  cass_cluster_set_protocol_version(cluster, CASS_PROTOCOL_VERSION_V4);

  CassError rc = CASS_OK;
  CassSession* session = cass_session_new();
  CassFuture* future = cass_session_connect(session, cluster);

  cass_future_wait(future);
  rc = cass_future_error_code(future);
  if (rc != CASS_OK) {
    fprintf(stderr, "failed to connect\n");
    exit(1);
  }
  cass_future_free(future);

  return 0;
}

ところが Connection reset by peer は出続けるわけですよ。原因不明すぎるので CLion から 2 台の Cassandra に接続できるように次のような docker-compose.yml でクラスタを起動します。

version: "3.8"

services:
  cassandra-1:
    image: cassandra:3.11.3
    ports:
      # ifconfig lo0 alias 172.16.0.2 (To delete the alias: ifconfig lo0 -alias 172.16.0.2)
      - 172.16.0.2:9042:9042
    networks:
      cassandra:
        ipv4_address: 172.16.0.2
    environment:
      CASSANDRA_SEEDS: 172.16.0.2,172.16.0.3
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M
    healthcheck:
        test: ["CMD", "cqlsh", "-e", "quit"]
        interval: 5s
        timeout: 5s
        retries: 60

  cassandra-2:
    image: cassandra:3.11.3
    networks:
      cassandra:
        ipv4_address: 172.16.0.3
    ports:
      # ifconfig lo0 alias 172.16.0.3 (To delete the alias: ifconfig lo0 -alias 172.16.0.3)
      - 172.16.0.3:9042:9042
    environment:
      CASSANDRA_SEEDS: 172.16.0.2,172.16.0.3
      MAX_HEAP_SIZE: 400M
      HEAP_NEWSIZE: 100M
    healthcheck:
        test: ["CMD", "cqlsh", "-e", "quit"]
        interval: 5s
        timeout: 5s
        retries: 60

networks:
  cassandra:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.16.0.0/24

コメントにも書いてありますが、事前に ifconfig を使って 172.16.0.2 などを loopback interface に紐付けておく必要があります。Cassandra driver は最初の contact points のノードからクラスタの情報を得て、その情報に含まれる IP アドレスに対してリクエストするので、CLion から Cassandra ノードの IP アドレスにアクセスできるようにする必要があります。もっと上手い方法があるかもしれないですが、これでアクセスできるようになります。

これで main.c と同様のコード（examples の basic を少し修正したもの）を実行してみると、試行錯誤の際にたまたまブレークポイントを設定していた TcpConnector::cancel() で止まって、呼び出し元を確認してみると次の箇所にたどり着きました。

cluster_connector.cpp#L268-L274

The cluster is initialized so the rest of the connectors can be canceled.

仕様かい！！！！

この commit で contact points に一斉にリクエストし、最初にレスポンスが返ってきたもの以外はキャンセルするようにしたと書かれていますね。詳細は追ってないですが、次のようなことが起こるんじゃないかと思います。

client が最初に contact points に対してクラスタのメタデータをリクエストする
client は最初にレスポンスが返ってきたノード以外は接続を閉じる（FIN パケットを送る）
server は全てのリクエストに対して返答しようとするが、既に CLOSE-WAIT になっていて、その接続に対してレスポンスを返すから RST パケットが返ってきて CLOSED になる
server は CLOSED になっていることも知らず次のリクエスト（client からのコマンド）を処理するためにデータを読み取ろうとする
Connection reset by peer

そんなわけで、Connection reset by peer を避けつつ contact points を複数指定したい場合は次のようにシーケンシャルに試す必要がありそうです。

#include <stdio.h>
#include <stdlib.h>
#include <cassandra.h>

#define CONTACT_POINT_COUNT 2

int main(int argc, char* argv[]) {
  CassCluster* cluster = cass_cluster_new();
  char* contact_points[CONTACT_POINT_COUNT] = { "cassandra-1", "cassandra-2" };
  CassSession* session;

  cass_cluster_set_protocol_version(cluster, CASS_PROTOCOL_VERSION_V4);
  for (int i = 0; i < CONTACT_POINT_COUNT; ++i) {
    cass_cluster_set_contact_points(cluster, contact_points[i]);
    CassError rc = CASS_OK;
    session = cass_session_new();
    CassFuture* future = cass_session_connect(session, cluster);
    cass_future_wait(future);
    rc = cass_future_error_code(future);
    cass_future_free(future);
    if (rc == CASS_OK) {
      break;
    } else {
      fprintf(stderr, "failed to connect\n");
      cass_session_free(session);

      if (i == CONTACT_POINT_COUNT - 1) {
        exit(1);
      }
    }
  }

  return 0;
}

上記の変更によって Connection reset by peer のログが出なくなることを確認できました。

まとめ

Connection reset by peer は Cassandra client が接続を閉じる出るログで、多くの場合 client の実装に問題がある
Cassandra の Connection reset by peer のログレベルは現在 TRACE になっているので、再現できる環境は限られている
Cassandra C/C++ driver では contact points が 2 つ以上あると最初にレスポンスが返ってきたもの以外の接続を閉じる仕様になっているので Connection reset by peer が出るのは仕方がない
- どうしても Connection reset by peer が出るのが気になるのであれば、contact points を 1 つだけ指定し、接続に失敗したら別のノードに接続を試みるよう自前でリトライするしかない

ECS の dependsOn で HEALTHY に依存させて HEALTHY にならなければ無限に待ち続けることがある

Tue, 29 Mar 2022 00:00:00 +0900

ECS の dependsOn では condition に HEALTHY を指定することができ、依存するコンテナのヘルスチェックが通るまで待つことができます。ところが、本来 essential なコンテナのヘルスチェックが通らないとタスク全体が終了するはずが、これを指定することで HEALTHY にならない限り、無限に PENDING な状態で待ち続けることがあるようです。後述の再現コードでは無限に待ち続けましたが、別のケース（ECS agent のバージョン等色々異なる）ではちょうど 10 分程度で stopped reason が launch timeout になったので、何らかの条件ではある程度の時間が経過すると timeout になるかもしれません。

再現コード

次のファイルに対して terraform apply することで再現確認できます。今実行すると AMI は ami-01a818286958067c9 (amzn2-ami-ecs-hvm-2.0.20220318-x86_64-ebs) になり、ECS agent version は 1.60.0 になりました。

provider "aws" {}

locals {
  application_name = "healthy-dependency-example"
}

data "aws_subnet" "default_1a" {
  default_for_az = true

  filter {
    name   = "availability-zone"
    values = ["ap-northeast-1a"]
  }
}

data "aws_ami" "most_recent_ecs_optimized" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-ecs-hvm-2.0.*-x86_64-ebs"]
  }
}

resource "aws_ecs_cluster" "main" {
  name = local.application_name
}

resource "aws_ecs_task_definition" "main" {
  family = local.application_name
  # fluetnd never becomes healhty
  container_definitions = <<-JSON
  [
    {
      "name": "main",
      "image": "ubuntu",
      "essential": true,
      "memoryReservation": 50,
      "dependsOn": [
        {
        "containerName": "fluentd",
        "condition": "HEALTHY"
        }
      ]
    },
    {
      "name": "fluentd",
      "image": "fluent/fluentd:v1.14.5-1.1",
      "essential": true,
      "memoryReservation": 50,
      "healthCheck": {
        "command": ["CMD", "nc", "-z", "127.0.0.1", "24225"],
        "interval": 5,
        "timeout": 5,
        "retries": 10
      }
    }
  ]
  JSON
}

resource "aws_ecs_service" "fluentd_forwarder" {
  name            = aws_ecs_task_definition.main.family
  cluster         = aws_ecs_cluster.main.name
  task_definition = aws_ecs_task_definition.main.arn
  desired_count   = 1
}


resource "aws_instance" "main" {
  ami           = data.aws_ami.most_recent_ecs_optimized.image_id
  instance_type = "c5.large"

  subnet_id = data.aws_subnet.default_1a.id

  associate_public_ip_address = true

  iam_instance_profile = "ecsInstanceRole"

  tags = {
    Name = local.application_name
  }

  user_data = <<-DATA
  #!/bin/bash
  cat <<'EOF' >> /etc/ecs/ecs.config
  ECS_CLUSTER=${aws_ecs_cluster.main.name}
  ECS_AVAILABLE_LOGGING_DRIVERS=["awslogs","fluentd"]
  EOF
  DATA
}

次のスクリーンショットのように created at から起動しないまま 30 分以上経過したので明示的に stop しました。

startTimeout で終了させることもできるらしい

他の環境で試した時は startTimeout を指定しても効果がなかった気がするんですが、ヘルスチェックの設定を指定しているコンテナに startTimeout を指定することで、その時間内に HEALTHY にならなければ stopped reason Task failed to start になることもあるようです。
次のスクリーンショットは fluentd コンテナの startTimeout として 60 を指定した場合のタスク詳細です。

ただし、その場合は新しいタスクを起動するのに 5 分ぐらいかかるケースもあるようです。すぐに起動するケースもあるようですが…

なお、run task で起動した task も同様に startTimeout で指定した時間が経過すると終了しました。startTimeout として 120 を指定しています。

fluentd worker が gem を読み込む際に稀に stuck するようで、その場合にタスクを終了し、別のタスクを起動してくれることを期待したんですが、挙動が不安ですね…

詳説 Amazon S3 ストレージ料金

Sun, 13 Feb 2022 00:00:00 +0900

Amazon S3 は AWS のサービスの中でも代表的なサービスの 1 つで、AWS を使っている人のほとんどが触れたことのあるサービスじゃないかと思いますが、料金体系の詳細を知っている人は意外に少ないんじゃないんでしょうか。
年末年始に個人アカウントにあるデータの整理をする際に料金体系の説明を隅から隅まで読んで完璧に理解したつもりの上でストレージクラスを S3 Standard - Infrequent Access から S3 Glacier Deep Archive に変更したにも関わらず想定外のコストがかかったので、自分が理解したことをメモとして残します。リージョンは Asia Pasific (Tokyo) を前提としますが、他のリージョンでも同様の考え方を適用できるはずです。

lifecycle を使わずに S3 の storage class を変更するには PUT Object - Copy を使うことになるみたいだけど、同じリージョン間の data transfer は無料だし copy と transition のコストは同じだから地道にコピーするのが良いか https://t.co/mOz52HWPDI
— Takeshi Arabiki (@a_bicky) January 2, 2022

storage class 変えるために copy object したら APN1-Retrieval-SIA の料金めっちゃかかってた…。lifecycle での transition だったらこの料金かからなかったりするんだろうか？内部的には copy object と同じことしてるんじゃないかと思うんだけど。
— Takeshi Arabiki (@a_bicky) January 4, 2022

S3 Standard のストレージ料金

ドキュメントに書いてあるとおり、ストレージクラスが S3 Standard の場合、最初の 50 TB / Month までは毎月かかる料金は $0.025 per GiB です。まずこの時点で躓く人もいるんじゃないかと思います。

「月の途中でオブジェクトを追加・削除した場合どうなるか？」

その問いに対する答えは FAQ の “Q: How will I be charged and billed for my use of Amazon S3?” に記載されています。

Assume you store 100 GB (107,374,182,400 bytes) of data in Amazon S3 Standard in your bucket for 15 days in March, and 100 TB (109,951,162,777,600 bytes) of data in Amazon S3 Standard for the final 16 days in March.

At the end of March, you would have the following usage in Byte-Hours: Total Byte-Hour usage = [107,374,182,400 bytes x 15 days x (24 hours / day)] + [109,951,162,777,600 bytes x 16 days x (24 hours / day)] = 42,259,901,212,262,400 Byte-Hours. Please calculate hours based on the actual number of days in a given month. For example, in our example we are using March which has 31 days or 744 hours.

Let’s convert this to GB-Months: 42,259,901,212,262,400 Byte-Hours / 1,073,741,824 bytes per GB / 744 hours per month = 52,900 GB-Months

This usage volume crosses two different volume tiers. The monthly storage price is calculated below assuming the data is stored in the US East (Northern Virginia) Region: 50 TB Tier: 51,200 GB x $0.023 = $1,177.60 50 TB to 450 TB Tier: 1,700 GB x $0.022 = $37.40

Total Storage cost = $1,177.60 + $37.40 = $1,215.00

3 月に 100 GiB と 100 TiB の S3 Standard オブジェクトをそれぞれ 15 日間と 16 日間保管した場合にかかる料金について説明されています。
その場合、1 時間単位で保存されているオブジェクトの合計サイズが 42,259,901,212,262,400 Byte-Hours になり、それを 31 日の 744 時間で割ったサイズを基に料金を求めていることがわかります。
つまり、3 月に 1 日だけ 31 GiB の S3 Standard オブジェクトを保存した場合、$0.025/GiB x 31 GiB x 1 day / 31 days = $0.025 の料金がかかり、4 月の場合は $0.025/GiB x 31 GiB x 1 day / 30 days = $0.02583… の料金がかかることになるみたいですね。

なお、FAQ やドキュメントには 1 時間だけ保管した場合の料金については言及されていない気がします。Cost Explorer を見る限りどうも日単位で請求されるようです。後述する S3 Standard - Infrequent Access の実験結果と合わせると、1 秒でも存在していれば 1 日分の料金がかかるのではなく、1 日のある時点に存在しているオブジェクトのサイズに対して料金が請求されものと予想されます。

S3 Standard - Infrequent Access のストレージ料金

ドキュメントに書いてあるとおり、ストレージクラスが S3 Standard - Infrequent Access（以降 Standard IA）の場合、毎月かかる料金は一律 $0.0138 per GiB です。ただし、次のような注釈があります。

** S3 Standard-IA and S3 One Zone-IA storage have a minimum billable object size of 128 KB. Smaller objects may be stored but will be charged for 128 KB of storage at the appropriate storage class rate. S3 Standard-IA, and S3 One Zone-IA storage are charged for a minimum storage duration of 30 days, and objects deleted before 30 days incur a pro-rated charge equal to the storage charge for the remaining days. Objects that are deleted, overwritten, or transitioned to a different storage class before 30 days will incur the normal storage usage charge plus a pro-rated charge for the remainder of the 30-day minimum. This includes objects that are deleted as a result of file operations performed by File Gateway. Objects stored for 30 days or longer will not incur a 30-day minimum charge.

つまりこういうことですね

128 KiB 未満のオブジェクトは 128 KiB であるものとして料金が算出される
オブジェクトが作成されてから 30 日未満で削除されたり別のストレージクラスに変換された場合でも 30 日分の料金がかかる

128 KiB 未満のオブジェクトのストレージ料金は Cost Explorer 等では APN1-TimedStorage-SIA-SmObjects に計上され、30 日未満で削除されたり別のストレージクラスに変換された場合のストレージ料金は APN1-EarlyDelete-SIA に計上されるようです。
APN1-TimedStorage-SIA-SmObjects や APN1-EarlyDelete-SIA については次のページに説明が載っています。

Understanding your AWS billing and usage reports for Amazon S3 - Amazon Simple Storage Service

ここで、理解を深めるために、次のようなライフサイクルルールを設定したバケットに 100 MB のオブジェクトを Standard IA で put してみます。

% aws s3api get-bucket-lifecycle --bucket $bucket
{
    "Rules": [
        {
            "ID": "transit-to-glacier",
            "Status": "Enabled",
            "Transition": {
                "Days": 1,
                "StorageClass": "GLACIER"
            }
        }
    ]
}

put するコマンドは次のとおりです。　

dd if=/dev/zero of=output.dat bs=1024k count=100
aws s3 cp --storage-class STANDARD_IA output.dat s3://$bucket/transit-to-glacier/

put 直後の結果は記録してないんですが、今オブジェクトの内容を確認すると次のような結果になりました。

% aws s3api list-objects-v2 --bucket $bucket --prefix transit
{
    "Contents": [
        {
            "Key": "transit-to-glacier/output.dat",
            "LastModified": "2022-01-04T17:22:13+00:00",
            "ETag": "\"0c4af570340e15f2be9924e70bc34257-13\"",
            "Size": 104857600,
            "StorageClass": "GLACIER"
        }
    ]
p}

Cost Explorer で service を S3 に絞り、Usage Type で group by した結果の CSV ファイルをダウンロードして関係のあるコストだけを見てみると次のようになりました。

Date	Usage	Cost ($)	Note
2022-01-04	APN1-Requests-SIA-Tier1	0.00013	ETag の末尾の 13 からわかるとおり、13 parts の multipart upload でアップロードされているので 13 PUT の料金
2022-01-05	APN1-TimedStorage-SIA-ByteHrs	0.0000434728	0.0138/GiB x 100 MiB / 1024 MiB/GiB x (24 hours/day x 1 day / 744 hours)
2022-01-06	APN1-TimedStorage-GlacierByteHrs	0.0000141803	32 KiB のメタデータの料金も考慮すると 0.0045/GiB x 102432 KiB / 1048576 KiB/GiB x (24 hours/day x 1 day / 744 hours)
2022-01-07	APN1-Requests-Tier3	0.00003426	Lifecycle Transition requests into S3 Glacier Flexible Retrieval ($0.03426 per 1,000 requests)
2022-01-07	APN1-TimedStorage-GlacierByteHrs	0.0000141803
2022-01-08	APN1-EarlyDelete-SIA	0.0011302928	0.0138/GiB x 100 MiB / 1024 MiB/GiB x (24 hours/day x 26 days / 744 hours)（4 日に put して 8 日に請求されたから、5 日〜7 日は APN1-TimedStorage-SIA-ByteHrs が 0 だけど 26 日分っぽい）
2022-01-08	APN1-TimedStorage-GlacierByteHrs	0.0000141803

なお、ストレージクラスが Standard IA や S3 Glacier Flexible Retrieval のオブジェクトはこれ以外に存在していないので、上記の料金はこの検証にかかった料金のみのはずです。

上記の結果からわかるように、Standard IA のオブジェクトを生成すると最低 30 日分のストレージ料金がかかるのかと思いきや、若干安く済むようです。単なるバグかもしれないですが。

また、S3 Standard の按分計算の考え方がわかっていれば、オブジェクトが作成されてから 30 日経過した後に月の途中でオブジェクトを削除しても 1 ヶ月丸々分の料金がかからないことは想像が付きます。

S3 Glacier のストレージ料金

S3 Glacier Flexible Retrieval と S3 Glacier Deep Archive ストレージクラスでは、ストレージ料金算出の際にオブジェクトそのもののサイズに加えてメタデータのサイズも考慮する必要があります。

For each object that is stored in S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive, Amazon S3 adds 40 KB of chargeable overhead for metadata, with 8 KB charged at S3 Standard rates and 32 KB charged at S3 Glacier Flexible Retrieval or S3 Deep Archive rates.

cf. Amazon S3 Simple Storage Service Pricing - Amazon Web Services

Standard IA の APN1-TimedStorage-GlacierByteHrs の補足説明でも書いたように、例えば 100 MiB の S3 Glacier Flexible Retrieval オブジェクトがあった場合、メタデータのうち 32 KiB は S3 Glacier Flexible Retrieval の料金がかかり、8 KiB は S3 Standard の料金がかかります。

それ以外は S3 Standard と Standard IA のストレージ料金の算出方法さえわかれば他のストレージクラスでも同様に計算できるはずなので詳細は割愛します。

ストレージクラスの変更にかかる料金

S3 オブジェクトのストレージクラスを変えるには次の 2 つの方法があるようです。

ライフサイクルでストレージクラスを変更する
- Lifecycle Transition requests into に対する料金がかかる
PUT Object - Copy API で同じキーに別ストレージクラスでコピーする
- コピー元のストレージクラスの data retrieval に対する料金と、コピー元ではなくおそらくコピー先のストレージクラスの COPY request に対する料金がかかる
- cf. Using Amazon S3 storage classes - Amazon Simple Storage Service

PUT Object - Copy API でストレージクラスを変更する場合に data retrieval に対する料金もかかることは FAQ の “Q: What charges will I incur if I change the storage class of an object from S3 Standard-IA to S3 Standard with a COPY request?” で次のように言及されています。

You will incur charges for an S3 Standard-IA COPY request and an S3 Standard-IA data retrieval.

この回答ではコピー元のストレージクラスの COPY request とコピー元のストレージクラスの data retrieval 料金がかかることになってますが、年始に 4,000 以上の Standard IA オブジェクトを Glacier Deep Archive にコピーしたところ、APN1-Requests-GDA-Tier1 が $0.2834243（約 4360 オブジェクト分）、APN1-Requests-SIA-Tier1 が $0.000020（2 オブジェクト分）かかっていることからも、COPY request はコピー先のストレージクラスの料金がかかるようです。
また、FAQ では Standard IA についてしか言及されていませんがおそらく Glacier Instant Retrieval も同様です。Glacier Instant Retrieval で言及がないのはこのストレージクラスが比較的新しいストレージクラスだからだと思います。他の Glacier ストレージクラスで言及がないのは直接 PUT Object - Copy API を使うことはできず、一度 restore しないといけないからでしょう。

Standard IA のオブジェクトをライフサイクルで Glacier に変更する検証にかかった料金からもわかるとおり、ライフサイクルでの変更であれば data retrieval に対する料金はかからないようです。
例えば Standard IA のオブジェクトを S3 Glacier Deep Archive に変更する場合、ライフサイクルで変更する場合は 1,000 オブジェクトに対して $0.065 かかるのに対して、COPY request は 1,000 リクエストに対して $0.065 なので、安く済ませたい場合はライフサイクルでの変更の方が data retrieval に対する料金がかからない分安いと言えます。Standard から Glacier Deep Archive に変更するのであれば data retrieval の料金がかからないのでどちらの方法を取っても料金は同じです。
もし Standard ストレージクラスの COPY request の料金がかかるのであれば、Standard ストレージクラスのオブジェクトを定期的に Glacier Deep Archive に変更する際に PUT Object - Copy API を使った方が、ライフサイクルを使うよりも安くなるということなので、このことからも COPY request はコピー先のストレージクラスに対してかかるものと思われます。

おまけ〜 ETag の計算方法〜

100 MiB の Standard IA オブジェクトを put する際にかかった料金の補足説明に次のように書きました。

ETag の末尾の 13 からわかるとおり、13 parts の multipart upload でアップロードされているので 13 PUT の料金

ローカルファイルと S3 オブジェクトの内容が同じかどうかチェックしたくて、etag がどのようなロジックで算出されているのか調べていた時に末尾が part の数であることを知ったんですが、Ruby だと次のようなメソッドで算出できるようです。

def calculate_digest(filename, part_size: nil, multipart_threshold: nil)
  file_size = File.size(filename)
  return Digest::MD5.file(filename).hexdigest if file_size < multipart_threshold

  part_size ||= Aws::S3::MultipartFileUploader.new.send(:compute_default_part_size, file_size)
  md5 = Digest::MD5.new
  digests = []
  File.open(filename, 'rb') do |f|
    buf = ''
    while f.read(part_size, buf)
      digests << md5.update(buf).digest!
    end
  end

  "#{md5.update(digests.join).hexdigest}-#{digests.size}"
end

part_size や multipart_threshold はオプションで変えられるので環境によって異なります。awscli と aws-sdk-ruby でデフォルト値も違います。
算出ロジックについての AWS の公式ドキュメントは見つからなかったんですが、このロジックは例えば次のページで言及されています。

s3cmd - What is the algorithm to compute the Amazon-S3 Etag for a file larger than 5GB? - Stack Overflow

なお、multipart upload でアップロードしたオブジェクトを PUT Object - Copy API でコピーすると etag の値はコンテンツ全体の MD5 値になるようです。

カランメソッドの全ステージを修了した

Sun, 06 Feb 2022 00:00:00 +0900

先日、カランメソッドの全ステージを修了しました。約 2 年という長い道のりになりましたが、最後までやり切ることができて一安心です。良い機会なのでカランメソッドについて振り返ってみます。

カランメソッドを始めたきっかけ

元々英語の勉強を始めたきっかけは re:Invent 2019 に参加することになったからでした。英語ができなくても十分楽しめると言っている人もいますが、より有意義な時間を過ごすためにも英語を勉強することを決意しました。当時は YouTube 広告で知った ENGLISH COMPANY に 2 ヶ月ほど通い、その後 2 週間程度 DMM 英会話で英会話の練習をしました。

ところが結果は次のように散々でした。

ブースを一人で回っても相手が何を言っているかほとんどわからなかったし、聞きたいことも聞けなかった
現地の方との懇親会的なものがあったが、相手が何を言っているかほとんどわからなかったし、まともに発言できなかった
re:Invent の醍醐味と言われているセッションに全く参加しなかった（する勇気もなかった）
- 講演が後で公開されることは知っていたのでワークショップメインにしたが、ワークショップも頑張って探せば資料が見つかることを後から知った
- 「講演は終わった後に講演者に質問できるのが良いよね」とか「同じ課題を抱えた人と議論できるセッションがあるのが良いよね」とか「Security Jam 参加しなかったの？もったいない！」とか他の参加者に言われて肩身が狭くなる始末…

一方で、一緒に参加した同僚（日本語も英語もペラペラのバイリンガル）はハッカソンで優勝したりと、とても満喫できている様子でした。

英語能力以外に社交性の問題もある気はしますが、次に参加する機会があれば、今度こそは有意義な時間にできるようにと、英語の勉強を継続することにしました。re:Invent 以外にも英語ができるようになることで、次のようにとにかく人生の選択肢が増えるのが大きなメリットと考えています。

何かの情報を得る時に洋書や英語の動画からも情報を得ることができる
- 海外の勉強会の動画を観て理解できるようになりたい
海外サービスから「ちょっとミーティングさせてくれない？」と打診があった時に快諾できる
出張や旅行で海外に行くことの敷居が下がる
英語能力を必須とする企業（外資系や海外企業など）を転職先の候補にできる
- 給与が上がる可能性も高い

そんな中 twitter でカランメソッドを知りました。TOEIC Listening & Reading ではパート 2（短い質問文に対して適切な回答を選択する問題）が一番苦手なことと、普通に英語の文章や例文を読むだけだと疑問文やそれに対する回答を見かけたり聞いたりする機会が稀なことから、自分の弱点を克服するのにちょうど良さそうだと思い、レッスンを受けてみることにしました。
QQ English とネイティブキャンプで迷って QQ English に決めた気がしますが、決め手は覚えていません…。

カランメソッドを終えた感想

カランメソッドがどのようなものかは QQ English による説明や他の方の記事に譲ります。個人的にはカランメソッド全ステージ制覇、実体験に基づく効果＆特徴まとめ - HALENG（ハレング）がよくまとまっていて、同じく全ステージ修了している方の書いた記事なので説得力もあるかなと思います。

カランメソッドを始める前の自分の英語能力に関する自己認識は次のとおりです。

リーディングは得意
- 専門分野の英語文章であれば辞書なしで読めるし（知らない単語があっても内容を推測できる）、比較的単純な文であればいちいち頭の中で日本語に訳さなくても内容を理解できる
リスニングとスピーキングにかなりの苦手意識がある
- 特に聞き返したり質問をする能力が皆無
ライティングに対してはそれほど苦手意識はない
- 自分の慣れたテーマにおいて 10 秒ぐらい考えれば自分の伝えたい内容はある程度書き起こせる
文法の知識は平均的な日本人より高いレベルにある（と思う）
音声変化についての知識がある
- これについては ENGLISH COMPANY がかなり力を入れていた
シャドーイングによる勉強ができる
- これも ENGLISH COMPANY がかなり力を入れていた

カランメソッドの最初のレッスンは “What’s this?” “It’s a pen.” のような初歩的な質問文と回答文ですが、質問に回答する経験があまりにもなさ過ぎて、これでも即答するのに割と苦労しました。また、「vowel (母音)」「consonant (子音)」のような英語を学習する上では超重要だけど日常会話ではあまり使わないような単語も習うので、ステージ 1 から始めたのは良かったと思います。¹

自分の場合、FAQ にあるとおり予習は一切せず、教科書に付いてくる音声の質問文をシャドーイングし、回答文をオーバーラッピングすることで復習していました。音声と同じスピードでスラスラ回答できるまで復習していたのでかなりの時間がかかりました。一度内容を理解したら滅多に教科書を見なかったので、ディクテーションでのスペルミスが多かったです。スペルは発音にも関係するので、もっと意識すべきだったと反省しています。

ちなみにステージ 8 のレッスン 112 に次のような長文があるんですが、こういうのもスラスラ言えるように練習してたので、かなり時間がかかったのは納得してもらえるんじゃないかと思います。

Q. Supposing there was a place, shall we say, somewhere in the middle of a jungle in South America, where you knew for sure that there was about fifty million pounds’ worth of gold, but the chances of returning alive were only fifty-fifty, would you go and take a chance and try your luck, or would you just stay at home and dream about it?

A. Supposing there was a place, shall we say, somewhere in the middle of a jungle in South America, where I knew for sure that there was about fifty million pounds’ worth of gold, but the chances of returning alive were only fifty-fifty, I’d just stay at home and dream about it.

ステージ 9 のレッスン 137 は次のような類の長文回答が 3 つあったりします。これを何も見ずに一字一句違わずスラスラ答える必要があるわけなのでかなり大変です。ステージ 9, 10 が一番大変な印象です。

Q. What kind of sign do we see on the side of the road that warns us that there’s danger ahead?

A. The kind of sign we see on the side of the road that warns us that there’s danger ahead is usually a red triangle with a picture of the danger in the middle. If, for example, there is a dangerous bend ahead, there will be a line in the shape of a dangerous bend inside the triangle.

レッスンでは先生が単語の説明などをしてくれますが、説明自体を聞き取れなかったり、説明してもらっている最中は理解できたけど次の単語を説明してもらっている間に最初の単語の内容を忘れたりということが最後までありました。教科書にも単語の説明が書いてあれば良いんですが、単語とそれを使った質問文・回答文がメインで、単語の説明は滅多に載ってないのが残念です。

個人的にはカランメソッドの良い点として次のような点があると思いました。

単語の説明や違いを説明する能力がかなり上がる
- “What’s the difference between …?” のように単語の意味の違いを尋ねる質問や、文法や文章の書き方についての質問が多く、その回答を空で言える必要がある
そこそこ複雑な構造の文を理解したり自分で書いたりする能力が上がる
- 1 文の中に接続詞や関係詞が複数出てくるような長文がざらにある
- 仕事で英語の文を書く時に今までよりもスラスラ複雑な文を書けるようになった実感がある
語彙力が上がる
- ステージが上がると知らない単語もけっこう出てくる
- 2020 年の 7 月から別途週 2 で 90 分の英会話レッスンをしているが、「これカランメソッドで習った単語で説明できる！」といった経験がしばしばある
英文法の復習になる
習った単語を別の単語の例文とかでも使うようになっていて、教材としてよく考えられている

逆に微妙な点としては次のような点が挙げられます。

自分の場合はリテンション能力が向上したという実感はない
- カランメソッドを受けた人の多くがリテンション能力に言及しているが、自分は復習をし過ぎて暗記になってしまっていたからか、リテンション能力が向上した実感はほとんどない
ちゃんとスラスラ回答しようと思うと基礎的な英語力ではなく暗記能力が必要で勉強方法として疑問
- クローズドクエスチョンに対する回答は質問文をちょっといじるだけで回答できるが、オープンクエスチョンもほとんどの回答文が固定で、一字一句間違えずに回答するのは非常に難しい
- 回答文を丸暗記するぐらい練習して初めて身になるという方針なのかもしれない
会話能力は身に付かない
- ステージが上になると自分の意見を自由に答える質問も増えるが、会話の練習を重視するなら普通に英会話のレッスンを受けた方が効率は良いだろう
- 自分の場合、英会話はカランメソッドを修了してからやり始める予定だったが、ひょんなことから英会話のレッスンも受けることになって、カランメソッドで習ったことを実践で活かす練習になってとても良かった
発音は一定レベル以上は上がらない
- 先生によるかもしれないが、自分は L の発音をたまに訂正されるぐらいだったし、細かく発音を訂正していたら物凄く時間がかかるだろうし、先生も生徒と同様に回答文を読み上げるのでそもそも訂正が難しいと思う
オンラインレッスンだと通信状況の当たり外れや映像のラグが気になる
- “What am I doing?” のような質問文はタイムラグのせいで、先生が回答文を読み上げるまでに何を答えるべきか認識できないことがある（そもそも何もジェスチャーしない先生もいるが）
- 特定のヘッドセットの問題か、先生と一緒に発声すると、先生が何を話しているのか全く聞こえないことがあり、先生自体の質が良くても予約するのを避けることになる（一度 Skype を使うことを提案されたことがあり、Skype だと問題なかったが、あまり先生を Skype に登録したくない）
ネイティブスピーカーの 1.5 倍で質問文を言える先生はかなりレア
- 人気の先生も含めて 50 以上の先生のレッスンを受けたが、教科書の音声より速い先生は 1, 2 人ぐらいしかいなかった（速く話してほしいと要望すれば速くしてもらえるかもしれない）
人気の先生でもけっこう発音を間違える
- 例えば shove は「シャブ」に近い音だが、ほとんどの先生は「ショブ」と発音していた
わざわざレッスンを受けなくても自習できそう
- ほとんど間違いを訂正されない（むしろ先生の方が間違える）
- わからない点があった場合に質問ができるわけでもない（もう一回説明してと言ったら説明してくれるし、質問したら答えてくれる先生もいるだろうけど、カランメソッド自体はそういう時間を設けない方針のはず）
- リーディングの時間は特に無駄（ステージ 11 とかになってくるとスラスラ読めてもリーディングだけで 10 分かかることがざら）

ステージ 4 ぐらいでやめる人がけっこういるみたいですが、ステージ 4 までは基本中の基本しかやらないし、質問文や回答文も単純なものばかりなので、ステージ 4 までやって意味がないと判断するのは時期尚早かなと思います。

カランメソッド修了までにかかった時間と費用

最初のレッスンが 2020 年 2 月 9 日で、最初の方は 2 日に 1 回、その後 1 年以上週 5, 6 回、その後半年以上週 4, 5 回 25 分のレッスン受けて 2022 年 1 月 26 日に最後のレッスンを受けたので 2 年近くかかったことになります。合計 491 レッスン受けたようなので、時間にして約 205 時間です。レッスン自体は 25 分ですが、自分の中で勉強方法が定着してからはレッスンの前に 1 〜 2 時間、レッスンの有無に限らずほぼ毎日寝る前に 1 〜 2 時間程度復習をしていたので、それらの時間も含めると費やした時間は 2000 時間を超えるんじゃないかと思います。

費用は約 25 万円で、内訳は次のとおりです。

項目	単価（円）	回数	合計（円）
月会費プラン(月16回コース)/800pts	7,348	7	51,436
月会費プラン(月30回コース)/1,500pts	10,638	16	170,208
月会費プラン(月 4回コース)/200pts	2,680	1	2,680
教科書	1,760	12	21,120
追加ポイント購入/200pts	2,037	1	2,037

QQ English はポイント制で、いずれかの月会費プランを契約して、足りなかったら追加ポイントを購入することになります。人気の先生は 50 ポイントより多くのポイントを消費するので、月 30 回コースだからといって 30 レッスン受けられるとは限りません。自分の場合、50 ポイントの先生で良い先生を見つけてはリピートしていたところ、半分以上の先生は予約に 60 〜 75 ポイント必要な先生になっていきました。また、月会費プランで付与されたポイントは原則次の更新までに使い切らないと失効します。失効しないようにする抜け道はありますが。

なお、FAQ には目安 310 レッスンと書いてありますが、先生と生徒両方共に優秀でネイティブスピーカーの 1.5 倍速でやり取りできない限り 310 レッスンでは終わらないと思います。おそらく平均で 550 〜 600 レッスンぐらいじゃないかと思います。自分の場合は前述のとおりかなりの時間をかけて復習しているので、平均的な人よりは少ないレッスンで終えられているんじゃないかと思います。

現在の英語能力

これだけ勉強したらどれぐらい英語力が上がったか気になりますよね！というわけでいくつか試してみました。

ELSA Speak

去年の 6 月 11 日に ELSA Speak をちょっと使ってみたんですが、当時は 61% でした。カランメソッドを始める前にテストしていたらもっと悪い結果になっていたと予想されます。

今年の 1 月 28 日には 64% だったので、ELSA Speak を全然やっていなかったにも関わらずちょっとだけスコアは改善している模様です。

発音がダメダメで、特に L, R, TH 辺りが致命的にダメなので要改善ですね。

QQ English のレベルチェック

QQ English のカリキュラムにはレベルチェックもあるので受けてみました。人によって内容は違うかもしれませんが、レベルチェックではあるトピックに関する 4 つの写真それぞれについて内容を説明しました。最初のアイスブレーキング的な会話や最後の総評的な時間を除くと、レベルチェック自体の所要時間は 20 分程度だと思います。

結果は次のとおりレベル 4 でした。

【レッスン内容】
-———————————————–
日付： 2022-01-27
時間： 00:00-00:30
教師： XXXX
カリキュラム：レベルチェック（Level check）
————————————————

Level Check

Overall =4.0
Vocabulary = 4.0
Comprehension = 4.0
Grammar = 4.0
Pronunciation = 4.0
Diction = 4.0
Confidence =4.0
Speed = 3.5
Responding Time = 3.5

STRONG POINTS:
He has good sentence construction and grammatical structure.
He shows enthusiasm and confidence in speaking the language.
He can take part in extended conversations.

POINTS FOR IMPROVEMENT:
He needs to be exposed to more complicated vocabulary.
He needs reinforcement in grammar and pronunciation.

NAME: Takeshi Arabiki
TOPIC: Ever and Never
AVERAGE LEVEL: 4.0
EVALUATOR:XXXX

普段レッスンを受けている先生よりも自分のことを知らない先生の方がより客観的な結果になるかなと思って、一度もレッスンを受けたことのない先生を指定してたんですが、直前にキャンセルになったので、自分のことを覚えているかわからないぐらい久しぶりの先生にチェックしてもらいました。
ちなみにレベル 4 は CEFR A2 相当らしいです（低い…）
cf. 英語レベル表 | オンライン英会話ならQQ English

絵を見て内容を説明する形式はスピーキングテストでよくある形式のようですが、英語力以上に、少ない情報量から自分の英語力を証明できる程度に話す内容を考えられる洞察力・想像力と、それを理路整然と難しい単語も織り交ぜながら説明できる頭の回転の速さが要求される気がます。もちろん英語力も必要ですが、英語力だけあってもダメですね。
ちなみ、前述のとおりカランメソッドだけで英会話ができるようになるかというとかなり微妙で、英会話をやっていなかったらもっと悲惨な結果になっていたと思います。

TOEIC スコアの推移

全ステージを修了してからはまだ TOEIC を受けてないですが、ステージ 11 の途中（Lesson 170 の p. 1002）で受けてみました。
カランメソッドの最初のレッスンの前に受けた TOEIC Listening & Reading のスコアは 870、最新のスコアは 935 でした。TOEIC 対策としては試験直前に模試を 1 回やっただけですが、まずまずの上がり幅じゃないかと思います。

試験日	Listening	Listening %ile Rank	Reading	Reading %ile Rank	Total
2008-01-13	285	35	320	66	605
2008-03-23	315	47	315	64	630
2009-05-31	340	57	365	78	705
2009-11-29	355	63	355	75	710
2016-05-29	355	52	400	86	755
2020-01-12	445	83	425	90	870
2021-08-22	455	85	480	98	935

個人的にはリスニングのスコアが大幅に上がってリーディングはほとんど変わらないと思ってたんですが、完全に逆でした。今回初めてリーディングパートを時間内に終わらせることができたんですが、カランメソッドでは比較的長く複雑な文を扱うので、スラスラ読めるようになったのかもしれません。

ちなみに、2019 年 9 月 19 日から約 2 ヶ月間は ENGLISH COMPANY で週 1 回 90 分のレッスンを受けたり、レッスンを受けない日は毎日 3, 4 時間ぐらい課せられた課題（TOEIC 対策の単語を覚えたり、パート 2 のディクテーションをやったり、TOEIC の文法問題集をやったり、パート 4 の音声を使ってシャドーイングしたり）をこなしたり（一応 1.5 時間ぐらいでこなせる想定の量らしい）、それに加えて毎週末 TOEIC の模試を受けないといけなかったりという生活だったので、2020 年 1 月 12 日の結果は TOEIC の慣れによって実際の能力より高く出ていた可能性はあります。

なお、リスニング 455 は CEFR B2、リーディング 480 は CEFR C1 に相当します。
cf. TOEIC Program各テストスコアとCEFRとの対照表｜【公式】TOEIC Program｜IIBC

TOEIC 900 超えというと、めちゃくちゃ英語ができるんだろうなと思っていたんですが、リスニングは完璧に聞き取れているわけではないし、「たぶんこれ」という感覚で答えているものもけっこうあるので、リスニングは 490 以上じゃないと CEFR C1 相当じゃないというのも納得です。

Duolingo English Test

Duolingo English Test も受けてみました。事前にガイドをひと通り読み、練習問題を 2 回こなして本試験に臨んだところ、結果は 105 で、CEFR B2 相当でした。

個人的な感覚では TOEIC の結果も踏まえると各英語スキルは次のような感じじゃないかと思っているので、Reading が関係する能力が B2 の上の方、Speaking が関係する能力が B1 の上の方というのは自己認識とも一致します。

Listening: B2
Reading: C1
Speaking: B1
Writing: B2

現在・今後について

自分は次の点が課題だと思っているので、それらを克服していきたいと思っています

リスニング能力
- 他の課題を克服すればある程度改善するはず
スピーキング能力
- 週 2 回の英会話を継続に加えて QQ English のトピックカンバセーションを受けてみる
特定の語の発音
- ELSA Speak を頑張る
語彙力
- iKnow! を頑張る

カランメソッドの復習も一人でやっていくつもりです。ステージ 11, 12 は full book revision がないのでとりあえずステージ 11, 12 を復習しています。
半年後と年末に再度 Duolingo English Test を受けてみて、年内に C1 に到達したい…！

QQ English はステージ 1 からしか始められないですが、ネイティブキャンプは途中のステージから始められるようです ↩

タスクの年度初め大掃除をしたい

Sun, 23 Jan 2022 00:00:00 +0900

普段こういう話はブログに書かないんですが、もしかしたら参考になるような意見ももらえるかもしれないと思って公開してみます。今自分が所属しているチームを想定して書いていますが、当てはまる組織も多いのではないかと思います。

タスクの年度初め大掃除とは

数営業日以内で消化できるし、やった方が良い・やりたいのに重要度・緊急度が高くなく消化できていないタスクをある程度一気に消化するイベント

何故年度初めなのか？

大掃除のことも考慮した上で目標を立てられる
年度末だと目標達成が優先されてほぼ確実に実現されないだろう
- 目標にちゃんと組み込まれていたとしても他の目標に比べて優先順位は下がることがほとんどだろう　
たくさんのタスクをこなすことで勢いに乗れる（かもしれない）

重要度・緊急度が低いタスクをどうしてわざわざ消化するのか？

主に次の 3 点が理由

管理されているタスクを減らすため
ある時急激に緊急度が上がって疲弊することがあるため
じわじわと生産性が低下していくため

以下詳細

管理されているタスクを減らすため

タスクが多いと「それはタスク化されていた気がする」、「このタスクは別のタスクと重複してる」というやり取りが頻繁に起きる。また、定期的に全タスクを棚卸ししているが、それにも多大な時間がかかる。
一定期間更新がないものは自動的にクローズすれば良いかもしれないが、その場合次のような問題がある

後でやることを約束にしていたタスクがクローズされる
- 「締め切りが近いので後でリファクタリングします、テスト追加します」みたいなことはよくあるはず
同じ内容のタスクを毎回作成する手間が増える
- 作成時の手間を省くと「これってどういうタスクだったけ？」と内容を思い出す手間が生じたり、他の人が見ても何のタスクかさっぱりわからなかったりし、作成する意味がない

ある時急激に緊急度が上がることがあるため

重要度・緊急度を見誤っているとも言えるかもしれないが、何かをきっかけに緊急度が上がり疲弊することがあるだろう。
日頃から重要度・緊急度の低いタスクでも潰しておくことで余裕を持った対応ができる。

じわじわと生産性が低下していくため

重要度・緊急度が低いタスクは次のような傾向がある

放置しておいてもサービスの障害に繋がらない（少なくとも繋がらないように見える）
既存のメンバーや特定の個人は困っていない
時間をかけることでカバーできる（運用でカバーできる）

これらを放置することで次のような問題が起きる

不要なコード・リソースの削除やリファクタリングをしないことによる生産性低下
- 特に新しい人が入った時に効いてくるはずだが、コミット数やデプロイ数とかを生産性の指標にするだけでは見えてこない生産性低下な気がする（良い指標があれば知りたい）
手動オペレーションを繰り返すことによる生産性低下
- これは SRE の文脈でいう「トイル」の割合を管理することでモニタリングできるかもしれない
精神的ストレスによる生産性低下
- 汚部屋で仕事するよりきれいな部屋で仕事したい人が多いと思うが、その感覚
- 自分の場合、生産性が低下しているかはわからないが他人よりストレスを感じやすいと思われる
- これによる生産性低下を計測する良い方法はないだろうか…（生産性低下というより離職率増加に繋がるものかもしれない）

どうやるか？

期間中にレビューに出せるようなタスクに取り掛かる
- 目安として数営業日以内にレビューに出せるもの
- 時間がかからなそうに見えて着手した後、時間がかかりそうとわかった時点でタスクを分割したり別のタスクに切り替える
重要度・緊急度は全く考えなくて良い
- とはいえ、やるだけ時間の無駄と思うようなタスクはやらない（そういうタスクは存在しないと思いたい）
大掃除の一環で行ったタスクは専用のタグを付けて識別できるようにする
誰かに見返りとして amazon ギフトカード 1 万円分とか送りたい
- 期間終了後、各人成果発表
- 「労をねぎらいたい」と思った人にに各人投票し、得票数の一番多かった人に進呈
  - 同率一位は山分け
- 期間中に重要度・緊急度の高い差し込みタスクを担当したメンバーへの配慮はどうするか？

rdkafka-ruby で Local: Broker transport failure (transport) が起きる場合の対処方法

Tue, 02 Nov 2021 00:00:00 +0900

rdkafka-ruby を使っていると “Local: Broker transport failure (transport)” というエラーに遭遇することがあります。様々な条件で発生するかもしれませんが、自分が遭遇したのは次の条件を全て満たす時です。

metadata.broker.list (bootstrap.servers) に指定されている broker のうち 1 台以上の調子が悪い
- 高負荷状態であるとか、broker が起動していないとか
producer を生成してからすぐに produce を実行する
produce を実行する際に partition_key が指定されている

なお、rdkafka-ruby のバージョンは 0.10.0、librdkafka のバージョンは 1.5.0 を前提としています。

エラーが起きる場合の対処方法

次のどれかの選択肢を取ることになります。設定値の調整ではどうにもなりません。

produce に指定する key と partition_key が同じであれば partition_key の指定をやめる

単純にリトライする

個別にリトライする

  attempt = 0
  begin
    attempt += 1
    producer.produce(**kwargs)
  rescue Rdkafka::RdkafkaError => e
    raise if attempt == 3
    logger.warn("Retry to produce due to #{e} (#{e.class}) (#{attempt}th attempt)")
    retry
  end

モンキーパッチを当てる

  class Rdkafka::Producer
    prepend Module.new {
      def partition_count(*args)
        attempt ||= 0
        attempt += 1
        super
      rescue Rdkafka::RdkafkaError => e
        raise if attempt == 3
        Rdkafka::Config.logger.warn(%Q{Retry to produce due to "#{e} (#{e.class})" (#{attempt}th attempt)})
        retry
      end
    }
  end

rd_kafka_metadata のタイムアウトが 1 秒以上になるようにモンキーパッチを当てる

  module Rdkafka::Bindings
    singleton_class.prepend Module.new {
      def rd_kafka_metadata(*args, timeout)
        timeout < 1250 ? super(*args, 1250) : super
      end
    }
  end

producer を生成してから 1 秒以内に produce を実行するのを避ける
- 例えばアプリケーション起動時に producer を生成してそれを使い回すなど

エラーが起きる理由

冒頭で述べた条件を全て満たす場合にエラーが起きる理由について説明します。

再現コード

localhost:9092 に Kafka broker が起動している場合、次のスクリプトを実行すると 2 回に 1 回程度 “Local: Broker transport failure (transport)” が起きます。

require 'rdkafka'

logger = Logger.new($stdout)

# Hack to display logs immediately
Rdkafka::Config::REQUIRED_CONFIG = { "log.queue": false }
module Rdkafka::Bindings
  def self.rd_kafka_conf_set_log_cb(*); end
  def self.rd_kafka_set_log_queue(*); end
end

producer = Rdkafka::Config.new({
  'metadata.broker.list': 'localhost:9092,example.com:9092',
  debug: 'broker,metadata',
}).producer

logger.info('Produce message')
begin
  producer.produce(
    topic:   'test',
    partition_key: 'partition_key',
  ).wait
rescue Rdkafka::RdkafkaError => e
  logger.error("#{e} (#{e.class})")
  raise
ensure
  producer.close
end

エラー発生時の backtrace は次のようになります。

/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/metadata.rb:20:in `initialize': Local: Broker transport failure (transport) (Rdkafka::RdkafkaError)
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:68:in `new'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:68:in `partition_count'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:106:in `produce'
        from /Users/arabiki/path/to/script.rb:19:in `<main>'

backtrace の情報から、メタデータの取得に失敗していることがわかります。
メタデータの取得は partition_key を指定した場合にのみ必要で、パーティション数を取得するために実行されています。
よって、もし key と partition_key が同じであれば partition_key の指定をなくすだけでエラーを回避できます。

余談ですが、partition_key を指定すると、partitioner に何を指定していても consistent_random partitioner が使われるので、注意が必要です。この問題は rdkafka-ruby#173 がマージされると解消します。

key と partition_key に異なるものを指定しつつエラーを回避するには、metadata.broker.list に指定している broker が複数台あるのにも関わらず、1 台が異常なだけで rd_kafka_metadata に失敗する理由がわかる必要があります。つまり、rdkafka-ruby や librdkafka の内部処理まで理解する必要があります。

produce の際の rdkafka-ruby & librdkafka の内部処理

まず、producer を生成する際、rdkafka-ruby は librdkafka の rd_kafka_new を呼ぶことで handler を生成します。

rd_kafka_new を実行すると、次のような処理が行われます。

main thread の作成
- この中で定期的に行いたい処理を実行している
metadata.broker.list に指定されている broker の追加
- broker ごとに thread を作成する
metadata.broker.list に指定されているうちランダムに選択した 1 台と接続
接続を確立した broker からメタデータを取得する
メタデータに存在する broker を登録する
- このタイミングで metadata.broker.list に指定されている broker は他の broker と同じ扱いになる

その後 produce を実行すると、メタデータを取得する関数である rd_kafka_metadata が呼び出されます。rdkafka-ruby の場合はタイムアウトが 250 ms でハードコーディングされています。rd_kafka_metadata の中で、問い合わせ先の broker を選択する処理である rd_kafka_broker_any_usable が呼び出され、この結果が NULL、つまり使用可能な broker が 1 台も見つからなかった場合に例のエラーになります。

rd_kafka_broker_any_usable では次のような処理が行われています。

state が UP か UPDATE の broker を 1 台選択
- 選択する際の優先順位は rdkafka_broker.c#L1366-L1372 にあるとおりで、接続に成功しやすいものを優先していそう
state が UP や UPDATE の broker がいない場合はランダムで選択した broker に接続を確立するよう命令する (rd_kafka_connect_any)
- operation queue に命令を加える
broker の state が変わるまで待機
1 〜 3 を繰り返す

rd_kafka_new 実行直後は、librdkafka が認識している broker は metadata.broker.list に指定したものだけであり、それらの state は INIT なので rd_kafka_connect_any が呼ばれます。ただし、この関数は短時間で何度も呼び出されると無視するようになっています。短時間というのはデフォルトで 50 ms です¹。
正常系では broker の state は次のように遷移するので、もし INIT から他の state に遷移する際に 50 ms 以上かつタイムアウト未満かかれば、再度 rd_kafka_connect_any が呼ばれた時に他の broker が選択されますが、この確率は極めて低そうです。

INIT
TRY_CONNECT
CONNECT
APIVERSION_QUERY
UP

よって、たまたま選択された broker が高負荷などの理由で、ある state（多くの場合は CONNECT）からなかなか変わらなかったらタイムアウトになるまで待ち続けることになります。

main thread では 1 秒間隔で rd_kafka_connect_any を実行しているので、1 秒経てば別の broker と接続を確立しようとします。よって、タイムアウトが 1 秒より大きいと metadata.broker.list に指定されている別の broker が選択されて、タイムアウトに引っかからない可能性があります。

ログを読み解く

再現コードを実行すると次のようなログが出力されますが、前述の挙動を頭に入れながらログを読み解いてみます。

/Users/arabiki/path/to/script.rb:6: warning: already initialized constant Rdkafka::Config::REQUIRED_CONFIG
/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/config.rb:103: warning: previous definition of REQUIRED_CONFIG was here
%7|1635820149.745|BROKER|rdkafka#producer-1| [thrd:app]: localhost:9092/bootstrap: Added new broker with NodeId -1
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd::0/internal]: :0/internal: Enter main broker thread
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Enter main broker thread
%7|1635820149.745|BROKER|rdkafka#producer-1| [thrd:app]: example.com:9092/bootstrap: Added new broker with NodeId -1
%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:app]: example.com:9092/bootstrap: Selected for cluster connection: bootstrap servers added (broker has 0 connection attempt(s))
%7|1635820149.745|INIT|rdkafka#producer-1| [thrd:app]: librdkafka v1.5.0 (0x10500ff) rdkafka#producer-1 initialized (builtin.features gzip,snappy,ssl,sasl,regex,lz4,sasl_gssapi,sasl_plain,sasl_scram,plugins,zstd,sasl_oauthbearer, GCC GXX PKGCONFIG OSXLD LIBDL PLUGINS ZLIB SSL SASL_CYRUS ZSTD HDRHISTOGRAM LZ4_EXT SYSLOG SNAPPY SOCKEM SASL_SCRAM SASL_OAUTHBEARER CRC32C_HW, debug 0xa)
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Enter main broker thread
%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Received CONNECT op
%7|1635820149.745|STATE|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Broker changed state INIT -> TRY_CONNECT
%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: broker in state TRY_CONNECT connecting
%7|1635820149.745|STATE|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Broker changed state TRY_CONNECT -> CONNECT
I, [2021-11-02T11:29:09.745968 #77599]  INFO -- : Produce message
%7|1635820149.746|CONNECT|rdkafka#producer-1| [thrd:app]: Not selecting any broker for cluster connection: still suppressed for 49ms: leader query
%7|1635820149.746|METADATA|rdkafka#producer-1| [thrd:app]: Skipping metadata refresh of 1 topic(s): no usable brokers
%7|1635820149.746|CONNECT|rdkafka#producer-1| [thrd:app]: Not selecting any broker for cluster connection: still suppressed for 49ms: application metadata request
%7|1635820149.762|CONNECT|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Connecting to ipv4#93.184.216.34:9092 (plaintext) with socket 17
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:app]: localhost:9092/bootstrap: Selected for cluster connection: application metadata request (broker has 0 connection attempt(s))
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Received CONNECT op
%7|1635820150.000|STATE|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Broker changed state INIT -> TRY_CONNECT
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: broker in state TRY_CONNECT connecting
%7|1635820150.000|STATE|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Broker changed state TRY_CONNECT -> CONNECT
E, [2021-11-02T11:29:10.001143 #77599] ERROR -- : Local: Broker transport failure (transport) (Rdkafka::RdkafkaError)
-- snip --
/Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/metadata.rb:20:in `initialize': Local: Broker transport failure (transport) (Rdkafka::RdkafkaError)
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:68:in `new'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:68:in `partition_count'
        from /Users/arabiki/.anyenv/envs/rbenv/versions/3.0.2/lib/ruby/gems/3.0.0/gems/rdkafka-0.10.0/lib/rdkafka/producer.rb:106:in `produce'
        from /Users/arabiki/path/to/script.rb:19:in `<main>'

次のログから、metadata.broker.list に指定された broker が追加され、broker のメイン関数が実行されたことがわかります。

%7|1635820149.745|BROKER|rdkafka#producer-1| [thrd:app]: localhost:9092/bootstrap: Added new broker with NodeId -1
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd::0/internal]: :0/internal: Enter main broker thread
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Enter main broker thread
%7|1635820149.745|BROKER|rdkafka#producer-1| [thrd:app]: example.com:9092/bootstrap: Added new broker with NodeId -1
%7|1635820149.745|BRKMAIN|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Enter main broker thread

次のログから、rd_kafka_connect_any で example.com:9092/bootstrap が選択され、example.com:9092/bootstrap の thread が CONNECT という命令を受け取り、接続を “確立” していることがわかります。

%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:app]: example.com:9092/bootstrap: Selected for cluster connection: bootstrap servers added (broker has 0 connection attempt(s))
%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Received CONNECT op
%7|1635820149.745|STATE|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Broker changed state INIT -> TRY_CONNECT
%7|1635820149.745|CONNECT|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: broker in state TRY_CONNECT connecting
%7|1635820149.745|STATE|rdkafka#producer-1| [thrd:example.com:9092/bootstrap]: example.com:9092/bootstrap: Broker changed state TRY_CONNECT -> CONNECT

次のログから、produce をした時に rd_kafka_connect_any が呼ばれるも、最初に rd_kafka_connect_any が呼ばれてから 1 ms 程度しか経っていないので無視されていることがわかります。そして、タイムアウトである約 250 ms が経ってから再度 rd_kafka_connect_any が呼ばれ、localhost:9092/bootstrap が選択されたことがわかります。ただ、タイムアウトが過ぎているので、”Local: Broker transport failure (transport)” になります。

I, [2021-11-02T11:29:09.745968 #77599]  INFO -- : Produce message
%7|1635820149.746|CONNECT|rdkafka#producer-1| [thrd:app]: Not selecting any broker for cluster connection: still suppressed for 49ms: application metadata request
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:app]: localhost:9092/bootstrap: Selected for cluster connection: application metadata request (broker has 0 connection attempt(s))
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Received CONNECT op
%7|1635820150.000|STATE|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Broker changed state INIT -> TRY_CONNECT
%7|1635820150.000|CONNECT|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: broker in state TRY_CONNECT connecting
%7|1635820150.000|STATE|rdkafka#producer-1| [thrd:localhost:9092/bootstrap]: localhost:9092/bootstrap: Broker changed state TRY_CONNECT -> CONNECT
E, [2021-11-02T11:29:10.001143 #77599] ERROR -- : Local: Broker transport failure (transport) (Rdkafka::RdkafkaError)

まとめ

以上のことから、冒頭で述べたように、設定値の調整ではエラーを回避することができず、次のいずれかの選択肢を取らなければならないことがわかったと思います。

produce に指定する key と partition_key が同じであれば partition_key の指定をやめる
単純にリトライする
rd_kafka_metadata のタイムアウトが 1 秒以上になるようにモンキーパッチを当てる
producer を生成してから 1 秒以内に produce を実行するのを避ける

おまけ〜CLion を使った librdkafka のデバッグ〜

IntelliJ IDEA や Visual Studio Code 等でも可能でしょうが、自分は CLion を使って librdkafka の挙動を理解しました。
librdkafka では非公式ではあるものの、CMake をサポートしています。よって、CLion に簡単にインポートすることができます。
インポートすると examples 以下のサンプルコードが CMake アプリケーションとして登録されるので、rdkafka_example に適当な引数を渡すだけでブレークポイントを設定しつつ様々な処理を行えます。
例えば今回のようにメタデータ取得の処理を理解したい場合は Program arguments に次の内容を指定します。

-L -b localhost:9092,example.com:9092 -d broker,metadata

reconnect.backoff.ms を 22 以下にすれば最小 11 ms にできます ↩

fluentd forwarder を daemon service として登録することで fluentd logging driver 起因の fluentd の負荷を分散させる

Mon, 22 Mar 2021 00:00:00 +0900

Docker の logging driver として fluentd logging driver を使うと、DNS や NLB で複数の fluentd プロセスに負荷を分散させようとしても特定のプロセスに負荷が集中することがあります。それを回避するのに FireLens が使えるという話を次の記事に書きました。

FireLens を使って fluentd logging driver 起因の fluentd の負荷を分散させる

ところが、既に fluentd が動いていると、FireLens を使うおうと思うと、既存の fluentd のポート番号の変更か、設定の統合を余儀なくされます。これを避けるために、daemon service (daemon scheduling strategy の service) の fluentd を設置することで同様のことを実現しようという話です。
なお、Fargate は非対応なので、Fargate でログを柔軟に処理しようと思うと FireLens 一択です。

リポジトリ

今回検証に使ったコードは次のリポジトリにまとめてあります。

https://github.com/abicky/fluentd-daemon-service-example

実験

logging driver の設定として NLB のエンドポイントを指定するタスクと、daemon service の fluentd の unix domain socket を指定するタスクを用意し、それぞれのタスクでログを流した時に fluentd aggregator に流れるログがどの程度偏るかを見てみます。

前者の logging driver の設定は次のとおりです。

"logConfiguration": {
  "logDriver": "fluentd",
  "options": {
    "tag": "docker.application-using-aggregator",
    "fluentd-address": "${aws_lb.fluentd_aggregator.dns_name}:24224",
    "fluentd-sub-second-precision": "true"
  }
}

cf. application.tf#L17-L24

後者の設定は次のとおりです。

"logConfiguration": {
  "logDriver": "fluentd",
  "options": {
    "tag": "docker.application-using-forwarder",
    "fluentd-address": "unix:///var/run/fluentd/unix.sock",
    "fluentd-sub-second-precision": "true"
  }
}

cf. application.tf#L39-L46

ログは次のように 1 ms 間隔で 180,000 回流し、10 タスク起動することにします。

require 'logger'

$stdout.sync = true
logger = Logger.new($stdout)

msg = "0123456789" * 10

logger.info "Started"
180_000.times do |i|
  logger.info "#{i}: #{msg}"
  sleep 0.001
end
logger.info "Finished"

cf. main.rb

実験結果

log driver に NLB のエンドポイントを直接指定した場合

次のコマンドでログを流しました。

./run.sh aggregator

fluentd aggregator の flowcount のログは次のとおりです。

fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:22:29.399876193 +0000 flowcount: {"count":83738,"count_rate":1384.09,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:22:29.689232469 +0000 flowcount: {"count":168222,"count_rate":2780.54,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:22:30.681630124 +0000 flowcount: {"count":128522,"count_rate":2124.34,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:22:31.994476770 +0000 flowcount: {"count":44181,"count_rate":730.26,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:23:29.899642102 +0000 flowcount: {"count":110185,"count_rate":1821.25,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:23:30.188844442 +0000 flowcount: {"count":220289,"count_rate":3641.18,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:23:31.181282460 +0000 flowcount: {"count":165269,"count_rate":2731.75,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:23:32.493979323 +0000 flowcount: {"count":55082,"count_rate":910.45,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:24:30.400072680 +0000 flowcount: {"count":110176,"count_rate":1821.08,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:24:30.688910751 +0000 flowcount: {"count":220303,"count_rate":3641.39,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:24:31.681876567 +0000 flowcount: {"count":165261,"count_rate":2731.57,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:24:32.993879277 +0000 flowcount: {"count":55062,"count_rate":910.12,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:25:30.899980807 +0000 flowcount: {"count":55905,"count_rate":924.05,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:25:31.188816896 +0000 flowcount: {"count":111194,"count_rate":1837.93,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:25:32.182087198 +0000 flowcount: {"count":80954,"count_rate":1338.08,"tag":"docker.application-using-aggregator"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:25:33.494263738 +0000 flowcount: {"count":25677,"count_rate":424.41,"tag":"docker.application-using-aggregator"}

タスクごとにログの数をまとめると次のようになります。

Task ID	Count
117809ec4164485db0c6c9859ed32e1b	360,004
46fbf162762b4555846904ad81dcfbc0	540,006
7db063d050df49f78d0aaf385b6586c7	720,008
ca804b3ee5764cf5a35e522a7c993134	180,002

ログの数にかなりの偏りが出ていることがわかります。

また、fluentd aggregator のコンテナの CPU 使用率を見ても、最も負荷の低いものと高いものでは 3 倍程度の差があります。

log driver に fluentd forwarder を指定した場合

次のコマンドでログを流しました。

./run.sh forwarder

fluentd aggregator の flowcount のログは次のとおりです。

fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:11:25.400127668 +0000 flowcount: {"count":12645,"count_rate":209.0,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:11:27.993792733 +0000 flowcount: {"count":9080,"count_rate":150.08,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:12:25.899463285 +0000 flowcount: {"count":117589,"count_rate":1943.65,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:12:26.188982726 +0000 flowcount: {"count":207846,"count_rate":3435.46,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:12:27.181862278 +0000 flowcount: {"count":117742,"count_rate":1946.16,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:12:28.493703609 +0000 flowcount: {"count":108880,"count_rate":1799.68,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:13:25.899981475 +0000 flowcount: {"count":126532,"count_rate":2108.86,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:13:26.688544172 +0000 flowcount: {"count":153804,"count_rate":2542.24,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:13:27.682246139 +0000 flowcount: {"count":153755,"count_rate":2541.4,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:13:28.994500244 +0000 flowcount: {"count":99695,"count_rate":1647.84,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:14:26.399402862 +0000 flowcount: {"count":153904,"count_rate":2543.9,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:14:26.688952640 +0000 flowcount: {"count":117573,"count_rate":1959.54,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:14:28.181709911 +0000 flowcount: {"count":145080,"count_rate":2398.05,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:14:29.493614957 +0000 flowcount: {"count":126420,"count_rate":2089.63,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/117809ec4164485db0c6c9859ed32e1b 2021-03-22 01:15:26.399921994 +0000 flowcount: {"count":59273,"count_rate":987.88,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/7db063d050df49f78d0aaf385b6586c7 2021-03-22 01:15:27.188492122 +0000 flowcount: {"count":27135,"count_rate":448.51,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/46fbf162762b4555846904ad81dcfbc0 2021-03-22 01:15:28.681455491 +0000 flowcount: {"count":27152,"count_rate":448.79,"tag":"docker.application-using-forwarder"}
fluentd/fluentd/ca804b3ee5764cf5a35e522a7c993134 2021-03-22 01:15:29.494035912 +0000 flowcount: {"count":35915,"count_rate":598.58,"tag":"docker.application-using-forwarder"}

タスクごとにログの数をまとめると次のようになります。

Task ID	Count
117809ec4164485db0c6c9859ed32e1b	469,943
46fbf162762b4555846904ad81dcfbc0	443,729
7db063d050df49f78d0aaf385b6586c7	506,358
ca804b3ee5764cf5a35e522a7c993134	379,990

先ほどと比べると偏りがかなり解消されていることがわかります。

一方で、fluentd forwarder の CPU 使用率は 70% 程度になっており、4 コアのうちほぼ 1 コアを使うぐらいの負荷がかかっています。この点に関しては fluent bit にすることで解消するかもしれません。

注意点

ログの偏りが解消することはわかりきっていたことなので、ハマりどころや運用する際に考慮した方が良さそうな点について触れます。

Unix domain socket を作成するディレクトリの権限

Docker の bind mount を利用する場合、mount したディレクトリは host の権限と同じになります。一方、fluentd の公式 Docker イメージではデフォルトで fluent ユーザで実行されるようになっています。よって、fluent ユーザのまま実行すると、mount したディレクトリによっては socket を作成することができません。

この問題を回避する典型的な方法としては次の 4 つが挙げられると思います。

/tmp 等 sticky bit の設定されたディレクトリを mount する
mount するディレクトリの ownership を予め fluent ユーザの UID のものにしておく
- 逆に mount するディレクトリの UID で実行するというアプローチもある
fluentd を root ユーザで動かす
fluentd を起動する直前の処理を root で動かして ownership を fluent ユーザに変更した上で fluent ユーザで fluentd を実行する

/tmp を使うのが一番無難な気がするし、今回の用途であれば /tmp を使うので問題ないはずですが、何となく抵抗があったので、4 を採用しました。つまり、task definition の user で root を指定し、次のように entrypoint.sh で ownership を変えた上で、fluent ユーザで fluentd を実行するようにしています。

if [ $(id -u) -eq 0 ]; then
    # We assume that /var/run/fluentd on the host is mounted into /fluentd/var/run
    # and the ECS agent creates the directory with root:root ownership,
    # so the ownership must be changed to create a unix domain socket.
    chown -R fluent /fluentd/var/run
    set -- su-exec fluent "$@"
fi

cf. entrypoint.sh#L29-L35

なお、回避方法としては次の issue の議論が参考になるかもしれません。

Add ability to mount volume as user other than root · Issue #2259 · moby/moby

Datadog による fluentd forwarder の監視

ログとはいえ、fluentd の queue が溜まりがちになっていたら worker を 2 つにするなどの対策を講じなければならないので監視は重要です。

Datadog には fluentd の integration が用意されているので、 auto discovery と組み合わせることで、monitor agent から取得できるメトリクスを簡単に送ることができます。
異常を察知するには次のメトリクスが使えるんじゃないかと思います。

fluentd.buffer_available_buffer_space_ratios
- total_limit_size に対する fluentd.buffer_total_queued_size の割合 cf. buffer.rb#L768-L777
fluentd.retry_count

まず、メトリクスを収集できるようにするには fluentd の設定に次の内容を追加します。

# cf. https://docs.datadoghq.com/integrations/fluentd/
<source>
  @id monitor-agent
  @type monitor_agent
  bind 0.0.0.0
  port 24220
</source>

cf. fluent.conf.erb#L7-L13

auto discovery を有効にするには、メトリクスを収集したい container の task definition で次のように label を指定すれば良いです。

"dockerLabels": {
  "com.datadoghq.ad.check_names": "[\"fluentd\"]",
  "com.datadoghq.ad.init_configs": "[{}]",
  "com.datadoghq.ad.instances": "[{\"monitor_agent_url\": \"http://%%host%%:24220/api/plugins.json\"}]"
}

cf. fluentd_forwarder.tf#L30-L34

これだけで datadog agent がよしなにメトリクスを収集してくれるんだから便利ですよね。auto discovery の設定方法についてはドキュメントを参照してください。
なお、datadog agent を awsvpc newtork mode で動かすと対象コンテナの 24220 番ポートにアクセスできなくてエラーになるようです。収集対象のタスクが awsvpc network mode で動いていても収集できないかもしれません。

fluentd forwarder のデプロイによるログの欠損

ログを流している途中で fluentd forwarder を force new deployment するとどの程度ログが欠損し、アプリケーションにもどのような影響があるか見てみます。

実験の時と同様 ./run.sh forwarder を実行し、1 分程経過したタイミングで forwarder service を force new deployment しました。

Task ID	Count
117809ec4164485db0c6c9859ed32e1b	421,013
46fbf162762b4555846904ad81dcfbc0	473,347
7db063d050df49f78d0aaf385b6586c7	518,518
ca804b3ee5764cf5a35e522a7c993134	385,437

合計 1,800,020 にならないといけないところが 1,798,315 になっているので、0.1% 程度ログが欠損していることになりますね。
たいていの場合、デプロイによってコンテナのログが 0.1% 程度欠損するのは許容できる気がしますが、もし許容できないのであれば、Docker 20.10.0 から fluentd-request-ack log option を指定できるようになっているので、ECS の Docker のバージョンが上がったら試してみると良いかもしれません。

cf. https://github.com/moby/moby/commit/008fc679742b1f6dc386b728887573987ac09feb

アプリケーションの影響については、Started のログが出てから Finished のログが出るまでの時間を見てみます。

まずこちらが force new deployment しなかった時のログです。3 分 20 秒程度ですね。

5032ea5b8c1b I, [2021-03-22T01:11:22.935291 #1]  INFO -- : Started
c3ecdd255020 I, [2021-03-22T01:11:23.254936 #1]  INFO -- : Started
43df4c4e1099 I, [2021-03-22T01:11:23.259080 #1]  INFO -- : Started
0a70717c1e6d I, [2021-03-22T01:11:23.268763 #1]  INFO -- : Started
c23d480bab7f I, [2021-03-22T01:11:23.366176 #1]  INFO -- : Started
cea2937c67d2 I, [2021-03-22T01:11:23.501495 #1]  INFO -- : Started
949ea1421645 I, [2021-03-22T01:11:23.509615 #1]  INFO -- : Started
5dbab423c5c7 I, [2021-03-22T01:11:23.564029 #1]  INFO -- : Started
e5aa23c34243 I, [2021-03-22T01:11:23.654518 #1]  INFO -- : Started
0da5702567e0 I, [2021-03-22T01:11:23.653471 #1]  INFO -- : Started
5032ea5b8c1b I, [2021-03-22T01:14:42.196975 #1]  INFO -- : Finished
c3ecdd255020 I, [2021-03-22T01:14:42.329838 #1]  INFO -- : Finished
0a70717c1e6d I, [2021-03-22T01:14:42.374640 #1]  INFO -- : Finished
43df4c4e1099 I, [2021-03-22T01:14:42.415482 #1]  INFO -- : Finished
c23d480bab7f I, [2021-03-22T01:14:42.519610 #1]  INFO -- : Finished
5dbab423c5c7 I, [2021-03-22T01:14:42.573078 #1]  INFO -- : Finished
949ea1421645 I, [2021-03-22T01:14:42.605540 #1]  INFO -- : Finished
cea2937c67d2 I, [2021-03-22T01:14:42.613742 #1]  INFO -- : Finished
0da5702567e0 I, [2021-03-22T01:14:42.618751 #1]  INFO -- : Finished
e5aa23c34243 I, [2021-03-22T01:14:42.670983 #1]  INFO -- : Finished

続いてこちらが force new deployment した時のログです。3 分 20 秒程度ですね。数秒程度遅くなっている気もしますが、あれだけ大量にログを吐いてこの程度の影響であれば、よほど頻繁にデプロイしない限り問題ないでしょう。

c0dcc062dd56 I, [2021-03-22T01:51:58.866743 #1]  INFO -- : Started
dcf70765a896 I, [2021-03-22T01:51:58.961938 #1]  INFO -- : Started
83cefa1beb95 I, [2021-03-22T01:51:59.027976 #1]  INFO -- : Started
8d21969cdd1c I, [2021-03-22T01:51:59.065431 #1]  INFO -- : Started
9ae9428183f8 I, [2021-03-22T01:51:59.429690 #1]  INFO -- : Started
634067e72fd5 I, [2021-03-22T01:51:59.440353 #1]  INFO -- : Started
70a19a8a2d21 I, [2021-03-22T01:51:59.482598 #1]  INFO -- : Started
c32ab2f625be I, [2021-03-22T01:51:59.495628 #1]  INFO -- : Started
3aef45741e12 I, [2021-03-22T01:51:59.498435 #1]  INFO -- : Started
545ce5061c10 I, [2021-03-22T01:51:59.567398 #1]  INFO -- : Started
c0dcc062dd56 I, [2021-03-22T01:55:22.440351 #1]  INFO -- : Finished
83cefa1beb95 I, [2021-03-22T01:55:22.497421 #1]  INFO -- : Finished
8d21969cdd1c I, [2021-03-22T01:55:22.557508 #1]  INFO -- : Finished
dcf70765a896 I, [2021-03-22T01:55:22.584022 #1]  INFO -- : Finished
70a19a8a2d21 I, [2021-03-22T01:55:22.788653 #1]  INFO -- : Finished
634067e72fd5 I, [2021-03-22T01:55:22.808537 #1]  INFO -- : Finished
3aef45741e12 I, [2021-03-22T01:55:22.868724 #1]  INFO -- : Finished
9ae9428183f8 I, [2021-03-22T01:55:22.881587 #1]  INFO -- : Finished
c32ab2f625be I, [2021-03-22T01:55:22.897849 #1]  INFO -- : Finished
545ce5061c10 I, [2021-03-22T01:55:22.976546 #1]  INFO -- : Finished

コンテナインスタンスの Draining 時の挙動

FireLens を使って fluentd logging driver 起因の fluentd の負荷を分散させるでも言及したように、以前はコンテナインスタンスを draining すると daemon service のタスクは即座に終了するようになっていました。

ECS agent に手が入った気配がないので AWS 内部のどこかで手が入ったんじゃないかと予想しますが、とりあえず ECS agent 1.50.3 では次のような挙動を示すようです。

service に属さないタスクが running であっても終了する
service に属するタスクが 1 つでもインスタンス上で動いていれば待ち続ける

つまり、spot instance の interruption warning で draining にした場合、2 分以内に終了しないタスクがあると正常終了しない可能性があります。
今回のような用途では 1 秒間隔でログを転送しているので大した影響はないでしょうが、重要なデータを扱う場合は注意が必要です。

以上、これで安心して負荷を分散させられますね！

ECS の煩わしいオペレーションをよしなにやってくれるツールを作った

Thu, 28 Jan 2021 00:00:00 +0900

ECS のオペレーションは色々と面倒なものが多いです。例えば、ECS クラスタを EC2 インスタンスで管理している場合、インスタンスの AMI を更新しようと思うと、新しいインスタンスを起動して、古いインスタンスをドレイニングして、古いインスタンスを落とすというオペレーションが発生します。また、ECS サービスの設定のうち、新規作成時にしか設定できない項目を変更しようと思うと、別名のサービスを新しく作成する必要があります。ちょっと設定を変えたいだけなのに名前を変えないといけないのは辛いですよね。

というわけで、そんな作業をよしなにやってくれるツールを作成しました。
https://github.com/abicky/ecsmec

Go 言語の勉強を兼ねて Go 言語で書いています。去年の春ぐらいに開発していて、1 年ぐらい間が空いてから仕上げたので、一貫性のないコードになっている箇所がちらほらあるかもです…

何をするコマンドか？

割と頑張って README を書いたので、詳細は README を読んでもらうと良いですが、現在次のようなオペレーションをサポートしています。

auto scaling group で管理している ECS クラスタのインスタンス入れ替え (replace-auto-scaling-group-instances)
spot fleet request で管理している ECS クラスタのキャンセル済みリクエストに属するインスタンスの停止 (terminate-spot-fleet-request-instances)
auto scaling group または spot fleet request で管理している ECS クラスタの縮小 (reduce-cluster-capacity)
ECS サービスの再作成 (recreate-service)

ECS サービスの再作成に関して、割とよくありそうなユースケースとして placement strategies や placement constraints の更新があります。
一応 UpdateService API では placement strategies や placement constraints も更新できるんですが、更新できるようになって 1 年近く経っても preview のままです。
cf. Amazon ECS supports in Preview updating Placement Strategy and Constraints for existing ECS Services

以上、ECS のオペレーションにかかる労力が少しでも緩和すれば幸いです。

FireLens を使って fluentd logging driver 起因の fluentd の負荷を分散させる

Mon, 07 Dec 2020 00:00:00 +0900

Fluentd aggregator を構成する際に、Route 53 や NLB を使うことで、forwarder では 1 つのエンドポイントを指定しつつ簡単に fluend の台数を増減させることができます。ところが、Docker で fluentd logging driver を使う際にそのエンドポイントを指定すると、一度コネクションが確立されるとずっとそのコネクションが使い回されるため、大量のログを吐くコンテナと接続された fluentd ホストだけが高負荷な状態が続くことになります。
この問題を解消するために FireLens を使ってみたという話です。

Fluentd logging driver の実装

Fluentd logging driver の実装は daemon/logger/fluentd/fluentd.go ですが、コネクションにメッセージを書き込むところでエラーにならない限りずっとコネクションが使い回されるようになっていることがわかります。
cf. fluent/fluent-logger-golang/fluent/fluent.go#L357-L408

つまり、fluent-logger-golang と docker に手を入れない限り特定の fluentd ホストの負荷が偏る問題は解消できないということです。

FireLens とは何か？

公式ドキュメントは Custom log routing で、logging driver として awsfirelens を指定することで sidecar container の fluentd または fluent bit にログを送ることができ、fluentd, fluent bit から各種サービスにログを送ることができる機能です。

試しに https://docs.aws.amazon.com/AmazonECS/latest/userguide/using_firelens.html#firelens-example-forward を参考に次のような設定のタスクを起動してみます。

{
  "family": "firelens-example-forward",
  "containerDefinitions": [
    {
      "essential": true,
      "image": "906394416424.dkr.ecr.ap-northeast-1.amazonaws.com/aws-for-fluent-bit:latest",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
      },
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "firelens-container",
          "awslogs-region": "ap-northeast-1",
          "awslogs-create-group": "true",
          "awslogs-stream-prefix": "firelens"
        }
      },
      "memoryReservation": 50
     },
     {
       "essential": true,
       "image": "httpd",
       "name": "app",
       "logConfiguration": {
         "logDriver":"awsfirelens",
         "options": {
          "Name": "forward",
          "Host": "172.31.22.30",
          "Port": "24224"
        }
      },
      "memoryReservation": 100
    }
  ]
}

172.31.22.30 は Fluentd が動いているホストの IP ですが、fluentd aggregator のエンドポイントとして NLB を使う場合は NLB のエンドポイントになります。

これで Web サーバにリクエストを送ると、5 秒ごとに新しいコネクションが作成されていることがわかります。

[ec2-user@ip-172-31-22-30 ~]$ while : ; do sudo nsenter -t $(docker inspect $(docker ps | awk '$2 == "httpd" { print $1 }') --format '{{.State.Pid}}') -n curl localhost; ss -tn | grep 24224; sleep 1; done
<html><body><h1>It works!</h1></body></html>
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49210
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49210
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49210
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49210
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49244
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49244
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49244
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49244
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49244
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49282
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49282
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49282
<html><body><h1>It works!</h1></body></html>
ESTAB   0         0              172.31.22.30:24224          172.17.0.3:49282

logging driver として awsfirelens を指定すると、内部的には logging driver として fluentd logging driver が使われていることがわかります。tag は <container-name>-firelens-<task-id> になります。
cf. agent/engine/docker_task_engine.go#L92-L93

[ec2-user@ip-172-31-22-30 ~]$ docker inspect $(docker ps | awk '$2 == "httpd" { print $1 }') | jq '.[0].HostConfig.LogConfig'
{
  "Type": "fluentd",
  "Config": {
    "fluentd-address": "unix:///var/lib/ecs/data/firelens/23e29749caef4e68903a88e9a60846d8/socket/fluent.sock",
    "fluentd-async-connect": "true",
    "fluentd-sub-second-precision": "true",
    "tag": "app-firelens-23e29749caef4e68903a88e9a60846d8"
  }
}

fluent bit の設定は次のようになっています。

[ec2-user@ip-172-31-22-30 ~]$ docker exec $(docker ps | awk '/fluent-bit/ { print $1 }') ps auxf
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root        36  0.0  0.7  51852  3368 ?        Rs   23:49   0:00 ps auxf
root         1  0.0  5.3 634200 25144 ?        Ssl  22:39   0:00 /fluent-bit/bin/fluent-bit -e /fluent-bit/firehose.so -e /fluent-bit/cloudwatch.so -e /fluent-bit/kinesis.so -c /fluent-bit/etc/fluent-bit.conf
[ec2-user@ip-172-31-22-30 ~]$ docker exec $(docker ps | awk '/fluent-bit/ { print $1 }') cat /fluent-bit/etc/fluent-bit.conf

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock

[INPUT]
    Name forward
    Listen 0.0.0.0
    Port 24224

[INPUT]
    Name tcp
    Tag firelens-healthcheck
    Listen 127.0.0.1
    Port 8877

[FILTER]
    Name record_modifier
    Match *
    Record ec2_instance_id i-0d7b73bc6c6b97f7c
    Record ecs_cluster test
    Record ecs_task_arn arn:aws:ecs:ap-northeast-1:695137853892:task/test/23e29749caef4e68903a88e9a60846d8
    Record ecs_task_definition firelens-example-forward:6

[OUTPUT]
    Name null
    Match firelens-healthcheck

[OUTPUT]
    Name forward
    Match app-firelens*
    Host 172.31.22.30
    Port 24224

docker image に同梱されている設定ファイルはこれですが、host に配置されているもので上書きされていることがわかります。また、他のコンテナの logging driver からアクセスできるように、unix domain socket は bind mounts されたディレクトリ上に存在していることもわかります。

[ec2-user@ip-172-31-22-30 ~]$ docker inspect $(docker ps | awk '/aws-for-fluent-bit/ { print $1 }') | jq '.[0].HostConfig.Binds'
[
  "/var/lib/ecs/data/firelens/23e29749caef4e68903a88e9a60846d8/config/fluent.conf:/fluent-bit/etc/fluent-bit.conf",
  "/var/lib/ecs/data/firelens/23e29749caef4e68903a88e9a60846d8/socket/:/var/run/"
]

なお、今年の 9 月頃に nanoseconds をサポートしているので、少し古い ecs agent だとログの時刻は秒単位になってしまいます。
cf. [FireLens] [request]: Send nanoseconds of a log records to a log router · Issue #839 · aws/containers-roadmap

Custom configuration file で設定を変更する

https://docs.aws.amazon.com/AmazonECS/latest/developerguide/firelens-taskdef.html#firelens-taskdef-customconfig に書いてあるように、S3 などに追加の設定ファイルを配置することで設定を変更することができます。このオプションを利用すると、次のように /fluent-bit/etc/fluent-bit.conf に @INCLUDE /fluent-bit/etc/external.conf の 1 行が追加され、指定したファイルの内容が読み込まれるようになっています。

[ec2-user@ip-172-31-22-30 ~]$ docker exec $(docker ps | awk '/fluent-bit/ { print $1 }') cat /fluent-bit/etc/fluent-bit.conf

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock

[INPUT]
    Name forward
    Listen 0.0.0.0
    Port 24224

[INPUT]
    Name tcp
    Tag firelens-healthcheck
    Listen 127.0.0.1
    Port 8877

[FILTER]
    Name record_modifier
    Match *
    Record ec2_instance_id i-0d7b73bc6c6b97f7c
    Record ecs_cluster test
    Record ecs_task_arn arn:aws:ecs:ap-northeast-1:695137853892:task/test/16cdc14c1e9c48bca7c2e28fe8c3fd51
    Record ecs_task_definition firelens-example-forward:14

@INCLUDE /fluent-bit/etc/external.conf

[OUTPUT]
    Name null
    Match firelens-healthcheck

[OUTPUT]
    Name forward
    Match app-firelens*
    Host 172.31.22.30
    Port 24224

これを利用すれば、例えば次の設定ファイルを指定することで <container-name>-firelens-<task-id> というタグを docker.<container-name> に変換することもできます。

[OUTPUT]
    Name null
    Match firelens-healthcheck

[FILTER]
    Name  rewrite_tag
    Match *-firelens*
    # cf. https://github.com/aws/amazon-ecs-agent/blob/v1.48.1/agent/engine/docker_task_engine.go#L1071
    Rule  $container_name ^/ecs-${TASK_FAMILY}-\d+-(.+)- docker.$1 false

[OUTPUT]
    Name forward
    Match *
    Host ${FLUENTD_HOST}
    Port ${FLUENTD_PORT}

タスク定義は次のように変わります。

{
  "family": "firelens-example-forward",
  "executionRoleArn": "arn:aws:iam::695137853892:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "essential": true,
      "image": "906394416424.dkr.ecr.ap-northeast-1.amazonaws.com/aws-for-fluent-bit:latest",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": {
          "config-file-type": "s3",
          "config-file-value": "arn:aws:s3:::test.abicky.net/fluent-bit.conf"
        }
      },
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "firelens-container",
          "awslogs-region": "ap-northeast-1",
          "awslogs-create-group": "true",
          "awslogs-stream-prefix": "firelens"
        }
      },
      "memoryReservation": 50,
      "environment": [
        {
          "name": "FLUENTD_HOST",
          "value": "172.31.22.30"
        },
        {
          "name": "FLUENTD_PORT",
          "value": "24224"
        },
        {
          "name": "TASK_FAMILY",
          "value": "firelens-example-forward"
        }
      ]
     },
     {
       "essential": true,
       "image": "httpd",
       "name": "app",
       "logConfiguration": {
         "logDriver":"awsfirelens"
      },
      "memoryReservation": 100
    }
  ]
}

fluent bit の設定には SERVICE を何個も書けるようなので、flush 間隔を短くしたい場合は次の内容をカスタム設定ファイルに書けば良いです。

[SERVICE]
    Flush 1

FireLens を使うと何が嬉しいのか？

単なる sidecar container であれば自前でも簡単に実現できそうです。ところが、実際にやってみようとすると、他のコンテナの logging driver からアクセスできるようにするにはホストから直接アクセスできるようにしなければならないことに気付きます。unix domain socket を使うにしても TCP を使うにしても、1 インスタンスに複数のタスクが配置される可能性を考慮すると、これは非常に面倒な問題です。FireLens を使う最大のメリットはそこの面倒をよしなに見てくれることでしょう。

FireLens を使わない選択肢としては DAEMON service として fluentd なり fluent bit なりを動かすことが考えられます。
cf. Centralized Container Logging with Fluent Bit

DAEMON service はインスタンスを draining にすると他のタスクより先に終了する可能性があったんですが、最近修正されたようです。
cf. https://github.com/aws/containers-roadmap/issues/128#issuecomment-736026241

draining にした後のログが見れないと困りますもんね。ただ、What’s New with Containers? にはそれらしい情報がないし、ecs agent にもそれらしい変更はないので詳細は不明ですが…

追記

Improving daemon services in Amazon ECS | Containers によれば、2020 年 11 月に修正されたようです

In November of 2020, we added an update to the ECS scheduler to drain daemon tasks last on a host. This ensures that when an instance is set to drain, ECS will terminate all other tasks before terminating the daemon task.

FireLens の微妙な点

FireLens を使うと嬉しいことについて言及しましたが、次の点は微妙だと思っています。

ログを収集するだけなら unix domain socket しか使わないのに 24224 番ポートを listen する
- cf. agent/taskresource/firelens/firelensconfig_unix.go#L88-L89
- 例えば awsvpc network mode で既に fluentd コンテナを起動している場合は FireLens を使うためだけにポート番号を変更しないといけない
環境変数として FLUENT_HOST, FLUENT_PORT という一般的な名前が使われている
- cf. agent/engine/docker_task_engine.go#L95-L97
- 例えば既にこれらの環境変数を使っていればコードを修正しないといけないし、環境変数がセットされることを知らなければ事故につながるかもしれない
  - 何故 FIRELENS_FLUENT_HOST, FIRELENS_FLUENT_PORT じゃない…
タグのフォーマットが <container-name>-firelens-<task-id> のようにハイフン区切りである
- ドット区切りだと fluentd, fluent bit の設定ファイルで扱いやすいのに…

FireLens の一番の魅力は log driver に指定することができ、よしなに unix domain socket を使ってくれることであり、24224 番ポートに fluentd, fluent bit を立てるのであればわざわざ FireLens を使う必要がないわけで、このようなオプトアウト不可能な機能が提供されているのは疑問です。

ActiveRecord::LockWaitTimeout, ActiveRecord::Deadlocked, ActiveRecord::ConnectionTimeoutError が起きた時に原因調査に役立つ情報を表示する gem を作った

Mon, 26 Oct 2020 00:00:00 +0900

それなりの規模のサービスを運用していると、不可解なエラーに遭遇することはよくあるものです。その中でもデータベース関連のエラーは一見難解な問題に見えるかもしれませんが、原因調査に役立つ情報をさえ出力すればたいていの場合は容易に原因を特定できるものです。というわけで、Rails でよく遭遇するエラーの調査に役立つ情報を出力する gem を作成しました。

activerecord-debug_errors

現在次のエラーをサポートしています。

ActiveRecord::LockWaitTimeout (MySQL のみ)
ActiveRecord::Deadlocked (MySQL のみ)
ActiveRecord::ConnectionTimeoutError

以下、具体的な例を用いてどのような情報が表示されるか説明します。

ActiveRecord::LockWaitTimeout

ActiveRecord::LockWaitTimeout が起きた場合、大きく次の 2 つの可能性が考えられます。

特定のレコードのロックを取ったトランザクションの処理が長時間かかっている
特定のレコードのロックを取ったトランザクションを開始したプロセスが死んでいる

いずれのケースにせよ、長時間かかっているトランザクションと、それを実行しているクライアントの情報があればかなりの手がかりになります。なので、activerecord-debug_errors では ActiveRecord::LockWaitTimeout が起きたら SHOW ENGINE INNODB STATUS の TRANSACTIONS セクションの情報と SHOW FULL PROCESSLIST の結果を表示します。

例えば次のスクリプトを実行してみます。

require 'active_record'
require 'activerecord-debug_errors'

ActiveRecord::Base.establish_connection(
  adapter:  'mysql2',
  host:     ENV['MYSQL_HOST'],
  port:     ENV['MYSQL_PORT'],
  username: ENV['MYSQL_USERNAME'],
  password: ENV['MYSQL_PASSWORD'],
  database: ENV['MYSQL_DATABASE'],
  variables: {
    innodb_lock_wait_timeout: 5,
  },
)

ActiveRecord::Base.logger = Logger.new($stdout).tap do |l|
  l.formatter = ActiveSupport::Logger::SimpleFormatter.new
  l.level = Logger::WARN
end

class User < ActiveRecord::Base; end

unless ActiveRecord::Base.connection.table_exists?('users')
  ActiveRecord::Base.connection.create_table('users') do |t|
    t.string 'name'
    t.index ['name'], name: 'ux_name', unique: true
  end
  User.create!(name: 'foo')
  User.create!(name: 'bar')
end

Array.new(2) do
  Thread.new do
    User.transaction do
      User.lock.find_by!(name: 'foo')
      sleep 7
    end
  end
end.each(&:join)

そうすると次のような出力が得られます。

ActiveRecord::LockWaitTimeout occurred:
------------
TRANSACTIONS
------------
Trx id counter 1511907
Purge done for trx's n:o < 1511588 undo n:o < 0 state: running but idle
History list length 42
LIST OF TRANSACTIONS FOR EACH SESSION:
---TRANSACTION 421781578717880, not started
0 lock struct(s), heap size 1136, 0 row lock(s)
---TRANSACTION 1511906, ACTIVE 5 sec
1 lock struct(s), heap size 1136, 1 row lock(s)
MySQL thread id 1016, OS thread handle 123145454059520, query id 62521 localhost 127.0.0.1 root starting
SHOW ENGINE INNODB STATUS
---TRANSACTION 1511905, ACTIVE 5 sec
3 lock struct(s), heap size 1136, 2 row lock(s)
MySQL thread id 1015, OS thread handle 123145453502464, query id 62520 localhost 127.0.0.1 root
-----------
PROCESSLIST
-----------
695     root    localhost:60956 information_schema      Sleep   9
1014    root    localhost:55971 test    Sleep   5
1015    root    localhost:55973 test    Sleep   5
1016    root    localhost:55974 test    Query   0       starting        SHOW FULL PROCESSLIST

上記の結果から、thread id 1015 と thread id 1016 のトランザクションが 5 秒かかっており、前者が localhost:55973、後者が localhost:55974 からのリクエストであることがわかります。この例だとわかりにくいですが、プロセスリストのユーザ情報、クライアントのホスト・ポート情報、SQL 情報から、ロックを保持したままのトランザクションを実行しているアプリケーションを特定できることもあるでしょう。例えば ECS を利用している場合、ECS agent のログをクライアントの IP で検索すればタスクを特定することができます。

ActiveRecord::Deadlocked

MySQL では SHOW ENGINE INNODB STATUS を実行すると LATEST DETECTED DEADLOCK というセクションが表示されるので、このセクションを確認することでデッドロックが起きた原因を調べることができます。なので、activerecord-debug_errors では ActiveRecord::Deadlocked が起きたら LATEST DETECTED DEADLOCK セクションの情報をログに出すようにしています。

例えば次のスクリプトを実行してみます。

require 'active_record'
require 'activerecord-debug_errors'

ActiveRecord::Base.establish_connection(
  adapter:  'mysql2',
  host:     ENV['MYSQL_HOST'],
  port:     ENV['MYSQL_PORT'],
  username: ENV['MYSQL_USERNAME'],
  password: ENV['MYSQL_PASSWORD'],
  database: ENV['MYSQL_DATABASE'],
)

ActiveRecord::Base.logger = Logger.new($stdout).tap do |l|
  l.formatter = ActiveSupport::Logger::SimpleFormatter.new
  l.level = Logger::WARN
end

class User < ActiveRecord::Base; end

unless ActiveRecord::Base.connection.table_exists?('users')
  ActiveRecord::Base.connection.create_table('users') do |t|
    t.string 'name'
    t.index ['name'], name: 'ux_name', unique: true
  end
  User.create!(name: 'foo')
  User.create!(name: 'bar')
end

ths = []
ths << Thread.new do
  User.transaction do
    User.lock.find_by!(name: 'foo')
    sleep 0.1
    User.lock.find_by!(name: 'bar')
  end
end

ths << Thread.new do
  User.transaction do
    User.lock.find_by!(name: 'bar')
    sleep 0.1
    User.lock.find_by!(name: 'foo')
  end
end

ths.each(&:join)

そうすると次のような出力が得られます。

ActiveRecord::Deadlocked occurred:
------------------------
LATEST DETECTED DEADLOCK
------------------------
2020-10-26 06:28:53 0x70000920c000
*** (1) TRANSACTION:
TRANSACTION 1511899, ACTIVE 1 sec starting index read
mysql tables in use 1, locked 1
LOCK WAIT 4 lock struct(s), heap size 1136, 3 row lock(s)
MySQL thread id 1006, OS thread handle 123145455173632, query id 62434 localhost 127.0.0.1 root statistics
SELECT `users`.* FROM `users` WHERE `users`.`name` = 'foo' LIMIT 1 FOR UPDATE
*** (1) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS space id 6659 page no 4 n bits 72 index ux_name of table `test`.`users` trx id 1511899 lock_mode X locks rec but not gap waiting
Record lock, heap no 2 PHYSICAL RECORD: n_fields 2; compact format; info bits 0
 0: len 3; hex 666f6f; asc foo;;
 1: len 8; hex 8000000000000001; asc         ;;

*** (2) TRANSACTION:
TRANSACTION 1511900, ACTIVE 1 sec starting index read
mysql tables in use 1, locked 1
4 lock struct(s), heap size 1136, 3 row lock(s)
MySQL thread id 1007, OS thread handle 123145455452160, query id 62435 localhost 127.0.0.1 root statistics
SELECT `users`.* FROM `users` WHERE `users`.`name` = 'bar' LIMIT 1 FOR UPDATE
*** (2) HOLDS THE LOCK(S):
RECORD LOCKS space id 6659 page no 4 n bits 72 index ux_name of table `test`.`users` trx id 1511900 lock_mode X locks rec but not gap
Record lock, heap no 2 PHYSICAL RECORD: n_fields 2; compact format; info bits 0
 0: len 3; hex 666f6f; asc foo;;
 1: len 8; hex 8000000000000001; asc         ;;

*** (2) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS space id 6659 page no 4 n bits 72 index ux_name of table `test`.`users` trx id 1511900 lock_mode X locks rec but not gap waiting
Record lock, heap no 3 PHYSICAL RECORD: n_fields 2; compact format; info bits 0
 0: len 3; hex 626172; asc bar;;
 1: len 8; hex 8000000000000002; asc         ;;

*** WE ROLL BACK TRANSACTION (2)

上記の出力結果から次のようなことがわかります。

1 つ目のトランザクションでは SELECT `users`.* FROM `users` WHERE `users`.`name` = 'foo' LIMIT 1 FOR UPDATE を実行している
1 つ目のトランザクションでは ux_name の name = ‘foo’ のインデックスレコードの排他ロックが取得できるのを待っている
2 つ目のトランザクションでは SELECT `users`.* FROM `users` WHERE `users`.`name` = 'bar' LIMIT 1 FOR UPDATE を実行している
2 つ目のトランザクションでは ux_name の name = ‘foo’ のインデックスレコードの排他ロックを保持している
2 つ目のトランザクションでは ux_name の name = ‘bar’ のインデックスレコードの排他ロックを取得できるのを待っている

LATEST DETECTED DEADLOCK の見方については InnoDB の行レベルロックについて解説してみるが参考になると思います。ただ、Gap Locks の範囲についての説明は間違っているかもしれないので注意してください…。MySQL のコードをいじったりしつつ実験した結果（rec1 <= x < rec2）と結論付けたんですが、ドキュメントの内容的にも「ギャップ」という名前的にも正しくは（rec1 < x < rec2）の気がします。

ActiveRecord::ConnectionTimeoutError

ActiveRecord のコネクションプールはデフォルトサイズが 5 で、一般的な使い方をしていれば 1 スレッドに対して 1 コネクションが割り当てられ、コネクションが足りなくなった場合は終了したスレッドが使っていたコネクションが使い回されるようになっています。よって、この理解が正しければ、DB に接続するスレッドが同時に 5 つを超えて存在しない限り ActiveRecord::ConnectionTimeoutError が起きることはありません。

ところがどういうわけか ActiveRecord::ConnectionTimeoutError に遭遇することもあることでしょう。activerecord-debug_errors ではコネクションを所有しているスレッドの情報を表示することで原因の特定に貢献します。

例えば次のスクリプトを実行してみます。

require 'active_record'
require 'activerecord-debug_errors'

ActiveRecord::Base.establish_connection(
  adapter:  'mysql2',
  host:     ENV['MYSQL_HOST'],
  port:     ENV['MYSQL_PORT'],
  username: ENV['MYSQL_USERNAME'],
  password: ENV['MYSQL_PASSWORD'],
  database: ENV['MYSQL_DATABASE'],
)

ActiveRecord::Base.logger = Logger.new($stdout).tap do |l|
  l.formatter = ActiveSupport::Logger::SimpleFormatter.new
  l.level = Logger::WARN
end

def foo
  ActiveRecord::Base.connection.execute("select 1")
  sleep 1
end

ActiveRecord::Base.connection.execute("select 1")
ths = []
ths << Thread.new(&method(:foo))
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  sleep 1
end
ths << Thread.new(&method(:foo))
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  sleep 1
end
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  sleep 1
end

ths.each(&:join)

すると次のような出力が得られます。

ActiveRecord::ConnectionTimeoutError occured:
  Thread #<Thread:0x00007fe51c05fa88 sleep_forever> status=sleep priority=0
      /tmp/script.rb:40:in `join'
      /tmp/script.rb:40:in `each'
      /tmp/script.rb:40:in `<main>'
  Thread #<Thread:0x00007fe51c1f2788 /tmp/script.rb:18 dead> status=false priority=0
  Thread #<Thread:0x00007fe51c1f2648 /tmp/script.rb:26 dead> status=false priority=0
  Thread #<Thread:0x00007fe51c1f24b8 /tmp/script.rb:18 dead> status=false priority=0
  Thread #<Thread:0x00007fe51c1f2418 /tmp/script.rb:31 dead> status=false priority=0

上記の情報から、次のようなスレッドがコネクションを所有していることがわかります。

40 行目で join を実行しているスレッド（メインスレッド）
18 行目に定義されている foo メソッドを実行していた 2 スレッド
26 行目のブロックを実行していた 1 スレッド
31 行目のブロックを実行していた 1 スレッド

この例ではメインスレッド以外のスレッドは処理を終了しているので ActiveRecord::ConnectionTimeoutError にはならないでほしいものですが、ActiveRecord では明示的にコネクションを解放しない限り、acquire_connection を実行した時にしかコネクションを解放しないのでエラーになっています。

よって、例えば次のようにすれば ActiveRecord::ConnectionTimeoutError は避けられます。

def foo
  ActiveRecord::Base.connection.execute("select 1")
  ActiveRecord::Base.connection_pool.release_connection
  sleep 1
end

ActiveRecord::Base.connection.execute("select 1")
ths = []
ths << Thread.new(&method(:foo))
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  ActiveRecord::Base.connection_pool.release_connection
  sleep 1
end
ths << Thread.new(&method(:foo))
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  ActiveRecord::Base.connection_pool.release_connection
  sleep 1
end
ths << Thread.new do
  ActiveRecord::Base.connection.execute("select 1")
  ActiveRecord::Base.connection_pool.release_connection
  sleep 1
end

ths.each(&:join)

以上、デバッグが捗りますね！

あらびき日記

PIM の Role Management Policy を作成する際の InsufficientPermissions を解消する

結論

最小再現コード

検証

Amazon のほしい物リストで意図せず旧住所宛に荷物が発送されてしまった時の対応方法

対応方法

配送業者が Amazon の場合

受取人によるキャンセル方法

購入者によるキャンセル方法

配送業者がヤマト運輸で未配達の場合

荷物が配達済みの場合（配送業者に関わらず共通）

何が起きたか？

やったこと

1. Amazon に連絡

2. ヤマト運輸に連絡

3. Amazon に連絡

4. ヤマト運輸に連絡

5. 旧住所の管理会社に連絡

6. ヤマト運輸に連絡

7. Amazon に連絡

8. Amazon に連絡

9. Amazon ギフトカードの送信

Auth0 の Deploy CLI Tool で Auth0 CLI の access token を利用する

Auth0 CLI の access token を使って export するサンプルコード

余談: access token の expiration を考慮するのが地味に大変

jq で timestamp を unixtime に変換することの問題点

date で timestamp を unixtime に変換することの問題点

AWS ユーザに送る Azure 権限管理 (RBAC) 入門

RBAC による権限管理

Actions と Data actions

Role assignment の scope

Role assignment

Role assignment の対象 (Identity)

Service principal

Managed identity

Workload identity

Service principal とは何なのか？

RBAC 以外の認証・認可

Terraform のドキュメントを読み解く

azurerm backend の認証に関する主な設定項目

最後に

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（後編） 〜Getting Started Guide の先へ〜

config.alloy の変更方法

config.alloy の反映方法

Alloy のデバッグ方法

Alloy custom resoure のデバッグ方法

OpenTelemetry 連携: Pod のログと OTLP receiver のログの labels を統一する

重要な label は Pod にアノテーションと環境変数を付与する

logs と receiver の config.alloy を変更する

おわりに

詳説 Grafana Alloy loki.process

loki.process の基礎知識

Log line

Labels

Extracted data

実践的な例

JSON のログに特定のフィールドが含まれていれば drop する

複数行にまたがる JSON のログに特定のフィールドが含まれていれば drop する

JSON のログをパースして変換する

デバッグ方法

Alloy のデバッグビルド

デバッグログの確認

Kubernetes 上の Alloy をリモートデバッグする

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（前編） 〜Getting Started Guide の先へ〜

Getting Started Guide に従って連携してみる

Alloy とは何か？

Helm chart の values を理解する

Grafana Cloud の token 管理

AKS における Secret 管理の例: Kubernetes Secret を作成する Deployment の導入

AKS における Secret 管理の例: 各 Alloy が Kubernetes Secret を作成

OpenTelemetry Collector の OTLP receiver で受け取ったデータに Kubernetes attributes processor で attribute を付与する

attribute が付与されない例

attribute が付与される例

どうして host IP を使うと attribute が付与されないのか？

どうして Service を使うと attribute が付与されるのか？

Terraform Provider for Azure Key Vault を作った 〜Azure の Key Vault secret を Terraform で安全に管理したい〜

使い方

azurerm_key_vault_secret からのマイグレーション

その他の選択肢

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（後編）〜Getting Started Guide の先へ〜

Kubernetes cluster と Grafana Cloud を Grafana Alloy で連携してみる（前編）〜Getting Started Guide の先へ〜

Terraform Provider for Azure Key Vault を作った〜Azure の Key Vault secret を Terraform で安全に管理したい〜

おまけ〜動作確認用 service principal の作成方法〜

PagerDuty のシフト回数を数える pd-shift というツールを作成した〜オンコール待機手当の計算を効率化する〜

前方互換性・後方互換性とは何なのか？〜Schema Registry における例〜

おまけ〜Kafka Streams アプリケーションでデータの Schema が変わった時の挙動を確認する〜

おまけ〜検証環境の構築〜