生産性向上ブログ

これまで 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 の中に含まれていましたｗ）

プラグインの対応状況

他のプラグインが Configuration as Code プラグインに対応するには、プラグインを修正する必要があるようです。プラグイン開発者向けのドキュメントがあります。

github.com

また、各プラグインの Configuration as Code プラグインに関する issue を一覧するためのダッシュボードがあります。

JCasC Compatibility - Jenkins JIRA

これを見ればある程度はプラグインの互換性についての問題を把握できます。

まとめ

デモを軽く動かしたレベルですが、Configuration as Code プラグインについてまとめてみました。

正直まだドキュメントが少なく、他プラグイン側での対応もまだこれからと思われるので、実用的になるのはまだ先ではないかと思われます。

しかし、Jenkins おじさんであればシステム設定をコード化したいと思ったことが一度はあるはずなので、このプラグインが発展していけばより堅牢な Jenkins が運用できるようになるのではと思われます。今後に期待です。

過去に、『CircleCI 2.0 で定期実行ジョブ（Nightly Builds）を実現する』という記事を書いたのですが、現在の CircleCI 2.0 ではもっと楽に cron 的な定期実行ジョブを記述できるようになっているので補足記事を書きます。

前の記事を書いた時点では CircleCI 自体にジョブ実行タイミングをスケジュールする機能がなかったので、外部の Lambda なりなんなりを使って API を叩くという遠回しな手段をとっていましたが、今では Workflows に "triggers" という構文が追加されているので、CircleCI のみで完結して定期実行ジョブを記述できるようになっています。

circleci.com

↑の記事を見てもらうのが一番わかりやすいと思いますが、英語しかないので一応こちらでも解説します。

version: 2
jobs:
  build:
    docker:
      - image: buildpack-deps:trusty
    steps:
      - run:
          command: echo 'build'
  nightly-build:
    docker:
      - image: buildpack-deps:trusty
    steps:
      - run:
          command: echo 'nightly-build'
workflows:
  version: 2
  commit-workflow:
    jobs:
      - build
  scheduled-workflow:
    triggers:
      - schedule:
          cron: "0 1 * * *"
          filters:
            branches:
              only:
                - master
    jobs:
      - nightly-build

上記の設定ですと、以下の 2 つのジョブが設定されます。

コミット時に commit-workflow が開始され、その中で build ジョブが実行されることにより "build" と echo される
日本時間で毎日午前 10 時（UTC で毎日午前 1 時）に schedule-workflow が開始され、その中で nightly-build ジョブが実行されることにより "nightly-build" と echo される

triggers 構文は、workflows の中でのみ記述できる設定です。これを書かなければこれまで通りコミット時に実行されます。

schedule の中に書かれている cron に、 crontab で使われるのと同じ書式で実行タイミングを記述します。UTC として解釈されるので注意が必要です。filters も必須パラメータで、どのブランチに対して実行するかを制限します。

前回の記事と比較して、こちらのほうが直観的ですし、圧倒的に楽になりました。CircleCI はユーザーがほしい機能を着実に実装してくれるイメージがあるので、今後も楽しみです。

生産性向上ブログ

継続的な生産性向上を目指すエンジニアのためのブログ

CircleCI 2.1 の新機能で yaml の記述を DRY にする方法

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