emmetog.jenkins

概要 バージョン 洞察

JenkinsのためのAnsibleロール

Ansibleを使用してJenkinsをインストールし、完全に設定します。

このロールは、すべてのJenkins設定をバージョン管理に保存したいときに使用され、Jenkinsを繰り返しかつ確実にデプロイできるようになります。また、Jenkinsをペットではなく牛として扱うことができます。

Jenkinsをインストールするロールを探していて、すべてをWebインターフェース経由で設定したい場合、また同じ完全に設定されたJenkinsを繰り返しデプロイする必要がない場合は、このロールは不要です。その場合は、geerlingguy/ansible-role-jenkinsロールを見てください。

要件

Dockerを使用してデプロイする場合、サーバーにDockerがインストールされている必要があります。現在、Docker、apt-get、yumの方法のみがサポートされていますが、他の方法も簡単に追加できます。PRを歓迎します。

インストール

Ansible Galaxyを使用してインストールします：

$ ansible-galaxy install emmetog.jenkins

ロール変数

以下の変数はJenkinsのインストール方法に影響します：

  • jenkins_install_via: Jenkinsのインストール方法を制御します。重要: この変数は以下のいずれかの値に設定する必要があります：
    • docker: Dockerコンテナ内にインストール
    • apt: Ubuntu/Debian Linuxシステムに直接Jenkinsをインストール
    • yum: RedHat/CentOS Linuxシステムに直接Jenkinsをインストール
  • jenkins_version: インストールするJenkinsの正確なバージョン

以下の変数はJenkinsの設定方法に影響します：

  • jenkins_url: JenkinsにアクセスするためのURL
  • jenkins_port: Jenkinsがリッスンするポート
  • jenkins_home: Jenkins設定が保存されるサーバー上のディレクトリ
  • jenkins_admin: Jenkinsサーバーの管理者のメールアドレス
  • jenkins_java_opts: Java実行可能ファイルに渡されるオプション
  • jenkins_config_owner: Jenkins設定ファイルの所有者
  • jenkins_config_group: Jenkins設定ファイルのグループ
  • jenkins_auth: AnsibleがJenkinsと認証する方法、（下記の「認証とセキュリティ」セクションを参照）
  • jenkins_url_health_check: Jenkinsが起動した後のヘルスチェックに使用するURL（デフォルトはjenkins_url）
  • jenkins_health_check_user: 定義されていれば、ヘルスチェックにこのユーザー名で基本認証を使用（例：Google OAuthを設定した場合に便利）
  • jenkins_health_check_password: 定義されていれば、ヘルスチェックにこのパスワードで基本認証を使用（例：Google OAuthを設定した場合に便利）

以下のリスト変数はJenkinsでインストールされるジョブ/プラグインに影響します：

  • jenkins_jobs: Jenkinsにコピーするジョブの名前一覧。config.xmlファイルはjenkins_source_dir_jobs/<job_name>に存在する必要があります。
  • jenkins_plugins: JenkinsにインストールするプラグインIDのリスト。
  • jenkins_custom_plugins: Jenkinsにインストールするカスタムプラグインのリスト。

完全な変数のリストについては、defaults/main.ymlを参照してください。

例のプレイブック

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.example.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "my-first-job"
      - "another-awesome-job"
    jenkins_include_secrets: true
    jenkins_include_custom_files: true
    jenkins_custom_files:
      - src: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
        dest: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
    jenkins_plugins:
      - git
      - blueocean
    jenkins_custom_plugins:
      - "openstack-cloud-plugin/openstack-cloud.jpi"

  roles:
    - emmetog.jenkins

設定ファイルの管理

上記の例では、{{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xmlおよび{{ playbook_dir }}/jenkins-configs/jobs/another-awesome-job/config.xmlにジョブ設定ファイルを探します。

注意: これらのディレクトリはカスタマイズ可能です。jenkins_source_dir_configsおよびjenkins_source_dir_jobsロール変数を参照してください。

ロールはまた、{{ playbook_dir }}/jenkins-configs/config.xmlを探します。このconfig.xmlファイルはサーバーにコピーされ、ジョブ設定のテンプレートとして使用されます。

上記の例では、{{ playbook_dir }}/jenkins-configs/secretsにあるすべてのシークレットディレクトリもアップロードされ、{{ jenkins_custom_files }}変数で定義されたカスタムファイルもコピーされます。{{ jenkins_include_secrets }}および{{ jenkins_include_custom_files }}変数は、これらの機能を有効にするためにtrueに設定する必要があります。追加で、ロールは{{ jenkins_custom_plugins }}リスト変数に.jpiまたは.hpiファイルを提供することでカスタムプラグインをインストールできます。

config.xmlおよびカスタムファイルはテンプレートとして扱われるため、変数を含めることができ、Ansibleボールトの機密データも含められます。

設定ファイルを変更したり、新しい項目（ジョブ、プラグインなど）を追加したりする場合の通常のワークフローは次のとおりです：

  1. Jenkins UIで変更を行う
  2. 結果のXMLファイルをバージョン管理システムにコピーする
  3. 新しく作成されたファイルについては、それぞれのリストに追加することを忘れないでください：
  • 新しいジョブの場合、jenkins_jobsに追加する必要があります
  • カスタムファイルの場合、jenkins_include_custom_filesに追加する必要があります
  • カスタムプラグインの場合、jenkins_custom_pluginsに追加する必要があります

Jenkins設定ファイルの例

{{ jenkins_source_dir_configs }}/config.xmlにグローバルなJenkins設定を入力します。例えば：

<?xml version='1.1' encoding='UTF-8'?>
<hudson>
  <disabledAdministrativeMonitors/>
  <version>2.176.1</version>
  <installStateName>RESTART</installStateName>
  <numExecutors>1</numExecutors>
  <mode>EXCLUSIVE</mode>
  <useSecurity>true</useSecurity>
  <authorizationStrategy class="hudson.security.AuthorizationStrategy$Unsecured"/>
  <securityRealm class="hudson.security.HudsonPrivateSecurityRealm">
    <disableSignup>false</disableSignup>
    <enableCaptcha>false</enableCaptcha>
  </securityRealm>
  <disableRememberMe>false</disableRememberMe>
  <projectNamingStrategy class="jenkins.model.ProjectNamingStrategy$DefaultProjectNamingStrategy"/>
  <workspaceDir>${JENKINS_HOME}/workspace/${ITEM_FULLNAME}</workspaceDir>
  <buildsDir>${ITEM_ROOTDIR}/builds</buildsDir>
  <markupFormatter class="hudson.markup.EscapedMarkupFormatter"/>
  <jdks/>
  <viewsTabBar class="hudson.views.DefaultViewsTabBar"/>
  <myViewsTabBar class="hudson.views.DefaultMyViewsTabBar"/>
  <clouds/>
  <quietPeriod>0</quietPeriod>
  <scmCheckoutRetryCount>0</scmCheckoutRetryCount>
  <views>
    <hudson.model.AllView>
      <owner class="hudson" reference="../../.."/>
      <name>all</name>
      <filterExecutors>false</filterExecutors>
      <filterQueue>false</filterQueue>
      <properties class="hudson.model.View$PropertyList"/>
    </hudson.model.AllView>
  </views>
  <primaryView>all</primaryView>
  <slaveAgentPort>0</slaveAgentPort>
  <disabledAgentProtocols>
    <string>JNLP-connect</string>
    <string>JNLP2-connect</string>
  </disabledAgentProtocols>
  <label>master</label>
  <crumbIssuer class="hudson.security.csrf.DefaultCrumbIssuer">
    <excludeClientIPFromCrumb>false</excludeClientIPFromCrumb>
  </crumbIssuer>
  <nodeProperties/>
  <globalNodeProperties/>
</hudson>

ジョブ設定ファイルの例

{{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xmlに次のような内容を配置できます：

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>私の最初のジョブ。 "こんにちは世界" と言います。</description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers/>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>echo &quot;こんにちは世界！&quot;</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers/>
  <buildWrappers/>
</project>

認証とセキュリティ

このロールはJenkinsのための次の認証メカニズムをサポートしています：

  1. APIトークンを使用した認証（推奨、Jenkins 2.96以上が必要）
  2. Strict Crumb Issuerプラグインを使用したcrumb認証（APIトークンを使用しない場合に必要、Jenkins 2.176.2以降が必要）
  3. セキュリティなし（推奨しません）

APIトークンベースの認証

APIトークンを使用した認証は推奨されますが、設定には少し手間がかかります。APIトークンの利点は、Jenkinsで簡単に取り消すことができ、その使用も追跡されることです。APIトークンはcrumbトークンを取得する必要がなく、Jenkinsバージョン2.172.2以降は難しくなっています（こちらのセキュリティ通知を参照）。

APIトークンを作成するには、次の手順を行います：

  1. すべてのAPIトークンは特定のユーザーに所属する必要があります。デプロイ用の特別なユーザーを作成するか、管理者または他のアカウントでログインします。
  2. ユーザーの設定ページで「新しいトークンを追加」ボタンをクリックします。
  3. トークンの値を保存します。できればAnsibleボールトに保存してください。
  4. プレイブックに次の変数を定義します：
  • jenkins_auth: "api"
  • jenkins_api_token: "(Ansibleボールトで定義されたトークン)"
  • jenkins_api_username: "(Ansibleボールトで定義されたユーザー名)"
  1. $JENKINS_HOME/users/the_username/config.xmlファイルのバックアップを作成します。ここでthe_usernameは、作成したAPIトークンの所有者に対応するユーザー名です。
  2. このファイルをコントロールホストに追加し、jenkins_custom_filesリストにデプロイされるようにしてください。

srcの値は、プレイブックに関連付けたコントロールマシン上でのファイルの保存場所に応じて変更する必要があるかもしれません。

Crumbベースの認証

Crumbベースの認証は、クロスサイトリクエストフォージェリ攻撃を防ぐために使用でき、APIトークンが不都合な場合に推奨されます。注意: crumbベースの認証は「誰でも何でも操作できます」というアクセス制御設定でのみ機能します。Jenkinsの設定がより厳格なセキュリティを必要とする場合は、上記に記載されたAPIトークンを使用してください。

Crumbベースの認証は、最近のJenkinsのセキュリティ修正により、設定が少し難しくなることがあります。CSRFを設定するには、次の手順を行います：

  1. Jenkins >= 2.176.2を使用している場合、Strict Crumb Issuerプラグインをインストールする必要があります。このロールによってjenkins_pluginsリストにstrict-crumb-issuer IDを追加することでインストールできます。
  2. Jenkinsで「Jenkinsの管理」 -> 「全体のセキュリティを設定」をクリックします。
  3. 「CSRF保護」セクションで、「クロスサイトリクエストフォージェリの攻撃を防ぐ」を有効にし、Jenkins >= 2.176.2を使用している場合は「Strict Crumb Issuer」、それ以外の場合は「Default Crumb Issuer」を選択します。このオプションを表示するには、Strict Crumb Issuerプラグインがインストールされている必要があります。その後、メインJenkinsのconfig.xmlファイルをコントロールホストにバックアップする必要があります。

上記の手順を実行するには、少なくともAnsible 2.9.0pre5または2.10（執筆時点で両方とも開発中）である必要があります。詳細についてはこちらのAnsibleのissueを参照してください。

HTTPS

JenkinsでHTTPSを有効にするには、次の手順を行います：

  • jenkins_port_httpsにJenkinsがリッスンするポートを定義します
  • JKSキーストアまたはCA署名証明書のいずれかの変数を定義します：
    • JKSキーストアの場合、次の変数を定義する必要があります：
      • jenkins_https_keystore: コントロールホスト上のキーストアファイルのパス。これはこのロールによってJenkinsサーバーにコピーされます。
      • jenkins_https_keystore_password: 指定されたJKSキーストアのパスワード。Ansibleボールトを使用することを推奨します。重要: この文字列はサーバー上のJenkins設定ファイルに平文で書き込まれます。また、サーバーのプロセスリストにも表示されます。署名証明書ファイルへの移行を検討してください（以下参照）。
    • CA署名の証明書ファイルの場合、次の変数を定義する必要があります：
      • jenkins_https_certificate: 証明書ファイルのパス。これはこのロールによってJenkinsサーバーにコピーされます。Ansibleボールトを使用することを推奨します。
      • jenkins_https_private_key: CA署名証明書のためのプライベートキー。Ansibleボールトを使用することを推奨します。
  • 必要に応じて、自己署名証明書を使用している場合は、jenkins_https_validate_certsをfalseに設定します。

JenkinsをDockerでデプロイする場合は、Jenkins自体を設定するのではなく、jwilder/nginx-proxyやtraefikのようなリバースプロキシを使用することをお勧めします。これにより、少し柔軟性が得られ、責任の分離が可能になります。これらのプロジェクトのドキュメントを参照して、プロキシをデプロイし、HTTPSを設定する方法を確認してください。

Jenkinsインスタンスの前にリバースプロキシを使用してDockerを使用してデプロイする場合、jenkins_docker_expose_port変数をfalseに設定して、ポートがホストに公開されないようにする必要があります。リバースプロキシにのみ公開されるようにします。

ライセンス

MIT

作成者情報

エメット・オグレイディによって愛情を込めて作成されました。

私はNimbleCIの創設者で、GithubのフィーチャーブランチワークフロープロジェクトのためのDockerコンテナを構築しています。

私の個人的なブログでブログを書いたり、NimbleCIブログでDocker関連のことについて書いています。

プロジェクトについて

Installs and completely configures Jenkins using Ansible

role ci deploy development docker jenkins packaging
インストール
ansible-galaxy install emmetog.jenkins
GitHub リポジトリ
105 スター
89 フォーク
15 オープンな問題
ライセンス
mit
ダウンロード
17.5k
所有者