CloudNative Days の『一日で学ぶクラウドネイティブ技術実践ハンズオン』で、イベント用の受講環境を作り直しました。受講者は配布された URL をブラウザで開くだけで、ハンズオンを始められます。目標は、参加するために必要なインフラの知識をできるだけ減らすことです。
背景
このハンズオンの手順書は GitHub で公開していて、誰でも自分で進められるように書かれています。自分で VM を作り、手元の端末から触る前提です。名前解決は手元の hosts ファイルで行い、アプリには example.com のドメインに HTTP でアクセスします。
イベントでは、実行委員会が受講者 1 人に 1 台ずつ AWS の VM を用意します。ただ、手順書はローカル前提のものをそのまま使っていました。そのため受講者は、VM に入るまでに次の作業が必要でした。
- 配布された
.pemの鍵で、VM に SSH する - 手元の
hostsファイルに、VM の IP とドメインを 25 行ほど書く - 手順書の
example.comを、自分の環境のドメインに読み替える
どれも Kubernetes の学習とは関係のない作業です。ここで詰まると、最初の章から遅れてしまいます。
| 年 | 作業のしかた |
|---|---|
| 一昨年まで | 受講者が自分の端末から VM に SSH する |
| 去年 | VM で code-server をホストし、ブラウザ版の VS Code で作業する |
| 今年 | 手順書とターミナルを並べた、ハンズオン専用の画面で作業する |
去年は code-server を入れて SSH を不要にしましたが、 hosts と読み替えはそのままでした。どちらの年も、ローカル前提のハンズオンを、こちらで用意した VM の上で動かしてもらう形です。今年は考え方を変えて、ハンズオンイベントのための環境として整えました。
今年からやったこと
- VM ごとにドメインを割り当てて、
hostsの設定と読み替えをなくした - HTTPS で配信して、ブラウザの警告をなくした
- 手順書とターミナルを 1 画面に並べた
- ログインを、token 付きの URL を開くだけにした
VM ごとのリソースは、すべて Terraform で作っています。
VM ごとにドメインを割り当てた
ローカルで進めるなら、 hosts に example.com を書けば十分です。開くのは自分の端末だけなので、本物のドメインは要りません。
イベントでは数十人の受講者が、それぞれ別の VM を使います。受講者ごとに hosts を書いてもらう代わりに、VM ごとに本物のドメインを割り当てました。Route53 に、VM ごとのワイルドカードレコードを登録しています。
resource "aws_route53_record" "wildcard_records" {
count = local.num_vms
zone_id = aws_route53_zone.delegated.zone_id
name = "*.vm${format("%02d", count.index + 1)}.handson.cloudnativedays.jp"
type = "A"
ttl = 300
records = [aws_instance.ubuntu_instance[count.index].public_ip]
} これで argocd.vm01.handson.cloudnativedays.jp や grafana.vm01.handson.cloudnativedays.jp が vm01 に向きます。
手順書の example.com は、VM の起動時にその VM のドメインに置き換えます。受講者は、手順書の URL をそのまま開けます。
(cd cnd-handson && git grep -lzI '\.example\.com' | xargs -0 -r perl -pi -e "s/\.example\.com/.$KP2_HOST/g") HTTPS で配信した
ローカルで進めるなら、HTTP でも困りません。イベントでは、受講者のブラウザから VM のアプリを開きます。HTTP のままだと、ブラウザに「保護されていない通信」の警告が出ます。慣れていない人ほど、ここで手が止まります。
VM ごとに本物のドメインを割り当てたので、公開の証明書を発行できます。証明書は Terraform の ACME プロバイダで、Let's Encrypt から発行しています。VM の上では Caddy が TLS を終端します。Caddy はホスト名を見て、kp2、code-server、ハンズオンで作る Ingress に振り分けます。
手順書とターミナルを 1 画面に並べた
Kubernetes のハンズオンは、ターミナルでコマンドを実行する作業が中心です。YAML を書き換える場面は多くありません。去年の code-server はエディタが中心の画面で、この進め方には合っていませんでした。今年は、手順書を読みながらコマンドを実行する画面に変えました。
この画面には、弊社のエンジニアが趣味で作っている kp2 というツールを使いました。kp2 は、Markdown の手順書を読みながら、ブラウザ上のターミナルでコマンドを実行するためのツールです。
画面の構成
ブラウザの左に Markdown の手順書を、右にターミナルを表示します。ターミナルでは VM のシェルが動いています。手順書はハンズオンのリポジトリの Markdown をそのまま表示するので、手順書用に別の資料を作る必要はありません。
ファイルの編集は vim を基本にしています。VS Code に慣れている人向けに、右上の Editor から code-server も開けます。
コマンドの実行
手順書のコードブロックには、Copy、Insert、Run の 3 つのボタンが付きます。
- Copy:クリップボードにコピーする
- Insert:ターミナルに入力だけする。値を直してから実行したいときに使う
- Run:ターミナルで実行する。コードブロックをダブルクリックしても実行できる
手順書とターミナルの間で、コピーと貼り付けを繰り返す必要がなくなりました。長いコマンドを貼り損ねたり、一部だけ実行したりするミスも減ります。
仕組み
kp2 は Rust で書かれた単一のバイナリです。ビルド済みの UI を同梱しているので、VM には kp2 を置いて起動するだけで動きます。
Browser
Markdown ──Run──▶ xterm.js ──WebSocket /ws──▶ kp2 (Rust) ──▶ PTY ──▶ $SHELL
│
└─ code-server ──▶ ブラウザ版 VS Code ブラウザのターミナルには xterm.js を使っています。kp2 が VM 上で PTY を開いてシェルを起動し、WebSocket でブラウザとつなぎます。Run ボタンを押すと、コマンドがこの WebSocket を通ってシェルに送られます。code-server が入っていれば、kp2 がそれを起動して Editor のペインに表示します。
VM では、systemd で kp2 を常駐させています。
kp2 --docs /home/ubuntu/cnd-handson --workspace /home/ubuntu \
--allowed-origin https://vm01.handson.cloudnativedays.jp --editor-url /code/ --docs で手順書のフォルダを、 --workspace でターミナルの開始ディレクトリを指定しています。残りの 2 つは、リバースプロキシの後ろで動かすために今回追加したオプションです。kp2 はもともと、ローカルで動かす前提のツールでした。
-
--allowed-origin:ターミナルへの接続を許可するオリジンを指定する -
--editor-url:エディタのペインで開く code-server の URL を指定する
URL を開くだけでログインできるようにした
VM は外から見えるので、誰でも開けるようにはできません。かといって、ID とパスワードを打ってもらうのも手間になります。そこで、VM ごとに token を作り、token 付きの URL を受講者に配布しました。
https://vm01.handson.cloudnativedays.jp/?token=xxxxxxxx URL を開くと、Caddy が Cookie を発行して、token を外した URL にリダイレクトします。以降は Cookie でログインした状態になります。
@login query token=xxxxxxxx
handle @login {
header Set-Cookie "kp2_token=xxxxxxxx; Path=/; Max-Age=604800; HttpOnly; Secure; SameSite=Lax"
redir * / 302
}
@noauth not header Cookie *kp2_token=xxxxxxxx*
respond @noauth "Open the kp2 URL you were given" 401 当日
Kubernetes やインフラの初心者にも、コンテナや Kubernetes を理解するハンズオンを提供できました。これまで対象にしきれていなかった層の人たちです。
同じ時期に、新しく加わった実行委員の方が、Kubernetes のイントロダクションとオーバービューの章を大きく更新してくれました。環境と手順書の両方を入門者向けに整えたことで、これまでフォローしきれなかった層まで対応できました。
最後に、準備から当日まで支えてくれた実行委員のみなさん、本当にありがとうございました。