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

リモートストレージからのシークレットの同期

Semaphore は、HashiCorp Vault、OpenBao、AWS Secrets Manager、Azure Key Vault、Devolutions Server (DVLS) などの外部シークレットマネージャーに接続し、そこからシークレットをキーストアに自動的にインポートできます。認証情報を手作業で Semaphore にコピーして最新の状態に保つ代わりに、Semaphore にリモートストレージを指定するだけで、ローカルのミラーが自動的に維持されます。

同期パスは、リモートストレージからどのシークレットをインポートし、取り込んだ後にどのように名前を付けるかを Semaphore に指示するルールです。シークレットマネージャーには多数のフォルダーにまたがる何千ものシークレットが保存されている場合があります。同期パスを使用すると、必要なサブツリーだけを選択し、作成されるキーの命名を制御できます。

主要な概念​

  • リモートストレージ — 外部シークレットマネージャーへの設定済みの接続。アドレスと、Semaphore が読み取りに使用する認証情報を含みます。
  • 同期 — リモートストレージからシークレットを読み取り、Semaphore に保存されているキーと整合させる処理。
  • 同期パス — パス、プレフィックス、区切り文字で構成される単一のインポートルール。

同期パスの仕組み​

各同期パスには次の 3 つのフィールドがあります。

  • パス — インポート元となるリモートストレージ内の場所。Semaphore が一覧取得して読み取る基点となるフォルダー、プレフィックス、またはサブツリーです。その配下で見つかったものすべてがインポートの候補になります。
  • プレフィックス — 生成されるすべてのキー名の先頭に追加される文字列。インポートしたシークレットに名前空間を付け、他のパスや他のストレージのキーと衝突しないようにするために使用します (例: prod-)。
  • 区切り文字 — シークレットのリモート上の位置を構成する各要素を、1 つのキー名に結合する際に使用する文字。リモートのシークレットは複数階層のフォルダーの中に存在することがあるため、区切り文字によってその階層がどのように 1 つの読みやすい名前に平坦化されるかが決まります。

同期が実行されると、Semaphore はパスを走査し、見つかった各シークレットについて、その位置を区切り文字で結合し、プレフィックスを先頭に付けてキー名を生成します。作成されるキーの種類 (SSH キー、ログイン/パスワード、または単純なシークレット文字列) は、リモートのシークレットの形式から自動的に推定されます。

1 つのストレージに複数の同期パスを定義できます。各パスは独立してインポートされるため、同じシークレットマネージャー内の関連のない複数の領域から取り込み、それぞれに独自のプレフィックスと命名スタイルを設定できます。

ヒント

プロバイダーごとに適切なデフォルト値が適用されます。たとえば、HashiCorp Vault、OpenBao、AWS Secrets Manager では区切り文字のデフォルトは /、Azure Key Vault では -、Devolutions Server では \ です。そのため、ほとんどの場合はパスを入力するだけで済みます。

同期の実行​

同期は次の 2 つの方法で実行されます。

  1. 手動。 ストレージを開き、今すぐ同期アクションを使用します。Semaphore は、設定された同期パスに基づいてそのストレージを直ちに整合させます。初回のインポートや、変更をすぐに取り込みたい場合に便利です。
  2. スケジュールによる自動実行。 ストレージでキーを同期を有効にし、同期間隔を分単位で設定します。Semaphore はその間隔でバックグラウンドで同期を再実行します。間隔を 0 にすると自動同期は無効になり、手動での同期のみが可能になります。

各ストレージには最後に同期した日時と、最後の試行が失敗したかどうかが記録されるため、ミラーの状態をいつでも確認できます。

注記

高可用性構成では、自動同期はノード間で調整され、特定の同期は一度に 1 つのノードでのみ実行されます。そのため、重複したインポートが発生することはありません。

同期がキーに与える影響​

同期は 1 回限りのコピーではなく、完全なミラーです。実行のたびに、Semaphore はリモートストレージと以前にインポートしたキーとを整合させます。

  • 同期パスの配下で見つかった新しいシークレットは、キーとして作成されます。
  • インポート済みの既存のキーは、現在のリモートの値に一致するように更新されます。
  • 以前にインポートされたが、リモートストレージにもう存在しないキーは削除されます。

Semaphore がインポートしたキーのみが対象となります。手動で作成したキーが同期によって変更または削除されることはありません。

警告

インポートされたキーはリモートシークレットの管理されたコピーであるため、ストレージを削除する (またはその同期を無効にする) と、そのストレージから取り込まれたキーも削除されます。

2 つのスコープ: 共有キーと環境変数​

同期パスは次の 2 つの場所で設定できます。

  • ストレージレベル — インポートしたシークレットは共有キーとなり、キーが使用されるプロジェクト内のあらゆる場所で利用できます。
  • 環境レベル — 変数グループからストレージとその同期パスを指定し、そのグループにスコープされた環境変数としてシークレットをインポートできます。

仕組みは同一で、インポートされたシークレットの保存先だけが異なります。

注意事項と制限​

  • 同期は外部ストレージタイプ (HashiCorp Vault、OpenBao、AWS Secrets Manager、Azure Key Vault、Devolutions Server) でのみサポートされます。組み込みのデータベースストレージはシークレットをネイティブに保持しており、同期するものはありません。
  • リモートストレージの認証情報自体 (Semaphore が認証に使用するトークンやキー) は、インポートされるシークレットとは別に安全に保存されます。
  • 同期がオフになり、パスが 1 つも残っていない場合、そのストレージの同期設定はクリアされます。