Jenkins のシステム設定を yaml で書けるようにする Configuration as Code プラグイン

これまで GUI から行っていた Jenkins のシステム設定を yaml で設定できる Configuration as Code プラグインについて解説します。

これまでの Jenkins as Code

〇〇 as code は近年いろいろなところで見かけますが、設定をコード化するとソフトウェア開発のプラクティスを適用できるようになり、以下のようなメリットがあります。

バージョン管理できる
- 変更を追跡できる
- 変更に問題があったときに素早く前の状態に戻せるので安全
GUI では設定が多いときに時間がかかるけど、コードで自動化されれば高速
簡単に再利用できる

Jenkins にも as code の波は来ています。例えば Docker を使えば Jenkins の master の環境構築をコード化できますし、ジョブの設定は Jenkinsfile を使えば groovy で記述することができます。

実はシステム設定についてもこれまでにコード化しようとする取り組みはありました。例えば、JENKINS_HOME に init.groovy という groovy スクリプトを置くと Jenkins の起動時にスクリプトを実行することができる仕組みがあります。

Post-initialization script - Jenkins - Jenkins Wiki

しかし、この仕組みを使うには groovy と Jenkins 内部への理解が必要で、GUI と比較すると手軽とは言えないものでした。

Configuration as Code プラグイン

上記の問題を解決するために新たに開発されたのが Configuration as Code プラグインです。このプラグインの記述は yaml なので特定のプログラミング言語の知識が必要なく、GUI の設定をそのままコード化したような構造なので Jenkins 内部への理解も必要ありません。

Configuration as Code のデザインについては JEP-201 で確認できます。

デモ用リポジトリ

Configuration as Code プラグインにはデモ用のリポジトリが存在します。

github.com

このプラグインの仕組みを理解するために動かしてみます。将来的には以下の手順が古くなって動かなくなる可能性があるので注意してください。ちなみに、この記事執筆時点のコミットハッシュは 5a89395d060c6059a754d6e587e8dac6a2c119f3 です。

このデモ環境を構築するためには、以下のものを事前に用意しておきます。

github アカウント
Jenkins の admin アカウントのパスワード
ssh の秘密鍵を ~/.ssh/id_rsa に保存

用意できたら動かしてみます。

$ git clone https://github.com/Praqma/praqma-jenkins-casc.git
$ cd praqma-jenkins-casc
$ vi jenkins.yaml
# "username: ReleasePraqma" となっている部分を用意した github のユーザー名に変更して保存
$ echo -n "<用意した github アカウントのアクセストークン>" > /var/deploy/secrets/github
$ echo -n "Jenkins の admin に設定するパスワード" > /var/deploy-secrets/adminpw
$ docker-compose up --build

もし mac で ERROR: for jenkins Cannot create container for service jenkins: invalid mount config for type "bind": bind source path does not exist というエラーが表示された場合は、Docker → Preferences → File Sharing で /var/deploy/secrets とこのデモ用リポジトリのディレクトリを追加する必要があります。

起動したら、localhost にアクセスすると Jenkins の画面が表示されるはずです。右上の「ログイン」をクリックし、ユーザー名 demoAdmin、パスワードは /var/deploy/secrets/adminpw に設定したパスワードでログインできます。

「Jenkins の管理」→「システムの設定」を見るといろいろ設定されているのが確認できます。

プラグインの仕組み

このデモ用リポジトリを元にプラグインの仕組みを見てみます。

まず、デモ環境はリポジトリ直下にある jenkins.yaml を元に Jenkins のシステム設定が行われます。例えば、jenkins.yaml を見てみると以下のような設定があります。

jenkins:
  systemMessage: "Welcome to the demo setup for Jenkins Configuration as Code plugin. For more information look in the official repo with our demo setup: https://github.com/Praqma/praqma-jenkins-casc"

この設定は、システムの設定にある「システムメッセージ」に対応しています。jenkins ブロック下の設定は Jenkins 本体のシステム設定に相当するみたいです。GUI の設定と対応がわかりやすいので、なんとなくでも理解はできますね。

シークレットの変数埋め込み

credentials:
  system:
    domainCredentials:
      - credentials:
          - usernamePassword:
              scope: SYSTEM
              id: github-user
              username: miyajan
              password: ${github}

credentials ブロックには上のような設定が書かれています。usernamePassword はユーザーの設定のようです。

${github} の変数部分はシークレットを yaml に直接書かずに渡すための書き方です。/var/deploy/secrets に置いたファイルが docker-compose の secrets で Jenkins コンテナの /run/secrets 下に置かれ、プラグインが /run/secrets 下のファイル名をキー、中身を値として変数に埋め込んでくれるようです。

読み込む jenkins.yaml の指定

docker-compose.yml の中に以下のような設定があります。

environment:
  - CASC_JENKINS_CONFIG=/var/jenkins_home/jenkins.yaml

Configuration as Code プラグインは CASC_JENKINS_CONFIG という環境変数を見て jenkins.yaml を読み込むようです。ここにはローカルファイルのパスだけでなくて、URL を指定することもできます。

Configuration as Code プラグインについての画面

「Jenkins の管理」→「Configuration as Code」に遷移すると Configuration as Code プラグインについての画面が表示されます。

例えば、"Documentation" リンクをクリックすると jenkins.yaml の設定のドキュメントが表示されます。インストールされているプラグインによって変わるので Jenkins から動的に生成しているようです。

"Export Configuration" をクリックすると現在の Jenkins の設定がこのプラグインで使える jenkins.yaml として出力されます。しかし、この機能で出力される yaml はそのまま使えるレベルではなく、あくまでも設定の参考にするための機能のようです。（ちなみに、自分が普段使ってる Jenkins で試したところ Java のスタックトレースが yaml の中に含まれていましたｗ）