以下の内容はhttps://sfujiwara.hatenablog.com/entry/sops-sakura-kmsより取得しました。

SOPSで「さくらのクラウドKMS」を使う sops-sakura-kms を作りました

この記事は さくらインターネット Advent Calendar 2025 2日目の記事です。

3行でまとめ

  • SOPS とさくらのクラウドKMSを組み合わせて使う sops-sakura-kms を開発しました
  • sops コマンドのラッパーとして動作します。sops 自体は改変しません
  • Terraform などとも連携できて便利です。どうぞご利用ください

サービス運用に使用するAPIキーやパスワードなど、いわゆる秘匿値をどう管理するかは悩ましいものです。1Password などのパスワード管理サービスや各種クラウドのシークレットマネージャーなどに保存するのが一般的ですが、バックアップや履歴管理のために、十分な強度を持った暗号化を施した上でリポジトリで管理したいことも多いと思います。

このような目的のために、自分はよく SOPS を使っていました。SOPS は元々 Mozilla が開発し、現在は CNCF (Cloud Native Computing Foundation) のサンドボックスプロジェクトとして管理されている暗号化ファイルエディタです。YAML や JSON などの設定ファイルの値を暗号化・復号化でき、AWS KMS、GCP KMS、Azure Key Vault、PGP、age など様々な鍵管理サービスと連携できます。

SOPS の嬉しいところは、YAML や JSON の構造やキーはそのまま、値だけを暗号化できることです。ファイル全体を暗号化してしまうよりも人間に優しい (= grep しやすい!) 状態で扱えます。

www.cncf.io

sops-sakura-kmsとは

sops-sakura-kms は、SOPS でさくらのクラウド KMS をデータキーの暗号化に使用できるようにするラッパーツールです。OSS として公開しています。

github.com

さくらのクラウド KMS について

さくらのクラウドは2025年に多数の新機能を追加しましたが、その中には KMS(Key Management Service) もあります。KMSはデータ暗号化に用いられる暗号鍵の作成、保管、削除などのライフサイクル管理を行うサービスで、FIPS 140-2 level 3 認証を受けた HSM (Hardware Security Module) と連携して暗号鍵を保護します。

cloud.sakura.ad.jp

KMS については、昨日12/1のアドベントカレンダーの記事もあわせてご覧ください。

qiita.com

せっかくさくらのクラウドでKMSが使えるようになったので、SOPSと組み合わせて使いたいと思ったのが開発のきっかけです。

SOPS に PR を送るべきか否か

SOPS は標準で AWS KMS、GCP KMS、Azure Key Vault、HashiCorp Vault などに対応していますが、さくらのクラウドKMSには対応していません。

最初は、SOPS に PRを送って対応してもらおうかと考えました。しかし既存の PR を調べたところ、Oracle Cloud (#1226)、Cloud.ru (#1718) など、各種クラウドのKMS対応を追加するPRはいくつも出ていましたが、これらは一向にマージされないようです。

メンテナーの気持ちになってみればそれはそうで、それほどメジャーでもない各クラウド固有の機能を見境なく取り込んでしまうと、のちのメンテナンスが大変になることは明らかです。

というわけでSOPS本体を変更しないアプローチを探したところ、いい感じに使えそうなアイデアが浮かんだので実装したのが sops-sakura-kms です。

動作の仕組み

sops-sakura-kms は、Hashicorp Vault Transit Engine 互換のHTTPサーバーとして動作します。

  1. sops-sakura-kmsを実行すると、ローカルで127.0.0.1:8200にVault Transit Engine互換のHTTPサーバーを起動します
  2. 環境変数 SOPS_VAULT_URIS、VAULT_ADDR、VAULT_TOKEN を設定し、sops コマンドを子プロセスとして実行します
  3. 起動された sops コマンドはデータキーの暗号化、複合化のために 127.0.0.1:8200 に Vault Transit Engine API で通信します
  4. サーバーはリクエストをさくらのクラウドKMS APIに中継し、実際の暗号化/復号化を行います

つまり SOPS から見ると「HashiCorp Vault」と通信しているように見えますが、実際にはさくらのクラウドKMSを使って暗号化・復号化が行われます。SOPSがすでに対応している Vault Transit Engine での暗号化機能に乗っかることで、SOPS本体を改変することなくさくらのクラウドKMSを利用できるようになりました。

インストール方法

sops-sakura-kms は複数の方法でインストールできます。

Homebrew

brew install fujiwara/tap/sops-sakura-kms

バイナリダウンロード

GitHubのリリースページ から、お使いの環境に合ったバイナリをダウンロードできます。

GitHub Actions

CI/CDパイプラインで使用する場合など、GitHub Actionsで簡単にセットアップできます。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: fujiwara/sops-sakura-kms@main
        with:
          version: 'v0.1.0'  # または 'latest'

Dockerコンテナ

コンテナイメージも提供しています。このイメージには sops-sakura-kms と sops の両方が含まれています。

docker run --rm \
    -e SAKURACLOUD_ACCESS_TOKEN \
    -e SAKURACLOUD_ACCESS_TOKEN_SECRET \
    -e SAKURACLOUD_KMS_KEY_ID \
    -v $(pwd):/work -w /work \
    ghcr.io/fujiwara/sops-sakura-kms:v0.1.0 \
    -d secrets.enc.yaml

セットアップ

環境変数の設定

以下の環境変数を設定します。

# さくらのクラウドAPIクレデンシャル
export SAKURACLOUD_ACCESS_TOKEN="your-access-token"
export SAKURACLOUD_ACCESS_TOKEN_SECRET="your-access-token-secret"

# さくらのクラウドKMSのリソースID（12桁の数字）
export SAKURACLOUD_KMS_KEY_ID="123456789012"

KMSキーIDは、KMSキーを作成した後に確認できるリソースIDです。

オプションの環境変数

動作をカスタマイズするためのオプション環境変数も用意されています。

# サーバーのみモードで実行（SOPSを実行しない）
export SSK_SERVER_ONLY=true

# サーバーのリッスンアドレス（デフォルト: 127.0.0.1:8200）
export SSK_SERVER_ADDR="127.0.0.1:8200"

# 実行するコマンド（デフォルト: sops）
export SSK_COMMAND="/path/to/sops"

基本的な使い方

sops-sakura-kmsは、sops コマンドの単純な代替として使用できます。コマンドライン引数は加工せずに sops に渡すため、通常の sops コマンドと同じように使えます。

ファイルの暗号化

sops-sakura-kms -e secrets.yaml > secrets.enc.yaml

ファイルの復号化

sops-sakura-kms -d secrets.enc.yaml

暗号化ファイルの編集

sops-sakura-kms secrets.enc.yaml

これだけです！裏側で自動的にローカルサーバーが起動し、さくらのクラウドKMSと連携して暗号化・復号化が行われます。

応用的な使い方

サーバーのみを起動する

sops-sakura-kms は、SOPS を実行せずに Vault Transit Engine 互換サーバーとして単独で動作させることもできます。

export SSK_SERVER_ONLY=true
sops-sakura-kms

この状態で、Vault APIエンドポイントを直接呼び出せます。

# データの暗号化
curl -X PUT http://127.0.0.1:8200/v1/transit/encrypt/123456789012 \
  -H "Content-Type: application/json" \
  -d '{"plaintext":"aGVsbG8gd29ybGQ="}'

# データの復号化
curl -X PUT http://127.0.0.1:8200/v1/transit/decrypt/123456789012 \
  -H "Content-Type: application/json" \
  -d '{"ciphertext":"vault:v1:..."}'

このモードは以下のような場面で便利です。

  • アプリケーションからVault Transit Engine APIを直接使用したい場合
  • サーバーを別サービスとして実行したい場合
  • 暗号化/復号化APIのテストやデバッグ

Terraformとの連携

Terraform と sops-sakura-kms を組み合わせてシークレットを復号できます。まず、暗号化ファイルを作成します。

sops-sakura-kms -e secrets.yaml > secrets.enc.yaml

次に、Terraformでsops_fileデータソースを使用します。

terraform {
  required_providers {
    sops = {
      source  = "carlpett/sops"
      version = "~> 1.0"
    }
  }
}

data "sops_file" "secrets" {
  source_file = "secrets.enc.yaml"
}

output "secret_value" {
  value     = data.sops_file.secrets.data["password"]
  sensitive = true
}

Terraformの実行時はSSK_COMMAND環境変数を使って、sopsの代わりにterraformを実行するように設定します。

export SSK_COMMAND=terraform
sops-sakura-kms plan
sops-sakura-kms apply

これにより、sops-sakura-kms が自動的にVault Transit Engine互換サーバーを起動し、必要な環境変数を設定した上で terraform コマンドを実行します。Terraform 実行中に動作する sops プロバイダーはローカルサーバーを使ってシークレットを復号します。

まとめ

sops-sakura-kms は、さくらのクラウドKMSを SOPS で利用可能にするラッパーツールです。Vault Transit Engine 互換サーバーとして動作することで、SOPS 本体を改変することなく、既存のエコシステムをそのまま活用できます。

インストールも設定も簡単で、既存の SOPS ワークフローをほぼそのまま移行できます。GitHub Actions や Docker コンテナもサポートしているので、CI/CD パイプラインへの組み込みも容易です。

さくらのクラウドを利用している方、これから利用を検討している方は、ぜひ試してみてください！ (ちなみにさくらインターネット社内でも、既に利用され始めています)



以上の内容はhttps://sfujiwara.hatenablog.com/entry/sops-sakura-kmsより取得しました。
このページはhttp://font.textar.tv/のウェブフォントを使用してます
不具合報告/要望等はこちらへお願いします。
モバイルやる夫Viewer Ver0.14