Jenkins からの移行

Jenkins を長年使用されていた方向けに、CircleCI に移行するうえで把握しておきたい基本的なコンセプトについて説明します。

CircleCI は、Jenkins とは大きく異なる製品であり、CI/CD の管理方法に関するコンセプトも多くの相違点が見られます。ただし、Jenkins のビルドの基本的な機能を CircleCI に移行するだけなら、それほど時間はかかりません。 移行を迅速に始めるために、以下のステップをお試しください。

1. スタートガイド: ガイドを参照しながら、CircleCI で最初のビルドを実行し、成功させましょう。

2. Execute Shell のコマンドをコピー & ペーストする: Jenkins 内のプロジェクトをそのまま複製して使用できる場合は、以下の内容のファイルを config.yml という名前でプロジェクトの .circleci/ ディレクトリに追加します。

    steps:
      - run: "Add any bash command you want here"
      - run:
          command: |
            echo "Arbitrary multi-line bash"
            echo "Copy-paste from 'Execute Shell' in Jenkins"

いくつかのプログラムとユーティリティは CircleCI イメージにプリインストールされていますが、他にビルドに必要な項目があれば run ステップでインストールする必要があります。 プロジェクトの依存関係は、次回のビルドに備え、save_cache と restore_cache ステップを使用して キャッシュすることができます。こうしておくと、全体のダウンロードとインストールが一度だけで済むようになります。

手動設定: Jenkins の Execute Shell 以外のプラグインまたはオプションを使用してビルドステップを実行していた場合は、Jenkins からビルドを手動で移植する必要があります。 すべての CircleCI 設定キーの詳細については、「 CircleCI の設定」を参照してください。

通常、Jenkins のプロジェクトは Jenkins の Web UI で設定され、その設定は Jenkins サーバーのファイルシステムに保存されています。 そのため、チームや組織内で構成情報を共有することは困難です。 VCS からリポジトリをクローンしても Jenkins に保存された情報はコピーされません。 また、Jenkins サーバーに設定を保存すると、すべての Jenkins サーバーを定期的にバックアップする必要が生じます。

CircleCI のビルドに関する設定の大部分は、各プロジェクトのルートディレクトリにある .circleci/config.yml という名前のファイルに保存されます。 CI/CD の設定も他のソースコードと同様に扱われるため、バックアップや共有が簡単に行えます。 ソースコードに格納すべきではないシークレットなどのごく一部のプロジェクト設定は、暗号化された状態で CircleCI アプリに保存されます。

Jenkins サーバーの管理は、運用部門のメンバーやチームに委ねられているケースがほとんどです。 その担当者は、依存関係のインストールやトラブルシューティングなど、CI/CD メンテナンスに関するさまざまなタスクに日々追われています。

CircleCI では、カスタムの依存関係が自動的にインストールされるフレッシュな環境で各ビルドが開始されるため、依存関係をインストールするために CircleCI 環境にアクセスする必要はなく、ビルドプロセス全体が確実に自動化されます。 また、実行環境でのトラブルシューティングは、CircleCI の SSH 機能を使ってすべての開発者が簡単かつ安全に実行することができます。

CircleCI をご自身のハードウェアにインストールする場合、(メタルレベルまたは VM レベルの) ホスト OS とコンテナ化されたビルド環境を分けておくと、セキュリティと運用の面できわめて有用です (詳細については、以下のセクション「 コンテナ内のビルド」を参照してください)。 運用部門のメンバーは、ビルドに支障をきたすことなくホスト OS 上で必要な作業を行うことができ、開発者にアクセス権を付与する必要はありません。 また開発者は、CircleCI の SSH 機能を使用して、運用に支障をきたすことなく任意のコンテナレベルでビルドをデバッグできます。

Jenkins では、Git リポジトリのチェックアウトなど、ほとんどすべての作業の実行にプラグインを使用する必要があります。 Jenkins のプラグインは、Jenkins 自体と同じように Java ベースで、少し複雑です。 Jenkins 内の数百もの拡張ポイントとやり取りを行い、JSP 形式のタグやビューを使用して Web ビューを生成します。

CircleCI にはすべてのコア CI 機能が組み込まれています。 VCS からのソースのチェックアウト、お気に入りのツールを使用したビルドやテストの実行、テスト出力の解析、アーティファクトの保存などの機能は、プラグインを必要としません。 ビルドやデプロイにカスタム機能を追加するには、適切な場所でいくつかの bash スニペットを使用します。

次の表は、 CircleCI Jenkins コンバーターツールを使用して変換できる、サポート対象プラグインです ( Jenkins コンバーターのセクションを参照)。

• Ant Plugin (ant)
• Authentication Tokens API Plugin (authentication-tokens)
• Bouncy Castle API Plugin (bouncycastle-api)
• Branch API Plugin (branch-api)
• Build Timeout (build-timeout)
• Command Agent Launcher Plugin (command-launcher)
• Config File Provider Plugin (config-file-provider)
• Credentials Binding Plugin (credentials-binding)
• Credentials Plugin (credentials)
• Display URL API (display-url-api)
• Docker Commons Plugin (docker-commons)
• Docker Pipeline (docker-workflow)
• Durable Task Plugin (durable-task)
• Email Extension Plugin (email-ext)
• Folders Plugin (cloudbees-folder)
• GitHub API Plugin (github-api)
• GitHub Branch Source Plugin (github-branch-source)
• GitHub plugin (github)
• Gradle Plugin (gradle)
• H2 API Plugin (h2-api)
• JUnit Plugin (junit)
• Jackson 2 API Plugin (jackson2-api)
• JavaScript GUI Lib: ACE Editor bundle plugin (ace-editor)
• JavaScript GUI Lib: Handlebars bundle plugin (handlebars)
• JavaScript GUI Lib: Moment.js bundle plugin (momentjs)
• JavaScript GUI Lib: jQuery bundles (jQuery and jQuery UI) plugin (jquery-detached)
• Jenkins Apache HttpComponents Client 4.x API Plugin (apache-httpcomponents-client-4-api)
• Jenkins GIT server Plugin (git-server)
• Jenkins Git client plugin (git-client)
• Jenkins Git plugin (git)
• Jenkins JSch dependency plugin (jsch)
• Jenkins Mailer Plugin (mailer)
• Jenkins Subversion Plug-in (subversion)
• Jenkins Workspace Cleanup Plugin (ws-cleanup)
• LDAP Plugin (ldap)
• Lockable Resources plugin (lockable-resources)
• MapDB API Plugin (mapdb-api)
• Matrix Authorization Strategy Plugin (matrix-auth)
• Matrix Project Plugin (matrix-project)
• OWASP Markup Formatter Plugin (antisamy-markup-formatter)
• Oracle Java SE Development Kit Installer Plugin (jdk-tool)
• PAM Authentication plugin (pam-auth)
• Pipeline (workflow-aggregator)
• Pipeline Graph Analysis Plugin (pipeline-graph-analysis)
• Pipeline Maven Integration Plugin (pipeline-maven)
• Pipeline Utility Steps (pipeline-utility-steps)
• Pipeline: API (workflow-api)
• Pipeline: Basic Steps (workflow-basic-steps)
• Pipeline: Build Step (pipeline-build-step)
• Pipeline: Declarative (pipeline-model-definition)
• Pipeline: Declarative Agent API (pipeline-model-declarative-agent)
• Pipeline: Declarative Extension Points API (pipeline-model-extensions)
• Pipeline: GitHub Groovy Libraries (pipeline-github-lib)
• Pipeline: Groovy (workflow-cps)
• Pipeline: Input Step (pipeline-input-step)
• Pipeline: Job (workflow-job)
• Pipeline: Milestone Step (pipeline-milestone-step)
• Pipeline: Model API (pipeline-model-api)
• Pipeline: Multibranch (workflow-multibranch)
• Pipeline: Nodes and Processes (workflow-durable-task-step)
• Pipeline: REST API Plugin (pipeline-rest-api)
• Pipeline: SCM Step (workflow-scm-step)
• Pipeline: Shared Groovy Libraries (workflow-cps-global-lib)
• Pipeline: Stage Step (pipeline-stage-step)
• Pipeline: Stage Tags Metadata (pipeline-stage-tags-metadata)
• Pipeline: Stage View Plugin (pipeline-stage-view)
• Pipeline: Step API (workflow-step-api)
• Pipeline: Supporting APIs (workflow-support)
• Plain Credentials Plugin (plain-credentials)
• Resource Disposer Plugin (resource-disposer)
• SCM API Plugin (scm-api)
• SSH Build Agents plugin (ssh-slaves)
• SSH Credentials Plugin (ssh-credentials)
• Script Security Plugin (script-security)
• Structs Plugin (structs)
• Timestamper (timestamper)
• Token Macro Plugin (token-macro)
• Trilead API Plugin (trilead-api)

Jenkins サーバーでも、ビルドを複数の「エージェント」マシンに分散させてジョブを実行することはできますが、事前に多くの作業を要します。 Jenkins の Wiki によると、Jenkins はクラスタリングミドルウェアではないため、事前の準備は容易ではないと説明されています。

CircleCI は、デフォルトでビルドを大規模なビルドマシンフリートに分散させます。 クラウド版 CircleCI を使用すれば、分散が自動的に行われます。プラン内で処理できるビルド数に達しない限り、ビルドがキューに入れられることはありません。 CircleCI Server を使用する場合も、CircleCI で Builder マシンクラスタが管理されるため、余計なツールを使用せずに済み、たいへん便利です。

ビルドシステム内のコンテナ化は複雑になる傾向があります。CI/CD システムの実装を構成するコンテナ内で任意のビルドコマンドやテストコマンドが実行され、それらのコマンドにコンテナの実行が含まれることもあるためです。 これらの点については、以下で詳しく説明します。 また、コンテナを実行するツールとしては Docker が絶大な人気を誇りますが、それ以外にもさまざまなツールが存在します。 ここでは、一般的な「コンテナ」と製品名である「Docker」という用語を使い分けながら説明していきます。

ワークフローに Docker などのツールを使用する場合は、CI/CD でも同じように使用したい場合があります。 Jenkins にはこうしたツールが組み込みでサポートされていないため、ユーザー自身がツールを実行環境にインストールする必要があります。

CircleCI にはかねてから Docker がプリインストールされており、.circleci/config.yml ファイルに Executor として docker を追加するだけで、ビルド内で Docker にアクセスできます。 詳細は、 実行環境の概要のページを参照してください。

Jenkins は一般に、ビルドサーバーの通常のディレクトリ内でビルドを実行するため、依存関係、ファイル、サーバーからの経時状態収集などに関して多くの問題が発生する可能性があります。 代替機能を提供するプラグインもありますが、手動でインストールしなければなりません。

CircleCI では、すべての Linux および Android のビルドが専用コンテナで実行され、コンテナは使用後に直ちに破棄されます (macOS ビルドは使い捨ての VM で実行されます)。 これにより、ビルドごとにフレッシュな環境が作成され、ビルドに不正なデータが入り込むことを防止できます。 このように 1 回限りの環境を使用して、使い捨ての概念を浸透させることで、すべての依存関係がコードに記述されるようになり、ビルドサーバーがそれぞれに少しずつ異なってしまう「スノーフレーク化」の問題を防止できます。

独自のハードウェアで CircleCI を使用してビルドを実行する場合は、すべてのビルドをコンテナで実行することで、ビルドを実行するためのハードウェアを有効に活用できます。

マルチスレッドなどの手法を利用すれば、Jenkins のビルドでも複数のテストを並列に実行できますが、データベースやファイルシステムなどの共有リソースに関して軽微な問題が発生する可能性があります。

CircleCI では、プロジェクトの設定で並列に処理できる数を増やせるため、プロジェクトの各ビルドで一度に複数のコンテナを使用できます。 各コンテナにテストが均等に割り振られることで、通常よりも大幅に短い時間で全体のビルドが完了します。 単純なマルチスレッドの場合とは異なり、各テストはそれぞれ独自の環境に置かれ、他のテストから完全に分離されています。 CircleCI の並列実行の詳細については、 テストの並列実行に関する説明を参照してください。

CircleCI の Jenkins コンバーターは、Jenkinsfile を .circleci/config.yml ファイルに簡単に変換できる Web ツールです。CircleCI でのビルドを素早く簡単に開始していただけます。

このコンバーターは宣言型の Jenkinsfile のみをサポートしています。 ご利用いただけるプラグインとステップの数は増え続けていますが、このツールの使用により、少なくとも 50% の作業が開始でき、 CircleCI 上でのビルドを開始しやすくなることを願っています。

現在サポートされているのは宣言型 (パイプライン) の Jenkinsfile のみです。

• サポートされている構文やプラグインは限られています。 サポートされていない構文とプラグインに Jenkinsfile が依存している場合は変換できません。 それらを手動で削除して下さい。

• 1 つのリクエストにつき受け付けられるのは 1 つの Jenkinsfile のみです。 つまり、 共有ライブラリでは解決されず、結果として得られる config.yml は不完全な場合があります。 場合によっては、解決不可能な共有ライブラリが存在してもコンバーターがエラーを発しないことがあるのでご注意ください。

• tools ブロックでは、maven、jdk、gradle にはツール名として Default のみがサポートされています。それ以外の名前だと変換に失敗します。 その場合は以下のように設定するか、手動で削除して下さい。

  例えば、以下のスタンザは、

  tools {
    maven 'Maven 3.6.3'
    jdk 'Corretto 8.232'
  }
  

  以下のように変更する必要があります。

  tools {
    maven 'Default'
    jdk 'Default'
  }
  

次のセクションでは、CircleCI パイプラインのさまざまな要素での次のステップについて説明します。

Jenkinsfile の入力で何が定義されていても、静的な Docker Executor である cimg/base が Executor として挿入されます。

cimg/base は非常に簡素なイメージなため、プロジェクトに別のイメージが必要になる可能性が高くなります。 別のイメージを探すには、 CircleCI イメージが最適です。 独自のカスタムイメージを作成する高度な手順については、 カスタム Docker イメージを参照して下さい。

使用例によっては、アプリケーションで OS リソースとジョブ環境へのフルアクセスが必要な場合は、 macOS Executor または Machine Executor が必要な場合があります。

CircleCI ワークフロー (Jenkins のパイプラインに相当) が Jenkinsfile から .circleci/config.yml に転送されます。これにはブランチのフィルタリングも含まれます。 コンバーターは、意図しないビルドがトリガーされないように、 スケジュール化されたビルドは転送しません。

CircleCI ジョブの多くの設定オプションには、相当する Jenkins の製品がありません。 CircleCI でのエクスペリエンスを高めるには、次の機能から始めることをお勧めします。

• コードのチェックアウト
• リソースクラス
• 並列実行
• キャッシュの 保存と リストア
• アーティファクトの保存

Jenkinsfile のコンバーターはステップを直接変換しようとしますが、すべてのステップを完全に変換するわけではありません。 これに対処するために、JFC_STACK_TRACE キーが追加され、出力 YAML 内の特定のステップを変換し、サポートされていないステップディレクティブに進む方法についてのガイダンスが提供されました。

• CircleCI Web アプリの概要