まずは開発環境を更新せねばということで諸々アップデートして動作を確認していたのですが、相変わらずVSCode + LLDBという構成だとlibクレートの単体テストをデバッグするときにブレークポイントが効かない。binクレートの単体テストだと効く。なぜか日本語のブログではこの問題に触れているのを見たことがないんですよね(そういう入門記事はだいたいサンプルがbinクレートなので、この問題を踏むのはもっと後のステップではあるんですが)。

私の環境固有の問題かなとも少し思ったんですが、GitHubのIssueを漁ってみると同じ問題を踏んでそうな人をちらほら見かけたので、今回はちょっと時間を使って原因を調べてみることにしました。

問題の再現手順とかワークアラウンドのスクリプトは下記のリポジトリにも置いてあります。

https://github.com/kwhrtsk/rust-lldb-workaround

解決方法だけ知りたい人はVSCode (CodeLLDB) の場合を参照してください。

問題の概要

macOSにおいて、rust-lldb でlibクレートのテストをデバッグしようとしたときに、ブレークポイントが効きません。VSCodeで CodeLLDB を使ってデバッグした場合も同様です。

【2020-03-06:追記】

masterには修正が入りました。詳細は末尾の追記を参照してください。

原因

直接の原因は、cargo testに--libオプションを付けてテストバイナリをビルドすると、LLDBのデバッグシンボル情報が書かれたファイル(.dSYM)がtarget/debug/ディレクトリに作成されないことです。

このため、ブレークポイントとして指定したシンボル情報をLLDBが解決できず、デバッガがブレークポイントで止まりません。

rust-lldbを使った場合は、後述のようにエラーが表示されるのですが、VSCode上でデバッグしている場合、lldb.verboseLoggingを有効にして出力ペインを注意深く見ていないと気づけないと思います。

環境

• Operating system: macOS Catalina 10.15.3
• Rust toolchain: stable-x86_64-apple-darwin
• Rustc version: 1.41.1 (f3e1a954d 2020-02-24)
• lldb: 9.0.1
• VSCode: 1.42.1
• CodeLLDB: 1.5.0

再現手順

• Cargo.toml

[package]name = "rust-lldb-workaround"version = "0.1.0"edition = "2018"

• src/lib.rs

#[cfg(test)]mod tests {    #[test]    fn it_works() {        assert_eq!(2 + 2, 4);    }}

it_worksにブレークポイントを仕掛けようとすると、下記のように失敗します。

下記のようなシェルスクリプトを実行するとこの様子を確認できます。

#!/bin/bashrm -rf targetbin=$(cargo test --lib --no-run --message-format=json | jq -r '.executable')rust-lldb $bin <<- EOFbreakpoint set --name tests::it_worksEOF

   Compiling rust-lldb-workaround v0.1.0 (/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround)    Finished test [unoptimized + debuginfo] target(s) in 0.51s(lldb) command script import "/Users/kawahara_taisuke/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"(lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust(lldb) type category enable Rust(lldb) target create "/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-6e0ca18365abb7b9"Current executable set to '/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-6e0ca18365abb7b9' (x86_64).(lldb) breakpoint set --name tests::it_worksBreakpoint 1: no locations (pending).WARNING:  Unable to resolve breakpoint to any actual locations.

詳細

binクレートの場合、cargo testは.dSYMファイルをtarget/debug/ディレクトリに作成します。このファイルは実際にはtarget/debug/deps/以下のファイルへのシンボリックリンクです。

% cargo test --bins --no-run --message-format=json 2> /dev/null | jq 'select(.target.kind | contains(["bin"])) | .filenames'[  "/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-4aae58342b9c3866",  "/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-4aae58342b9c3866.dSYM"]% ls -l target/debugtotal 1720drwxr-xr-x  2 kawahara_taisuke  staff      64  3  3 13:47 builddrwxr-xr-x  8 kawahara_taisuke  staff     256  3  3 13:47 depsdrwxr-xr-x  2 kawahara_taisuke  staff      64  3  3 13:47 examplesdrwxr-xr-x  4 kawahara_taisuke  staff     128  3  3 13:47 incremental-rwxr-xr-x  2 kawahara_taisuke  staff  874952  3  3 13:47 rust_lldb_workaround-4aae58342b9c3866-rw-r--r--  1 kawahara_taisuke  staff     282  3  3 13:47 rust_lldb_workaround-4aae58342b9c3866.dlrwxr-xr-x  1 kawahara_taisuke  staff      47  3  3 13:47 rust_lldb_workaround-4aae58342b9c3866.dSYM -> deps/rust_lldb_workaround-4aae58342b9c3866.dSYM

しかし、libクレートを対象とするとこのシンボリックリンクが作成されません。rust-lldb及びVSCodeのデバッガ(CodeLLDB)でブレークポイントが効かないのは直接的にはこれが原因です。

% cargo test --lib --no-run --message-format=json 2> /dev/null | jq 'select(.target.kind | contains(["lib"])) | .filenames'[  "/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-6e0ca18365abb7b9"]% ls -l target/debugtotal 1720drwxr-xr-x  2 kawahara_taisuke  staff      64  3  3 13:49 builddrwxr-xr-x  5 kawahara_taisuke  staff     160  3  3 13:49 depsdrwxr-xr-x  2 kawahara_taisuke  staff      64  3  3 13:49 examplesdrwxr-xr-x  3 kawahara_taisuke  staff      96  3  3 13:49 incremental-rwxr-xr-x  2 kawahara_taisuke  staff  874968  3  3 13:49 rust_lldb_workaround-6e0ca18365abb7b9-rw-r--r--  1 kawahara_taisuke  staff     201  3  3 13:49 rust_lldb_workaround-6e0ca18365abb7b9.d% ls -l target/debug/depstotal 1720-rwxr-xr-x  2 kawahara_taisuke  staff  874968  3  3 13:49 rust_lldb_workaround-6e0ca18365abb7b9-rw-r--r--  1 kawahara_taisuke  staff     290  3  3 13:49 rust_lldb_workaround-6e0ca18365abb7b9.ddrwxr-xr-x  3 kawahara_taisuke  staff      96  3  3 13:49 rust_lldb_workaround-6e0ca18365abb7b9.dSYM

cargo の実装を見る限りこの挙動は意図したもので、テストの場合はdepsの下を直接実行してもらう想定だったようです。(参考)

https://github.com/rust-lang/cargo/blob/e618d47a1765ca18d1601d4cf891a55a34d23aed/src/cargo/core/compiler/build_context/target_info.rs#L260-L269

対処法としては次の方法が考えられます。

1. rust-lldbでadd-dsymコマンドを実行する。
2. .dSYMへのリンクをtarget/debug/以下に作る。
3. cargo test --message-format=jsonの出力するexecutableをdepsの下に変更する。

1の方法はCodeLLDBなど使用するVSCode拡張全てに対処が必要で、あまり筋がよくないと思ったので除外しました。

2と3は根本的に解決しようとすると両方ともcargoの動作を変える必要があるのですが、2についてはcargo testとrust-lldbの間にシンボリックリンクを作る処理を挟めば良いので簡単そうです。

この記事では2の方法でのワークアラウンドを示します。

rust-lldbコマンドを直接実行する場合

先ほどのシェルスクリプトを下記のように修正します。

#!/bin/bashrm -rf targetbin=$(cargo test --lib --no-run --message-format=json | jq -r '.executable')# .dSYMディレクトリへのシンボリックリンクを作成(cd target/debug && for d in deps/*.dSYM; do ln -sf $d ./; done)rust-lldb $bin <<- EOFbreakpoint set --name tests::it_worksEOF

ブレークポイントの設置が成功するようになります。

   Compiling rust-lldb-workaround v0.1.0 (/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround)    Finished test [unoptimized + debuginfo] target(s) in 0.53s(lldb) command script import "/Users/kawahara_taisuke/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"(lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust(lldb) type category enable Rust(lldb) target create "/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-6e0ca18365abb7b9"Current executable set to '/Users/kawahara_taisuke/.ghq/github.com/kwhrtsk/rust-lldb-workaround/target/debug/rust_lldb_workaround-6e0ca18365abb7b9' (x86_64).(lldb) breakpoint set --name tests::it_worksBreakpoint 1: where = rust_lldb_workaround-6e0ca18365abb7b9`rust_lldb_workaround::tests::it_works::h666f078a6b384dfd + 18 at lib.rs:7:8, address = 0x0000000100000cd2

VSCode (CodeLLDB) の場合

launch.json と tasks.json を修正して、cargo testの直後に.dSYMのシンボリックリンクを自動で作成するようにします。

• .vscode/launch.json

preLaunchTaskを追加した以外はVSCodeからLLVMテンプレートで作ったものそのままです。

{  "version": "0.2.0",  "configurations": [    {      "type": "lldb",      "request": "launch",      "name": "Debug unit tests in library 'rust-lldb-workaround'",      "cargo": {        "args": [          "test",          "--no-run",          "--lib",          "--package=rust-lldb-workaround"        ],        "filter": {          "name": "rust-lldb-workaround",          "kind": "lib"        }      },      "args": [],      "cwd": "${workspaceFolder}",      // この行を追加      "preLaunchTask": "symlink dSYM"    }  ]}

• .vscode/tasks.json

launch.jsonのpreLaunchTaskで参照されているタスクの定義です。このタスクでは、target/debugディレクトリに移動してtarget/debug/deps/ディレクトリ以下の全ての*.dSYMのシンボリックリンクを作成します。

{  "version": "2.0.0",  "tasks": [    {      "label": "symlink dSYM",      "type": "shell",      "command": "sh",      "args": [        "-c",        "cd ${workspaceFolder}/target/debug; for d in deps/*.dSYM; do ln -fs $d ./; done"      ]    }  ]}

なお Rust Test Lens を使う場合は、上記のタスクを自動で実行することができません。この場合は事前に一度 cargo test --lib --no-run を実行した後、手動で上記のタスクを実行して.dSYMのシンボリックリンクを作っておく必要があります。

終わりに

この問題はrust-lang/cargo#7960で既に起票されているので、将来的には修正されるかもしれません。

【2020-03-06:追記】

rust-lang/cargo#7965 で修正され、masterにもマージされました。
この修正は2020年4月23日リリース予定の Cargo 1.43 に反映される見込みです。

• 第一回 Docker編
• 第二回 Docker Compose/Dockerfile編
• 第三回 Kubernetes入門編
• 第四回 Kubernetes基礎編
• 第五回 Kubernetes応用編
• 第六回 Helm編

はじめにHelmについて簡単に紹介した後、前回の Kubernetes応用編で作成したマニフェストをもとにHelmチャートの作り方を説明します。

サンプルコードは全て下記のリポジトリにあります。

https://github.com/kwhrtsk/rails-k8s-demoapp

前提

• macOSでの作業を前提としています。
• 使用したツールのバージョンなどは 初回 の記事を参照してください。
• ツールのインストール手順は 第三回 の記事を参照してください。

準備

まずサンプルアプリのコードをチェックアウトしてminikubeを起動してください。前回とほぼ同じですが、minikubeのメモリを3GBに増やしています。これは2GBだと後述するSentryの起動に失敗するためです。すでに2GBで作っている場合はminikubeインスタンスを作り直すか、Sentryを使ったhelmコマンドのチュートリアルを飛ばしてください。Railsのサンプルアプリは2GBでも動作します。

また、今回は初めからIngressアドオンを有効にしています。minikubeインスタンスを削除した場合は忘れずにもう一度有効にしてください。

# サンプルアプリのコードをチェックアウト$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp# minikubeを起動$ minikube start --cpus=3 --memory=3072 --vm-driver=hyperkit --disk-size=12g# Ingressアドオンをインストール$ minikube addons enable ingress# kubernetesのダッシュボードをオープン$ minikube dashboard

Helmとは

Helm - The Kubernetes Package Manager

アプリケーションに必要なマニフェストファイル一式をパッケージ化して管理するためのツールです。これを使うと必要なコンテナをまとめてk8sにデプロイすることができます。このパッケージはChartと呼ばれます。

HelmではマニフェストファイルをGoのtext/template形式でテンプレート化することができ、イメージのタグやレプリカの数など、マニフェストの一部をパラメータ化することができます。これらのパラメータは通常デフォルト値を持ち、Chartパッケージをk8sにデプロイ（インストール）する際に上書きできます。

Helmでは公式リポジトリで配布されているChartをk8sクラスタにデプロイすることもできるし、自分で開発しているプライベートなアプリのChartを作成して、Helmでk8sにデプロイすることもできます。

• Helm Docs

Helmをk8sにインストールする方法

Helmはクライアント・サーバモデルのアプリケーションです。k8sクラスタ側にTillerと呼ばれるサーバモジュールをインストールします。クライアントはhelmコマンドです。

minikubeの場合は下記のコマンドでTillerをインストールできます。

# インストールが完了するまでブロック$ helm init --wait

Tillerがインストールされているかどうかは下記のコマンドで確認できます。

$ helm versionClient: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}Server: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}

アンインストールは下記のコマンドです。

$ helm reset

Helmによるパッケージ管理のチュートリアル

この章ではSentry というWebアプリを題材に、Chartを使ってアプリケーションをminikubeにデプロイするデモをします。

Sentryはアプリケーションのエラー情報を収集してSlackなどに通知するためのサービスです。SentryのWebサービスはPythonで実装されていますが、Ruby用のクライアントもgemとして配布されており、Railsにも簡単に組み込むことができます。

• Raven is a Ruby client for Sentry
• Ruby on Rails – Sentry Documentation

SaaSを利用することもできるのですが、公式のDockerイメージが配布されており、Dockerを使って自前で運用することもできます。

Sentryサービスの内部構成はPythonのWebアプリ、バックグラウンドジョブのためのワーカー、PostgreSQLサーバ、Redisサーバとそれなりに複雑です。ただ、Helm Chartを使えば比較的簡単にセットアップすることが可能です。

この章ではhelmコマンドのチュートリアルとしてminikube上にSentryをセットアップする手順を示します。

helm update repo: リポジトリ情報の更新

公式のChartリポジトリはここです。

https://github.com/kubernetes/charts

このリポジトリはstableとincubatorの二つに別れています。

helmコマンドはローカルにこのリポジトリの情報をキャッシュしています。下記のコマンドでこのキャッシュを更新することができます。

$ helm repo update...Skip local chart repository...Successfully got an update from the "stable" chart repository...Successfully got an update from the "jenkins-x" chart repositoryUpdate Complete. ⎈ Happy Helming!⎈

helm search: Chartの検索

helm searchコマンドでstableのChartを検索することができます。

$ helm search sentryNAME            CHART VERSION   APP VERSION     DESCRIPTIONstable/sentry   0.1.14          8.17            Sentry is a cross-platform crash reporting and ...

少しややこしいですが、CHART VERSIONはマニフェストやパラメータ定義などこのChart自体のバージョンを示し、APP VERSIONはSentryのバージョンを示しています。

パラメータなしで実行すると全てのChartを表示します。

helm inspect: Chartの詳細情報の表示

Chartのメタ情報やパラメータのデフォルト値、READMEなどを表示するコマンドがあります。

$ helm inspect stable/sentry

後述するhelm installの-fや--setオプションで指定できるパラメータの一覧などを確認することができます。

helm install: Chartのインストール（デプロイ）

下記のコマンドを実行すると、stable/sentryというChartをminikubeにデプロイします。

$ helm install stable/sentry \  --name sentry \  --namespace sentry \  --wait \  --timeout 600 \  --version 0.1.14 \  --set service.type=NodePort \  --set ingress.enabled=true \  --set ingress.hostname=$(minikube ip).nip.io \  --set image.tag=8.22 \  --set email.host="" \  --set sentrySecret=sentry \  --set postgresql.postgresPassword=postgres \  --set redis.redisPassword=redis

色々オプションを指定していますが、実際のところはhelm install stable/sentryだけでも動作します。今回は比較的よく使いそうなオプションをまとめて紹介します。

はじめに、特に重要な--nameオプションについて説明します。k8sにデプロイされたChartのインスタンスはReleaseと呼ばれ、一意な名前を持ちます(Helmでは同じChartのReleaseを二つ以上デプロイすることができます)。この名前を--nameオプションで指定することができます。この例ではsentryという名前をつけていますが、本来はstagingやproductionなど環境を示すような名前をつける方が良いかもしれません。

名前を指定しない場合はhappy-pandaのように辞書から単語を二つ適当に拾ってきてくっつけたみたいな名前が自動的に与えられます。helm upgradeやhelm deleteなど、特定のReleaseを対象とするコマンドはこの名前で対象を指定するので、できるだけわかりやすい名前を自分でつけるのがおすすめです。

その他のオプションの意味は次の通りです。

• --namespaceオプションでは、このChartのAPIオブジェクトを作成するNamespaceをsentryにしています。Namespaceについては後述します。
• --waitオプションをつけると、各オブジェクトの状態が準備完了になるまで待機してからコマンドを終了します。
• --timeoutオプションは--waitのタイムアウト値(秒)です。筆者の環境ではstable/sentryの初期化に5分強かかるので、10分に拡張しています。
• --versionオプションはインストールするChartのバージョンです。指定しないと最新版がインストールされます。
• --setオプションはChartに定義されているパラメータを入力しています。この例では次のパラメータの値をデフォルトから変更しています。
  • service.type: Serviceオブジェクトのタイプです。デフォルトはLoadBalancerなのですが、minikubeが対応していないためNodePortに変更しています。--waitオプションをつけている場合、LoadBalancerのままだとServiceオブジェクトの状態が準備完了にならず、コマンドがタイムアウトして失敗します。
  • ingress.enabled: デフォルトではIngressを使わない設定になっていますが、この例では有効にしています。
  • ingress.hostname: minikube ipとワイルドカードDNSを組み合わせたURLにしています。
  • image.tag: sentryイメージのタグです。Sentry自体のバージョンを意味します。デフォルトは8.17ですが、新しいバージョンが出ているので8.22に変更しています。
  • email.host: 招待メールやレポートなどメールを送信するためのSMTPサーバを指定します。空文字を指定するとメール送信機能が無効化されます。
  • sentrySecret: Sentry内部での暗号処理の鍵です。省略するとランダムな文字列が自動的に割り当てられます。*2
  • postgres.postgresPassword: PostgreSQLサーバのパスワードです。省略するとランダムな文字列が自動的に割り当てられます。*2
  • redis.redisPassword: Redisサーバのパスワードです。省略するとランダムな文字列が自動的に割り当てられます。*2

*2: これらのパラメータを省略してランダム文字列にした場合、email.hostのような別のパラメータを更新した場合にもランダム文字列が再生成されてDBに接続できなくなるなどの問題が起きるため、継続的に運用する予定なら明示的に設定しておくのが無難です。

--setでは見ての通り複数のパラメータを指定できます。パラメータの一覧を書いたYAMLファイルを-fオプションに渡すことでも同様のことができます。

# values-custom.yamlservice:  type: NodePortingress:  enabled: trueimage:  tag: 8.22email:  host: ""sentrySecret: sentrypostgresql:  postgresPassword: postgresredis:  redisPassword: redis

上記のようなYAMLファイルを用意して、-fオプションに渡します。この例では、ingress.hostnameのみminikube ipコマンドの出力を使いたいので--setで指定しています。

$ helm install stable/sentry \  --name sentry \  --namespace sentry \  --wait \  --timeout 600 \  --version 0.1.14 \  --f values-custom.yaml \  --set ingress.hostname=$(minikube ip).nip.io

このChartのソースコードは下記にあります。他にどのようなパラメータがあるかなどはここを参照してください。

kubernetes/charts | stable/sentry

結構時間がかかるので、別の端末にログを表示して進捗を確認できるようにしておくと良いでしょう。

$ stern --namespace sentry ".*"

完了すると下記のようなメッセージが表示されます。

NAME:   sentryLAST DEPLOYED: Tue May 22 00:07:12 2018NAMESPACE: sentrySTATUS: DEPLOYEDRESOURCES:==> v1/SecretNAME               TYPE    DATA  AGEsentry-postgresql  Opaque  1     5msentry-redis       Opaque  1     5msentry-sentry      Opaque  3     5m==> v1/PersistentVolumeClaimNAME               STATUS  VOLUME                                    CAPACITY  ACCESS MODES  STORAGECLASS  AGEsentry-postgresql  Bound   pvc-a3af7917-5d08-11e8-9576-9a07dd1ebfb4  8Gi       RWO           standard      5msentry-redis       Bound   pvc-a3b0850d-5d08-11e8-9576-9a07dd1ebfb4  8Gi       RWO           standard      5msentry-sentry      Bound   pvc-a3b159e9-5d08-11e8-9576-9a07dd1ebfb4  10Gi      RWO           standard      5m==> v1/ServiceNAME               TYPE       CLUSTER-IP      EXTERNAL-IP  PORT(S)         AGEsentry-postgresql  ClusterIP  10.106.179.194  <none>       5432/TCP        5msentry-redis       ClusterIP  10.104.155.56   <none>       6379/TCP        5msentry-sentry      NodePort   10.101.218.50   <none>       9000:31416/TCP  5m==> v1beta1/DeploymentNAME                  DESIRED  CURRENT  UP-TO-DATE  AVAILABLE  AGEsentry-postgresql     1        1        1           1          5msentry-redis          1        1        1           1          5msentry-sentry-cron    1        1        1           1          5msentry-sentry-web     1        1        1           1          5msentry-sentry-worker  2        2        2           2          5m==> v1beta1/IngressNAME           HOSTS                 ADDRESS        PORTS  AGEsentry-sentry  192.168.64.29.nip.io  192.168.64.29  80     5m==> v1/Pod(related)NAME                                   READY  STATUS   RESTARTS  AGEsentry-postgresql-5795779885-hh88k     1/1    Running  0         5msentry-redis-6f8d889d4d-r5wbh          1/1    Running  0         5msentry-sentry-cron-8578df4d69-2kzd9    1/1    Running  0         5msentry-sentry-web-6b857b74c8-96fsq     1/1    Running  1         5msentry-sentry-worker-66cf9bb6db-2qzkh  1/1    Running  0         5msentry-sentry-worker-66cf9bb6db-x9plg  1/1    Running  0         5mNOTES:1. Get the application URL by running these commands:  export NODE_PORT=$(kubectl get --namespace sentry -o jsonpath="{.spec.ports[0].nodePort}" services sentry-sentry)  export NODE_IP=$(kubectl get nodes --namespace sentry -o jsonpath="{.items[0].status.addresses[0].address}")  echo http://$NODE_IP:$NODE_PORT/auth/login/sentry2. Log in with  USER: admin@sentry.local  Get login password with    kubectl get secret --namespace sentry sentry-sentry -o jsonpath="{.data.user-password}" | base64 --decode

作成されたAPIオブジェクトのレポートと、Chart側で設定された初期メッセージがNOTES以下に表示されています。

1. Get the application URL...にはログインURLの取得方法が書いてありますが、これはNodePortを使う場合のものです。今回はパラメータでIngressを有効にしているので、ログインURLは open http://$(minikube ip).nip.io/ でOKです。2. Log in with手順に従って初期ユーザのパスワードを取得し、Sentryの管理画面にログインできることを確認してください。ユーザ名は admin@sentry.local で、パスワードは上記のkubectl get secretコマンドを実行して表示されるテキストです。最後に%が化けて表示されるようですが、その前までのテキストを入力してください。

公式のChartはだいたいインストール後にこのようなヘルプメッセージが表示されます。このメッセージもGoのテンプレート構文で記述されています。

kubernetes/charts | stable/sentry/templates/NOTES.txt

helm list: クラスタ上のChartインスタンス(Release)の一覧を表示

k8sクラスタにインストール済みのReleaseの一覧は下記のコマンドで確認できます。

$ helm listNAME    REVISION        UPDATED                         STATUS          CHART           NAMESPACEsentry  1               Tue May 22 00:07:12 2018        DEPLOYED        sentry-0.1.14   sentry

helm upgrade: Chartの更新のデプロイ

Release名を指定して、

$ helm upgrade sentry

helm delete: ReleaseとAPIオブジェクトの削除

作成したReleaseによって作られたAPIオブジェクトを削除する場合は、下記のコマンドを実行します。

$ helm delete --purge sentry

パラメータにはReleaseの名前を指定します。--purgeオプションをつけるとRelease自体も削除します。このオプションをつけない場合、APIオブジェクトだけが削除され、Releaseは削除されずにHelmの管理DBに残る点に注意してください。purgeするまでその名前のReleaseを新しく作ることはできません。

なお、stable/sentryの場合は少し厄介で、READMEにも書かれている通りhelm deleteしただけではJobのオブジェクトが残ります。

$ kubectl get all --namespace sentryNAME                           READY     STATUS      RESTARTS   AGEpod/sentry-db-init-9mnqq       0/1       Completed   0          22hpod/sentry-db-init-ckgzj       0/1       Error       0          22hpod/sentry-user-create-8dgbj   0/1       Completed   0          22hNAME                           DESIRED   SUCCESSFUL   AGEjob.batch/sentry-db-init       1         1            22hjob.batch/sentry-user-create   1         1            22h

これらのオブジェクトは下記のように個別に削除する必要があります。

$ kubectl delete job/sentry-db-init job/sentry-user-create

sentry-db-initのsentry部分はReleaseの名前です。別の名前でhelm installするとここも変わるので注意してください。後述するようにネームスペースごと削除してしまう方が簡単です。

$ kubectl delete ns sentry

NamespaceとContextについて

k8sにはNamespaceというオブジェクトがあり、DeploymentやServiceなど主要なオブジェクトは基本的にいずれかのNamespaceに属しています。前回の記事まで全くNamespaceを指定してこなかったのですが、ずっとdefaultという組み込みのNamespaceが操作の対象になっていました。

# defaultネームスペースのPodのリストを表示$ kubectl get pods# sentryネームスペースのPodのリストを表示$ kubectl -n sentry get pods

また、これまでのサンプルではServiceのエンドポイントにアクセスする際にはそのサービスの名前をDNS名として指定しました。同一のネームスペース内のオブジェクトから接続する場合はそれで良いのですが、異なるネームスペースのオブジェクトから接続する場合には${サービス名}.${ネームスペース名}のようにドメインを追加する必要があります。

ところで、default以外のネームスペースを主に使う場合に、kubectlのパラメータにその都度-nオプションを指定するのは面倒です。

kubectlコマンドにはContextという概念があり、コマンド側で接続先のk8sクラスタやデフォルトのネームスペースを記憶しています。

• 接続先のクラスタやデフォルトのネームスペースなどの情報をContextという単位で保存
• Contextは複数保存でき、有効になっているのはそのうちの一つ(CURRENT)
• 有効なContextを切り替えることで接続先クラスタやデフォルトのネームスペースを変更可能

これらの設定は ~/.kube/config に記録されています。

kubectl config get-contexts: Contextの一覧の表示

minikubeしか使っていない場合は下記のようになっていると思います。

$ kubectl config get-contextsCURRENT   NAME       CLUSTER    AUTHINFO   NAMESPACE*         minikube   minikube   minikube

kubectl config current-context: 現在有効になっているContext名の表示

$ kubectl config current-contextminikube

kubectl config view: Contextの詳細の表示

~/.kube/configの中身を表示しているだけです。

$ kubectl config viewapiVersion: v1clusters:- cluster:    certificate-authority: /Users/kawahara_taisuke/.minikube/ca.crt    server: https://192.168.64.29:8443  name: minikubecontexts:- context:    cluster: minikube    user: minikube  name: minikubecurrent-context: minikubekind: Configpreferences: {}users:- name: minikube  user:    client-certificate: /Users/kawahara_taisuke/.minikube/client.crt    client-key: /Users/kawahara_taisuke/.minikube/client.key

kubectl config set-context: Contextの作成または更新

現在のContextのネームスペースをsentryに変更するにはこうします。

$ kubectl config set-context $(kubectl config current-context) --namespace=sentryContext "minikube" modified.# 変わっていることを確認$ kubectl config get-contextsCURRENT   NAME       CLUSTER    AUTHINFO   NAMESPACE*         minikube   minikube   minikube   sentry

無指定(default)に戻す場合はこうします。

$ kubectl config unset contexts.minikube.namespaceProperty "contexts.minikube.namespace" unset.# 戻っていることを確認$ kubectl config get-contextsCURRENT   NAME       CLUSTER    AUTHINFO   NAMESPACE*         minikube   minikube   minikube

存在しない名前を指定すると新しいContextを作ります。次の例はクラスタがminikubeでネームスペースがsentryであるContextの例です。

$ kubectl config set-context minikube-sentry --cluster=minikube --user=minikube --namespace=sentry$ kubectl config get-contextsCURRENT   NAME              CLUSTER    AUTHINFO   NAMESPACE*         minikube          minikube   minikube          minikube-sentry   minikube   minikube   sentry

kubectl config use-context: 有効なContextを変更

$ kubectl config use-context minikube-sentry% kubectl config get-contextsCURRENT   NAME              CLUSTER    AUTHINFO   NAMESPACE          minikube          minikube   minikube*         minikube-sentry   minikube   minikube   sentry

kubectl config delete-context: Contextの削除

指定したコンテキストを削除できます。

$ kubectl config delete-context minikube-sentry

kubectxとkubens

Contextとネームスペースの切り替えは見ての通り煩雑です。kubectxとkubensというツールを使えばもっと簡単に切り替えの操作を行うことができます。

macOSの場合はHomebrewでインストール可能です。

$ brew install kubectx

インストール時に--with-short-nameオプションをつけると、コマンド名をkctxとknsに変更できます。kubectlとの前方一致部分が減るのでシェルでの補完が少し楽になります。

kctx(kubectx)はContextの一覧表示と切り替え、削除、リネームが可能です。

$ kctx                        # パラメータ無しだとContext一覧を表示(有効なものは黄色で表示)$ kctx minikube-sentry        # 指定したContextに切り替え(Tabで補完が効く)$ kctx -                      # 一つ前のContextに戻る$ kctx -d minikube-sentry     # Contextを削除$ kctx sentry=minikube-sentry # minikube-sentry を sentry にリネーム$ kctx sentry=.               # 現在のContextを sentry にリネーム

kns(kubens)は現在のContextに対して、ネームスペースの一覧表示と切り替えが可能です。

$ kns         # ネームスペースの一覧表示(現在のネームスペースを黄色で表示)$ kns sentry  # 指定したネームスペースをデフォルトに変更(Tabで補完が効く)$ kns -       # 一つ前のネームスペースに変更

なお、kubectx(kctx)ではContextの作成や削除はできませんのでkubectlコマンドを使う必要があります。ただ、知っての通りminikubeの場合はminikube startの際に自動的にContextが作成されますし、GCPのGKEの場合も指定したGKEクラスタに接続するためのContextを作成する機能がgcloudコマンドに組み込まれています。

gcloud container clusters get-credentials | Cloud SDK | Google Cloud

minikubeやGKEを使っている限りではContextを作成したり編集したりする機会はそれほど多くないと思いますので、kctxとknsの使い方を覚えておけばほとんどの場合十分です。

Namespaceの削除について

helm installで--namespaceオプションを指定すると、当該ネームスペースがない場合は自動的に作成されます。このネームスペースはhelm deleteしても残ります。

ネームスペースを削除する場合にはkubectl deleteを使います。

$ kubectl delete namespace sentry# または$ kubectl delete ns sentry

ネームスペース内のオブジェクトが全て削除される点に注意してください。

永続ボリュームも確認無しで削除されるため、事故によるデータロストに十分注意する必要があります。PVオブジェクトが削除された場合に、データの実体(GCPのPersistentDiskやAWSのEBSなど)が削除されず残るようにするためには、StorageClassのreclaimPolicyをRetainに変更しておく必要があります。

Chartの作り方

前節では既存のパッケージを使う方法を見てきました。今節では自分でパッケージを作り、k8sクラスタにデプロイする方法を見ていきます。

具体的には、第2回で取り上げたサンプルアプリのHelm Chartを作成します。構成はStep4のマニフェストファイルと同等にします。

最終的なコードは下記に置いてあります。

k8s/chart/

なお、このドキュメントでは作ったHelm Chartをアプリのパッケージとして公開するというより、プライベートなアプリのk8sマニフェストをHelmで管理できるようにChart化する、という使い方を想定しています。

このような使い方においては、作成したChartをリポジトリサーバに登録する必要はなく、helmコマンドでローカルFS上のChartディレクトリを直接指定することでChartのデプロイを行うことができます。

helm upgrade –install: 作ったChartのデプロイ

サンプルコードのChartをデプロイしてみましょう。

もしもまだであれば、準備の節を参照して、サンプルコードのチェックアウトとminikubeの起動を済ませて置いてください。

次に、サンプルアプリのイメージをminikube上でビルドしておいてください。

$ cd rails-k8s-demoapp$ (eval $(minikube docker-env) && $ docker build . -t demoapp:0.0.1)

また、Step4と同じくIngressのTLS証明書用のSecretオブジェクトはkubectlコマンドで作成します。証明書と鍵の内容をChartのパラメータ化することも不可能ではないのですが煩雑なので、公式リポジトリのChartもSecretオブジェクトの名前だけをパラメータ化しているものが多いようです。今回はそれにならいます。

ちょっと手を抜いてMakefileを利用して作成します。手順はStep4の時と同じなので詳細は前回の記事を参照してください。

cd k8s/chart$ make kubectl-create-secret-tls

Tiller(Helmのサーバモジュール)のインストールがまだであれば下記を実行します。

$ helm init --wait

次に、helm upgradeコマンドでChartをminikubeにデプロイします。

$ helm upgrade staging . --install --wait \  --set ingress.host=demoapp-puma.$(minikube ip).nip.io

stagingはReleaseの名前です。--installオプションをつけると、Releaseが存在しない場合のみhelm installのような動作をするようになります。初回と2回目以降でコマンドを分けずに済むので便利です。

--setでは、ingress.hostというパラメータを指定しています。

最後にブラウザでWebアプリを開きます。

$ open https://demoapp-puma.$(minikube ip).nip.io/

Makefileに同様のタスクを定義しているので、下記のコマンドでも同じことができます。

$ make helm-init$ make minikube-docker-build$ make kubectl-create-secret-tls$ make helm-upgrade$ make open# または単に$ make

Releaseと証明書の削除は次のコマンドです。

make clean

helm template: テンプレートのレンダリング

Chartに含まれるテンプレートが最終的にどのようなYAMLデータになるかを事前に確認するには、helm templateコマンドを使います。

$ cd rails-k8s-demoapp/k8s/chart$ helm template . --name staging

上記のコマンドは、すべてのテンプレートにパラメータを埋め込んだ結果を表示します。

• .はChartディレクトリのパスです。stable/sentryのようにリポジトリのChartを指定することもできます。
• --nameオプションはReleaseの名前です。この他に、--setや-fでパラメータを指定することもできます。レンダリングの際はそれらの値を埋め込んだ結果が表示されます。

また、特定のテンプレートのみレンダリングしたい場合は-xオプションを指定します。

$ helm template . --name staging -x templates/puma-deploy.yaml

-xオプションの値は、カレントディレクトリからの相対パスではなく、Chartのルートディレクトリからの相対パスを指定する必要がある点に注意してください。

helm create: 新しいChartの作成

demoappという名前のChartを作るには下記のようにします。

$ cd rails-k8s-demoapp/k8s$ helm create demoapp

次のような構成のディレクトリが作られます。

demoapp/ Chart.yaml values.yaml charts/ templates/    NOTES.txt    _helpers.tpl    deployment.yaml    ingress.yaml    service.yaml

作成後、demoappディレクトリはリネームしても問題ありません。

• Chart.yamlには、Chartの名前やバージョンなどの情報が記述されます。
• values.yamlには、Chartのパラメータのデフォルト値が記述されます。
• charts/には、このChartが依存している別のChartを保存します。今回は扱いません。
• templates/には、次のファイルを保存します。
  • NOTES.txtは、Chartのインストール後に表示するメッセージです。
  • _helpers.tplには、テンプレート全般で再利用するための部分テンプレートを書きます。
  • 残りの*.yamlがマニフェストのテンプレートです。

helm createで作成した直後のChartは、DeploymentとServiceを一つずつ作成して、Ingress経由でそれを外部に公開するというk8sの基本構成が記述されています。なので、それらを一旦削除します。

rm demoapp/values.yaml demoapp/templates/*.yaml

次に、Step4のマニフェスト一式をdemoapp/templates/以下にコピーします。

cp manifests-step4/*.yaml demoapp/templates/

さて、これでおおよそ動くChartができました。Ingress以外はこのままでも動作します *1。demoapp/templates/に置くのはテンプレートなので、テンプレートとしての構文を一切使わないYAMLのままでもとりあえず動くのです。マニフェストファイルが存在するプロジェクトをHelm Chart化する場合には、このように一旦templates/ディレクトリに置いてから各マニフェストファイルをテンプレート構文で書き換えていくことになります。

そうやって作成したChartが下記のパスにあります。

k8s/chart/

次節以降では、このChartの中のテンプレートとStep4のマニフェストを比較しつつ、Chartの書き方を解説します。

*1: Ingressについては、ホスト名を示すパラメータが$(minikube ip)というコマンドで取得するまでわからないため、下記のように元々sedで${MINIKUBE_IP}を書き換えてからkubectl apply -f -に流し込む前提のマニフェストでした。Chart化する際には、テンプレートの機能を使ってパラメータとしてこのホスト名を指定できるようにします。

# k8s/manifests-step4/puma-ing.yaml---apiVersion: extensions/v1beta1kind: Ingressmetadata:  name: demoapp-puma  # 省略spec:  tls:  - hosts:    - demoapp-puma.${MINIKUBE_IP}.nip.io    secretName: demoapp-puma-tls  rules:  - host: demoapp-puma.${MINIKUBE_IP}.nip.io    # 省略

export MINIKUBE_IP=$(minikube ip)cat *.yaml | sed s/\${MINIKUBE_IP}/$(MINIKUBE_IP)/ | kubectl apply --record -f -

詳細な説明は 前回の記事を参照してください。

テンプレート

Helm Chartのテンプレート構文は、ほぼGo言語のtext/templateです。ただし、下記のように拡張されています。

• Sprigのtemplate functionが50個ほど使えるようになっています。
• ValuesやChart, Releaseなどの組み込みオブジェクトが追加されています。

はじめに、Step4時点でのpumaのDeploymentを例に、Chartのテンプレート化の勘所とテンプレート記法の基本を説明します。

元になるマニフェストは下記です。

# k8s/manifests-step4/puma-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-puma  labels:    app: demoapp    component: pumaspec:  replicas: 2  selector:    matchLabels:      app: demoapp      component: puma  template:    metadata:      labels:        app: demoapp        component: puma    spec:      restartPolicy: Always      containers:        - name: puma          image: demoapp:0.0.1          imagePullPolicy: IfNotPresent          command:            - ./bin/start-puma          livenessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          readinessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          envFrom:            - configMapRef:                name: demoapp-rails-env            - secretRef:                name: demoapp-rails-env

これをテンプレート化したものが下記です。

# k8s/chart/templates/puma-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: {{ template "demoapp.puma.name" . }}  labels:    app: {{ template "demoapp.name" . }}    chart: {{ template "demoapp.chart" . }}    release: {{ .Release.Name }}    heritage: {{ .Release.Service }}    component: pumaspec:  replicas: {{ .Values.puma.replicas }}  selector:    matchLabels:      app: {{ template "demoapp.name" . }}      release: {{ .Release.Name }}      component: puma  template:    metadata:      labels:        app: {{ template "demoapp.name" . }}        release: {{ .Release.Name }}        component: puma      annotations:        checksum/rails-env-cm: {{ include (print $.Template.BasePath "/rails-env-cm.yaml") . | sha256sum }}        checksum/rails-env-secret: {{ include (print $.Template.BasePath "/rails-env-secret.yaml") . | sha256sum }}    spec:      restartPolicy: Always      containers:        - name: puma          image: {{ .Values.rails.image.repository }}:{{ .Values.rails.image.tag }}          imagePullPolicy: IfNotPresent          command:            - ./bin/start-puma          livenessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          readinessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          envFrom:            - configMapRef:                name: {{ template "demoapp.rails-env.name" . }}            - secretRef:                name: {{ template "demoapp.rails-env.name" . }}

このようにテンプレートでは{{ }}の中にコード片を埋め込んでいきます。

いっぱい差分があるように見えますが、書き換えられているものは次の四つです。

• レプリカの数やイメージの名前など、パラメータ化されたもの
• オブジェクトの名前
• ラベル
• アノテーション

次節以降で、一つずつ詳細を見ていきます。

パラメータ化

Chart版のマニフェストでは、レプリカの数とイメージの名前がパラメータ化されています。Step4のマニフェストとChartのテンプレートから関連する部分だけを抜き出して比較します。

# before: k8s/manifests-step4/puma-deploy.yamlspec:  replicas: 2  template:    spec:      containers:        - name: puma          image: demoapp:0.0.1# after: k8s/chart/templates/puma-deploy.yamlspec:  replicas: {{ .Values.puma.replicas }}  template:    spec:      containers:        - name: puma          image: {{ .Values.rails.image.repository }}:{{ .Values.rails.image.tag }}

Valuesという組み込みオブジェクトの値を参照しています。これはChartの利用者側で任意に変更可能なパラメータを管理するオブジェクトです。パラメータのデフォルト値はChartディレクトリのvalues.yamlファイルに記述します。この値はhelm installまたはhelm upgradeの際に--setオプションや-fオプションで上書きすることができます。(詳細は前半のSentryのデモを参照してください)

サンプルコードのvalues.yamlから今回関連のある部分だけを以下に抜き出しています。

puma:  replicas: 2rails:  image:    repository: demoapp    tag: 0.0.1

このYAMLデータの中身を.Values.puma.replicasのように.区切りで指定することができます。

オブジェクトの名前

次に、オブジェクトの名前に関する部分だけを抜き出して比較します。

# before: k8s/manifests-step4/puma-deploy.yamlmetadata:  name: demoapp-pumaspec:  template:    spec:      containers:        - name: puma          envFrom:            - configMapRef:                name: demoapp-rails-env            - secretRef:                name: demoapp-rails-env# after: k8s/chart/templates/puma-deploy.yamlmetadata:  name: {{ template "demoapp.puma.name" . }}spec:  template:    spec:      containers:        - name: puma          envFrom:            - configMapRef:                name: {{ template "demoapp.rails-env.name" . }}            - secretRef:                name: {{ template "demoapp.rails-env.name" . }}

templateというのは、定義済みの部分テンプレートを呼び出すActionです。Helmの場合、templates/_helpers.tplでdefineにより定義した値を埋め込むことになります。この例では、demoapp.puma.nameという定義を参照しています。

以下、templates/_helpers.tplから関連のある部分だけ抜き出します。

{{/* k8s/chart/templates/_helpers.tpl */}}{{- define "demoapp.fullname" -}}{{- if .Values.fullnameOverride -}}{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}{{- else -}}{{- $name := default .Chart.Name .Values.nameOverride -}}{{- if contains $name .Release.Name -}}{{- .Release.Name | trunc 63 | trimSuffix "-" -}}{{- else -}}{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}{{- end -}}{{- end -}}{{- end -}}{{- define "demoapp.puma.name" -}}{{- include "demoapp.fullname" . -}}-puma{{- end -}}{{- define "demoapp.rails-env.name" -}}{{- include "demoapp.fullname" . -}}-rails-env{{- end -}}

demoapp.fullname、demoapp.puma.name, demoapp.rials-env.nameの三つのdefineがあります。前者はhelm createした時から存在するもので、残り二つは筆者が追加したものです。

結構ボリュームがあるのですが、ほとんどの状況では次のようなシンプルな結果になります。

• demoapp.fullnameは、Chart.yamlに書かれたnameフィールドの値にReleaseの名前をプレフィクスとしてつけた文字列を返します。サンプルの場合は、Releaseの名前がstagingならstaging-demoappになります。
• demoapp.puma.nameは、Releaseがstagingの場合はstaging-demoapp-pumaになります。includeは、define定義の中でさらに別の部分テンプレートを参照する時に使います。
• demoapp.rails-env.nameは、Releaseがstagingの場合はstaging-demoapp-rails-envになります。

つまりChart化した後のオブジェクト名には、元々のマニフェストでの名前であるdemoapp-pumaにプレフィクスとしてReleaseの名前をつけていることになります。Helm Chartでは、このようにオブジェクトの名前にReleaseの名前をプレフィクスとしてつけるのが慣例です。

なお、defineを追加せずdemoapp.fullnameだけを使って下記のように書くことも可能です。

metadata:  name: {{ template "demoapp.fullname" . }}-pumaspec:  template:    spec:      containers:        - name: puma          envFrom:            - configMapRef:                name: {{ template "demoapp.fullname" . }}-rails-env            - secretRef:                name: {{ template "demoapp.fullname" . }}-rails-env

公式のHelmチャートにはこのように書かれているものも多いですが、typoに気づきにくいという問題があるので、このサンプルでは前記のようにdefineして共通化しています。

ところで、template関数の呼び出しの際には名前を示す一つ目のパラメータの後ろに.がありますが、これはカレントスコープを渡していることを示しています。テンプレート定義の内部で.Valuesや.Releaseなどの組み込みオブジェクトを参照する場合には、呼び出し時にスコープを渡す必要がある点に注意してください。これはincludeも同様です。

SETTING THE SCOPE OF A TEMPLATE

ラベル

次に、ラベルに関連するところだけを抜き出して比較します。

# before: k8s/manifests-step4/puma-deploy.yamlmetadata:  labels:    app: demoapp    component: pumaspec:  selector:    matchLabels:      app: demoapp      component: puma# after: k8s/chart/templates/puma-deploy.yamlmetadata:  labels:    app: {{ template "demoapp.name" . }}    chart: {{ template "demoapp.chart" . }}    release: {{ .Release.Name }}    heritage: {{ .Release.Service }}    component: pumaspec:  selector:    matchLabels:      app: {{ template "demoapp.name" . }}      release: {{ .Release.Name }}      component: puma

元々appとcomponentだったところに、chart、release、heritageが追加されています。これらのラベルは、Helmの公式ドキュメントでBest Practiceのページに標準的なラベルとして定義されているものです。

STANDARD LABELS - Chart Best Practices

chartはChartの名前、releaseはReleaseの名前を示すラベルです。heritageは常にTillerという文字列になります。これはこのオブジェクトがHelm(Tiller)によって管理されているということを示します。

releaseのみ、.spec.selector.matchLabelsにも追加されている点に注意してください。これは同一のChartが同じNamespace内に複数のReleaseとしてデプロイされた場合に、適切に分離されるために必要です。chartとheritageは動作に直接影響しませんが、慣例として推奨されているラベルです。

アノテーション

最後にアノテーションについて説明します。

下記のように、マニフェストにはなかった.spec.template.metadata.annotationsエントリがテンプレートには追加されています。

# after: k8s/chart/templates/puma-deploy.yamlspec:  template:    metadata:      annotations:        checksum/rails-env-cm: {{ include (print $.Template.BasePath "/rails-env-cm.yaml") . | sha256sum }}        checksum/rails-env-secret: {{ include (print $.Template.BasePath "/rails-env-secret.yaml") . | sha256sum }}

アノテーションは、オブジェクトの識別以外に使われるメタ情報です(識別に使うのはラベル)。ラベルと同様にKey-Value形式の構造で、通常はビルドやリリースに関する情報やモニタリングのための情報などを記録します。

ところで、ConfigMapまたはSecretから環境変数などの設定情報を参照しているDeploymentには、運用上少し面倒な制限があります。それは、ConfigMapやSecretの内容を更新したとしても、それを参照するDeploymentはローリングアップデートされるわけではないということです。

一方、Deploymentはこのアノテーションが更新された場合もローリングリスタートが行われます。そこでそれを利用して、ConfigMapまたはSecretの更新後にkubectl patchコマンドなどを用いてアノテーションを更新することで強制的にローリングリスタートをかけるというテクニックが知られています。

kubectl patch deploy demoapp-puma -p \  "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"config-updated-at\":\"`date +'%s'`\"}}}}}"

Helmでテンプレート使う場合には、先に挙げた例のようにConfigMapおよびSecretのマニフェストのダイジェストをアノテーションに含めることで、これらの設定オブジェクトの内容が変わったときに自動的にローリングリスタートがかかるようにできます。このダイジェスト計算はレンダリング後のマニフェストに対して行われるため、例えばrails-env-cm.yamlに全く変更が無い場合でも、values.yamlを編集するなどしてrails-env-cm.yaml内部で参照しているValuesの値が変わればDeploymentはリスタートされます。

Automatically Roll Deployments When ConfigMaps or Secrets change

同様のアノテーションをsidekiq-deploy.yamlにも追加しています。なお、mysql-deploy.yamlでもConfigMapとSecretを参照していますが、こちらは初回起動時に作成するDBやユーザなどの情報が主で運用中に変更することを想定していないため、アノテーションは追加していません。

関数とパイプライン

関数とパイプラインを使いこなすことでテンプレートはより便利になります。

Secretオブジェクトの定義では、データの値を次に示すようにBASE64エンコードして記述する必要がありました。

# k8s/manifests-step4/rails-env-secret.yaml---apiVersion: v1kind: Secretmetadata:  name: demoapp-rails-envdata:  SECRET_KEY_BASE: MTIz    # echo -n "123" | base64  MYSQL_PASSWORD: c2VjcmV0 # echo -n "secret" | base64

いちいちエンコードしてからファイルに記述するのは面倒です。

Helmのテンプレートでは先に述べたようにSprigの関数が組み込まれているため、b64encという関数を使って次のようにSecretを定義することができます。

# k8s/chart/templates/rails-env-secret.yaml---apiVersion: v1kind: Secretmetadata:  name: {{ template "demoapp.rails-env.name" . }}data:  SECRET_KEY_BASE: {{ .Values.env.secret.SECRET_KEY_BASE | b64enc }}  MYSQL_PASSWORD: {{ .Values.env.secret.MYSQL_PASSWORD | b64enc }}

# k8s/chart/values.yamlenv:  secret:    MYSQL_PASSWORD: secret    SECRET_KEY_BASE: "123"

{{ }}の中身はパイプラインであり、| 演算子を使って別の関数のパラメータとすることができます。関数が二つ以上のパラメータをとる場合、|の後ろの関数には最後のパラメータとして|の前の結果が渡されます。

比較的よく使われる関数にdefaultとquoteがあります。これを使った例を一つ見てみましょう。

{{ .Values.rails.testValue | default "abc" | b64enc | quote }}

defaultは、二つ目のパラメータが空の場合は一つ目の値を、空でない場合は二つ目の値を返す関数です。quoteは、パラメータの前後に"をつけた文字列を返す関数です。上記の例では、.Values.rails.testValueをBASE64エンコードして"で囲むという処理です。.Values.rails.testValueが空だった場合はabcという文字列を代わりにエンコードしてクォートします。

フロー制御

今回のサンプルでは特に使っていないのですが、テンプレートではif/elseによる分岐やrangeによるループを使用できます。

Flow Control

stable/sentryのingress.yamlが参考になると思います。

https://github.com/kubernetes/charts/blob/master/stable/sentry/templates/ingress.yaml

values.yaml

ここではvalues.yamlについて説明します。サンプルコードのvalues.yamlは次のような内容です。

mysql:  image:    repository: mysql    tag: 5.7.21  storage:    size: 8Gi    className: standardredis:  image:    repository: redis    tag: 4.0.9  storage:    size: 8Gi    className: standardpuma:  replicas: 2sidekiq:  replicas: 1  timeout: 60rails:  image:    repository: demoapp    tag: 0.0.1    setupDbTag: 0.0.1ingress:  tlsSecretName: demoapp-puma-tls  # required from --set parameter  # helm upgrade release-name . --set ingress.host=demoapp-puma.${MINIKUBE_IP}.nip.io  # host: demoapp-puma.${MINIKUBE_IP}.nip.ioenv:  configmap:    MYSQL_USER: demoapp    MYSQL_DATABASE: demoapp_production    RAILS_SERVE_STATIC_FILES: "true"    RAILS_LOG_TO_STDOUT: "true"  secret:    MYSQL_PASSWORD: secret    MYSQL_ROOT_PASSWORD: topsecret    SECRET_KEY_BASE: "123"

注意が必要なのは下記の点です。

• Jobオブジェクトで参照するイメージのタグはDeploymentと分ける必要があります。具体的には.rails.image.tagと.rails.image.setupDbTagです。Jobのイメージは変更不可なので、分けておかないとアプリを更新できなくなります。
• 秘匿情報は集約しておく方が管理が楽です。この例では.env.secretの下にまとめています。こうしておくとsopsやyaml_vaultでファイルの一部だけ暗号化するのが簡単になります。これについては次節で詳細を説明します。

参考:

• Values Files
• Values - Best Practices

values.yamlに含まれる秘密情報の暗号化

先の例では、DBのパスワードやRailsのSECRET_KEY_BASEなどの秘密情報がvalues.yamlに平文で書き込まれていました。プライベートなアプリの場合でも、こういった秘密情報は平文のままでリポジトリにコミットするべきではありません。

ここでは、YAMLファイルを暗号化する方法を二つ紹介します。

GCP KMSの準備

紹介する方法は、いずれもGCP KMSまたはAWS KMSで暗号鍵を管理できます。今回はGCP KMSを使う方法を紹介します。

Cloud SDKをインストールした後、適当なプロジェクトを作成しください。その後、下記のコマンドを実行して鍵を作成してください。

# ログイン$ gcloud auth login# キーリングの作成$ gcloud kms keyrings create demoapp --location global# キーの作成$ gcloud kms keys create values-key --location global --keyring demoapp --purpose encryption# 作成したキーの確認$ gcloud kms keys list --location global --keyring demoappNAME                                                                                PURPOSE          LABELS  PRIMARY_ID  PRIMARY_STATEprojects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key  ENCRYPT_DECRYPT          1           ENABLED

この例では、プロジェクトIDはrails-k8s-demoappです。各自の環境に合わせて読み替えてください。

途中、下記のようなメッセージが出た場合は、ブラウザでリンクを開いてKMSを有効化してください。

ERROR: (gcloud.kms.keyrings.create) FAILED_PRECONDITION: Google Cloud KMS API has not been used in this project before, or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview?project=123456789012 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.

使い終わった鍵は忘れずに破棄しておいてください。使っていなくても費用が発生します。

https://cloud.google.com/kms/pricing?hl=ja

また、下記のページを参照してサービスアカウントキーを作成してください。

https://cloud.google.com/docs/authentication/getting-started

役割は、Cloud KMS - クラウドKMS暗号鍵の暗号化/復号化を選択します。JSON形式でダウンロードした鍵を kms-key.jsonという名前で保存してください。

yaml_vault

yaml_vaultはruby製の暗号化ツールです。AWS KMSまたはGCP KMSで暗号鍵を管理することができます。

gemでインストールできます。GCP KMSを使う場合は、google-api-clientも必要です。

$ gem install yaml_vault google-api-client

Gemfileに追加しても良いですが、そのままだとDockerイメージのサイズが50MBほど増えるため、少し工夫が必要です。

下記のコマンドを実行すると、values.yamlを暗号化してencrypted_values.yamlに出力します。その際、暗号化するキーを--keyオプションで限定している点に注目してください。このオプションを指定しない場合、YAMLの全ての値が暗号化されます。

$ yaml_vault encrypt values.yaml -o encrypted_values.yaml --cryptor=gcp-kms \  --gcp-kms-resource-id=projects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key \  --gcp-credential-file=kms-key.json \  --key '$.env.secret'encrypted values.yaml -> encrypted_values.yaml

暗号化されたファイルは次のような内容になります。

# encrypted_values.yamlmysql:  image:    repository: mysql    tag: 5.7.21  storage:    size: 8Gi    className: standardredis:  image:    repository: redis    tag: 4.0.9  storage:    size: 8Gi    className: standardpuma:  replicas: 2sidekiq:  replicas: 1  timeout: 60rails:  image:    repository: demoapp    tag: 0.0.1    setupDbTag: 0.0.1ingress:  tlsSecretName: demoapp-puma-tlsenv:  configmap:    MYSQL_USER: demoapp    MYSQL_DATABASE: demoapp_production    RAILS_SERVE_STATIC_FILES: "true"    RAILS_LOG_TO_STDOUT: "true"  secret:    MYSQL_PASSWORD: CiQA/TkaHXJd4HsdRnMTJ9tgso7tYdCbIJxuWbGgj5UJfpkbI+gSOADQcvdxFdICOfR8oiQa1GOM9UX0koe0AC9TM5C+fpV1nRuaajJGAF0IfFRf9KtKKHyz/Qp4ad3E    MYSQL_ROOT_PASSWORD: CiQA/TkaHbi65E4QSHRKwpxRQcD43rMwo4rr9aUgAj8ezPjgtGcSOwDQcvdxaMRAJ+yE87zeGDIBCbeZVzyZMXAg83Odxj2y9fbL4NELzViD5bqx8XoxWe0Y7nhWYJomNpmC    SECRET_KEY_BASE: "CiQA/TkaHfsk/7i7IrlJVhheCPifd0bCvho9CJgRbiR10lnqc1oSMgDQcvdxijXncXs0gYuMfk9/IdeSiL8fApLEDd6zISmgnmZh3d7KxNioeliHZcWApaai"

復号するときは次のようにします。

$ yaml_vault decrypt encrypted_values.yaml -o values.yaml --cryptor=gcp-kms \  --gcp-kms-resource-id=projects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key \  --gcp-credential-file=kms-key.json \  --key '$.env.secret'

yaml_vaultを使って運用する場合には、values.yamlはコミットせず、暗号文のencrypted_values.yamlをコミットして運用します。

なお、暗号化を行う際には、元の平文に変更がなかったとしても毎回暗号文の部分は値が変わってしまう点に注意が必要です。

sops

sopsはmozilla製の暗号化ツールです。

使用するためには、まずGCPの鍵を環境変数で指定する必要があります。

$ export GOOGLE_APPLICATION_CREDENTIALS=kms-key.json

暗号化は下記のように行います。

$ sops --encrypt --gcp-kms projects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key values.yaml > encrypted_values.yaml

ファイル全体が下記のように暗号化されます。

mysql:    image:        repository: ENC[AES256_GCM,data:eD0o4pw=,iv:3DbUfobOeqAL0kowEKVqbMjtEC88J9/nMysGdMf4nqk=,tag:wEwatUbf9v1/LVPLYkunPA==,type:str]        tag: ENC[AES256_GCM,data:PgWECj+7,iv:UlUPjWbxO+lW6bAm/2F5JTfAbbWa3/wCjyOIyGmEG7I=,tag:vPmfEGQkKKxE7nsJsZfYZA==,type:str]    storage:        size: ENC[AES256_GCM,data:Zn9a,iv:OaFk2rRTiNB3doRZBo5SvL/7j5G1PLKA0H7mBXpa/Ew=,tag:04A9OIJgYlXWOwk35kPHqg==,type:str]        className: ENC[AES256_GCM,data:k4J42uu3fiE=,iv:YrXlk57NgadQg9VQaTbTjo8E5nT5XWZXz6UvNXiSO6E=,tag:hCOuXuQBY3rSxzsY4sx+0A==,type:str]redis:    image:        repository: ENC[AES256_GCM,data:wjqwX64=,iv:hqxguyQImpZFgGz83CyQhfi/tGZbIefTHbpXMiMuL3w=,tag:Y5kdJOxdH4R2HMrYeFv5xA==,type:str]        tag: ENC[AES256_GCM,data:tCM+YHQ=,iv:owoFufImNd81KqP5XVvEdA+3ZHpZMYp1Q56pHm7lW/o=,tag:VuiJh+zPegQvjfMMySRWTA==,type:str]    storage:        size: ENC[AES256_GCM,data:g5n2,iv:AVbPlOkfrBFq9UzuILE6fgt6Xww6311KbyFhXHnpiAk=,tag:S+xMDWCQ3XlT7PCQlB4kiw==,type:str]        className: ENC[AES256_GCM,data:yrqW0RSihnc=,iv:O9wpDqHd3zYNdoS8VJI1y2giLnSByaGAvGrDMrF8ba8=,tag:hmE475vdibBfUc8R21AMzg==,type:str]puma:    replicas: ENC[AES256_GCM,data:oA==,iv:RkUoYXEivf5vzDrWBD7kWaGtyr1k4lApn1T0qWA67K0=,tag:Z4fPAiGEtfuxxaqQM2nXQw==,type:int]sidekiq:    replicas: ENC[AES256_GCM,data:QQ==,iv:NWZPcXVz7tcuXIRftmacJ2SegYfDgh/iwS82ovlYeNA=,tag:J2WSY3vjOkJcNvIJrLFy7w==,type:int]    timeout: ENC[AES256_GCM,data:G5s=,iv:t/866qY7jTnGSRUQAhgXWEw9lcdtHll8fYIQsyARo4A=,tag:yZ2cIFXdJO2xis4B9mzWSA==,type:int]rails:    image:        repository: ENC[AES256_GCM,data:x4dh5BigFg==,iv:C7jm5zl6rr7PeLwgX2i73Yo1yKWp+lv3eA0zCJipuk4=,tag:2FhxjAmnnIYVTsN6WkFoBQ==,type:str]        tag: ENC[AES256_GCM,data:WaWw06E=,iv:S8Tx8rQPfzfk00of3HiNJVJYM3qeNQKNxxyHYyvTAFM=,tag:74upYPpg3fMoEya9YFTVog==,type:str]        setupDbTag: ENC[AES256_GCM,data:zFo1gJ0=,iv:+P0F1hH5TagxLLe7yqCMAfoLtEsu+s5lLV7WKDJFp7s=,tag:T/Bix+hd1DZBIhA634mVrQ==,type:str]ingress:    tlsSecretName: ENC[AES256_GCM,data:sJcZXlktHsdfsYm6BbkGQg==,iv:J+bmgm2qC0wIMSDzXec9xsujOl3kjfFVUv+qmk3FWhs=,tag:qyecdT2dDvsPI+rAGe9+oA==,type:str]    #ENC[AES256_GCM,data:H0TCFT5qkWAfK6E+j9sSjudYmCVAKckB7CQxgwbH,iv:kl625mCSUA/NNV35CU+xez9GOFggKnDm5nXYJ9waVMU=,tag:AKdSsCJNcfdC+I3nvXhStw==,type:comment]    #ENC[AES256_GCM,data:cGNTwdT+KF0CoUCmNVwLxyvUqNozAZvz0xDWzoEB/qElfEMVRSqdPXMjMjsjEy1Apm0WOBfp5HFgZUFW16Q+vucAhgeFAn0mM7WhADNjKZGZUw==,iv:sMn+N9nHPbWB0Raps0559jxHKDMeo98CfnUIjIvTFjU=,tag:bR8mdcFEf2ZaJ2IdKHp9xg==,type:comment]    #ENC[AES256_GCM,data:cl97jwOSlNZmfBAK+GjtzUZgqyABB9bXUN0J+xeFQpc5I3V3Ez2Olrc=,iv:jcrqo86rp+SVSB+lKLee/YdEz+8IfnULzYA+A0vj+SA=,tag:tqSfgPe//SlU0GJSog0PcQ==,type:comment]env:    configmap:        MYSQL_USER: ENC[AES256_GCM,data:ckkEsrePZg==,iv:ssnCPFBqnihIe5c9T79EJlA2vGWsihOI53RL1SwdklA=,tag:ewyXNB6S6Kd25FIcSGtF4w==,type:str]        MYSQL_DATABASE: ENC[AES256_GCM,data:LmgD+B0MF2jaHXiLAbL57UdT,iv:0eivT7Dkkso4zcvbekb0Li5CBGEn4TcaAFzcC7QtvTs=,tag:/k2xCsM+BKkPF540QZNRqA==,type:str]        RAILS_SERVE_STATIC_FILES: ENC[AES256_GCM,data:B7YMSg==,iv:XM6zzCChuIPUUYmOog/XvbaC88j+AZtNcfps2/e/2h0=,tag:AK9aHDYW2WaBTITLQuBA6Q==,type:str]        RAILS_LOG_TO_STDOUT: ENC[AES256_GCM,data:HV9B/Q==,iv:mSKjUGQSmCXKcCutSmjnenb3lVzVHWEKrTa+N+nBexY=,tag:4bYviLxwkVCZgjjNZ3cvFQ==,type:str]    secret:        MYSQL_PASSWORD: ENC[AES256_GCM,data:aRQsAyGK,iv:tjhn1oDqbp83vNartgIL4S8SgveNLUL91gjUzSCBuNo=,tag:1PtcSk8gt0XBuboZzE93pQ==,type:str]        MYSQL_ROOT_PASSWORD: ENC[AES256_GCM,data:QgUKdkPZ3URM,iv:iQl52u3fruHtoBh6uLCJ0ArzvLHbw7XbNVQcKuBbaVs=,tag:u/V3k0D15Ne0TQLfRcTF/g==,type:str]        SECRET_KEY_BASE: ENC[AES256_GCM,data:0Bsu,iv:1MfHBuEa2fF84H+IJXHeufBWH+dJWGEE4zJqts3EJrw=,tag:VAgJgAS+xlgAKnPeff1eHA==,type:str]sops:    kms: []    gcp_kms:    -   resource_id: projects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key        created_at: '2018-05-28T14:55:44Z'        enc: CiQA/TkaHVv9JRDpzqLYXfGD8QDW92/4xSZhMcuao5VlStYzBAwSSQDQcvdxZjXWoG1h8nEbj9o1TNWvdSlz5rxY/l9WEd/WieUiORJLVxI+MCsZ764vUksSk9jrmPxnLqlrfKy/Klz/6yKGi3pyx/g=    lastmodified: '2018-05-28T14:55:45Z'    mac: ENC[AES256_GCM,data:zoHHamGXApQLsCJSxYuuVkYFo8xAROv+ier9wZYEpn2jDu9vwDZObwEb52Ewx4UTEJphq4KWi/DKodcUZHfyhWIEjqpwwUxqlIXlWmq1AO5XERa/XS0egi6gK3VnKYHsxbRSKF/hY/DOS6bO5A6Fnh0lBfENUZ8qStt5gKtwPOE=,iv:FK4V/TOHJ6cY3mPk4rlrgrSWm8s+HFazY+62d8Cck58=,tag:HkgWUGc4O4rcHZ1jDY+viQ==,type:str]    pgp: []    unencrypted_suffix: _unencrypted    version: 3.0.5

このファイルを編集するときは、下記のように直接sopsコマンドで指定します。

$ sops encrypted_values.yaml

するとファイルの内容が復号され、環境変数EDITORで指定したエディタ上で編集可能になります。保存してエディタを閉じると再び暗号化された状態で保存されます。

$ sops --decrypt --gcp-kms projects/rails-k8s-demoapp/locations/global/keyRings/demoapp/cryptoKeys/values-key encrypted_values.yaml > values.yaml

sopsもyaml_vaultのようにファイルの一部分だけを暗号化することもできますが、「YAMLデータのキーにサフィックスをつけて指定した部分だけを平文にする」という仕組みであり、values.yamlの構造に直接影響を与える方法なので使いにくいです。

Encrypting only part of a file

sopsを使う場合、values.yamlには秘密情報を以外の値だけを書くようにし、secret-values.yamlに秘密情報を全て取り出して、常に-fオプションでsecret-values.yamlも指定するという方法が良いと思います。

Subchart

Helm Chartでは、他のChartをSubchartとして使用することができます。

Subcharts and Global Values

例えばstable/sentryパッケージはstable/postgresとstable/redisをSubchartとして使用しており、PostgreSQLとRedisのセットアップはこれらのChartに依存しています。

今回、rails-k8s-demoappのChartではあえてstable/mysqlとstable/redisを使わずに自前でテンプレートを用意しました。この理由は公式のChartと言えどまだ枯れているとは言えないと判断したためです。

例えばstable/redisではパスワードを示すパラメータの名前が途中で変わっており、stable/sentryの現時点での最新版(0.1.14)は古いバージョンのstable/redis(0.10.1)に依存しています。そのため最新のstable/redisのドキュメントを見て設定してしまうと動きません。(バージョンを指定してドキュメントを見られるようなサービスもありません)

また、当然Valuesで変更できる部分以外の動作は変更できなくなるため、Chart側で十分な柔軟性が確保されていない場合には、自分のアプリケーションの要件を満たせないあるいは途中で満たせなくなる可能性があります。

このあたりはChefの(特に初期の)コミュニティクックブックに状況が似ていると思います。

公式のChartとして公開することを目指すのであればできるだけ他のChartを利用するべきだと思いますが、そうでない場合には無理に依存を増やす必要はありません。公式のChartは汎用性を高めるために多機能なものが多く、全貌を把握すること自体がコストになるケースもあります。簡単なものなら自作した方がトータルでは楽なことも多いです。

また、Subchartまで完全に自分でコントロール可能な場合はChartの分割を検討しても良いと思いますが、多くのChartに依存されたChartは更新が難しくなるので、そこはトレードオフになります。

まとめ

この節では、プライベートなアプリのHelm Chartの作り方に関して、k8sのプレーンなマニフェストをどのようにテンプレート化するかについて、puma-deploy.yamlを例に説明しました。

その他のオブジェクトのマニフェストについてもだいたい同じような手順でテンプレート化できるため、それらについての詳細な説明は割愛します。コードを見てみてください。

k8s/chart/

自作のChartによるワークフロー

以下についてはすでに説明しました。

• helm create: 新しいChartの作成
• helm template: テンプレートのレンダリング
• helm upgrade –install: 作ったChartのデプロイ

この節では、アプリケーションを運用する上でさらに必要になるであろういくつかのオペレーションを説明します。

helm upgrade: Chartの更新を反映

コマンド自体は初回デプロイと同じhelm upgradeを使いますが、アプリケーションを更新する場合には次のいずれかの方法でDeploymentのイメージを変更する必要があります。

1. --setオプションでrails.image.tagを変更する。

この場合、次のように新しいタグを指定して実行します。

$ helm upgrade staging . --install --wait \  --set ingress.host=demoapp-puma.$(minikube ip).nip.io \  --set rails.image.tag=0.0.2

2. values.yamlファイルの.rails.image.tagとChart.yamlのバージョン情報を書き換えてhelm upgradeを実行する。

差分は典型的には下記のようになります。

diff --git a/k8s/chart/Chart.yaml b/k8s/chart/Chart.yamlindex 43907c6..a6283b0 100644--- a/k8s/chart/Chart.yaml+++ b/k8s/chart/Chart.yaml@@ -1,5 +1,5 @@ apiVersion: v1-appVersion: "0.0.1"+appVersion: "0.0.2" description: A Helm chart for Kubernetes name: demoapp-version: 0.0.1+version: 0.0.2diff --git a/k8s/chart/values.yaml b/k8s/chart/values.yamlindex 3f6eea1..96610f8 100644--- a/k8s/chart/values.yaml+++ b/k8s/chart/values.yaml@@ -24,7 +24,7 @@ sidekiq: rails:   image:     repository: demoapp-    tag: 0.0.1+    tag: 0.0.2     setupDbTag: 0.0.1 ingress:

ファイルを書き換えたら、初回デプロイと全く同じコマンドを実行します。

$ helm upgrade staging . --install --wait \  --set ingress.host=demoapp-puma.$(minikube ip).nip.io

簡単なのは1の方法ですが、現在デプロイされているイメージの情報がgit側に残らないというデメリットがあります。

長期的には2の方法がおすすめです。Chart.yamlのversionも更新しておくと、後に紹介するhelm historyとgitのログでインフラ構成の履歴を追うのが楽になります。

helm upgrade

helm history: Releaseの履歴を表示

指定したReleaseの更新履歴を表示します。

$ helm history stagingREVISION        UPDATED                         STATUS          CHART           DESCRIPTION1               Mon May 28 00:01:37 2018        SUPERSEDED      demoapp-0.0.1   Install complete2               Mon May 28 00:07:00 2018        DEPLOYED        demoapp-0.0.2   Upgrade complete

REVISIONは、そのReleaseの現在のバージョンを示す数値で、1から始まりhelm upgradeするたびに1ずつ増えていきます。

helm history

helm rollback: Releaseを前のリビジョンに戻す

Releaseの状態を指定したリビジョンに戻します。

$ helm rollback staging 1Rollback was a success! Happy Helming!$ helm history stagingREVISION        UPDATED                         STATUS          CHART           DESCRIPTION1               Mon May 28 00:01:37 2018        SUPERSEDED      demoapp-0.0.1   Install complete2               Mon May 28 00:07:00 2018        SUPERSEDED      demoapp-0.0.2   Upgrade complete3               Mon May 28 00:10:31 2018        DEPLOYED        demoapp-0.0.1   Rollback to 1

helm rollback

helm get: Releaseの詳細を表示

指定したReleaseに関する下記の情報を表示することができます。

• Chartの名称やデプロイ日時などの基本情報
• values.yamlと--setや-fオプションなどの値をマージした最終的なValuesオブジェクト
• 全テンプレートのレンダリング済みマニフェスト

$ helm get stagingREVISION: 1RELEASED: Mon May 28 00:01:37 2018CHART: demoapp-0.0.1USER-SUPPLIED VALUES:ingress:  host: demoapp-puma.192.168.64.29.nip.ioCOMPUTED VALUES:env:  configmap:    MYSQL_DATABASE: demoapp_production    MYSQL_USER: demoapp    RAILS_LOG_TO_STDOUT: "true"    RAILS_SERVE_STATIC_FILES: "true"(省略)HOOKS:MANIFEST:---# Source: demoapp/templates/mysql-env-secret.yamlapiVersion: v1kind: Secretmetadata:  name: staging-demoapp-mysql-envdata:  MYSQL_PASSWORD: c2VjcmV0  MYSQL_ROOT_PASSWORD: dG9wc2VjcmV0(省略)

helm get

helm diff: Chartの差分を表示

helmコマンドはプラグイン機構により拡張することが可能です。

利用可能なプラグインは下記のページに掲載されています。

HELM PLUGINS

ここではプラグインの一つHelm Diffを紹介します。

helm pluginコマンドでインストールできます。

$ helm plugin install https://github.com/databus23/helm-diff

helm diffコマンドを使うと、helm upgradeにより発生する差分をdiff形式で表示することができます。

% helm diff upgrade staging . --set ingress.host=demoapp-puma.$(minikube ip).nip.io --set rails.image.tag=0.0.2staging-demoapp-sidekiq, Deployment (apps/v1) has changed:  # Source: demoapp/templates/sidekiq-deploy.yaml  apiVersion: apps/v1  kind: Deployment(省略)-           image: demoapp:0.0.1+           image: demoapp:0.0.2(省略)staging-demoapp-puma, Deployment (apps/v1) has changed:  # Source: demoapp/templates/puma-deploy.yaml  apiVersion: apps/v1  kind: Deployment(省略)-           image: demoapp:0.0.1+           image: demoapp:0.0.2(省略)

また、helm rollbackで発生する差分や、過去のリビジョン同士の差分を表示することもできます。詳細はHelm Diffのドキュメントを参照してください。

$ helm diff -h

おわりに

Railsアプリ開発のためのDocker/Kubernetes入門を主題として、Docker/Kubernetesの基本と、小さなRailsアプリケーションをHelmでk8sクラスタにデプロイする方法について書きました。

Docker/Kubernetesを本番サービスへ投入するのであれば、さらに下記について学ぶと良いと思います。

• GCPやAWSのようなパブリッククラウドでk8sを使う方法(GKEやkops)
• ロールベースのアクセス制御(Using RBAC Authorization)
• k8sクラスタ自体やその上で稼働するアプリケーションのリソース監視(Prometheusとの統合など)
• Dockerイメージのさらなるスリム化の手法
• Podをどのノードに配置するかを制御する方法(Assigning Pods to Nodes、Taints and Tolerations)
• Podに割り当てるCPUやメモリなどの計算資源を制御する方法(Managing Compute Resources for Containers)
• 負荷に応じて動的にPodの数を増減させる方法(Horizontal Pod Autoscaler)

クラウドを使うならGKEが簡単でおすすめですが、GKEでHelmを使おうとするとRBACが最初のハードルになると思います。次回はその辺りについて書きたいと思います。

• 第一回 Docker編
• 第二回 Docker Compose/Dockerfile編
• 第三回 Kubernetes入門編
• 第四回 Kubernetes基礎編
• 第五回 Kubernetes応用編
• 第六回 Helm編

前回のKubernetes基礎編では、Step1として第2回Docker Compose/Dockerfile編のdocker-compose-preview.ymlに相当する構成をDeployment, Service, ConfigMap, Secretの4種のAPIオブジェクトで記述しました。マニフェストファイル一式はサンプルコードの k8s/manifests-step1/ ディレクトリにあります。

この構成には下記に挙げる三つの制約があります。

• pumaコンテナを複数起動するとrails db:setupが並列実行されてエラーになる。
• MySQLやRedisのデータが永続化されていないため、コンテナを停止するとデータも消える。
• pumaに外部からアクセスするためのエンドポイントを本番環境で運用するのが難しい。

今回はこれらの制約をStep2からStep4で解消していきます。

サンプルコードは全て下記のリポジトリにあります。

https://github.com/kwhrtsk/rails-k8s-demoapp

前提

• macOSでの作業を前提としています。
• 使用したツールのバージョンなどは 初回 の記事を参照してください。
• ツールのインストール手順は 第三回 の記事を参照してください。

準備

まずサンプルアプリのコードをチェックアウトしてminikubeを起動してください。(前回と同じなのですでにやっている人は読み飛ばしてください)

# サンプルアプリのコードをチェックアウト$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp# minikubeを起動$ minikube start --cpus=3 --memory=2048 --vm-driver=hyperkit --disk-size=12g# kubernetesのダッシュボードをオープン$ minikube dashboard

Step2: Job

サンプルコードは全て下記のディレクトリにあります。

k8s/manifests-step2/

Step1の構成ではpumaのレプリカの数を1に指定していましたが、一定以上の性能を出そうとするとレプリカの数は2以上に設定する必要があります。ところが、このままの構成でpumaコンテナを複数起動すると、rails db:setupが並列実行されてエラーが発生します。

次のような手順でこれを確認できます。

まずpuma-deploy.yamlを書き換えてreplicasを2にします。

diff --git a/k8s/manifests-step1/puma-deploy.yaml b/k8s/manifests-step1/puma-deploy.yamlindex 003f484..c17f9bb 100644--- a/k8s/manifests-step1/puma-deploy.yaml+++ b/k8s/manifests-step1/puma-deploy.yaml@@ -7,7 +7,7 @@ metadata:     app: demoapp     component: puma spec:-  replicas: 1+  replicas: 2   selector:     matchLabels:       app: demoapp

次にsternでログを監視しつつ、別の端末でkubectl applyを実行し、APIオブジェクトを作成します。

$ cd k8s/manifests-step1# デプロイ済みのオブジェクトがある場合は削除$ cat *.yaml | kubectl delete -f -# ログを監視$ stern "demoapp.*"# 別の端末で実行$ cat *.yaml | kubectl apply -f -

タイミング依存なのでエラーが発生しない場合もありますが、それなりの確率で下記のようなエラーがsternの端末上に表示されるはずです。

demoapp-puma-749c456c87-2wk5c puma + ./bin/wait-for demoapp-redis 6379demoapp-puma-749c456c87-2wk5c puma + ./bin/rails db:setup_if_not_yetdemoapp-puma-749c456c87-lwwb7 puma + ./bin/wait-for demoapp-redis 6379demoapp-puma-749c456c87-lwwb7 puma + ./bin/rails db:setup_if_not_yetdemoapp-puma-749c456c87-lwwb7 puma Database 'demoapp_production' already existsdemoapp-puma-749c456c87-2wk5c puma Database 'demoapp_production' already existsdemoapp-puma-749c456c87-lwwb7 puma -- create_table("messages", {:options=>"ENGINE=InnoDB DEFAULT CHARSET=utf8", :force=>:cascade})demoapp-puma-749c456c87-2wk5c puma -- create_table("messages", {:options=>"ENGINE=InnoDB DEFAULT CHARSET=utf8", :force=>:cascade})demoapp-puma-749c456c87-lwwb7 puma    -> 0.0505sdemoapp-puma-749c456c87-2wk5c puma    -> 0.0925sdemoapp-puma-749c456c87-2wk5c puma rails aborted!demoapp-puma-749c456c87-2wk5c puma ActiveRecord::RecordNotUnique: Mysql2::Error: Duplicate entry '20180411125010' for key 'PRIMARY': INSERT INTO `schema_migrations` (version) VALUES (20180411125010)

2つのpuma用のPodがほぼ同じタイミングで./bin/rails db:setup_if_not_yetを実行していることがわかります。このRakeタスクは第二回 Docker Compose/Dockerfile編で説明しましたが、下記のような内容です。

# lib/tasks/db.rakenamespace :db do  desc "Invoke db:setup task only if the task has never been invoked yet."  task setup_if_not_yet: [:environment] do    begin      if !ActiveRecord::SchemaMigration.table_exists?        # データベースは存在するが、必ずあるはずのテーブルがない        Rake::Task["db:setup"].invoke        exit 0      end    rescue ActiveRecord::NoDatabaseError      # データベースが存在しない      Rake::Task["db:setup"].invoke      exit 0    end  endend

rails db:setupの初回実行時に作成されるテーブルの有無を確認して、テーブルが存在しない場合のみrails db:setupを実行していますが、テーブルの確認とタスクの実行の間がクリティカルセクションになっているため、何らかの方法で排他制御しなければrails db:setupが2重に実行される可能性があります。前述のエラーはまさにこれが原因です。

MySQLやRedisを使ってロックを取るなどこれを排他制御することは技術的には可能なのですが、rails db:setupのように一度きりしか実行しないような処理を記述するには Job というAPIオブジェクトが適任ですので、これを例に使い方を説明します。

ところで、典型的なRailsのワークフローには、DBの初期化を行うrails db:setupに加えて、スキーマの変更などを行うマイグレーション用のタスクrails db:migrateがあります。一見するとこれもJobで管理するのが良さそうなのですが、Jobは一度APIオブジェクトを作成するとDeploymentのようにイメージを変更できないという制約があります。そのため、新しいマイグレーションを作成するたびにJobオブジェクトも新規に作成する必要があり、運用が煩雑になります。また、rails db:setupとは異なり、rails db:migrateには(少なくともDBがMySQLかPostgreSQLの場合には)RDBMSのロック機構を使ってマイグレーションが多重実行されないように排他制御する仕組みが組み込まれているため、pumaの起動前に毎回実行しても実質的な問題が発生しません。

そこで Step2 では全体の構成を下記のように変更します。

• rails db:setupはJobとして定義し、アプリを最初にk8sにデプロイした時に一度だけ実行する。
• rails db:migrateはpumaの起動前に毎回実行する。(複数のpumaコンテナにより同時に起動される可能性があるが問題ない)

まずは rails db:setup を実行するための Job のマニフェストを書きます。

# k8s/manifests-step2/setup-db-job.yaml---apiVersion: batch/v1 # Deploymentのapps/v1とは異なる点に注意kind: Jobmetadata:  name: demoapp-setup-dbspec:  backoffLimit: 4 # ジョブを失敗したと見なすまでの再試行回数  template:    metadata:      labels:        app: demoapp        component: setup-db    spec:      restartPolicy: Never # OnFailureにするとbackoffLimitが効かない場合があるのでNeverにする      containers:        - name: setup-db          image: demoapp:0.0.1          command:            - ./bin/setup-db          envFrom:            - configMapRef:                name: demoapp-rails-env            - secretRef:                name: demoapp-rails-env

内容はpumaやsidekiqのDeploymentと似ています。まず同じようにdemoappイメージを指定します。また、.spec.template以下の内容もほぼ同じですが、livenessProbeなどの項目が無い分Deploymentよりもシンプルな内容になります。

Job固有の設定値について簡単に補足します。

• backoffLimitのデフォルト値は6です。4を指定しているのは単にサンプルとして例示するためで深い意味はありません。
• restartPolicyはOnFailureかNeverを指定できます。OnFailureの場合はジョブが失敗したときにPodはそのままで内部のコンテナだけ作り直します。Neverの場合はPodごと作り直します。今回の場合どちらでも良いのですが、既知の問題によりNeverだとbackoffLimitが無視されるケースがあると公式ドキュメントにも書いてあるのでNeverを指定しています。

詳細は下記のドキュメントを参照してください。

• Jobs - Run to Completion | Kubernetes
• Kubernetes API Reference Docs

commandに指定している ./bin/setup-db は下記のような内容で、単にmysqlの起動を待ち受けてから(Step1ではpumaで実行していた)rails db:setup_if_not_yetを実行します。

#!/bin/bash -xucd $(dirname $0)/.../bin/wait-for $MYSQL_HOST 3306./bin/rails db:setup_if_not_yet

また、puma-deploy.yamlも次のように修正します。

--- k8s/manifests-step1/puma-deploy.yaml        2018-05-11 23:30:49.000000000 +0900+++ k8s/manifests-step2/puma-deploy.yaml        2018-05-11 23:57:17.000000000 +0900@@ -7,7 +7,7 @@     app: demoapp     component: puma spec:-  replicas: 1+  replicas: 2   selector:     matchLabels:       app: demoapp@@ -24,7 +24,7 @@           image: demoapp:0.0.1           imagePullPolicy: IfNotPresent           command:-            - ./bin/setup-db-and-start-puma+            - ./bin/start-puma           livenessProbe:             httpGet:               path: /health_check/full

replicasを2に増やし、commandを./bin/start-pumaに変更しています。./bin/start-pumaは下記のような内容です。

#!/bin/bash -xcd $(dirname $0)/..trap "pkill -P $$" EXIT./bin/wait-for $MYSQL_HOST 3306./bin/wait-for $REDIS_HOST 6379./bin/rails db:try_migrate./bin/pumactl start

Step1ではpumactlコマンドの実行前に./bin/rails db:setup_if_not_yetを実行していましたが、代わりにrails db:try_migrateを実行します。このRakeタスクは下記のような定義です。

# lib/tasks/db.rakenamespace :db do  desc "Wait for db:setup task to complete."  task wait_for_setup_completion: [:environment] do    loop do      begin        if !ActiveRecord::InternalMetadata.table_exists?          # データベースは存在するが、必ずあるはずのテーブルがない          sleep 1        elsif !ActiveRecord::InternalMetadata.where(key: :environment).exists?          # テーブルはあるがレコードが存在しない          sleep 1        else          break        end      rescue ActiveRecord::NoDatabaseError        # データベースが存在しない        sleep 1      end    end  end  desc "Invoke db:migrate task and ignore errors caused by parallel execution."  task try_migrate: [:wait_for_setup_completion] do    begin      Rake::Task["db:migrate"].invoke    rescue ActiveRecord::ConcurrentMigrationError => e      Rails.logger.info "Skip migrations because another migration process is currently running."    end  endend

行数は多いですがやっていることはrails db:setupの完了を待ってからrails db:migrateを実行しているだけです。

ただし、db:migrateタスクでActiveRecord::ConcurrentMigrationErrorという例外が発生した場合は、エラー終了しないように捕捉してINFOレベルでログに書き出すようにしています。

この例外は、マイグレーションが多重起動された際に、ロックを取れなかったプロセス側が発生させる例外で、実害はありません。単にそのプロセスではマイグレーションがスキップされたということを示しています。

アプリイメージの更新とローリングリスタートの動作確認

Step2での修正はJobの追加とpuma用のDeploymentの定義の変更の2点だけですが、これを機にdemoappのイメージを更新してpuma用のDeploymentに反映し、Podがローリングリスタートされる様子を確認してみましょう。demoappの更新は新規マイグレーションを含む内容にしてみます。

まずStep2のマニフェストでdemoappをminikubeにデプロイします。

# Railsアプリのイメージをビルド$ (eval $(minikube docker-env) && docker build . -t demoapp:0.0.1)$ cd k8s/manifests-step2# APIオブジェクトを作成$ cat *.yaml | kubectl apply -f -# puma deploymentの起動が完了するまで待機$ kubectl rollout status deploy demoapp-puma# puma serviceのエンドポイントをブラウザでオープン$ minikube service demoapp-puma

次に、messagesテーブルにlikesというカラムを追加するだけの内容で新しいマイグレーションを作ります。

# RAILS_ROOTに移動してローカル環境にMySQLとRedisを起動しDBを初期化$ cd ../../$ rm -r tmp/mysql tmp/redis$ docker-compose up -d# しばらく待ってから$ ./bin/rails db:setup# 新しいマイグレーションを作成して、ローカル環境にマイグレーション実行$ ./bin/rails g migration AddLiksToMessage likes:integer$ ./bin/rails db:migrate

新しいdemoappのイメージを作りデプロイします。

# タグを0.0.2に変えてRailsアプリのイメージをビルド$ (eval $(minikube docker-env) && docker build . -t demoapp:0.0.2)# 新しいイメージをデプロイして更新が完了するのを待つ$ kubectl set image deploy/demoapp-puma puma=demoapp:0.0.2$ kubectl set image deploy/demoapp-sidekiq sidekiq=demoapp:0.0.2$ kubectl rollout status deploy demoapp-puma$ kubectl rollout status deploy demoapp-sidekiq

事前に別の端末で下記のコマンドをそれぞれ実行しておくとローリングリスタートに伴うPodの入れ替わりの様子を確認しやすいと思います。

# puma用のPodのログを表示$ stern "demoapp-puma-.*"# APIオブジェクトの変化を監視して表示$ kubectl get deployments --watch$ kubectl get replicasets --watch$ kubectl get pods --watch

watchコマンドを用いる方法もおすすめです。watchコマンドは brew install watch でインストールできます。

# 更新頻度を1秒に指定$ watch -n 1 kubectl get deployments,replicasets,pods

kubectl set image deploy/demoapp-puma puma=demoapp:0.0.2を実行するとpumaのDeploymentが更新され、ローリングアップデートが開始します(puma=demoapp:0.0.2のpumaは、puma-deploy.yamlで定義したコンテナのnameです)。

この際、puma-deploy.yamlのreplicasが2だと下記のような動作になり、rails db:migrateの競合は起きません。

1. 新しいPodを一つ起動開始
2. 1のPodが起動完了し、古いPodのうち一つが停止し、さらに新しいPodを一つ起動開始
3. 2のPodが起動完了し、残りの古いPodが停止

replicasが4だと下記のような動作になり、高い確率でrails db:migrateが競合します。(puma-deploy.yamlを編集して試してみてください)

1. 古いPodを一つ停止すると同時に新しいPodを二つ起動開始
2. 1のPod二つがほぼ同時に起動完了し、古いPodがさらに停止され、新しいPodがさらに二つ起動開始
3. 2のPod二つがほぼ同時に起動完了し、最後のPodが停止

rails db:migrateがほぼ同時に起動された場合には、遅い方のPodのログに下記のようなメッセージが残るはずです。

INFO -- : Skip migrations because another migration process is currently running.

なお、Deploymentの更新の際のPodの入れ替えはこのように徐々に新しいものに入れ替えるような動作になっていますが、これはマニフェストの.spec.strategyで変更することができます。puma-deploy.yamlの例では特に指定していないのでデフォルトのRollingUpdateになっていますが、Recreateを指定すると古いPodを全て削除してから新しいPodを立ち上げるようになります。これについてはStep3で取り上げます。

また、replicasが4のケースだと、一時的に起動中のPodの数が5つに、READYな状態のPodは3つになっている点に注意してください。急激なサービスのスループット低下とインフラ負荷の増加を防ぐため、レプリカの数が多い場合はデフォルトでこのような動作をするようになっています。ローリングアップデート中におけるREADYな状態のPodの割合と起動中(準備中含む)のPodの割合は、それぞれ.spec.strategy.rollingUpdate.maxUnavailableと.spec.strategy.rollingUpdate.maxSurgeで指定できます。デフォルト値はいずれも25%です。これについては本ドキュメントではこれ以上説明しないので、詳細は下記の資料を参照してください。

Writing a Deployment Spec

graceful stop

k8sのようにBlue-Greenデプロイメントでアプリケーションの更新を行う場合、新しいインスタンスを立ち上げつつ古い方のインスタンスは順次停止します。この際、実行中の処理はできるだけ強制終了せずに、完了するまで待ってからアプリケーションプロセスを停止することが望ましいです。

pumaとsidekiqの場合は次のようなことを意味します。

• puma: 処理中のリクエストのレスポンスを返し終わってから停止する。
• sidekiq: 処理中のジョブが全て完了してから停止する。

一般的にこのような停止処理のことをgraceful stopと呼びます。

前節で述べたローリングリスタートの際には、k8sは停止するPodの全てのコンテナにSIGTERMシグナルを送信し、コンテナのメインプロセスが停止するのを待ちます。そのため、コンテナで起動するプロセスはSIGTERMを受け取った時にgraceful stopするように実装しておく必要があります。

pumaとsidekiqはいずれもSIGTERMを受け取った際にgraceful stopする仕様なので、このままでも問題ない場合もあるのですが、下記の点に気をつける必要があります。

• シェルスクリプトでラップしている場合は、trapコマンドなどでシグナルを捕捉して子プロセスにもSIGTERMを送ること。サンプルは第2回を参照してください。
• sidekiqはSIGTERMを受け取ってからジョブの強制終了まで8秒しか待たない。これが短すぎる場合は起動時の-tオプションで変更しておくこと。サンプルは第4回の記事を参照してください。
• k8sがコンテナを強制停止するまでの猶予期間が30秒で足りない場合は、Deploymentのspec.template.spec.terminationGracePeriodSecondsで変更しておくこと。(参考)

pumaとsidekiqのシグナルの扱いについては下記のドキュメントを参照してください。

• puma/signals.md
• Signals mperham/sidekiq Wiki

Makefileのサンプル

Step2のディレクトリにもMakefileを置いてあります。本節に出てきた各種操作は(マイグレーションの作成以外は)対応するタスクを定義してあるので、ローリングアップデートの動作を確認する際にはmakeコマンドを使うと簡単にオペレーションを実行することができます。

$ cd k8s/manifests-step2# タグを指定してイメージをビルドし、APIオブジェクト一式を作成(TAGは省略可)$ make TAG=0.0.1# タグを指定してイメージをビルドし、puma用Deploymentに反映$ make TAG=0.0.2 update# APIオブジェクトの削除$ make clean

MakefileはStep1のものをベースにいくつか修正を加えた内容です。miniube-docker-buildは、指定されたタグが存在する場合はビルドをスキップするようにしています。

# k8s/manifests-step2/MakefileSHELL = /bin/bashifeq ($(TAG),)    tag := 0.0.1else    tag := $(TAG)endifall:    $(MAKE) minikube-docker-build    $(MAKE) kubectl-apply    $(MAKE) kubectl-rollout-status    $(MAKE) minikube-serviceclean: kubectl-deleteupdate:     $(MAKE) TAG=$(tag) minikube-docker-build    $(MAKE) TAG=$(tag) deployminikube-docker-build:    eval $$(minikube docker-env) && \        if [ "$$(docker image ls -q demoapp:$(tag))" == "" ]; then \            docker build ../../ -t demoapp:$(tag); \        fikubectl-apply:    cat *.yaml | kubectl apply -f -kubectl-rollout-status:    kubectl rollout status deploy demoapp-puma    kubectl rollout status deploy demoapp-sidekiqminikube-service:    minikube service demoapp-pumakubectl-delete:    cat *.yaml | kubectl delete -f -deploy:    kubectl set image deploy/demoapp-puma puma=demoapp:$(tag)    kubectl set image deploy/demoapp-sidekiq sidekiq=demoapp:$(tag)    kubectl rollout status deploy demoapp-puma    kubectl rollout status deploy demoapp-sidekiqstern:    stern demoapp.*

Step3: PersistentVolumeClaim(PVC)

サンプルコードは全て下記のディレクトリにあります。

k8s/manifests-step3/

Step2の時点ではMySQLとRedisのデータ領域が永続化されていないため、何らかの障害でPodが停止するとDBの内容が全て消えるという制約があります。

Step2のマニフェストでAPIオブジェクト一式を作成した後、mysqlのPodをkubectl deleteコマンドで削除すると、pumaのヘルスチェックが失敗するようになるのを確認できます。

$ cd k8s/manifests-step2# APIオブジェクトを作成$ cat *.yaml | kubectl apply -f -# puma deploymentの起動が完了するまで待機$ kubectl rollout status deploy demoapp-puma# MySQL用のPodを削除$ kubectl delete pod -l "app=demoapp,component=mysql"# pumaのログを確認$ stern "demoapp-puma-.*"(省略)demoapp-puma-5cdbdbfc76-d6ftm puma I, [2018-05-13T12:11:56.303988 #33]  INFO -- : [026a124c-fedb-4423-8587-40bec3481cde] health_check failed:demoapp-puma-5cdbdbfc76-d6ftm pumademoapp-puma-5cdbdbfc76-d6ftm puma Migrations are pending. To resolve this issue, run:demoapp-puma-5cdbdbfc76-d6ftm pumademoapp-puma-5cdbdbfc76-d6ftm puma         bin/rails db:migrate RAILS_ENV=production

そこでStep3では、MySQLとRedisにPersistentVolume(以後、PV)というAPIオブジェクトを割り当ててデータボリュームとして使用し、DBの内容がPodの生死に関わらず維持されるようにします。

PVは永続ストレージを抽象化したAPIオブジェクトです。PVの実体はNFSやGlusterFSのようなネットワークストレージでも良いし、GCP上であればGCEのPersistentDisk、AWSであればEBSを使うこともできます。これをボリュームタイプと呼びます。

PVのボリュームタイプはプラグインとして実装されていて、すでに主要なネットワークストレージとパブリッククラウドのストレージサービスに対応しています。

Types of Persistent Volumes

MySQLのようなデータベースをk8sで運用するためには、障害でPodやk8sノードがクラッシュした場合に、新しいPodにデータ領域を引き継ぐ必要があります。k8sでは先に挙げたようなドライバ経由でk8sクラスタの外にデータを保存することによってこれを実現しています。

PVオブジェクトは直接マニフェストを書いて作ることもできますが、PersistentVolumeClaim(以後、PVC)というAPIオブジェクトのDynamic Provisioningという機能を経由して作る方が簡単なので、本ドキュメントではその方法で説明します。

まずMySQL用のPVCオブジェクトのマニフェスト mysql-pvc.yaml を作成します。

# k8s/manifests-step3/mysql-pvc.yaml---kind: PersistentVolumeClaimapiVersion: v1metadata:  name: demoapp-mysql  labels:    app: demoapp    component: mysqlspec:  accessModes:    - ReadWriteOnce          # 同時に一つのプロセスからしか読み書きしないモードを指定  resources:    requests:      storage: 8Gi           # 確保する永続ストレージのサイズを指定  storageClassName: standard # 後述

.spec.storageClassNameにはStorageClassというAPIオブジェクトの名前を指定します。StorageClassの詳細については後述します。

次に mysql-deploy.yaml へこのPVCを結びつけます。コメントをつけている行は、Step2での定義に追加した部分です。

# k8s/manifests-step3/mysql-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-mysql  labels:    app: demoapp    component: mysqlspec:  replicas: 1  selector:    matchLabels:      app: demoapp      component: mysql  strategy:            # 更新時の動作を指定    type: Recreate     # 古いPodを停止してから新しいPodを起動  template:    metadata:      labels:        app: demoapp        component: mysql    spec:      restartPolicy: Always      volumes:                          #         - name: data                    # .volumeMountsの.nameで指定          persistentVolumeClaim:        #            claimName: demoapp-mysql    # PVCオブジェクトの.metadata.nameを指定      initContainers:                   # 前処理用のコンテナ        - name: "remove-lost-found"     # データディレクトリの"lost+found"ディレクトリを削除          image: "busybox:1.25.0"          command:             - rm            - -fr            - /var/lib/mysql/lost+found          volumeMounts:            - name: data              mountPath: /var/lib/mysql      containers:        - name: mysql          image: mysql:5.7.21          livenessProbe:            tcpSocket:              port: 3306          readinessProbe:            tcpSocket:              port: 3306          volumeMounts:                 #            - name: data                # .volumesの.nameを指定              mountPath: /var/lib/mysql # MySQLのデータディレクトリを指定          envFrom:            - configMapRef:                name: demoapp-mysql-env            - secretRef:                name: demoapp-mysql-env

このようにPVCオブジェクトを指定すると、Deploymentの作成時にStorageClassに応じたPVが自動的に作成され、指定したパスにマウントされます。この例では mysql-pvc.yamlで定義したPVCによって作られたPVをMySQLのデータディレクトリである/var/lib/mysqlにマウントしています。

.spec.template.spec.initContainersは前処理用のコンテナの定義です。メインのコンテナを起動する前に自動的に実行されます。この例ではMySQLのデータディレクトリである/var/lib/mysqlディレクトリにlost+foundというディレクトリがあれば削除するという処理を入れています。PVCで確保したボリュームの中身は後述するStorageClassによって異なる場合があるのですが、mysqlイメージは/var/lib/mysqlディレクトリが空でない場合、DBの初期化処理がエラーで失敗します。minikubeの場合は空なのですが、GKEのようにlost+foundディレクトリが最初から存在する場合もあるので、ある程度どこでも動くようにinitContainersでこれを取り除いています。

また、.spec.strategy.typeにRecreateを指定している点に注意してください。Step2でも説明しましたが、これは更新時のPodの入れ替えの挙動を指定するパラメータです。デフォルトはRollingUpdateになっており、古いPodを停止する前に新しいPodを起動します。MySQLは同一のデータディレクトリを複数のサーバが参照するとエラーになるため、Recreateを指定して二つ以上のPodが同時に起動しないようにしています。

Redisについてもほぼ同様に、redis-pvc.yamlを追加してredis-deploy.yamlを更新しています。特筆すべき点はないので説明は割愛します。詳細はサンプルコードを参照してください。

• k8s/manifests-step3/redis-pvc.yaml
• k8s/manifests-step3/redis-deploy.yaml

StorageClassについて

StorageClassは、永続ストレージの設定をまとめたオブジェクトです。設定とはボリュームタイプやPVの削除時にデータオブジェクトを残すかどうかといった項目です。minikubeの場合、クラスタの作成時に自動的にstandardという名前のStorageClassが作られるのでそれを指定しています。このオブジェクトの定義は、minikube dashboard上または下記のコマンドで確認できます。

$ kubectl get storageclass standard -o yaml

重要な部分を抜粋すると下記のような内容です。

apiVersion: storage.k8s.io/v1kind: StorageClassmetadata:  annotations:    storageclass.beta.kubernetes.io/is-default-class: "true"  name: standardprovisioner: k8s.io/minikube-hostpathreclaimPolicy: DeletevolumeBindingMode: Immediate

.provisionerがボリュームプラグインの種類を示しています。minikube-hostpathはシングルノードでの検証用のもので、minikube VM上のローカルストレージをデータの保存先として使用します。

GCPのGKEでk8sクラスタを作った場合も、自動的にstandardという名前のStorageClassが作られますが、下記の通り.provisionerはGCEのPersistentDiskが指定されているため、マルチノードクラスタでの運用に耐えるものとなっています。

apiVersion: storage.k8s.io/v1kind: StorageClassmetadata:  annotations:    storageclass.beta.kubernetes.io/is-default-class: "true"  name: standardprovisioner: kubernetes.io/gce-pdparameters:  type: pd-standardreclaimPolicy: Delete

重要なのは、PVCオブジェクトでは単にstandardという名前だけを指定しており、ボリュームプラグインのようなクラスタ環境に依存するパラメータを一切記述していないという点です。これにより、この例のようにminikubeとGKEのような異なるプラットフォームであっても、それぞれの環境に応じて適切に設定されたStorageClassが同じ名前で用意されていれば、このマニフェストはいずれのクラスタにもデプロイ可能になります。

StatefulSetについて

k8sにはStatefulSetというAPIオブジェクトがあります。このオブジェクトはステートフルなアプリケーションを管理するためのものと位置付けられています。

StatefulSets

そのため、一見するとMySQLやRedisのようなサービスを管理する際にはDeploymentではなくStatefulSetを使うべきではと思われるのですが、StatefulSetが必要になるのは Set の名が示す通りMySQLのマスター/スレーブ構成など複数のコンテナでクラスタを組む場合です。

Step3の例のように単一のコンテナによるステートフルなアプリケーションの場合、Deploymentを使って.spec.strategy.typeをRecreateにするだけで十分です。

ということが公式のドキュメントにも書いてあるのでリンクを貼っておきます。
Run a Single-Instance Stateful Application

ステートフルなサービスの運用について

Railsアプリケーションをクラウド上のk8sクラスタ上で運用する場合には、MySQLやRedisのような永続データを持つサービスはコンテナ化せず、クラウドベンダのマネージドサービスを使うという方法も考えられます。

特に可用性などの要件が厳しい場合には、簡単にマルチAZでマスタースレーブ構成を運用できるAmazon RDSのようなサービスは魅力的な選択肢です。

一方、可用性やデータロスト耐性に対する要求がそこまで厳しくない場合には、Step3で示したような構成も悪くない選択肢です。Podやk8sノードに障害が発生した場合には、新しいPodが即座に作成されて永続ボリュームの内容を引き継ぎます。Amazon EBSやGCE Persistent Diskのようなストレージサービスを永続ボリュームとして使う場合、定期的なスナップショットを取るのは簡単です。

確かにマルチ構成のAmazon RDSと比較すると障害発生時のダウンタイムは長くなる可能性が高いし、永続ボリュームに障害が発生した場合には直前のスナップショットまでデータロストするリスクがありますが、それを許容できるような場合にはこの程度の構成で十分とも言えます。

Step4: Ingress

サンプルコードは全て下記のディレクトリにあります。

k8s/manifests-step4/

Step3の時点では、Railsアプリ(pumaプロセス)の外部向けのインタフェースとして、NodePortタイプのServiceオブジェクトを使っていました。この方法ではk8sクラスタを構成する全てのノードにエンドポイントが用意されます。minikubeのようにシングルノード構成の検証用クラスタではこれで十分ですが、マルチノード構成の本番環境ではそのまま運用するのは難しいでしょう。少なくとも負荷分散や可用性担保のためには前段にロードバランサが必要になります。そうするとノードの追加や縮退の際にロードバランサの設定も変更する必要が生じ、管理が煩雑になります。

そのため、このような用途でServiceオブジェクトを使う場合には、通常はLoadBalancerというタイプを指定します。

LoadBalancerを指定した場合にどのような仕組みで接続用のエンドポイントが用意されるかはk8sのデプロイ先の環境によって異なります。例えばAWS上であればELBを使うことができます。一方、minikubeはLoadBalancerに完全には対応していません。そのため、LoadBalancerタイプでServiceを作ると下記のようにEXTERNAL-IPがいつまでもpendingの状態のまま変わらず、ダッシュボードでも準備中のアイコンが表示され続けます。

% kubectl get svcNAME            TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGEdemoapp-mysql   ClusterIP      10.99.99.47      <none>        3306/TCP         1mdemoapp-puma    LoadBalancer   10.98.211.117    <pending>     3000:32320/TCP   1mdemoapp-redis   ClusterIP      10.111.218.160   <none>        6379/TCP         1mkubernetes      ClusterIP      10.96.0.1        <none>        443/TCP          8m

参考: docker - kubernetes service external ip pending - Stack Overflow

一方、k8sには負荷分散やSSLターミネーション、ホスト名やリクエストパスによるバーチャルホストなど、外部向けのエンドポイントを抽象化することにより特化した機能を持つIngressというオブジェクトがあります。これらの機能の一部はLoadBalancerタイプのServiceでも実現できますが、AWSのELBなどバックエンドごとに固有のannotationで指定する必要があり、Ingressに比べると可搬性の面で劣ります。

そこでこのStep4では外部向けのエンドポイントにIngressを使うように構成を変更します。LoadBalancerタイプのServiceの使い方については説明しません。詳細は下記のドキュメントを参照してください。

• Ingress | Kubernetes
• Services | Kubernetes

Ingress コントローラのインストール

PersistentVolume同様、Ingressもまたその実装がk8sクラスタのデプロイ先に依存する機能です。GKEではGCPのネットワーク機能を使って実装されていますが、その他の環境ではIngressコントローラをPodとしてk8sクラスタ上に動かしておく必要があります。

Ingress controllers

Ingressコントローラの中にはGLBC(ingress-gce)のようにクラウドプロバイダ固有の機能を使ったものと、NGINX Ingress Controller(ingress-nginx)のようにどこでも動作するものがあります。

幸いにしてminikubeではNGINX Ingress Controllerをaddonとして簡単にインストールすることができます。本ドキュメントで示すマニフェストを試す場合には、minikubeインスタンスの起動後に下記のコマンドを実行してください。

$ minikube addons enable ingress

動作確認の手順

このドキュメントでは、下記のような構成を目指します。

• pumaサービスへ https://demoapp-puma.$(minikube ip).nip.io/ というホスト名で接続できるようにする。
• サーバ証明書には自己署名のダミー証明書を使用する。
• IngressでSSL終端して、ServiceにはHTTPで接続する。

Step3以前と比べて少し手順が変わっています。各コマンドの詳細は次節以降で説明します。

# Railsアプリのイメージをビルド$ (eval $(minikube docker-env) && docker build . -t demoapp:0.0.1)$ cd k8s/manifests-step4# ダミーのサーバ証明書を作成COMMON_NAME=demoapp-puma.$(minikube ip).nip.ioopenssl req -new -x509 -nodes -keyout server.key -days 3650 \  -subj "/CN=${COMMON_NAME}" \  -extensions v3_req \  -config <(cat openssl.conf | sed s/\${COMMON_NAME}/$COMMON_NAME/) > server.pemunset COMMON_NAME# 証明書をSecretオブジェクトとして登録kubectl create secret tls demoapp-puma-tls --key server.key --cert server.pem# APIオブジェクトを作成export MINIKUBE_IP=$(minikube ip)cat *.yaml | sed s/\${MINIKUBE_IP}/$MINIKUBE_IP/ | kubectl apply -f -# puma deploymentの起動が完了するまで待機$ kubectl rollout status deploy demoapp-puma# puma Ingressのエンドポイントをブラウザでオープン$ open https://demoapp-puma.$(minikube ip).nip.io/# 作成したAPIオブジェクトを削除cat *.yaml | kubectl delete -f -kubectl delete secret demoapp-puma-tls

Makefileを置いてあるので下記のコマンドで代替できます。

$ cd k8s/manifests-step4# Railsアプリのイメージをビルド$ make minikube-docker-build# ダミーのサーバ証明書を作成しSecretオブジェクトとして登録$ make kubectl-create-secret-tls# APIオブジェクトを作成$ make kubectl-apply# puma deploymentの起動が完了するまで待機$ make kubectl-rollout-status# puma Ingressのエンドポイントをブラウザでオープン$ make open

単にmakeとだけ入力すると順番に全部実行します。

$ make

ダミーのサーバ証明書の作成

HTTPSで接続できるようにするためにはサーバ証明書が必要です。kube-legoというモジュールを使えばIngressとLet’s Encryptを連携して動的に証明書を作成するようなこともできるのですが、今回はもっとシンプルにopensslコマンドで自己署名証明書(いわゆるオレオレ証明書)を作ります。

まず下記のような内容でopensslの設定ファイルを用意します。Chromeではバージョン58以降、subjectAltName(SAN)が設定されていない証明書はエラー扱いになりました。下記の設定はSANを設定するためのものです。

# k8s/manifests-step4/openssl.conf[req]distinguished_name=req_distinguished_namereq_extensions=v3_req[v3_req]basicConstraints=CA:FALSEkeyUsage=nonRepudiation, digitalSignature, keyEnciphermentsubjectAltName=@alt_names[req_distinguished_name][alt_names]DNS.1=${COMMON_NAME}

次に下記のようなコマンドで証明書(server.pem)と鍵(server.key)を作成します。

COMMON_NAME=demoapp-puma.$(minikube ip).nip.ioopenssl req -new -x509 -nodes -keyout server.key -days 3650 \  -subj "/CN=${COMMON_NAME}" \  -extensions v3_req \  -config <(cat openssl.conf | sed s/\${COMMON_NAME}/$COMMON_NAME/) > server.pemunset COMMON_NAME

ホスト名は前述の通りdemoapp-puma.$(minikube ip).nip.io/とします。$(minikube ip)部分はminikubeインスタンスの立ち上げごとに変わる可能性があるため、設定ファイルはテンプレートとして扱い、${COMMON_NAME}と記述されている部分をsedコマンドで書き換えています。

内容は下記のコマンドで確認できます。

$ openssl x509 -text < server.pem(一部抜粋)Certificate:    Signature Algorithm: sha256WithRSAEncryption        Issuer: CN=demoapp-puma.192.168.64.25.nip.io        Subject: CN=demoapp-puma.192.168.64.25.nip.io        X509v3 extensions:            X509v3 Subject Alternative Name:                DNS:demoapp-puma.192.168.64.25.nip.io

macOSの場合、server.pemをキーチェーンに追加して信頼するようにしておけばブラウザの警告を抑止できます。後で忘れずに削除してください。

なお、Step4にもMakefileを置いているので、証明書の作成は下記のコマンドで代替できます。

$ cd k8s/manifests-step4$ make server.pem# minikube ipが変わったら必ず作り直すこと$ make --always-make server.pem

証明書用のSecretオブジェクトの作成

Ingressで先ほど作成した証明書と鍵を使うためには、Secretオブジェクトに登録する必要があります。これまでに紹介したSecretオブジェクトのようにYAML形式のマニフェストファイルを書いても良いのですが、TLS用の証明書と鍵をファイルから登録することについてはkubectlコマンドがサポートしているため、下記のように登録します。

kubectl create secret tls demoapp-puma-tls --key server.key --cert server.pem# またはmake kubectl-create-secret-tls

Ingressオブジェクト

# k8s/manifests-step4/puma-ing.yml---apiVersion: extensions/v1beta1kind: Ingressmetadata:  name: demoapp-puma  annotations:    kubernetes.io/ingress.allow-http: "false" # HTTPでのアクセスを禁止    # GKEで確保済みの静的IPアドレスを指定する場合は下記のようにする    # kubernetes.io/ingress.global-static-ip-name: rails-k8s-demoappspec:  tls:  - hosts:    - demoapp-puma.${MINIKUBE_IP}.nip.io     # このTLS証明書で受けるホスト名のリスト    secretName: demoapp-puma-tls             # 証明書と鍵のSecretオブジェクトの名前  rules:  - host: demoapp-puma.${MINIKUBE_IP}.nip.io # ホスト名    http:      paths:      - backend:          serviceName: demoapp-puma          # バックエンドのServiceの名前とポート          servicePort: 3000

${MINIKUBE_IP}となっている部分は、kubectlコマンドに渡す前にsedコマンドで置換します。

$ export MINIKUBE_IP=$(minikube ip)$ cat *.yaml | sed s/\${MINIKUBE_IP}/$MINIKUBE_IP/ | kubectl apply -f -

より実践的な課題として、GKEにデプロイした場合の設定方法については下記のドキュメントを参照してください。

Ingress での HTTP 負荷分散の設定 | Kubernetes Engine のドキュメント

ワイルドカードDNS

nip.ioというのはワイルドカードDNSと呼ばれるサービスのドメインの一つです。Exentrique Solutionsという企業によって運営されています。

http://nip.io/

下記のようにサブドメインに相当するIPアドレスを動的に返してくれるため、プライベートアドレスを使ったテストに便利です。

$ dig +short 192.168.64.25.nip.io192.168.64.25$ dig +short www.192.168.64.25.nip.io192.168.64.25

先ごろ発表された Jenkins X でも使われていました。

nip.ioはPowerDNSとカスタムスクリプトの組みわせで実装されているとのことです。nip.io自体はOSSではないのですが、Dockerで動作するnip.ioクローンが存在します。

https://github.com/resmo/nip.io

今回のようにTLSの上で通信する場合にはセキュリティリスクは限定的だと思いますが、DNSを外部に依存したくない場合には自前でnip.ioクローンを運用するかdnsmasqなどの利用を検討してください。

envsubst

openssl.confやpuma-ing.yamlでは、$(minikube ip)に相当する部分をsedコマンドで環境変数に置換していました。このようにテキストファイルの一部を環境変数で置換する場合には envsubst というコマンドを使うとさらに簡単です。

macOSの場合はHomebrewでgettextパッケージでインストールできますが、パスを通すためにはbrew linkに--forceオプションをつけて実行する必要があります。

$ brew install gettext$ brew link gettext --force

今回の場合は置換の対象が一つと少なくsedでの代替が容易だったので、手順全体の依存を減らすためにあえて採用しませんでしたが、マニフェストを全体をテンプレート化して多数のパラメータを注入できるようにしたいのであれば、採用を検討しても良いかもしれません。

ただし、そのような目的のためには次回紹介するHelmを使う方がおすすめです。例えばSecretのデータエントリはBase64でエンコードする必要がありますが、envsubstでそれを実現しようとすると煩雑な手順になりますが、Helmであれば簡単です。

まとめ

下記のオブジェクトについての最低限の説明と、これらを使ってpuma、sidekiq、mysql、redisのコンテナをk8s上で管理するための実例を示しました。

• Deployment
• Service
• ConfigMap
• Secret
• Job
• PersistentVolumeClaim
• Ingress

k8sに関しては、次のステップとして下記について調べるのが良いと思います。

• ConfigMapやSecretの内容をボリュームとしてPodにマウントする方法(MySQLやRedisの設定ファイルの管理など)
• CronJobオブジェクトによる定期実行ジョブの定義方法(DBのバックアップなど)
• CPUやメモリの上限の設定方法

なお、今回はYAMLファイルとしてマニフェストを管理する方法を示しましたが、この構成においては下記の課題があります。

• ステージング環境やQA環境など、一部だけ設定を変更した環境を作るのが難しい
• Secretの定義ファイルにBase64エンコードした値を読み書きするのが面倒

これらの課題に対するアプローチとして、次回は Helm を使う方法を紹介します。

• 第一回 Docker編
• 第二回 Docker Compose/Dockerfile編
• 第三回 Kubernetes入門編
• 第四回 Kubernetes基礎編
• 第五回 Kubernetes応用編
• 第六回 Helm編

今回は以下のサンプルアプリケーションをminikubeにデプロイするためのマニフェストや手順について説明します。

https://github.com/kwhrtsk/rails-k8s-demoapp

前提

• macOSでの作業を前提としています。
• 使用したツールのバージョンなどは 初回 の記事を参照してください。
• ツールのインストール手順は 前回 の記事を参照してください。

準備

まずサンプルアプリのコードをチェックアウトしてminikubeを起動してください。(前回と同じなのですでにやっている人は読み飛ばしてください)

# サンプルアプリのコードをチェックアウト$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp# minikubeを起動$ minikube start --cpus=3 --memory=2048 --vm-driver=hyperkit --disk-size=12g# kubernetesのダッシュボードをオープン$ minikube dashboard

概要

前回は下記について説明しました。

• APIオブジェクトを定義するマニフェストファイルをYAML形式で記述する方法
• マニフェストファイルとkubectlコマンドを使ってAPIオブジェクトを管理する方法

今回は実際にRailsアプリをMySQLやRedisなどのミドルウェアも含めて丸ごとk8sクラスタ上にデプロイするための手順を説明します。一度に多種のAPIオブジェクトを使うと全体を理解するのが難しくなるので、4つのステップに分けて進めます。

Step1では、第2回Docker Compose/Dockerfile編のdocker-compose-preview.ymlに相当する構成をできるだけ少ないAPIオブジェクトで簡潔に記述します。この時点では簡潔さと引き換えにいくつかの制約がありますが、それらをStep2からStep4で解消していきます。

今回のKubernetes基礎編ではStep1を説明し、次回のKubernetes応用編でStep2以降を説明します。

Railsアプリのイメージをminikube上で使えるようにする方法

マニフェストの説明に入る前に、ビルドしたRailsアプリのイメージをminikube上にデプロイできるようにする方法を説明します。

いくつかの方法があります。

1. Docker Hubのようなパブリックレジストリに登録する。
2. AWSのECRやGCPのContainer Registryのようなプライベートレジストリサービスに登録する。
3. プライベートレジストリサービスを自前で用意してそこに登録する。
4. minikube VM上のDockerプロセス上に接続して直接イメージをビルドする。

今回は一番簡単な4の方法を使います。

準備 の節を参照して、サンプルコードをチェックアウトしminikubeを起動したら、下記のコマンドを実行してください。

$ (eval $(minikube docker-env) && docker build . -t demoapp:0.0.1)

minikube docker-envコマンドは、minikube VM上のDockerプロセスに接続できるようにするための環境変数を出力します。上記のようにすることでminikube VM上のDockerプロセス上で直接イメージをビルドします。これにより、マニフェストではイメージ名をdemoapp:0.0.1と指定すればこのイメージを使えるようになります。

この方法を使う場合、タグにはlatest以外の値を指定してください。k8sの仕様で、タグがlatestになっているイメージを指定するとコンテナの起動前に必ずレジストリからイメージをpullしようとするため、4の方法だと必ず失敗するようになってしまいます。

これは4の方法を使う場合の制約ではあるのですが、インフラの構成管理という観点ではそもそもイメージのタグにlatestを使うとデプロイされるバージョンがタイミング依存になるため、4以外の方法でもlatestタグの使用は避けたほうが良いと思います。

Step1: Deployment, Service, ConfigMap, Secret

Step1では、第2回Docker Compose/Dockerfile編のComposeファイルdocker-compose-preview.ymlに相当する構成を(いくつかの制約と引き換えに)できるだけ簡潔に記述します。

# docker-compose-preview.ymlversion: "3"services:  puma:    image: demoapp    build:      context: .    env_file:      - .dockerenv/rails    ports:      - 3000:3000    depends_on:      - mysql      - redis    command: ./bin/setup-db-and-start-puma  sidekiq:    image: demoapp    env_file:      - .dockerenv/rails    depends_on:      - puma    command: ./bin/start-sidekiq  mysql:    image: mysql:5.7.21    env_file:      - .dockerenv/mysql  redis:    image: redis:4.0.9    command: redis-server --appendonly yes

このComposeファイルの要点は下記の通りです。

• puma, sidekiq, mysql, redisの4つのサービス(コンテナ)を起動
• puma, sidekiqコンテナに設定する環境変数は .dockerenv/rails にまとめて記述
• mysqlコンテナに設定する環境変数は .dockerenv/mysql にまとめて記述
• pumaコンテナには3000番ポートで接続可能
• データベーススキーマの初期化(rails db:setup)はpumaコンテナの起動時に実行
  • 詳細は前回の記事の./bin/setup-db-and-start-pumaの解説を参照

これと同等の構成をk8sで実現するために、Deployment、Service、ConfigMap、Secretの4種類のAPIオブジェクトを使います。

Deploymentは、Pod(≒コンテナ)の起動管理を行うオブジェクトです。Serviceは、PodへアクセスするためのI/Fを提供します。この二つは前回のKubernetes入門編で解説したので詳細はそちらを参照してください。

DeploymentとServiceの組み合わせで、Docker Composeにおけるserviceに相当する機能になります。今回の例だと、mysql, redis, pumaのサービスには外部のコンテナまたはクラスタの外部（ブラウザ）からアクセスする必要があるため、DeploymentとServiceを一組ずつ定義します。sidekiqは外から参照する必要がないため、Deploymentのみ定義します。

ConfigMapとSecretは、Deploymentに設定する環境変数の管理に使います。今回の使い方ではComposeファイルにおける.dockerenv/mysqlと.dockerenv/railsに相当します。

使用するマニフェストファイルは以下の11個で、全てk8s/manifests-step1/に置いてあります。一つのYAMLファイルに一つのAPIオブジェクトの定義を書いています。

• mysql-deploy.yaml
• mysql-env-cm.yaml
• mysql-env-secret.yaml
• mysql-svc.yaml
• redis-deploy.yaml
• redis-svc.yaml
• puma-deploy.yaml
• puma-svc.yaml
• rails-env-cm.yaml
• rails-env-secret.yaml
• sidekiq-deploy.yaml

これから順に内容を説明していきますが、まずはデプロイを実行してみましょう。

準備 の節を参照して、サンプルコードをチェックアウトしminikubeを起動したら、下記のコマンドを実行してください。デプロイが済んだ後、ブラウザでサンプルアプリを開くことができます。

# Railsアプリのイメージをビルド$ (eval $(minikube docker-env) && docker build . -t demoapp:0.0.1)$ cd k8s/manifests-step1# APIオブジェクトを作成$ cat *.yaml | kubectl apply -f -# pumaとsidekiqの起動が完了するまで待機$ kubectl rollout status deploy demoapp-puma$ kubectl rollout status deploy demoapp-sidekiq# puma serviceのエンドポイントをブラウザでオープン$ minikube service demoapp-puma

上記の手順と等価なタスクをMakefileに定義してあるので、代わりにmakeコマンドで実行することもできます。

$ cd k8s/manifests-step1$ make kubectl-apply$ make kubectl-rollout-status$ make minikube-service# またはパラメータなしの make で全て順に実行

APIオブジェクトを削除するには次のようにします。

$ cd k8s/manifests-step1$ cat *.yaml | kubectl delete -f -# または make clean

Makefileは下記のような内容です。GNU Makeで動作を確認しています。

# k8s/manifests-step1/MakefileSHELL = /bin/bashall:    $(MAKE) minikube-docker-build    $(MAKE) kubectl-apply    $(MAKE) kubectl-rollout-status    $(MAKE) minikube-serviceclean: kubectl-deleteminikube-docker-build:    eval $$(minikube docker-env) && docker build ../../ -t demoapp:0.0.1kubectl-apply:    cat *.yaml | kubectl apply -f -kubectl-rollout-status:    kubectl rollout status deploy demoapp-puma    kubectl rollout status deploy demoapp-sidekiqminikube-service:    minikube service demoapp-pumakubectl-delete:    cat *.yaml | kubectl delete -f -

スクリプト化するまでもないような短いコマンドであっても、定型的な処理はこのように形として残しておくのがおすすめです。こういった小さな積み重ねがチーム内に暗黙知が生まれることを防ぎます。

次に、各マニフェストファイルの内容を説明します。

mysql-deploy.yaml: mysql の Deployment

はじめにMySQLに関連するマニフェストの内容を説明します。

まずは Deployment から。

# k8s/manifests-step1/mysql-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-mysql  labels:    app: demoapp    component: mysqlspec:  replicas: 1  selector:    matchLabels:      app: demoapp      component: mysql  template:    metadata:      labels:        app: demoapp        component: mysql    spec:      restartPolicy: Always      containers:        - name: mysql          image: mysql:5.7.21          livenessProbe:            tcpSocket:              port: 3306          readinessProbe:            tcpSocket:              port: 3306          envFrom:            - configMapRef:                name: demoapp-mysql-env            - secretRef:                name: demoapp-mysql-env

最初なので全般事項についてもここで説明します。

• .metadata.nameにはdemoapp-mysqlのようにdemoapp-というプレフィクスをつけます。例えば、Serviceオブジェクトの名前をredisにしてしまうと、それ以降に起動する全てのコンテナにk8sによってREDIS_PORTのような環境変数が設定されるのですが、sidekiqなど一部のgemはこういった環境変数によって動作が変わってしまう場合があります。名前のプレフィクスはこのような環境変数とgemなどで一般的に使用される環境変数が競合するのを避けるのが目的です。自動設定される環境変数の詳細についてはドキュメントを参照してください。
• 各種ラベルには、共通でappラベルにdemoappを、コンポーネントごとにcomponentラベルを設定します。コンポーネントはpuma, sidekiq, mysql, redisなどです。
• 同一のコンポーネントに属するAPIオブジェクトには、同一の名前とラベルを設定します。例えば、mysql用のDeployment、Serviceには.metadata.nameに共通のdemoapp-mysqlという名前をつけます。また、.metadata.labelsにはapp: demoapp, component: mysqlの二つを設定します。
• マニフェストのファイル名には、コンポーネントとAPIオブジェクトの種類の略称を使います。例えば mysql の Deploymentであれば mysql-deploy.yaml となります。略称については 前回のkubectl getの節を参照してください。

次に、mysqlのための固有の設定について説明します。

livenessProbeとreadinessProbeは、コンテナの死活監視のための設定項目です。この例では3306番ポートにTCP接続できるかどうかで判定を行なっています。また、上記では使用していませんが、それぞれinitialDelaySeconds(最初に検査を行うまでの待機秒数)やperiodSeconds(検査の間隔: デフォルト10秒)などの項目を設定することができます(詳細)。また、コマンドを実行したりHTTPリクエストを投げることもできます。

livenessProbeで死亡判定されると、ReplicaSetはrestartPolicyに基づいてそのPodの再起動か再作成を試みます。条件が厳しすぎるとプロセスの起動処理中に強制的に再起動されていつまで経っても起動しなくなります。その場合はinitialDelaySecondsなどの値を緩めるなどして調整する必要があります。

readinessProbeはServiceオブジェクトがそのPodに接続リクエストを転送するかどうかの判定に使います。こちらは起動直後のPodにリクエストを転送するのを防ぐことなどを目的に使用します。

envFromは環境変数を設定するための項目です。この例では ConfigMap と Secret という別のAPIオブジェクトを参照して環境変数を設定しています。ConfigMapとSecretについては後述します。

envを使うと直接Deploymentの定義の内部に環境変数を定義することもできます。詳細は下記を参照してください。

Define Environment Variables for a Container | Kubernetes

mysql-svc.yaml: mysql の Service

続いてmysql-service.yamlの内容を説明します。

# k8s/manifests-step1/mysql-svc.yaml---apiVersion: v1kind: Servicemetadata:  name: demoapp-mysql  labels:    app: demoapp    component: mysqlspec:  ports:    - protocol: TCP      port: 3306  selector:    app: demoapp    component: mysql

.spec.selectorにappとcomponentという二つのラベルを指定しています。これはmysql-deploy.yamlの.spec.template.metadata.labelsと一致させる必要があります。

前回のKubernetes入門編ではappというラベル一つでDeploymentとServiceを接続していましたが、今回はDeploymentがmysqlの他にredisやpumaなど複数存在するため、app: demoappというラベルだけだとmysqlのServiceがredisやpumaのPodを参照して混線することになります。これを避けるためにappとcomponentという二つのラベルをセレクタに指定しています。

mysql-env-cm.yaml: mysqlの環境変数用ConfigMap

次にmysql-env-cm.yamlを説明します。

# k8s/manifests-step1/mysql-env-cm.yaml---apiVersion: v1kind: ConfigMapmetadata:  name: demoapp-mysql-envdata:  MYSQL_USER: demoapp  MYSQL_DATABASE: demoapp_production

ConfigMapは環境変数や設定ファイルなどアプリケーションのパラメータを管理するためのAPIオブジェクトです。使用形態には大まかに3つの方法があります。

1. envFromで丸ごと環境変数に設定する。
2. envでキーを指定して個別に環境変数に設定する。
3. キーを指定して値をファイルとしてPod上のファイルにマウントする。

mysql-deploy.yamlでは1の方法を使っています。関係ある部分だけ抜き出すと下記の通りです。

# k8s/manifests-step1/mysql-deploy.yaml---spec:  template:    spec:      containers:        - name: mysql          image: mysql:5.7.21          envFrom:            - configMapRef:                name: demoapp-mysql-env # ConfigMapの `.metadata.name` を指定

このように参照すると、ConfigMapの.dataの各エントリが全て環境変数として設定されます。

2の方法で同じことをしようとすると下記のようになります。

# k8s/manifests-step1/mysql-deploy.yaml---spec:  template:    spec:      containers:        - name: mysql          image: mysql:5.7.21          env:            - name: MYSQL_USER  # 環境変数名を指定              valueFrom:                configMapKeyRef:                  name: demoapp-mysql-env # ConfigMapの`.metadata.name`を指定                  key: MYSQL_USER         # ConfigMapの`.data`エントリのキーを指定            - name: MYSQL_DATABASE              valueFrom:                configMapKeyRef:                  name: demoapp-mysql-env                  key: DATABASE

だいぶ冗長になりました。envFromは比較的最近追加された機能なので以前はこの方法で書いていましたが大変でした。ConfigMapはできるだけ用途に応じた単位で分割して、envFromを使えるようにした方が良いと思います。

3の方法は、例えば/etc/mysql/my.cnfのような設定ファイルをConfigMapで管理する方法です。.dataエントリに定義した値をファイルとしてPod上の任意のパスにマウントすることができます。この方法についてはこのドキュメントでは扱いませんので、詳細は下記の資料を参照してください。

Configure a Pod to Use a ConfigMap | Kubernetes

ConfigMapとSecretについては、APIオブジェクトの名前(.metadata.name)を${プレフィクス}-${コンポーネント}の形式ではなく、さらに-envを付け加えてdemoapp-mysql-envのような形にしています。これは将来的に環境変数に加えて3の方法で設定ファイルを追加する場合に名前が競合するのを防ぐ意図があります。(設定ファイル用のConfigMapを追加する場合はdemoapp-mysql-confのような名前にするのが良いと思います)

• Configure a Pod to Use a ConfigMap | Kubernetes

mysql-env-secret.yaml: mysqlの環境変数用Secret

最後にmysql-env-secret.yamlを説明します。

# k8s/manifests-step1/mysql-env-secret.yaml---apiVersion: v1kind: Secretmetadata:  name: demoapp-mysql-envdata:  MYSQL_PASSWORD: c2VjcmV0 # echo -n "secret" | base64  MYSQL_ROOT_PASSWORD: dG9wc2VjcmV0 # echo -n "topsecret" | base64

SecretはConfigMap同様キー・バリュー形式で設定値を管理できるAPIオブジェクトですが、パスワードやクレデンシャルなど機密性の高い情報を管理することを前提としています。

Secretは、ConfigMapと比較すると表面的には下記の点が異なります。

• .dataエントリに値を書き込むときはBASE64エンコードして書く必要がある。
• Dashboard上ではデフォルトで値が表示されないようになっている。(クリックで表示させることはできる)
  • GCPのConsole上だと表示できない

また、Secretの中身はPodのtmpfs上に展開されディスクには書き込まれないなど、内部的にはConfigMapよりも安全性に配慮された運用が行われます。セキュリティ上の制限については下記のドキュメントを参照してください。

Encrypting Secret Data at Rest | Kubernetes

Deploymentからの参照方法はほとんどConfigMapと同じなので説明を割愛します。configMapRefの代わりにsecretRefを使う必要がある点にだけ注意してください。

なお、SecretオブジェクトのマニフェストファイルにはBASE64エンコードしただけの値を書いているので平文で機密情報を書いているのと同じです。通常はこのままgitリポジトリにコミットすることはしません。実際の運用の際には sopsやyaml_vault とGCP/AWSのKMSで暗号化するのがおすすめですが、それについてはHelm編で紹介したいと思います。

redis-deploy.yaml: redis の Deployment

次にRedisに関連するマニフェストの内容を説明します。

まずは Deployment から。

# k8s/manifests-step1/redis-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-redis  labels:    app: demoapp    component: redisspec:  replicas: 1  selector:    matchLabels:      app: demoapp      component: redis  template:    metadata:      labels:        app: demoapp        component: redis    spec:      restartPolicy: Always      containers:        - name: redis          image: redis:4.0.9          livenessProbe:            tcpSocket:              port: 6379          readinessProbe:            tcpSocket:              port: 6379          command:            - redis-server            - --appendonly            - "yes"

構造としては mysql-deploy.yaml とほとんど同じです。

commandに関しては、docker-compose-preview.yamlでは下記のように文字列のエントリとして定義していましたが、k8sのマニフェストでは上記の通り配列として定義する必要がある点に注意してください。

services:  redis:    image: redis:4.0.9    command: redis-server --appendonly yes

redis-svc.yaml: redis の Service

続いて Service の内容を確認します。

# k8s/manifests-step1/redis-svc.yaml---apiVersion: v1kind: Servicemetadata:  name: demoapp-redis  labels:    app: demoapp    component: redisspec:  ports:    - protocol: TCP      port: 6379  selector:    app: demoapp    component: redis

componentとポート番号が違うだけでmysqlのものとほとんど同じです。特筆すべき点はありません。

puma-deploy.yaml: puma の Deployment

いよいよRailsアプリ本体のためのマニフェストの説明に移ります。

まずはpuma用のDeploymentから説明します。

# k8s/manifests-step1/puma-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-puma  labels:    app: demoapp    component: pumaspec:  replicas: 1  selector:    matchLabels:      app: demoapp      component: puma  template:    metadata:      labels:        app: demoapp        component: puma    spec:      restartPolicy: Always      containers:        - name: puma          image: demoapp:0.0.1          imagePullPolicy: IfNotPresent          command:            - ./bin/setup-db-and-start-puma          livenessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          readinessProbe:            httpGet:              path: /health_check/full              port: 3000            initialDelaySeconds: 30          envFrom:            - configMapRef:                name: demoapp-rails-env            - secretRef:                name: demoapp-rails-env

• imageにはdocker buildコマンドで指定したイメージ名を指定します。
• imagePullPolicyはIfNotPresentを指定します。前述の通りこのイメージはレジストリに登録していないためです。
• commandにはdocker-compose-preview.ymlと同じく./bin/setup-db-and-start-pumaを指定します。これはpumaの起動前にrails db:setupを試みるスクリプトです。詳細は第2回の記事で説明しました。
• livenessProbeとreadinessProbeではそれぞれ/health_check/fullというパスを指定しています。このサンプルアプリではhealth_checkというgemで死活監視用のエンドポイントを実装しています。このパスを叩くだけでMySQLやRedisとの接続検証を行うことができるようになります。
• envFromでは、demoapp-rails-envという名前のConfigMapとSecretを参照しています。これらのオブジェクトはdocker-compose-preview.ymlにおけるenv_fileに相当する環境変数の設定を保持しています。

puma-svc.yaml: puma の Service

次にpuma用のServiceの定義を確認します。

# k8s/manifests-step1/puma-svc.yaml---apiVersion: v1kind: Servicemetadata:  name: demoapp-puma  labels:    app: demoapp    component: pumaspec:  type: NodePort  ports:    - protocol: TCP      port: 3000  selector:    app: demoapp    component: puma

.spec.typeにNodePortを指定しています。mysqlやredisと異なり、pumaの接続相手は他のコンテナではなくクラスタの外にあるブラウザです。そのため、クラスタ内での通信のためのエンドポイントを生成するClusterIPの代わりにNodePortを指定しています。

NodePortを指定すると、k8sクラスタを構成する全てのノードに、このサービスへ接続するためのエンドポイントが作成されます。.ports[*].nodePortで公開するポートを指定することもできますが、使用中のポートを指定するとエラーになります。無指定の場合は、30000-32767のレンジから自動的に割り当てられます。いずれの場合も、ポート番号は全てのノードで同じになります。

Type NodePort

minikubeの場合、このサービスへ接続するためのURLはminikube service listで確認することができます。

% minikube service list|-------------|----------------------|----------------------------||  NAMESPACE  |         NAME         |            URL             ||-------------|----------------------|----------------------------|| default     | demoapp-mysql        | No node port               || default     | demoapp-puma         | http://192.168.64.25:32320 || default     | demoapp-redis        | No node port               || default     | kubernetes           | No node port               || kube-system | default-http-backend | http://192.168.64.25:30001 || kube-system | kube-dns             | No node port               || kube-system | kubernetes-dashboard | http://192.168.64.25:30000 ||-------------|----------------------|----------------------------|

また、minikube service demoapp-pumaのようにServiceの名前をパラメータとして渡せば、そのURLをブラウザでオープンすることができます。典型的には、http://$(minikube ip):32320のようにminikube ipにランダムなポート番号を与えた形式のURLでアクセスできるようになります。

さて、前述のようにNodePortを指定するとk8sクラスタを構成する全てのノードにエンドポイントが用意されます。minikubeのようにシングルノード構成の検証用クラスタではこれで十分ですが、マルチノード構成の本番環境では不十分です。少なくとも負荷分散や可用性担保のためには前段にロードバランサが必要になるし、k8sの外側でロードバランサの管理をするのは面倒です。

外向けのエンドポイントにロードバランサを組み合わせる場合、通常はLoadBalancerタイプのServiceかIngressというオブジェクトを使います。次回Kubernetes応用編のStep4ではIngressを使ってこの問題に対処する方法を示します。

rails-env-cm.yaml: pumaとsidekiqに共通の環境変数用ConfigMap

下記のような内容です。MySQLやRedisのホスト名として、それぞれmysql-svc.yamlとredis-svc.yamlで定義したServiceオブジェクトの名前を指定しています。

# k8s/manifests-step1/rails-env-cm.yaml---apiVersion: v1kind: ConfigMapmetadata:  name: demoapp-rails-envdata:  RAILS_SERVE_STATIC_FILES: "true"  RAILS_LOG_TO_STDOUT: "true"  SIDEKIQ_TIMEOUT: "60"  MYSQL_HOST: demoapp-mysql  MYSQL_USER: demoapp  MYSQL_DATABASE: demoapp_production  REDIS_HOST: demoapp-redis  REDIS_URL: redis://demoapp-redis:6379/1

rails-env-secret.yaml: pumaとsidekiqに共通の環境変数用Secret

特筆すべき点は特にありません。

mysql-env-secret.yamlの説明の際にも述べたとおり、環境変数の値はこの時点では暗号化されていないため、実際の運用においては sopsやyaml_vault で暗号化するなどしてからgitリポジトリに含める必要があります。

# k8s/manifests-step1/rails-env-secret.yaml---apiVersion: v1kind: Secretmetadata:  name: demoapp-rails-envdata:  SECRET_KEY_BASE: MTIz # echo -n "123" | base64  MYSQL_PASSWORD: c2VjcmV0 # echo -n "secret" | base64

sidekiq-deploy.yaml: sidekiq の Deployment

最後にsidekiq用のDeploymentの定義を見ます。

# k8s/manifests-step1/sidekiq-deploy.yaml---apiVersion: apps/v1kind: Deploymentmetadata:  name: demoapp-sidekiq  labels:    app: demoapp    component: sidekiqspec:  replicas: 1  selector:    matchLabels:      app: demoapp      component: sidekiq  template:    metadata:      labels:        app: demoapp        component: sidekiq    spec:      restartPolicy: Always      terminationGracePeriodSeconds: 65      containers:        - name: sidekiq          image: demoapp:0.0.1          imagePullPolicy: IfNotPresent          command:            - ./bin/start-sidekiq          livenessProbe:            exec:              command:                - ./bin/health-check-sidekiq            initialDelaySeconds: 30          envFrom:            - configMapRef:                name: demoapp-rails-env            - secretRef:                name: demoapp-rails-env

内容としてはほぼpuma-deploy.yamlと同じですが、下記の点に注目してください。

• terminationGracePeriodSecondsはPodにTERMシグナルを送ってからプロセスの終了を待つ時間です。この時間を超えるとプロセスはKILLシグナルで強制的に停止されます。デフォルト値は30秒です(参考)。./bin/start-sidekiqでは-t $SIDEKIQ_TIMEOUTオプションをつけてsidekiqを起動しており、$SIDEKIQ_TIMEOUTにはrails-env-cm.yamlで60秒を指定しているので、terminationGracePeriodSecondsには65秒を設定しています。ローリングアップデートやコンテナ終了時の動作の詳細についてはStep2で説明します。
• livenessProbeはpumaと異なりexecタイプで独自実装のコマンドを呼び出します。内容については後述します。
• Serviceと接続しないためreadinessProbeは定義しません。
• envFromは完全にpumaと同じです。厳密にいうと環境変数SECRET_KEY_BASEは無くても動作するのですが、設定を簡素化するためにpumaと共通化しています。

sidekiqワーカープロセスの死活監視

sidekiqのワーカープロセスには、pumaのようなヘルスチェックのためのインタフェースがありません。sidekiqのオプションでPIDをファイルに書き出すようにすればプロセスの存在確認くらいはできるのですが、そもそもプロセスが停止しているようなケースではコンテナ自体が終了してしまうためk8s側で死亡判定できます。問題は何らかの原因でsidekiqプロセスが生きたまま応答しなくなっているようなケースをいかに検出するかです。

sidekiqのワーカープロセスは定期的に自身のホスト名やプロセスIDなどの情報をRedisに書き込んでいます。この処理はheartbeatと呼ばれています。(詳細はこの素敵な絵文字メソッドを参照)

heartbeatは5秒間隔で実行されますが、60秒間更新が無いと自動的にRedisから削除されるようになっています。heartbeatによってRedisに書き込まれたワーカーのリストはsidekiqのWeb UI上でも確認することができます。

そしてこのワーカーのリストは、SidekiqのAPIでも取得することができます。

https://github.com/mperham/sidekiq/wiki/API#processes

k8sではPodのホスト名はPodの名前と同じになるのでユニークであることが保証されています。livenessProbeで実行しているスクリプト./bin/health-check-sidekiqでは、このAPIを利用してワーカーのリストに自身のホスト名が含まれているかどうかを確認しています。

#!/bin/bash -ecd $(dirname $0)/.../bin/rake sidekiq:status

# lib/tasks/sidekiq.rakenamespace :sidekiq do  desc "Health check for sidekiq worker process."  task status: [:environment] do    require "socket"    hostname = Socket.gethostname    if Sidekiq::ProcessSet.new.any? { |ps| ps["hostname"] == hostname }      exit 0    else      exit 1    end  endend

死活監視が意図したように動作するかどうかは、sidekiqプロセスにSIGSTOPシグナルを送ってサスペンドすれば確認できます。SIGKILLやSIGTERMなどでは即座にコンテナが終了するため、livenessProbeを待たずPodが再起動される点に注意してください。

$ kubectl get podsNAME                               READY     STATUS    RESTARTS   AGEdemoapp-mysql-57d56b47cd-ztc5k     1/1       Running   0          2mdemoapp-puma-749c456c87-6vhrl      1/1       Running   0          2mdemoapp-redis-58f795f487-v2x4j     1/1       Running   0          2mdemoapp-sidekiq-669cd7cb6c-bfhpf   1/1       Running   0          2m$ kubectl exec demoapp-sidekiq-669cd7cb6c-bfhpf -- pgrep -l sidekiq31 sidekiq 5.1.3 app [0 of 25 busy]$ kubectl exec demoapp-sidekiq-669cd7cb6c-bfhpf -- pkill -STOP sidekiq

この後、60秒ほど待つとSidekiqのWeb UI上でワーカープロセスが消えるのを確認できます。さらにその後、だいたい10秒に一度の頻度でヘルスチェックが失敗したというログがsidekiqのPodのイベントログに表示されます。3回失敗したところでコンテナがKillされて再起動し、再びSidekiqのWeb UI上に新しいワーカーが現れるのを確認できます。

$ kubectl get pods --watchNAME                               READY     STATUS    RESTARTS   AGEdemoapp-mysql-57d56b47cd-ztc5k     1/1       Running   0          3mdemoapp-puma-749c456c87-6vhrl      1/1       Running   0          3mdemoapp-redis-58f795f487-v2x4j     1/1       Running   0          3mdemoapp-sidekiq-669cd7cb6c-bfhpf   1/1       Running   0          3mdemoapp-sidekiq-669cd7cb6c-bfhpf   1/1       Running   1         5m$ kubectl describe pod demoapp-sidekiq-669cd7cb6c-bfhpf(省略)Events:  Type     Reason                 Age               From               Message  ----     ------                 ----              ----               -------  Normal   Scheduled              5m                default-scheduler  Successfully assigned demoapp-sidekiq-669cd7cb6c-bfhpf to minikube  Normal   SuccessfulMountVolume  5m                kubelet, minikube  MountVolume.SetUp succeeded for volume "default-token-dzvgp"  Warning  Unhealthy              42s (x3 over 1m)  kubelet, minikube  Liveness probe failed:  Normal   Pulled                 11s (x2 over 5m)  kubelet, minikube  Container image "demoapp:0.0.1" already present on machine  Normal   Created                11s (x2 over 5m)  kubelet, minikube  Created container  Normal   Started                11s (x2 over 5m)  kubelet, minikube  Started container  Normal   Killing                11s               kubelet, minikube  Killing container with id docker://sidekiq:Container failed liveness probe.. Container will be killed and recreated.

まとめ

Step1では、第2回Docker Compose/Dockerfile編のdocker-compose-preview.ymlに相当する構成をDeployment, Service, ConfigMap, Secretの4種のAPIオブジェクトで記述しました。

この時点では下記に挙げる三つの制約があります。

• pumaコンテナを複数起動するとrails db:setupが並列実行されてエラーになる。
• MySQLやRedisのデータが永続化されていないため、コンテナを停止するとデータも消える。
• pumaに外部からアクセスするためのエンドポイントを本番環境で運用するのが難しい。

これらの制約を解消する方法は次回Kubernetes応用編で取り上げたいと思います。

参考情報

• Kubernetes API Reference Docs(v1.10)

• 第一回 Docker編
• 第二回 Docker Compose/Dockerfile編
• 第三回 Kubernetes入門編
• 第四回 Kubernetes基礎編
• 第五回 Kubernetes応用編
• 第六回 Helm編

今回は下記について書きます。

• 最小限のk8s入門
• minikubeの使い方
• kubectlコマンドのチュートリアル

前提

• macOSでの作業を前提としています。
• 使用したツールのバージョンなどは 初回 の記事を参照してください。

はじめに

Kubernetesには膨大な機能があるので、最初から汎用的な使い方を学ぼうとすると挫折しがちです。このドキュメントでは、紹介する機能や概念を「初心者がRailsアプリを動かすために必要な機能」という観点で限定し、かつ段階的に説明していきます。

まずは minikubeを使ってmacOS上の仮想マシンにスタンドアローンのk8sクラスタを作り、そこに前回 Docker Compose/Dockerfile編 で使用したサンプルアプリをデプロイする具体的な手順を示します。

紹介するサンプルコードは全て下記のリポジトリにあります。

https://github.com/kwhrtsk/rails-k8s-demoapp

開発環境の構築

下記のツールを使います。

• minikubek8sクラスタをローカルVM上に構築するためのツールです。
• hyperkitのドライバminikubeがmacOS上でVMを操作するために必要です。
• kubectlk8sクラスタを操作するためのCLIツールです。
• helmk8sのマニフェストをパッケージとして管理するためのツールです。第六回 Helm編で使用します。
• sternk8s上のコンテナのログを見るためのツールです。必須ではありませんがあると便利です。
• GNU MakeXCode付属のものを使います。無くても大丈夫です。

minikubeとkubectlとsternはHomebrew(cask)でインストールできます。

$ brew cask install minikube$ brew install kubernetes-cli kubernetes-helm$ brew install stern

hyperkitのドライバは次の手順でインストールしてください。参考

$ curl -LO https://storage.googleapis.com/minikube/releases/latest/docker-machine-driver-hyperkit \&& chmod +x docker-machine-driver-hyperkit \&& sudo mv docker-machine-driver-hyperkit /usr/local/bin/ \&& sudo chown root:wheel /usr/local/bin/docker-machine-driver-hyperkit \&& sudo chmod u+s /usr/local/bin/docker-machine-driver-hyperkit

macOS版のminikubeでは、hyperkitの代わりにVirtualBoxを使うこともできます。全ての手順は両方で動作を確認していますが、hyperkitの方が高速です。筆者の環境ではRailsアプリやMySQLなど一式k8sにデプロイするのにかかる時間はVirtualBoxだとおおよそ2分20秒前後、hyperkitだと50秒前後でした。

最小限のKubernetes(k8s)入門

Kubernetesとは

k8sはDocker Composeと同じく複数のコンテナを管理するためのツールです。

Docker Composeでは一つのホスト上に複数のコンテナを起動することができましたが、k8sでは複数のDockerサーバで一つのクラスタを構成し、その上に複数のコンテナを分散配置することができます。

また、Docker Composeは単にコンテナの起動や停止だけでなく、コンテナ間通信やボリュームの管理を行うことができましたが、k8sはさらにロードバランサや定期実行ジョブなど実環境で必要になる多様な機能を抽象化し管理することができます。

minikubeとは

k8sをセットアップして使えるようにするためには色々な方法があります。代表的なものをいくつか紹介します。

• GKE: GCP上のマネージドサービス
• kops: AWS上にec2インスタンスを複数起動してk8sクラスタとして構成するツール
• AKS: Azure上のマネージドサービス
• kubespray: オンプレミスを含む任意の環境にk8sクラスタをセットアップするツール

本番環境でk8sを運用するためには上記のようなものを使う必要がありますが、k8sを試してみるだけなら手元の環境で動作するminikubeを使うのが一番簡単です。

minikubeは端末上のVMへk8sをインストールして簡単に使えるようにするためのツールです。VMドライバとしてはVirtualBox、hyperkit、KVMなどがサポートされています。

minikube/drivers.md

macOS上で試すのであれば VirtualBox か hyperkit が簡単です。デフォルトでは VirtualBox が選択されるようですが、hyperkitの方が高速なのでこちらを使うのがおすすめです。

hyperkitはmacOS組み込みの仮想化フレームワーク「Hypervisor Framework」を使うためのツールで、Docker for Macでも使われています。

次節以降ではminikubeの基本的な使い方を説明します。

minikube start: k8sクラスタ用VMの作成と起動

下記のコマンドを実行すると、CPUコア3つ、メモリ2GBを割り当ててminikube専用のVMインスタンスを起動することができます。

# hyperkitを使う場合$ minikube start --cpus=3 --memory=2048 --vm-driver=hyperkit --disk-size=12g# virtualboxを使う場合$ minikube start --cpus=3 --memory=2048 --vm-driver=virtualbox

このドキュメントで紹介する手順は全て上記の構成で動作を確認しています。

hyperkitを使う場合、--disk-sizeを指定しないと無条件に20GBのファイルが~/.minikube/machines/minikube/minikube.rawdisk に作成されます。ホスト側のストレージが足りない場合はこれが原因で起動に失敗することがあるので注意してください。上記の例では12GB割り当てています。

VirtualBoxを使う場合、ストレージファイルは必要に応じて拡張されていくのでサイズ指定は省略しています。ストレージの消費量は起動直後で2GB程度です。

minikube dashboard: k8sダッシュボード

下記のコマンドを実行すると、ブラウザでk8sのダッシュボードが開かれます。

$ minikube dashboard

このダッシュボード上では、k8sクラスタ上の各種オブジェクトの状態の確認や編集を行うことができます。

minikube docker-env: VM上のdockerdに接続するための環境変数の表示

minikubeが動作しているVM上でもDockerプロセスが動作しています。

普段 docker image ls などのコマンドを実行するとDocker for MacのDockerプロセスに接続していますが、下記のようにminikube docker-envで出力される環境変数をロードするとminikube VM上のDockerプロセスに接続することができます。

$ eval $(minikube docker-env)$ docker image lsREPOSITORY                                   TAG        IMAGE ID        CREATED        SIZEk8s.gcr.io/kube-proxy-amd64                  v1.10.0    bfc21aadc7d3    5 weeks ago    97MBk8s.gcr.io/kube-apiserver-amd64              v1.10.0    af20925d51a3    5 weeks ago    225MBk8s.gcr.io/kube-controller-manager-amd64     v1.10.0    ad86dbed1555    5 weeks ago    148MBk8s.gcr.io/kube-scheduler-amd64              v1.10.0    704ba848e69a    5 weeks ago    50.4MB(省略)

通常、自分でビルドしたイメージをk8s上でコンテナとして起動するためには、何らかのレジストリサービスにそのイメージを登録する必要があるのですが、このドキュメントでは手順を簡単にするためにminikube VM上のDockerプロセスに直接接続してRailsアプリのイメージをビルドする方法を紹介します。これについての詳細は次回Kubernetes応用編で説明します。

minikube delete: k8sクラスタ用VMの停止と削除

下記のコマンドを実行すると、k8s用に作成したVMを丸ごと削除します。気軽にk8sクラスタの初期化を行えるのがminikubeの良いところです。

$ minikube delete

k8sの基本

k8sではコンテナを直接操作することはありません。DeploymentやServiceなど抽象化されたリソースを介してコンテナの起動や停止を行います。これらのリソースをk8sではAPIオブジェクトと呼びます(単にオブジェクトと呼ばれることもあります)。

k8sクラスタにAPIオブジェクトを作成したり更新したりする方法には大まかに3つの方法があります。

1. YAML形式のマニフェストファイルをkubectl apply -fで指定して実行する。
2. kubectl create deploymentやkubectl run、kubectl exposeなどのコマンドを実行する。
3. ダッシュボード上のメニューで作成や更新を実行する。

インフラ構成を管理する上で一番望ましいのは、構成をコード化してバージョン管理できる1の方法です。このドキュメントでは、一部の例外をのぞいて全て1の方法で説明します。

一部の例外というのは以下の二つです。詳細は後述します。

• TLS証明書用のSecretオブジェクトの作成
• テストを目的とした対話的な操作のための一時的なコンテナの作成

準備

まずサンプルアプリのコードをチェックアウトしてminikubeを起動してください。

# サンプルアプリのコードをチェックアウト$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp# minikubeを起動$ minikube start --cpus=3 --memory=2048 --vm-driver=hyperkit --disk-size=12g# kubernetesのダッシュボードをオープン$ minikube dashboard

APIオブジェクトのマニフェストファイルとkubectlのチュートリアル

この節ではAPIオブジェクトの例としてDeploymentとServiceを取り上げ、kubectlコマンドを使用してオブジェクトの作成などを行う方法を説明します。

Deploymentの概要

k8sの最も重要なAPIオブジェクトの一つはDeploymentです。状態を持たないアプリケーションのコンテナはDeploymentオブジェクトによって管理します。

Deploymentオブジェクトを作成すると、その配下へ自動的にReplicaSetとPodというオブジェクトが作成されます。

Podはk8sにおいてコンテナを管理するための最小単位です。多くの場合、コンテナと一対一に対応しています。(一つのPodに複数のコンテナを入れることもできますが、それは高度なユースケースであるとドキュメントにも書いてありますし、ここでは取り上げません)

ReplicaSetは、同じ設定で作られたPodがreplicasパラメータで指定された個数だけ維持されるように調整します。

        +--------------+        |  Deployment  |        +------+-------+               |        +------+-------+        |  ReplicaSet  |   replicas: 2        +-+----------+-+          |          |      +---+---+  +---+---+      |  Pod  |  |  Pod  |      +-------+  +-------+

Deploymentは、ReplicaSetを管理します。コンテナイメージの更新などを行う際には新しい設定のReplicaSetを作成して、古いReplicaSetからPodを削除しながら新しいReplicaSetにPodを作成します。

              +--------------+              |  Deployment  |              +------------+-+                :          |   +------------+-+      +-+----------+-+     |  ReplicaSet  |  ->  |  ReplicaSet  |     +-+----------+-+      +-+----------+-+       |          |          |          |     +---+---+  +---+---+  +---+---+  +---+---+ |  Pod  |  |  Pod  |  |  Pod  |  |  Pod  | +-------+  +-------+  +-------+  +-------+

Deploymentのマニフェストファイルの例

以下のYAMLデータはmysql:5.7.21のコンテナを一つ起動するだけのDeploymentのマニフェストファイルです。

# k8s/manifests-step0/mysql-deploy.yaml---apiVersion: apps/v1   # このYAMLデータのスキーマバージョンkind: Deployment      # オブジェクトの種類metadata:  name: mysql         # オブジェクトの名前  labels:             # オブジェクトを選択するために使うラベル(後述)    app: mysql        # 任意のキー・値を設定して良いspec:  replicas: 1         # 起動するPodの数  selector:               matchLabels:      # .spec.template.metadata.labelsと一致させる必要がある      app: mysql  template:    metadata:      labels:         # ReplicaSetとPodに付けられるラベル        app: mysql    spec:      restartPolicy: Always   # コンテナが死亡した際の対応      containers:        - name: mysql         # コンテナのNAME属性に使用          image: mysql:5.7.21 # コンテナイメージ          env:                # 環境変数を指定            - name: MYSQL_ALLOW_EMPTY_PASSWORD              value: "yes"

• Deploymentのドキュメント
• DeploymentのAPIリファレンス

簡単な注釈を加えていますが、わかりにくい部分をいくつか補足します。

• .apiVersion

apps/v1の他に、v1、extensions/v1beta1などの値を取る場合があり、kindとapiVersionの組み合わせによってYAMLデータの構造が決まります。

各オブジェクトのapiVersionの推奨値はk8sのAPIバージョンによって決まっていて、例えば2018年5月30日時点で最新のk8sのバージョン1.10では、DeploymentのapiVersionの推奨値はapps/v1になります。

参考: Workloads API changes in versions 1.8 and 1.9 | Kubernetes

• .metadata.labels

ラベルです。他のAPIオブジェクトの設定からこのDeploymentを参照する際に使用する場合があります。また、kubectl getなど一部のCLIツールでオブジェクトをフィルタリングする際にも使用できます。

• .spec.selector.matchLabels

以前のバージョンでは省略できたのですが、apiVersionがapps/v1になって必須パラメータになりました。必ず .spec.template.metadata.labels にマッチしている必要があります。書き方によっては、別のDeploymentで定義したオブジェクトを参照してしまう場合があるので注意が必要です。

• .spec.template.spec.restartPolicy

コンテナが停止した時に再起動するかどうかをAlways, OnFailure, Neverのいずれかで指定します。参考

このファイルはサンプルコードのk8s/manifests-step0/mysql-deploy.yamlに置いてあります。

以降、このマニフェストファイルを使ってkubectlコマンドの基本的な使い方を説明します。

kubectl apply: APIオブジェクトの作成と更新

前述のYAMLファイルを使ってk8sクラスタにDeploymentオブジェクトを作るには下記のようにします。

$ kubectl apply -f k8s/manifests-step0/mysql-deploy.yamldeployment.apps "mysql" created

複数のYAMLファイルを指定する場合は下記のように標準入力で指定します。

$ cat k8s/manifests-step0/*.yaml | kubectl apply -f -

この際、各オブジェクトの定義が --- で区切られている必要がある点に注意してください。上記のようにcatで結合しやすいように、あらかじめ各YAMLファイルの先頭に --- を入れておくのが良いと思います。

作成したオブジェクトの設定を更新したい場合は、マニフェストファイルを編集してもう一度同じコマンドを実行します。

以前のバージョンでは、作成はkubectl create -f、更新はkubectl apply -fと使い分けていましたが、現在は両方ともkubectl apply -fを使います。

• kubectl apply | Kubectl Reference Docs

kubectl get: APIオブジェクトの状態の確認

Deployment、ReplicaSet、Podオブジェクトの状態を確認するには、下記のようにします。

$ kubectl get deployments,replicaset,podsNAME                          DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGEdeployment.extensions/mysql   1         1         1            1           1sNAME                                     DESIRED   CURRENT   READY     AGEreplicaset.extensions/mysql-55fb9dc7db   1         1         1         1sNAME                         READY     STATUS    RESTARTS   AGEpod/mysql-55fb9dc7db-5mh8v   1/1       Running   0          1s

kubectl getのパラメータにはAPIオブジェクトの種類を示す文字列を指定しますが、略称がある場合はそれを使えます。

# kubectl get deploymentsと同じ$ kubectl get deploy

このドキュメントで扱う主要なAPIオブジェクトの略称は下記の通りです。

完全なリストはパラメータ無しで kubectl get を実行すると表示されます。

• kubectl get | Kubectl Reference Docs

kubectl logs (またはstern): コンテナのログの確認

コンテナのログを確認するには、オブジェクトの種類とNAMEを指定して下記のようにします。NAMEは前述のkubectl getで確認できます。

# Deploymentを指定する場合$ kubectl logs deployments/mysql# ReplicaSetを指定する場合$ kubectl logs replicasets/mysql-55fb9dc7db# Podを指定する場合$ kubectl logs pods/mysql-55fb9dc7db-5mh8v

これはdocker container logs相当の機能です。コンテナの標準出力と標準エラー出力の履歴を確認できます。

Podを指定する場合、マニフェストファイルで設定したラベル(.spec.template.metadata.labels)の値を使って、下記のように指定できます。

$ kubectl logs --selector "app=mysql"# ラベルが複数ある場合はカンマ区切りでAND指定$ kubectl logs --selector "app=demoapp,component=mysql"

ログの閲覧は stern を使うともっと簡単です。Podの名前に対して正規表現でマッチさせることができ、複数のPodのログを一度にtailすることができます。

$ stern "mysql.*"

• kubectl logs | Kubectl Reference Docs

kubectl port-forward: コンテナのポートをホスト側にポートフォワード

Docker ComposeではportsエントリをYAMLファイルに書いておくだけでコンテナのポートをホスト側にマッピングすることができましたが、k8sではクラスタの外側からコンテナに接続するためにはServiceやIngressなど別のAPIオブジェクトを設定する必要があります。

ただし、kubectl port-forwardコマンドを使うと、k8sクラスタのノードにsshで接続して特定のコンテナのポートをホストOSにポートフォワードすることができます。このコマンドではDeploymentまたはPodの名前をパラメータに指定する必要があります。

# Deploymentを指定する場合$ kubectl port-forward deployment/mysql 3306:3306# TYPEを省略するとPodを指定したことになる$ kubectl port-forward mysql-55fb9dc7db-5mh8v 3306:3306

ポート番号は左側がホスト側のポートです。コンテナとホストのポートが同じ場合は3306のように番号を一つだけ指定することもできます。

別のターミナルで下記のコマンドを実行すると、k8s上のmysqlコンテナに接続することができます。オブジェクトの起動直後はエラーになる場合があるので、数秒待ってから試してみてください。

$ mysql -u root --host 0.0.0.0 --port 3306

Podの名前を指定する場合は、下記のようにするとラベルでオブジェクトを選択することができます。

$ kubectl port-forward $(kubectl get pods --selector "app=mysql" --output "jsonpath={.items..metadata.name}") 3306

• kubectl port-forward | Kubectl Reference Docs

kubectl delete: APIオブジェクトの削除

kubectl apply -fで指定したファイルを指定してオブジェクトを削除することができます。

$ kubectl delete -f k8s/manifests-step0/mysql-deploy.yaml

• kubectl delete | Kubectl Reference Docs

Serviceの概要

k8sの最も重要なAPIオブジェクトのもう一つはServiceです。

前節ではmysqlコンテナを管理するDeploymentの例を示しましたが、別のPodからこのMySQLサーバにアクセスするためにはPodのIPアドレスとポートを指定する必要があります。PodのIPアドレスは起動するたびに変わってしまうので、アプリケーションの設定に記述することはできません。

Serviceオブジェクトを作ると、ラベルで指定したPod群へアクセスできるIPアドレスとDNS名がk8sによって用意されます。

前節のmysqlのDeploymentに対応するService定義の例を示します。

# k8s/manifests-step0/mysql-svc.yaml---apiVersion: v1kind: Servicemetadata:  name: mysql  labels:    app: mysqlspec:  type: ClusterIP  ports:    - protocol: TCP      port: 3306     # 接続するPod側のポートを指定  selector:          # 接続するPodのラベルを指定    app: mysql

上記のマニフェストをkubectl applyで実行してServiceオブジェクトを作ると、k8sクラスタ上のコンテナ上ではServiceオブジェクトの名前である"mysql"という文字列をホスト名として指定することでmysqlのDeploymentが管理しているPodにアクセスできるようになります。

.spec.typeにはClusterIP、NodePort、LoadBalancer、ExternalNameのいずれかを指定します。ClusterIPは、このServiceオブジェクトが作るエンドポイントがk8sクラスタの内部向けであることを意味します。k8sクラスタの外側からアクセスできるようなエンドポイントを作る場合にはNodePortまたはLoadBalancerを指定します。このドキュメントでは、最終的にはIngressオブジェクトを使用して外部向けのエンドポイントを用意するため、NodePortやLoadBalancerの詳細については割愛します。また、ExternalNameを使うとk8sの外側のサービスのエイリアスを作ることができますが、このドキュメントでは扱いません。

• Serviceのドキュメント
• ServiceのAPIリファレンス

kubectl run: コマンドによるDeploymentの作成

インフラ構成管理の観点からは全てのDeploymentはマニフェストファイルで管理するのが望ましいのですが、k8sクラスタ上に一時的なコンテナを作成して簡単なオペレーションを実行したい時もあります。

そのような場合にはkubectl runコマンドを使うとYAMLファイル無しでDeploymentを作成することができ便利です。フォアグラウンドで対話的なコマンドを実行することもできるため、トラブルシュートにも最適です。

利用例として、前節までに紹介したmysql用のDeploymentとServiceを作成した後、kubectl runコマンドでシェルを起動し、Serviceによって用意されたエンドポイント経由でMySQLサーバに接続する方法を示します。

まずmysqlのDeploymentとServiceを作成します。

$ kubectl apply -f k8s/manifests-step0/mysql-deploy.yamldeployment.apps "mysql" created$ kubectl apply -f k8s/manifests-step0/mysql-svc.yamlservice "mysql" created$ kubectl get deployments,replicasets,pods,servicesNAME                          DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGEdeployment.extensions/mysql   1         1         1            1           9sNAME                                    DESIRED   CURRENT   READY     AGEreplicaset.extensions/mysql-b59b886c9   1         1         1         9sNAME                        READY     STATUS    RESTARTS   AGEpod/mysql-b59b886c9-955tg   1/1       Running   0          9sNAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGEservice/kubernetes   ClusterIP   10.96.0.1        <none>        443/TCP    1dservice/mysql        ClusterIP   10.110.107.218   <none>        3306/TCP   4s

service/kubernetesはシステム標準のServiceです。service/mysqlというServiceオブジェクトが作成されているのを確認できます。

次に下記のコマンドで新たにmysql:5.7.21イメージのDeploymentを作成します。コンテナの中ではmysqldコマンドの代わりに対話モードでbashを起動して、プロンプトからMySQLサーバに接続します。

$ kubectl run mysql-client --image=mysql:5.7.21 -it --rm --restart=Never /bin/bashIf you don't see a command prompt, try pressing enter.root@mysql-client:/#

上記のようにシェルのプロンプトが表示されたらmysqlコマンドを入力してください。

root@mysql-client:/# mysql -u root --host mysqlWelcome to the MySQL monitor.  Commands end with ; or \g.Your MySQL connection id is 2Server version: 5.7.21 MySQL Community Server (GPL)Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.Oracle is a registered trademark of Oracle Corporation and/or itsaffiliates. Other names may be trademarks of their respectiveowners.Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.mysql>

MySQLサーバに接続できました。kubectl runコマンドのパラメータの意味は次の通りです。

• mysql-clientはDeploymentの名前です。
• --imageはコンテナのイメージ名です。
• -itオプションはdocker container run(旧 docker run)コマンドと同じ意味です。
• --rmオプションを指定すると、コマンドの終了時に自動的にDeployment削除されます。
• --restart=NeverをつけておかないとDeploymentが削除されるまでのわずかな間にPodが再起動されるケースがあり、動作がやや不安定になります。

kubectl explain: ドキュメントの表示

すでに見てきたように、マニフェストファイルは結構複雑な構造のYAMLデータです。慣れないうちはリファレンスを見ながら書くことになると思いますが、公式サイトのドキュメントは個々の機能の解説に注力しているため、今ひとつマニフェスト定義自体の全貌をつかむことができません。

• Deploymentのドキュメント
• Serviceのドキュメント

マニフェストの構造を確認するためにはAPIのリファレンスを参照する方が確実です。

• DeploymentのAPIリファレンス
• ServiceのAPIリファレンス

また、kubectlには指定したオブジェクトのAPIリファレンスを参照する機能があります。Webよりもこちらの方が便利かもしれません。

$ kubectl explain --api-version=apps/v1 deploymentKIND:     DeploymentVERSION:  apps/v1DESCRIPTION:     Deployment enables declarative updates for Pods and ReplicaSets.FIELDS:   apiVersion   <string>     APIVersion defines the versioned schema of this representation of an     object. Servers should convert recognized schemas to the latest internal     value, and may reject unrecognized values. More info:     https://git.k8s.io/community/contributors/devel/api-conventions.md#resources   kind <string>     Kind is a string value representing the REST resource this object     represents. Servers may infer this from the endpoint the client submits     requests to. Cannot be updated. In CamelCase. More info:     https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds   metadata     <Object>     Standard object metadata.   spec <Object>     Specification of the desired behavior of the Deployment.   status       <Object>     Most recently observed status of the Deployment.

オブジェクトの名前に続けて.区切りでフィールドを指定するとネストした要素のドキュメントを参照できます。また、オブジェクトの名前はkubectl getと同じ略称を使うことができます。

$ kubectl explain --api-version=apps/v1 deployment.spec.template.spec.containers.resourcesKIND:     DeploymentVERSION:  apps/v1RESOURCE: resources <Object>DESCRIPTION:     Compute Resources required by this container. Cannot be updated. More info:     https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources     ResourceRequirements describes the compute resource requirements.FIELDS:   limits       <map[string]string>     Limits describes the maximum amount of compute resources allowed. More     info:     https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/   requests     <map[string]string>     Requests describes the minimum amount of compute resources required. If     Requests is omitted for a container, it defaults to Limits if that is     explicitly specified, otherwise to an implementation-defined value. More     info:     https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/

参考情報

Kubernetesのより詳細な情報は下記のドキュメントを参照してください。

• APIリファレンス(v1.10)
  • マニフェストのスキーマに関する網羅的な定義はここが詳しいです。
• Concepts | Kubernetes
  • メニューが階層化しているため慣れるまでわかりにくいですが、各種APIオブジェクトの解説はここが公式なドキュメントです。今回のドキュメントで取り上げたオブジェクトのドキュメントを挙げておきます。
  • Deployments
  • ReplicaSet
  • Pods
  • Services
• kubectl Cheat Sheet | Kubernetes
  • kubectlコマンドのチートシートです。1度目を通しておくと引き出しが増えるのでおすすめです。

おすすめの書籍はこの2冊です。

一冊めの「プログラマのためのDocker教科書」は前回の記事でも紹介した書籍です。おおよそ2章分と比較的大きく紙面を割いてKubernetesの概要と基礎的なAPIオブジェクトの説明がわかりやすく書いてあります。また、GCP上で開発を行う方法がコードの管理からイメージのビルドまで丁寧に説明してあり、付録でGCPの使い方まで説明されていて手厚いです。

一方、Podの死活監視の設定やServiceによるサービスディスカバリの詳細など、少し踏み込んだ内容は大胆に省略してあります。もう少し詳しい仕組みを知りたい場合は二冊目の「入門Kubernetes」で補うのが良いと思います。これ一冊で入門するのは正直しんどいと思うのですが、ある程度知識を持った状態で読むのであればおすすめです。

次回は Kubernetes基礎編 です。

• 第一回 Docker編
• 第二回 Docker Compose/Dockerfile編
• 第三回 Kubernetes入門編
• 第四回 Kubernetes基礎編
• 第五回 Kubernetes応用編
• 第六回 Helm編

今回は下記について書きます。

• 最小限のDocker Compose入門
• Docker Composeを使った各種ミドルウェアのインストールと管理
• RailsアプリケーションのDockerイメージの作り方
• Docker Composeによるローカルプレビュー環境の構築

サンプルアプリケーション

簡単なRailsアプリを例に、Docker Composeの使い方やDockerfileの書き方を説明します。このサンプルアプリrails-k8s-demoappのコードは下記のリポジトリに置いています。

https://github.com/kwhrtsk/rails-k8s-demoapp

rails-k8s-demoappは「フォームでメッセージを送信すると画面上のリストに追加して表示する」だけの小さなアプリです。

仕様は極小ですが、できるだけ一般的なRailsアプリの構成に近くなるように下記の要件を満たすものにしています。

• ミドルウェアとしてMySQLとRedis(SidekiqとActionCableのため)を使用
• ActiveJobを使用: Pumaの他にSidekiqプロセスの起動が必要なケースを想定
  • 新しいメッセージが追加されると、3秒後に逆順の文字列をさらにメッセージとして追加するようなジョブをSidekiqで実行します。
• ActionCableを使用: websocketが必要なケースを想定
  • 新しいメッセージが追加された時にActionCableでブラウザに通知を行いページリロードさせます。
• Webpackerを使用: アセットのビルドにnodeとyarnが必要なケースを想定
  • フロントエンドのコードはTypeScriptで書いています。
  • webpackでBootstrap v4を組み込んでいます。

下記のコマンドで動作を確認することができます。RubyやRailsの開発環境は必要ありません。gitとDockerがインストールされていれば動きます。

$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp$ docker-compose -f docker-compose-preview.yml up -d$ open http://localhost:3000/

docker-composeコマンドの使い方やサンプルアプリケーションで使っているdocker-compose.ymlとDockerfileについては順に説明します。

最小限のDocker Compose入門

Docker Composeとは

複数のコンテナをYAML形式の構成ファイルで一括管理するツールです。

• この構成ファイルを Composeファイル と呼びます。
• 通常、ファイル名はdocker-compose.ymlです。

Railsアプリ開発において、Docker Composeには大きく二つの用途があります。

1. 開発環境におけるMySQLやRedisなどのミドルウェアのインストールと実行管理
2. 完成したRailsアプリを(特に開発者以外が)簡単に手元で実行するための仕組み

以降、それぞれの詳細について説明します。

Docker Composeを使った各種ミドルウェアのインストールと実行管理

一般的なRailsアプリケーションでは、PostgreSQLやMySQLなどのRDBMSに加えて、しばしばRedisやElasticsearchなどのミドルウェアを使用します。従来、macOS上でRailsアプリの開発を行う場合にはこれらのミドルウェアのmacOS版をインストールし、サービスとして起動しておく必要があったため、READMEには長々とセットアップの手順を書いたりしていました。

一方、先に挙げたようなメジャーなプロダクトはいずれも公式のDockerイメージが存在するため、適切に書かれた docker-compose.yml ファイルさえあれば、docker-compose up コマンドを一つ実行するだけで必要なミドルウェアのイメージの取得からコンテナの起動まですべて自動で行うことができます。

また、コンテナとしてミドルウェアを起動する際には個別にバージョンやデータの保存場所を指定できるため、導入の手順が簡単になるだけでなく下記のようなメリットもあります。

• 複数の開発プロジェクトを並行して進める際に、ミドルウェアの細かいバージョンや内部データを完全に独立して管理できる。
• 古いバージョンのミドルウェアを要求するようなプロジェクトの開発環境を維持しやすい。

Composeファイル(docker-compose.yml)のサンプル

前述のサンプルアプリケーションではMySQLとRedisを使います。この2つを起動するためのdocker-compose.ymlは下記のような内容です。通常、このファイルはプロジェクトのルートディレクトリに置きます。

version: "3"services:  mysql:    image: mysql:5.7.21    environment:      - MYSQL_ROOT_PASSWORD=$MYSQL_PASSWORD    ports:      - 3306:3306    volumes:      - ./tmp/mysql:/var/lib/mysql  redis:    image: redis:4.0.9    ports:      - 6379:6379    volumes:      - ./tmp/redis:/data    command: redis-server --appendonly yes

servicesの下にコンテナ(Docker Comoposeの文脈ではサービス)の定義を書いていきます。

mysqlについては、前回Docker編のdocker container run(mysql編) に出てきた docker container runコマンドとやっていることはほぼ同じです。

• environment: 環境変数を追加してコンテナを起動します。
  • .envrcに書かれている環境変数 MYSQL_PASSWORDをrootユーザのパスワードとして設定するため、MYSQL_ROOT_PASSWORDの値として設定しています。
  • ローカルの開発環境で作業を行う際には、direnvなどのツールで.envrcの内容をシェルに設定するという想定です。
  • MYSQL_ALLOW_EMPTY_PASSWORDにyesを設定するとrootのパスワードを空にすることもできます。
• ports: コンテナのポート(右側)をホスト側のポート(左側)にマッピングします。
• volumes: ホスト側のパス(左側)をコンテナ上のパス(右側)にマッピングします。docker container runの-vオプションとは異なり、ホスト側の相対パスで指定できます。

redisのcommandには、データをストレージに永続化するためのオプションを指定しています。

Composeファイルには多数の機能があります。詳細については下記のリファレンスを参照してください。

• Compose file version 3 reference | Docker Documentation
• Compose ファイル・リファレンス | 日本語版 ドキュメント

mysqlとredisのイメージに指定できる環境変数やコマンドのオプションについては、公式リポジトリのドキュメントを参照してください。

• library/mysql - Docker Hub
• library/redis - Docker Hub

docker-compose up: 各種ミドルウェアのインストールと起動

まず、.envrcに書かれた環境変数を設定してください。

$ source .envrc# direnvを使っている場合は下記でも可$ direnv allow

下記のコマンドを実行すると、Docker Hubからmysqlとredisのイメージを取得してコンテナが起動します。(-dはバックグラウンドで起動するという意味です)

-fで任意のComposeファイルを指定できますが、省略するとカレントディレクトリのdocker-compose.ymlが参照されます。

$ docker-compose up -dCreating network "railsk8sdemoapp_default" with the default driverPulling mysql (mysql:5.7.21)...5.7.21: Pulling from library/mysql2a72cbf407d6: Pull complete38680a9b47a8: Pull complete4c732aa0eb1b: Pull completec5317a34eddd: Pull completef92be680366c: Pull completee8ecd8bec5ab: Pull complete2a650284a6a8: Pull complete5b5108d08c6d: Pull completebeaff1261757: Pull completec1a55c6375b5: Pull complete8181cde51c65: Pull completeDigest: sha256:691c55aabb3c4e3b89b953dd2f022f7ea845e5443954767d321d5f5fa394e28cStatus: Downloaded newer image for mysql:5.7.21Pulling redis (redis:4.0.9)...4.0.9: Pulling from library/redisb0568b191983: Pull complete6637dc5b29fe: Pull complete7b4314315f15: Pull complete2fd86759b5ff: Pull complete0f04862b5a3b: Pull complete2db0056aa977: Pull completeDigest: sha256:6b9f935e89af002225c0dcdadf1fd74245b4cc1e3e91222f7e4769c236cf80d4Status: Downloaded newer image for redis:4.0.9Creating railsk8sdemoapp_redis_1 ... doneCreating railsk8sdemoapp_mysql_1 ... done

2回目以降は取得済みのイメージを使用するため、起動は少し早くなります。

• docker-compose up | Docker Documentation
• docker-compose up | 日本語版 ドキュメント

MySQLとRedisが起動した後であれば、下記のように開発環境用の各種プロセスを起動できます。

$ gem install foreman$ bundle install --path=vendor/bundle$ yarn install$ ./bin/rails db:setup$ foreman start -f Procfile

foremanでは、puma、sidekiq、webpack-dev-serverの三つを起動します。(ruby, node, yarnが必要です)

# Procfileweb: ./bin/rails s -p 3000worker: ./bin/sidekiqclient: ./bin/webpack-dev-server

docker-compose ps: コンテナの一覧を取得する

docker-compose.ymlに定義されたサービスのコンテナ一覧を表示します。

$ docker-compose psName                        Command               State           Ports-----------------------------------------------------------------------------------------railsk8sdemoapp_mysql_1   docker-entrypoint.sh mysqld      Up      0.0.0.0:3306->3306/tcprailsk8sdemoapp_redis_1   docker-entrypoint.sh redis ...   Up      0.0.0.0:6379->6379/tcp

コンテナの名前は、${プレフィクス}_${サービス名}_${連番}になります。プレフィクスはカレントディレクトリから-や_を除いた文字列になります。連番がついているのは一つのサービスに複数のコンテナが起動し得るためです。(今回は紹介しませんが、docker-compose scaleコマンドでサービスごとのコンテナの数を増減させることができます)

• docker-compose ps | Docker Documentation
• docker-compose ps | 日本語版 ドキュメント

docker-compose down: コンテナの削除

下記のコマンドを実行すると、docker-compose.ymlに書かれたすべてのサービスのコンテナを停止した後、削除します。-vオプションは関連するデータボリュームも削除するという意味です。(ホスト側のボリュームをマウントしている場合は残ります)

$ docker-compose down -vStopping railsk8sdemoapp_mysql_1 ... doneStopping railsk8sdemoapp_redis_1 ... doneRemoving railsk8sdemoapp_mysql_1 ... doneRemoving railsk8sdemoapp_redis_1 ... doneRemoving network railsk8sdemoapp_default

• docker-compose down | Docker Documentation
• docker-compose down | 日本語版 ドキュメント

最小限のDockerfile入門

RailsアプリのDockerイメージを作る方法を説明します。

Dockerイメージを作るには、まずDockerfileにイメージの作り方を記述します。

サンプルアプリ rails-k8s-demoapp に同梱している下記のようなDockerfileを例に説明します。

### image for buildFROM ruby:2.5.1-alpine AS build-envARG RAILS_ROOT=/appARG BUILD_PACKAGES="build-base curl-dev git"ARG DEV_PACKAGES="libxml2-dev libxslt-dev mysql-dev yaml-dev zlib-dev nodejs yarn"ARG RUBY_PACKAGES="tzdata yaml"ENV BUNDLE_APP_CONFIG="$RAILS_ROOT/.bundle"WORKDIR $RAILS_ROOT# install packagesRUN apk update \ && apk upgrade \ && apk add --update --no-cache $BUILD_PACKAGES $DEV_PACKAGES $RUBY_PACKAGES# install rubygemCOPY Gemfile Gemfile.lock $RAILS_ROOT/RUN bundle install -j4 --path=vendor/bundle# install npmCOPY package.json yarn.lock $RAILS_ROOT/RUN yarn install# build assetsCOPY . $RAILS_ROOTRUN bundle exec rake webpacker:compileRUN bundle exec rake assets:precompile### image for executionFROM ruby:2.5.1-alpineLABEL maintainer 'Kawahara Taisuke <kwhrtsk@gmail.com>'ARG RAILS_ROOT=/appARG PACKAGES="tzdata yaml mariadb-client-libs bash"ENV RAILS_ENV=productionENV BUNDLE_APP_CONFIG="$RAILS_ROOT/.bundle"WORKDIR $RAILS_ROOT# install packagesRUN apk update \ && apk upgrade \ && apk add --update --no-cache $PACKAGESCOPY --from=build-env $RAILS_ROOT $RAILS_ROOT

Dockerfileでは、上記の例のようにFROMやRUNなどのコマンドを一行に一つ書きます。各コマンドの詳細は下記のリファレンスを参照してください。docker image build コマンドでイメージの作成を行うと、Dockerfile に書かれたコマンドが上から順に実行されます。

• Dockerfile reference | Docker Documentation
• Dockerfile リファレンス | 日本語版 ドキュメント

このDockerfileでrails-k8s-demoappのイメージをビルドするには下記のようにします。

$ git clone https://github.com/kwhrtsk/rails-k8s-demoapp.git$ cd rails-k8s-demoapp$ docker image build . -t demoapp:latest

.はビルドコンテキストです。通常、Dockerfileが置いてあるパスを指定します。-tはイメージの名前です。

• docker image build | Docker Documentation
• 旧コマンド名は docker build です。ドキュメントはこちらの方が詳しいです。
  • docker build | Docker Documentation
  • docker build | 日本語版 ドキュメント

これでRailsアプリのイメージができました。下記のコマンドでコンテナを起動できます。

$ docker container run -it --rm demoapp:latest lsGemfile                     libGemfile.lock                logProcfile                    node_modulesREADME.md                   package.jsonRakefile                    publicapp                         specbin                         storageconfig                      testconfig.ru                   tmpdb                          tsconfig.jsondocker-compose-preview.yml  vendordocker-compose.yml          yarn.lockk8s

この例ではlsコマンドを実行してコンテナのファイルを表示しています。上記のようにアプリケーションルートディレクトリの中身が表示されるはずです。

次にDockerfileの中身を順に解説していきます。

FROM

FROMコマンドではベースイメージを指定します。サンプルのDockerfileでは2回出てきますが、このケースでは2つイメージを作っています。

FROM ruby:2.5.1-alpine AS build-env# ...FROM ruby:2.5.1-alpine# ...COPY --from=build-env $RAILS_ROOT $RAILS_ROOT

前半がgemやnpmのC拡張やjsやcssなどのアセットの ビルド用イメージ で、後半がアプリケーションとして運用する 実行用イメージ です。後半では前半のビルドの結果を単にコピーしています。このように2段階に分けてイメージを作成している理由は、イメージのサイズを小さくするためです。詳細は レイヤについて で説明します。

最終的なイメージの成果物は後者の 実行用イメージ です。前者は削除しても構いませんが、残しておくと2回目以降のビルドが差分で実行されるため速くなります(これについても後述)。

次にベースイメージのruby:2.5.1-alpineについて説明します。Docker Hubのrubyリポジトリには大まかに3系統のタグがあります。

• ruby:<version>: Debian stretchベース
• ruby:slim: Debian stretchベースだがインストールされたパッケージが少ない
• ruby:alpine: Alpine Linuxベース

今回はイメージサイズが最も小さいruby:2.5.1-alpineを使います。

% docker imagesruby                2.5.1-alpine        b620ae34414c        9 days ago           55.5MBruby                2.5.1-slim          85b814a932e6        9 days ago           172MBruby                2.5.1               1624ebb80e3e        9 days ago           863MB

また、Alpine LinuxのパッケージマネージャであるapkはDebianのaptと比べてNode.jsやYARNのインストールやキャッシュの制御がより簡単というメリットもあります。

• FROM | Docker Documentation
• FROM | 日本語版 ドキュメント

ENV, ARG

ENVとARGはどちらもコンテナに環境変数を設定するコマンドですが、ARGで指定した環境変数はイメージのビルド時にだけ設定され、作成済みのイメージをコンテナ化した際には残っていないという特徴があります。また、docker image buildコマンドの--build-argやdocker-compose.ymlのargsオプションで上書きすることができます。例えば、プロキシ環境下でイメージをビルドする際にHTTP_PROXYのような環境変数を指定する際には、ENVではなくARGを使うのが望ましいです。

このサンプルではインストールするパッケージの名前などをARGで設定しています。また、ENVでは環境変数 RAILS_ENV を production に設定しています。

### image for build# ...# アプリケーションのインストール先ARG RAILS_ROOT=/app# gemやnpmのC拡張やjs, cssなどのアセットのビルドに必要なパッケージARG BUILD_PACKAGES="build-base curl-dev git"ARG DEV_PACKAGES="libxml2-dev libxslt-dev mysql-dev yaml-dev zlib-dev nodejs yarn"ARG RUBY_PACKAGES="tzdata yaml"ENV BUNDLE_APP_CONFIG="$RAILS_ROOT/.bundle"### image for execution# ...# Railsアプリの実行に必要なパッケージARG PACKAGES="tzdata yaml mariadb-client-libs bash"ENV RAILS_ENV=productionENV BUNDLE_APP_CONFIG="$RAILS_ROOT/.bundle"

BUNDLE_APP_CONFIGはrubyイメージがもともと持っている環境変数です。このDockerfileでは、ビルド済みのbundleディレクトリを丸ごと実行イメージにコピーしたいので、gemのインストール先を${RAILS_ROOT}/vendor/bundleに指定しています。このようにインストール先を変更した場合には BUNDLE_APP_CONFIG を上記のように上書きしないとbundle execが正常に動作しません。

ただし、この挙動は紛らわしいという指摘もあるため、将来の更新で修正されるかもしれません。

introduction of BUNDLE_APP_CONFIG leads to unexpected behavior for ‘statically’ bundled apps Issue #129 · docker-library/ruby

• ENV | Docker Documentation
• ENV | 日本語版 ドキュメント
• ARG | Docker Documentation
• ARG | 日本語版 ドキュメント

WORKDIR

WORKDIRはこのイメージから作成したコンテナ上でコマンドを実行するときのカレントディレクトリです。この例では /app をRailsアプリのルートディレクトリとして指定しているので、WORKDIRも同じパスにしています。

ARG RAILS_ROOT=/appWORKDIR $RAILS_ROOT

また、RUNやCOPYなどのDockerfileのコマンドもWORKDIRで指定したパスで実行されます。

• WORKDIR | Docker Documentation
• WORKDIR | 日本語版 ドキュメント

RUN, COPY

RUNはコマンドを実行します。主にパッケージのインストールやアプリケーションのビルドなどを行います。

COPYはホスト側のファイルをコンテナ側に複製します。この時、.dockerignoreファイルで指定されたファイルは複製されません。パスワードやクレデンシャルのような秘匿値を書いたファイルは忘れずに.dockerignoreに追加してください。また、.dockerignoreに一致したファイルはイメージのビルド時にdockerdへ転送されなくなるため、.gitやnode_modulesなどビルド時に不要でかつサイズやファイル数が大きいディレクトリも指定するのがセオリーです。

今回ベースイメージにしているのはruby:2.5.1-alpineというイメージですが、これはAlpine Linuxというディストリビューションをベースにしています。Alpine Linuxではapkというパッケージマネージャを使います。使用可能なパッケージを下記のサイトで検索できます。Alpine Linux packages

RUN apk update \ && apk upgrade \ && apk add --update --no-cache $BUILD_PACKAGES $DEV_PACKAGES $RUBY_PACKAGES

• RUN | Docker Documentation
• RUN | 日本語版 ドキュメント
• COPY | Docker Documentation
• COPY | 日本語版 ドキュメント
• .dockerignore | Docker Documentation
• .dockerignore | 日本語版 ドキュメント

レイヤについて

Dockerイメージのデータはレイヤと呼ばれる単位で記録されており、DockerfileのRUNやCOPYなどのコマンドは実行するたびに新しいレイヤに結果が記録されます。またイメージのビルドや送受信はレイヤ単位でキャッシュされて差分実行されるため、適切な単位でレイヤを分割しなければビルドやデプロイに無駄な時間がかかるようになります。特に、一度追加したファイルは別のレイヤで削除したとしても以前のレイヤに残り続けるため、イメージ全体のファイルサイズは減らない点に注意が必要です。

一般的に、Dockerfileではイメージのファイルサイズを減らしたりビルドやデプロイの速度を上げるために次のような工夫をします。

• Gemfile、Gemfile.lockのコピーとbundle installの実行はアプリケーションコードのCOPYより前で個別に行う。

gemの追加は比較的頻度の少ない作業なので、こうしておくとbundle installの頻度を減らしてビルドを高速化できます。package.jsonとyarn.lockのコピー、yarnの実行についても同様です。

• ビルド用のイメージと実行用のイメージを分けて、実行時に必要なファイルだけをビルド用のイメージから実行用のイメージにコピーする。

このようにすることでビルドに必要なパッケージが含まれるレイヤを丸ごと削除できます。

「1つのRUNコマンドでパッケージのインストール、ビルド、パッケージやキャッシュの削除を行う」ことでも同じことを実現できますが、パッケージのインストールとビルドのレイヤが同じになるので、アプリのコードを更新しただけでもビルド時にはパッケージのインストールからやり直しになり、余分に時間がかかるようになります。COPYコマンドの--fromオプションは比較的最近追加された機能なので、古いドキュメントにはよくこのようなやり方が書いてあります(古いランタイムに配慮して止むを得ずこのような実装になっているケースもあるかもしれません)。

docker-composeコマンドによるローカルプレビュー環境

RailsアプリのDockerイメージを作れるようになったので、次は「Ruby/Railsの開発環境がなくても、DockerさえあればRailsアプリのイメージを作成して起動できるようにする」ためのComposeファイルを用意します。

ローカルでの開発用に docker-compose.yml がすでにあるので、docker-compose-preview.yml というファイル名で用意します。

version: "3"services:  puma:    image: demoapp    build:      context: .    env_file:      - .dockerenv/rails    ports:      - 3000:3000    depends_on:      - mysql      - redis    command: ./bin/setup-db-and-start-puma  sidekiq:    image: demoapp    env_file:      - .dockerenv/rails    depends_on:      - puma    command: ./bin/start-sidekiq  mysql:    image: mysql:5.7.21    env_file:      - .dockerenv/mysql  redis:    image: redis:4.0.9    command: redis-server --appendonly yes

コードをチェックアウトした後、下記のコマンドを実行するだけでRailsアプリが http://localhost:3000/ に起動するようになります。

$ docker-compose -f docker-compose-preview.yml up -d

ログを見たい場合は-dオプションを外すか、下記のようにしてください。

$ docker-compose -f docker-compose-preview.yml logs -f

後始末は下記のようにします。-vを外すとデータボリュームが残ってしまうので注意してください。

$ docker-compose -f docker-compose-preview.yml down -v

このYAMLファイルのポイントは下記の通り。

• mysqlとredisにはpumaとsidekiqのコンテナから接続できれば良いので、ports(ホスト側へのポートマッピング)エントリを書きません。
  • コンテナ同士は特に設定をしなくても互いのポートにアクセスできます。
• pumaにはbuildエントリを追加して、docker-compose up実行時にイメージをビルドするようにしています。
  • 2回目以降、イメージを強制的にビルドする際には --build オプションをつける必要があります。
• pumaはdepends_onでmysqlを指定して、mysqlコンテナの起動後にrake db:setupが実行されるようにしています。
  • ただしこれだけだと不十分なのでncでmysqlの3306番ポートを確認して起動するまでループします。後述。
• puma、sidekiq、mysqlにはenv_fileを指定し、共通の環境変数をファイルで一括指定します。後述。

pumaとsidekiqのcommandでは、./bin/setup-db-start-puma, ./bin/start-sidekiqというコマンドをそれぞれ指定しています。これは下記のような内容です。

# ./bin/setup-db-and-start-pumacd $(dirname $0)/..trap "pkill -P $$" EXIT./bin/wait-for $MYSQL_HOST 3306./bin/wait-for $REDIS_HOST 6379./bin/rails db:setup_if_not_yet./bin/pumactl start

# ./bin/start-sidekiqcd $(dirname $0)/..trap "pkill -P $$" EXIT./bin/wait-for $MYSQL_HOST 3306./bin/wait-for $REDIS_HOST 6379./bin/sidekiq -t ${SIDEKIQ_TIMEOUT:-8}

pumaやsidekiqの起動をシェルスクリプトでラップする場合、ラッパ側のシェルがTERMやINTなどのシグナルで停止すると子プロセスのpumaやsidekiqが起動したまま残ってしまいます。上記のtrapはそれを防ぐための記述で、スクリプトの停止時に子プロセスへTERMシグナルを送るように指定しています。

sidekiqの-tオプションは実行中のジョブを強制的に停止するまでのタイムアウト値で、オプションを指定しない場合のデフォルト値は8秒です。このスクリプトでは環境変数SIDEKIQ_TIMEOUTでこの値を変更できるようにしています。環境変数が存在しない場合はデフォルト値と同じ8秒が指定されます。

./bin/wait-for は下記のような内容で、パラメータで指定したホストのポートをncコマンドでチェックして接続可能になるまで待機するだけのスクリプトです。

# ./bin/wait-forHOST=$1PORT=$2while :do  nc -w 1 -z $HOST $PORT  if [[ $? = 0 ]]; then    break;  fi  sleep 1done

db:setup_if_not_yetは下記のようなRakeタスクで、まだrake db:setupを実行したことがなさそうな時だけ実行します。

# lib/tasks/db.rakenamespace :db do  task setup_if_not_yet: [:environment] do    begin      ActiveRecord::Base.connection    rescue ActiveRecord::NoDatabaseError      # database not exists      Rake::Task["db:setup"].invoke      exit 0    else      if !ActiveRecord::SchemaMigration.table_exists?        # database exists but tables not exists        Rake::Task["db:setup"].invoke        exit 0      end    end  endend

.dockerenv/railsはpumaとsidekiqに共通の環境変数の設定ファイルです。

RAILS_SERVE_STATIC_FILES=trueRAILS_LOG_TO_STDOUT=trueSIDEKIQ_TIMEOUT=60SECRET_KEY_BASE=123MYSQL_HOST=mysqlMYSQL_USER=demoappMYSQL_PASSWORD=secretMYSQL_DATABASE=demoapp_productionREDIS_HOST=redisREDIS_URL=redis://redis:6379/1

.dockerenv/mysqlはmysql用の環境変数の設定ファイルです。デーベース名、ユーザ名、パスワードを書いています。

MYSQL_USER=demoappMYSQL_PASSWORD=secretMYSQL_DATABASE=demoapp_productionMYSQL_ROOT_PASSWORD=topsecret

公式のmysqlイメージでは、rootユーザのパスワードの他、コンテナの起動時に作成するデータベースとそのデータベースにアクセスできるユーザとパスワードも環境変数で指定できます。.dockerenv/mysqlで設定している4つの環境変数はそのためのものです。

また、Railsアプリ側ではMySQLやRedisの接続先など実行環境に依存するようなパラメータを全て環境変数で受け取れるようにしておく必要があります。

まずデータベースの設定ファイルでは、MYSQL_HOST, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORDでそれぞれDBのホスト名、データベース名、ユーザ名、パスワードを受け取れるようにしておきます。(話を簡単にするため、mysqlコンテナと環境変数の名前を合わせています)

# config/database.ymldefault: &default  adapter: mysql2  encoding: utf8  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>  username: <%= ENV.fetch("MYSQL_USER") { "root" } %>  password: <%= ENV.fetch("MYSQL_PASSWORD") { "" } %>  host: <%= ENV.fetch("MYSQL_HOST") { "0.0.0.0" } %>development:  <<: *default  database: demoapp_developmenttest:  <<: *default  database: demoapp_testproduction:  <<: *default  database: <%= ENV.fetch("MYSQL_DATABASE") { "demoapp_production" } %>

また、ActionCableの設定ファイルでは環境変数 REDIS_URL でRedisの接続先を指定できるようにしておきます。

# config/cable.ymldevelopment:  adapter: redis  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>test:  adapter: asyncproduction:  adapter: redis  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>  channel_prefix: demoapp_production

Sidekiqについてはもともと環境変数 REDIS_URL で接続先を切り替えられる仕様なので特に何もしなくて良いです。別の方法で接続先を指定したい場合は config/initializers/sidekiq.rb というファイルを作って設定を追加します。詳細は下記のドキュメントを参照してください。

Using Redis mperham/sidekiq Wiki

REDIS_HOSTは前述のbin/wait-forに渡すパラメータとして使っています。

SECRET_KEY_BASEはCookieに改ざん検知のためのHMACダイジェストをつけるときの秘密鍵を指定するための環境変数ですが、Rails 5.2.0のデフォルトの動作ではCredentialsで暗号化されたファイル config/credentials.yml.enc に書かれた値を鍵として使うようになっています。下記のコマンドでこのファイルの中身を確認できます。

% ./bin/rails credentials:show# aws:#   access_key_id: 123#   secret_access_key: 345# Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.secret_key_base: f758dcb894cf0fee1b68f7989ebd65f5fd0dbb3c366e61789c112836789dfda22def856b6419ae96447352bbdd8873b90ae0096cd61d9532775caca8c04e0783

ただ、この値は本番環境でも使う値になるので、今回のような不特定多数に配布するのが前提のプレビュー環境には使えません。HMAC用の鍵はCredentials の値よりも環境変数SECRET_KEY_BASEの値が優先される実装になっているので、今回は環境変数を設定します。また、Credentialsの秘密鍵(環境変数RAILS_MASTER_KEYまたはconfig/master.key)は設定しません。(デフォルトでは設定しなくてもエラーにはなりません。)

RAILS_SERVE_STATIC_FILESは、jsやcssなどのファイルをpumaが応答するかどうかを指定するための設定値です。これはRails標準の仕組みで、実装は config/environments/production.rb を参照してください。本番環境ではこのような静的なアセットファイルはnginxやCDNで配信するのが望ましいのですが、今回は構成を簡単にするためにtrueにしておきます。

RAILS_LOG_TO_STDOUTは、production環境でRailsのログ出力先を標準入力に切り替えるための環境変数です。これもRails標準の仕組みで、実装は config/environments/production.rb を参照してください。

こういった環境変数設定用のファイルに本番環境の値を書く場合には、GitリポジトリやDockerイメージに含めないように注意してください。.gitignore と .dockerignore にそれらのファイル名を書いておくと意図せず混入させることを防ぐことができます。

本稿では、docker-compose-preview.ymlで構築するのはあくまでプレビュー用の環境であり、本番環境はKubernetesで構築するという前提です。Kubernetes上のアプリに環境変数を設定する際には全く別の方法を用いるため、Composeファイルなどに書いた設定値は全て本番環境とは異なる値という想定なので、リポジトリにコミットしています。

また、env_fileで指定するファイルは、direnvで使う.envrcなどシェルに環境変数を設定するスクリプトとは根本的に異なるものなので下記の点に注意してください。

• exportはつけない。
• コマンドは実行できない。
• 値をクオートしてはいけない。(環境変数に'や"を含む形で設定されてしまいます)

コンテナ間の通信について

コンテナにはそれぞれ固有のIPアドレスが割り当てられます。docker container runコマンドで起動したコンテナ同士が互いのIPアドレスを知るためにはオプション指定が必要ですが、docker-composeで起動したコンテナ同士は、互いのサービス名をホスト名として通信できるように自動的に設定されます。また、ホスト側からコンテナに接続する際にはportsエントリでポートマッピングの設定を書く必要がありましたが、docker-composeで起動したコンテナ同士はこういった設定なしで互いの全てのポートにアクセスできます。

MySQLの接続設定をもう一度掲載します。下記のようにMYSQL_HOST環境変数でホスト名を指定するようになっています。

# config/database.ymldefault: &default  adapter: mysql2  encoding: utf8  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>  username: <%= ENV.fetch("MYSQL_USER") { "root" } %>  password: <%= ENV.fetch("MYSQL_PASSWORD") { "" } %>  host: <%= ENV.fetch("MYSQL_HOST") { "0.0.0.0" } %># 省略production:  <<: *default  database: <%= ENV.fetch("MYSQL_DATABASE") { "demoapp_production" } %>

.dockerenv/railsでは下記のようにmysqlという文字列をMYSQL_HOST環境変数に設定していました。

MYSQL_HOST=mysql

このmysqlというのは、docker-compose-preview.ymlのサービス名を指しています。

version: "3"services:  # 省略  mysql: # <- これがサービス名    image: mysql:5.7.21  # 省略

docker container runコマンドに--linkオプションをつけるとdocker-composeが自動的に準備してくれていたようなことを手動で行うこともできますが、Railsアプリ開発という主題においては必要になる場面はほぼ無いと思いますので、詳細は割愛します。

ローカル開発環境のRailsアプリをDocker化するかどうか

少なくともホストOSがmacOSなのであれば、ローカルの開発環境においてはRailsアプリまでDockerコンテナの上で動かす必要はないと筆者は考えています。

• RailsアプリがmacOSで動いてLinux(コンテナ)だと動かないケースは多くない。
• 多くの場合、macOS上でRailsアプリの開発環境を用意するのはそれほど面倒ではない。
• ./bin/rails gや./bin/rails cなどちょっとしたコマンドが全てdockerコマンド経由になるのは煩雑すぎる。
• springの対応が面倒

以上の理由で、私の主観ではメリットをデメリットが上回っていると感じるので、開発環境においては下記のような構成をとっています。

• Railsプロセス自体はホスト側(macOS/Linux)で直接起動する。
• Railsプロセスが接続するMySQLやRedisなどのミドルウェアはdocker-compsoeで起動する。

参考情報

Docker Composeのより詳細な使い方は下記のドキュメントを参照してください。

• docker-composeコマンドについて
  • Overview of docker-compose CLI | Docker Documentation
  • Compose CLI リファレンス | 日本語版 ドキュメント
• Composeファイル(docker-compose.yml)について
  • Compose file version 3 reference | Docker Documentation
  • Compose ファイル・リファレンス | 日本語版 ドキュメント

Dockerfileのより詳細な仕様については下記のドキュメントを参照してください。

• Dockerfile reference | Docker Documentation
• Dockerfile リファレンス | 日本語版 ドキュメント

おすすめの書籍は「プログラマのためのDocker教科書」です。2018/4/11に第2版が出ました。

前回のDocker編で扱った範囲も含めて、本ドキュメントでは紹介しなかったコマンドやDockerfile/Composeファイルの機能が一通り紹介されています。また、コンテナ技術の概要や使いどころ、プライベートレジストリやイメージの公開方法などDocker周辺を広く浅く解説してあり、入門には良い書籍だと思います。後半ではKubernetesにも軽く触れてあります。

次回は Kubernetes入門編 です。

概要

この記事はシリーズ連載記事の第一回です。シリーズ全体の概要は次の通りです。

はじめに、DockerやKubernetesの概要について簡単に説明しつつ、dockerコマンドやkubectlコマンドの基本的な使い方をチュートリアル風味で紹介します。

次に、ごく小さな仕様の具体的なRailsアプリを題材として、Docker Composeの構成ファイルやKubernetesのマニフェストの具体的なサンプルと使い方を示し、最終的にHelmを使ってKubernetesクラスタにデプロイする方法を説明します。

DockerとKubernetesの全機能を網羅的に学ぼうとすると膨大な時間が必要になるので、この記事では「RailsアプリをKubernetesで運用すること」にフォーカスして一つ一つの概念や機能の詳細は必要最小限に絞り、より詳細な資料へのポインタを置くに留めます。

シリーズ全体の構成は次の通りです。

• 第一回 Docker編
  • 最小限のDocker入門
  • dockerコマンドのチュートリアル
• 第二回 Docker Compose/Dockerfile編
  • 最小限のDocker Compose入門
  • Docker Composeを使った各種ミドルウェアのインストールと管理
  • RailsアプリケーションのDockerイメージの作り方
  • Docker Composeによるローカルプレビュー環境の構築
• 第三回 Kubernetes入門編
  • 最小限のk8s入門
  • minikubeの使い方
  • kubectlコマンドのチュートリアル
• 第四回 Kubernetes基礎編
  • kubectlコマンドとYAML形式のマニフェストファイルでRailsアプリをk8sにデプロイする方法
• 第五回 Kubernetes応用編
  • 基礎編で残した課題の解決編
• 第六回 Helm編
  • 最小限のHelm入門
  • HelmでRailsアプリをk8sにデプロイする方法

全てのサンプルコードはここにあります。

https://github.com/kwhrtsk/rails-k8s-demoapp

前提

• 各種ツール類のインストール手順はmacOSでの作業を前提としています。
• HomebrewとHomebrew-Caskを使います。
  • Homebrew-Caskのインストールはbrew tap caskroom/cask
• Docker for Macを使います。
  • Docker Community Edition for MacのGet Dockerをクリック
• k8s関連ツールのインストール手順は後述します。
• ツールのインストール手順を除けば、Linuxでもおおよそ同じ手順で動作を確認できると思います。

それぞれ下記のバージョンで動作を確認しています。

最小限のDocker入門

Docker初心者がRailsアプリをk8sで動かすまでに最低限必要なDockerについての知識とdockerコマンドの操作方法を書きます。Rails固有のトピックを知りたい人は Docker Compose/Dockerfile編 までスキップしてください。

Dockerとは

LXC(Linux Containers)と呼ばれる技術を使ってアプリケーションの開発やデプロイを行うためのツール及びプラットフォームです。LXCやDockerについて解説されたドキュメントは山ほどあるのでここでは詳細は割愛します。

• 15分で分かるLXC（Linux Containers）の仕組みと基本的な使い方 | さくらのナレッジ
• 第1回 Dockerとは : 超入門Docker - ＠IT

dockerのコマンド体系について

2017年1月にリリースされたDocker 1.13で docker コマンドの構成が整理されました。アナウンスは Introducing Docker 1.13 - Docker BlogのCLI restructuredの部分です。

「旧コマンドは引き続きサポートするが、新コマンドの使用を勧める」とのことなのでこのドキュメントでは新しいコマンド体系で説明します。ただ、古いドキュメントには旧コマンド体系で書かれているものも多いため、対応する旧コマンドについても紹介します。

このドキュメントで紹介するコマンドの新旧対応は下記の通りです。基本的にはimageかcontainerのサブコマンドへの移動ですが、一部違うものがあるので太字にしています。

以降の節で順にこれらのコマンドの使い方を説明します。見出しの括弧は旧コマンドです。

また、各節の終わりにリファレンスへのリンクを置いていますが、少なくとも本稿の執筆時点においては旧コマンドの方が詳細に書かれているので、必要に応じてそちらも参照してください。なお日本語版のドキュメントにはまだ新コマンド版のリファレンスはありません。

シェルの補完について

dockerのサブコマンドは、 861162a44 のようなハッシュ値や、romantic_neumann のようにランダムな英単語の組み合わせで自動生成されたコンテナ名をパラメータとして受け取ります。

Docker for Macにはbashやzshでコマンドの補完を行うためのスクリプトが同梱されていますが、ただインストールするだけでは有効になりません。補完のための設定については別に記事を書いたのでこちらを参照してください。

bash/zshとfzfでDocker関連コマンドの補完を行う方法

docker image pull (docker pull): イメージを取得する

イメージとはコンテナの雛形です。docker image pullコマンドでリポジトリとタグを指定し、イメージを取得します。MySQLの公式リポジトリから5.7.21のタグが付いたイメージを取得する場合は下記のようにします。

$ docker image pull mysql:5.7.215.7.21: Pulling from library/mysql2a72cbf407d6: Pull complete38680a9b47a8: Pull complete4c732aa0eb1b: Pull completec5317a34eddd: Pull completef92be680366c: Pull completee8ecd8bec5ab: Pull complete2a650284a6a8: Pull complete5b5108d08c6d: Pull completebeaff1261757: Pull completec1a55c6375b5: Pull complete8181cde51c65: Pull completeDigest: sha256:691c55aabb3c4e3b89b953dd2f022f7ea845e5443954767d321d5f5fa394e28cStatus: Downloaded newer image for mysql:5.7.21

タグは、多くの場合バージョンを指します。ただし、ここでいうバージョンはイメージのバージョンではなく、アプリケーションのバージョンであることが多いため、同じタグを指定してもタイミングによって違うイメージを取得するケースがある点に注意が必要です。

例えばmysql:5.7は現時点ではmysql:5.7.21と同じイメージを指していますが、以前はmysql:5.7.20を指していました。タグを指定しないとlatestというタグを指定したとみなされます。

リポジトリを管理しているサービスをレジストリと呼びます。MySQLやRedisなどの主要なプロダクトの公式イメージは Docker Hub というレジストリで配布されており、上記の例ではDocker Hub上のリポジトリからイメージを取得しています。Docker Hub上のリポジトリは下記のページで探すことができます。

https://hub.docker.com/explore/

Docker Hub以外のレジストリを使う場合は下記のようにリポジトリの前にレジストリのホスト名とポート番号を書きます。例えばローカルレジストリ myregistry.local:5000 から testing/test-image を取得する場合は下記のようになります。

$ docker image pull myregistry.local:5000/testing/test-image

• docker image pull | Docker Documentation
• 旧コマンド名は docker pull です。ドキュメントはこちらの方が詳しいです。
  • docker pull | Docker Documentation
  • docker pull | 日本語版 ドキュメント