こんにちは、テクマトリックスの米田です。
JenkinsはCI/CDの定番ツールとして、多くの方に知られています。実際に触れてみた方も多いと思います。Jenkinsの設定をして運用していくと、Jenkinsを他のチームで運用したりするために、現在の環境の設定を複製する場合があります。この時に便利なのがJenkins Configuration as Codeプラグインです。今回はこのプラグインを実際に利用し、Jenkinsの設定をファイルに出力して利用してみたので、本記事で紹介します。

Jenkins Configuration as Code(JCasC)とは

概要

JenkinsはCI/CDの定番ツールであり、基本的に多くの設定をGUIでおこないます。しかし、GUIで設定をおこなうと以下の課題が生じます。

• 手動操作によりヒューマンエラーが発生する
• 複数の環境で同じ設定を再現するのに時間がかかる
• 設定内容のバージョン管理ができず、変更履歴を追跡するのが困難

これらの課題を解決するために登場したのがJenkins Configuration as Codeプラグイン（以下JCasC）です。
JCasCは、Jenkinsの設定をGUI操作ではなく、yamlファイルで宣言的に管理できるプラグインです。このプラグインの利用により、Jenkinsの設定をコードとして扱えるようになり、Infrastructure as Code(IaC)の考え方をJenkinsに踏襲できます。具体的には以下のメリットが挙げられます。

• 再現性の向上：同じ設定を複数環境に適用できる
• バージョン管理：yamlファイルをGitで管理し、履歴管理やレビューが可能

JCasCのプラグイン公式ページにはJCasCについて以下のような記載があります。

Setting up Jenkins is a complex process, as both Jenkins and its plugins require some tuning and configuration, with dozens of parameters to set within the web UI manage section.
Jenkins Configuration as Code provides the ability to define this whole configuration as a simple, human-friendly, plain text yaml syntax. Without any manual steps, this configuration can be validated and applied to a Jenkins controller in a fully reproducible way. With JCasC, setting up a new Jenkins controller will become a no-brainer event.

https://www.jenkins.io/projects/jcasc/#manage-configuration-as-human-readable-config-files

Jenkins のセットアップは複雑なプロセスです。Jenkins とそのプラグインはどちらも、Web UI の管理セクションで設定するパラメータが数十個もあり、ある程度の調整と設定が必要です。
Jenkins Configuration as Code を使用すると、この設定全体をシンプルで人間に分かりやすいプレーンテキストの yaml 構文で定義できます。手動で設定する必要はなく、この設定を検証し、完全に再現可能な方法で Jenkins コントローラーに適用できます。JCasC を使えば、新しい Jenkins コントローラーのセットアップは簡単です。

Google 翻訳を基に一部修正

JCasCのyamlファイルの構成

JCasCのyamlファイルには、デフォルトで4つの構成があります。JCasCのJenkins公式ページによると以下です。

JCasCを使ってみる

目標

コンテナaで起動したJenkinsコントローラaの設定をyamlファイルとしてエクスポートし、コンテナbで起動した別のJenkinsコントローラbにインポートします。JCasCにより、設定が別環境でも正しく再現されることを確認することが目標です。今回は以下の3項目を確認します。

• システムメッセージ
• 認証情報
• Tools

利用手順

● Jenkinsコントローラa/b共通の作業

1. Jenkinsコントローラが動作するコンテナの用意

Jenkinsコントローラa/bで共通のDockerfileとdocker-compose.ymlを用意しました。以下にディレクトリ構成とファイルの記述例を示します。

./
├ Dockerfile
└ docker-compose.yml

FROM jenkins/jenkins:2.528.1-lts-jdk21

services:
  jenkins-a:
    build: ./
    container_name: jenkins-a
    ports:
      - "18080:8080"
      - "18090:50000"
    volumes:
      - jenkins-a_home:/var/jenkins_home

  jenkins-b:
    build: ./
    container_name: jenkins-b
    ports:
      - "28080:8080"
      - "28090:50000"
    volumes:
      - jenkins-b_home:/var/jenkins_home

volumes:
  jenkins-a_home:
  jenkins-b_home:

docker-compose.ymlのあるディレクトリで以下のコマンドを実行し、Docker Composeを起動します。

$ docker compose up -d

● Jenkinsコントローラaでの作業

a-1. Jenkinsを構築する
JCasCでは、一からJenkinsの設定をyamlファイルとして記述できますが、GUIで設定を進めた後にその内容をyamlファイルとして出力することもできます。今回は簡単にするため、後者の手順を採用します。まずはJenkinsの設定を行います。

・システムメッセージ
[Jenkinsの管理] > [System] > [システムメッセージ]には以下のように記述しました。

・認証情報
[Jenkinsの管理] > [Credentials]で、Jenkinsコントローラaで作成した認証情報であることが分かる、ユーザー名とパスワードの組み合わせのexampleCredentials-aを作成しました。

・Tools
[Jenkinsの管理] > [Tools]で、Mavenバージョン3.9.11をインストールするよう以下の設定をおこないました。

a-2. Configuration as Codeプラグインをインストール
[Jenkinsの管理] > [Plugins] > [Available plugins]にアクセスし、Configuration as Codeプラグインをインストールします。

a-3. yamlファイルのエクスポート
[Jenkinsの管理]画面を確認すると[Configuration as Code]という項目が表示されます。[Jenkinsの管理] > [Configuration as Code] にアクセスすると以下の画面が表示されます。

「Export configuration」をクリックし、Jenkinsコントローラaで設定した内容をyamlファイルにエクスポートします。デフォルトではjenkins.yamlというファイル名でローカルにエクスポートされます。今回は、Jenkinsコントローラaからエクスポートしたyamlファイルであることを示すため、ファイル名をjenkins-a-export.yamlに修正します。
エクスポートしたyamlファイルの一部を以下に示します。「システムメッセージ」「認証情報」「Toolのインストール」の部分に着目すると、a-1で設定した内容がyamlファイルにも反映されていることが分かります（認証情報、システムメッセージ、Tool部分のみ抜粋）。

configuration-as-code: {
  }

# 認証情報
credentials:
  system:
    domainCredentials:
    - credentials:
      - usernamePassword:
          description: "JCasC検証用の認証情報-a"
          id: "exampleCredentials-a"
          password: "{AQAAABAAAAAgxt+WC0TYTjEzsO/KGFvhcwBRP10FfMh/OScbBaZSak+IP1lJ6IG+hVJvzsdwHvxq}"
          scope: GLOBAL
          username: "exampleCredentials-a"
      domain: {
        }

# システムメッセージ
jenkins:
  systemMessage: "Hello from Jenkins-a"

# Tool
tool:
  maven:
    installations:
    - name: "Maven-3.9.11-a"
      properties:
      - installSource:
          installers:
          - maven:
              id: "3.9.11"

● Jenkinsコントローラbでの作業

b-1. ローカルのyamlファイルをコンテナbへ配置

JenkinsはDockerコンテナで動作しているので、b-3でyamlファイルをJenkinsをインポートする際、yamlファイルはコンテナに配置している必要があります。以下のコマンドをローカルで実行して、ローカルにあるyamlファイルをコンテナへコピーします。

$ docker cp C:\path\to\jenkins-a-export.yaml jenkins-b:/var/jenkins_home/jenkins-a-export.yaml

b-2. JCasCプラグインのインストール
a-3でエクスポートしたyamlファイルをインポートする時も同様に、JCasCプラグインのインストールが必要です。a-2と同様にJCasCプラグインをインストールします。

b-3. yamlファイルのインポート
[Jenkinsの管理] > [Configuration as Code] にアクセスします。「Replace configuration source with: Path or URL」の欄にyamlファイルのパスを記述し、「Apply new configuration」をクリックしてyamlファイルの設定をインポートします。

確認

Jenkinsコントローラaで設定した内容が、Jenkinsコントローラbに正しく反映されているか確認します。

・システムメッセージ
[Jenkinsの管理] > [System] > [システムメッセージ]を確認します。Jenkinsコントローラaで設定していたシステムメッセージが新たに反映されていることが確認できます。

・認証情報
[Jenkinsの管理] > [Credentials]を確認すると、Jenkinsコントローラaで作成した認証情報がJenkinsコントローラbでも反映されていることが分かります。

・Tools
[Jenkinsの管理] > [Tools]を確認します。以下のように、Jenkinsコントローラaと同様の表示となっていることが分かります。

Jenkinsコントローラbで簡単なパイプラインを作成して動作させたところ、Mavenを利用したジョブが実行できることも確認できました。

pipeline {
    agent any
    tools {
        maven 'Maven-3.9.11-a'
    }
    stages {
        stage('Build') {
            steps {
                sh "mvn -version"
            }
        }
    }
}

JCasC利用時の注意点

• ユーザー情報はyamlファイルに含まれない
  Jenkinsコントローラaでyamlファイルをエクスポートし、Jenkinsコントローラbへインポートした際、Jenkinsコントローラaで設定していたユーザー情報で、Jenkinsコントローラbにログインすることができませんでした。これはJenkinsのユーザーデータベースが、Jenkinsのデータを保管するJENKINS_HOMEに格納されるためです。あくまでJCasCでは「設定」のみをエクスポートの対象としているため、ローカルのJENKINS_HOMEにあるJenkinsのユーザーの情報（ユーザー名やパスワード、メールアドレスなど）はyamlファイルに含まれません。（JENKINS_HOMEとJCasCのyamlファイルの違いは下記の章で触れます）
• セキュリティ
  yamlファイルの編集権限がある人や、Jenkinsの管理画面の編集権限がある人が誰でもJenkinsの設定を変更できてしまいます。あるユーザーに意図したよりも高い権限が付与されたり、機密データが漏洩する可能性もあるため、Jenkins自体へのアクセス権限はもちろんのこと、yamlファイルの編集に対しても適切な権限管理が必要です。
• yamlファイルの配置
  JCasCで指定していたyamlファイルが削除されると、Jenkinsは再起動時にyamlファイルを参照できず、503エラーを表示します。そのためyamlファイルの配置は必須となるので、誤って削除しないよう注意しましょう。決まったディレクトリに保管すると管理しやすいため、yamlファイルはJENKINS_HOME配下など、決まったディレクトリに配置することが効果的です。
• 設定の無効化
  JCasCによる設定が不要になったり、元の設定でJenkinsを動作させたいとき、JCasCプラグイン自体に設定を無効化する機能はありません。そのため、JCasCプラグインそのものを無効化する必要があります。JCasCプラグインを無効化したい場合、[Jenkinsの管理] > [Plugins] > [Installed plugins]にアクセスし、Configuration as Codeプラグインを無効化してください。プラグインを無効化した後は、直前の設定内容が引き継がれます。

JENKINS_HOMEとJCasCのyamlファイルの違い

JCasCを利用する際、Jenkinsのデータを保管している「JENKINS_HOME」と混同しやすいため、こちらの章で両者の違いを整理します。
JENKINS_HOMEは「Jenkinsの実態が全て置かれているディレクトリ」です。JENKINS_HOMEには主に以下の内容が含まれています。

• インストールされたプラグイン ⇒ JENKINS_HOME/plugins/*.jpi
• ローカルユーザーの情報 ⇒ JENKINS_HOME/users/
• ジョブの実行履歴 ⇒ JENKINS_HOME/jobs/
• Credentialsの暗号化データ
• ビルドログやワークスペース

JENKINS_HOMEを丸ごとコピーすればJenkinsをそのまま再現することができます。ただし、バイナリファイルなども含むため、構成管理は難しいです。
一方で、JCasCのyamlファイルは「Jenkinsの設定項目を再現するための宣言的なコード」です。yamlファイルに含まれる情報は、下記が挙げられます。

• 認証方式（LDAP/ローカルユーザーの利用）
• 権限設定
• Credentialsの設定値
• Toolsの設定
• 各種プラグインの設定

設定項目（Configuration）の再現に特化した情報だけが含まれるため、Jenkinsの「設定」を再現できます。ローカルユーザーやプラグイン本体は含まれません。

このように、JENKINS_HOMEとJCasCのyamlファイルは、似ているようで全く異なります。Jenkinsの移行や構成管理では、これらの違いを理解して使い分けることが重要です。

まとめ

今回はJenkins Configuration as Codeプラグイン(JCasC)を用いて、Jenkinsの設定が別のJenkinsで再現できることを確認しました。JCasCを用いることでJenkinsの設定をバージョン管理でき、手軽に展開できます。適切な権限管理を設ける必要があり、yamlファイルを削除してしまうとJenkinsが起動できなくなるなど、注意点もあるため、JCasCの導入には準備の時間が必要だと感じました。JENKINS_HOMEとの役割の違いを理解することも重要です。とはいえ、JCasCは使いこなせれば便利なプラグインだと感じました。ぜひ利用してみてください。

弊社の開発基盤構築ソリューションチームでは、JenkinsやGitHub Actionsを利用したCI環境の構築を承っています。CI環境の導入や構築について気になることがあれば、ぜひお気軽にお問い合わせください。

参考リンク
Jenkins Configuration as Codeプラグインのプラグイン公式ページ
Jenkins Configuration as CodeプラグインのJenkins公式ページ
Jenkins Configuration as CodeプラグインのGitHubリポジトリ