タグマッピング¶

build-images フェーズ、 deploy-services フェーズでコンテナイメージをダウンロードする場合に、コンテナイメージが不本意にバージョンアップしていしまい、障害の原因となる場合があります。タグマッピングでは、これを避けるために docker のイメージのタグを固定したり一時的に変更したりする方法を提供します。

タグマッピング指定¶

タグマッピングはコンテキストディレクトリ(.hive/ステージ名)に tag-mapping.json というファイルを作成することで利用できます。このファイルにタグマッピングオブジェクトを記述すると、その内容に応じてダウンロードするタグが変換されます。タグマッピングオブジェクトは、マッピング前のタグをキー、マッピング後のタグを値に持つオブジェクトです。例えば、以下のように指定することで、 mariadb:10.5 を mariadb:10.5.12 に、 hive3.pdns:5000/image_pdnsrecursor:latest を hive3.pdns:5000/image_pdnsrecursor@sha256:cdf0f7d5ac067a3df4b5e08047e7240d57cc49fff55742e66be5a816cce968c2 に変換することができます。

{
  "mariadb:10.5": "mariadb:10.5.12",
  "hive3.pdns:5000/image_pdnsrecursor:latest": "hive3.pdns:5000/image_pdnsrecursor@sha256:cdf0f7d5ac067a3df4b5e08047e7240d57cc49fff55742e66be5a816cce968c2"
}

タグマッピングの対象¶

イメージをダウンロードする以下の3つのケースがタグマッピングの対象となります。

build-images フェーズでサービス定義の image.from 属性に指定されいるものをダウンロードする場合
deploy-services フェーズでサービス定義の image 属性に指定されいるものをダウンロードする場合
deploy-services フェーズでビルドされてリポジトリサーバに登録されているものをダウンロードする場合

最後のケースでは、変換対象のイメージタグは以下のパターンになります。

${リポジトリサーバ名}:5000/image_${サービス名}:latest

例えば、サーバが1台で hive名が "pdns"、ステージが "private" 、サービス名が pdnsrecursor の場合は以下のようなイメージタグになります。

p-hive0.pdns:5000/image_pdnsrecursor:latest

また、リポジトリ上のダイジェスト値を @ に続けて指定することで、最新でない(latestタグが付いていない)ものを指定してダウンロードすることが可能です。例えば、イメージIDがわかっていれば、

docker inspect --format='{{index .RepoDigests 0}}' イメージID

を実行して、リポジトリ上のダイジェスト値を調べ、

p-hive0.pdns:5000/image_pdnsrecursor@sha256:cdf0f7d5ac067a3df4b5e08047e7240d57cc49fff55742e66be5a816cce968c2

のように指定することができます。

タグマッピングの運用¶

hive-builder のソースコードを git で版管理を行っている場合でも、タグマッピングを利用して、開発途上の最新版を利用するか、動作が確認されている安定版を利用するかを切り分けることができます。ここではその運用方法について提案します。まず、git に登録されるソースコード上でどのようにタグを指定するかについて、開発フェーズと運用フェーズに分けることとします。

開発フェーズ¶

開発フェーズでは、ソースコード上のサービス定義の image.from 属性や image 属性には、latest など常に最新版を指し示すタグを指定しておきます。このコードを git に登録しておくことにより、 git pull で取得したソースコードからそのままビルドすると最新版がダウンロードされます。一方で、結合テスト環境やデモ環境のように安定稼働が重視される環境では、コンテナイメージのバージョンを固定したい場合があります。このような場合はタグマッピング機能でコンテナイメージのバージョンを固定できます。結合テスト環境やデモ環境では、最初に稼働確認が取れた時点ですべてのコンテナイメージのバージョンをタグマッピングで固定することを推奨します。 latest などの最新版を指し示すタグに対して稼働確認が取れたバージョンのタグへのマッピングを指定して tag-mapping.json を作成してください。以降イメージを明示的にバージョンアップする場合は tag-mapping.json を編集してバージョンアップの対象となるタグのマッピング先を修正してください。

例： powerdns のコンテナのバージョンを検証環境のテスト中は 4.5.1-1 に固定しておきたい場合、

inventory/powerdns.yml:

 plugin: hive_services
 services:
  powerdns:
   image: procube/powerdns:latest
...

.hive/staging/tag-mapping.json

{
  "procube/powerdns:latest": "procube/powerdns:4.5.1-1"
}

運用フェーズ¶

運用フェーズでは、ソースコード上のサービス定義の image.from 属性や image 属性には、安定稼働が確認されたバージョンのイメージのタグを指定しておきます。このコードを git に登録しておくことにより、 git pull で取得したソースコードからそのままビルドすると安定版がダウンロードされます。一方で、ステージング環境のように新しいバージョンのテストが優先される環境では、タグマッピング機能でコンテナイメージの最新版がダウンロードされるように設定できます。このような環境では、安定版をを指し示すタグに対してlatest などの最新版へのタグへのマッピングを指定して tag-mapping.json を作成してください。

例： powerdns のコンテナのバージョンを運用中の環境では 4.5.1-1 を使用しているが、テスト環境でコンテナを最新にバージョンアップしてテストする場合、

inventory/powerdns.yml:

 plugin: hive_services
 services:
  powerdns:
   image: procube/powerdns:4.5.1-1
...

.hive/staging/tag-mapping.json

{
  "procube/powerdns:4.5.1-1": "procube/powerdns:latest"
}

本番環境での切り戻し¶

本番環境で特定のサービスに対して build-images フェーズ、deploy-services フェーズを実行してコンテナをバージョンアップした後、その内容に問題があって切り戻さなければならない場合があります。このような場合にタグマッピングを利用して切り戻すことが可能です。

docker images

で、切り戻し対象のイメージを特定し、

docker inspect --format='{{index .RepoDigests 0}}' イメージID

でタグを取得し、これを tag-mapping.json に指定してからサービスをデプロイすることで切り戻しできます。たとえば、タグが hive3.pdns:5000/image_pdnsrecursor@sha256:cdf0f7d5ac067a3df4b5e08047e7240d57cc49fff55742e66be5a816cce968c2 である場合、 tag-mapping.json を

{
  "hive3.pdns:5000/image_pdnsrecursor:latest": "hive3.pdns:5000/image_pdnsrecursor@sha256:cdf0f7d5ac067a3df4b5e08047e7240d57cc49fff55742e66be5a816cce968c2"
}

のように指定し、

hive deploy-services -l pdnsrecursor

を実行することで切り戻しを実行できます。

ソフトウェアパッケージのバージョン管理について¶

タグマッピングではコンテナイメージのバージョンを管理できますが、 build-images フェーズで yum, pipy, npmjs などのパブリックリポジトリからダウンロードされるソフトウェアは管理できません。プロジェクトごとに ansilbe コードの中で対応する必要があることにご注意ください。