GitLab CI/CD Catalog のすゝめ

2024年10月22日 14:31

はじめに

こんにちは、SRE チームの吉村です。

2024 年 5 月に GitLab 17.0 がリリースされ、新たに GitLab CI/CD Catalog が一般公開されたのですが、この GitLab CI/CD Catalog という機能を皆さんはご存じでしょうか？『GitHub Actions の Marketplace のような機能』と言えばピンと来る方も多いかもしれません。

GitLab CI/CD Catalog は、作成した CI/CD のパイプライン設定やパラメーター（以降、CI/CD コンポーネント）をカタログ化し、再利用をより容易かつ効率的に行える機能のことです。これまでも、include キーワードを使用して外部ファイルを読み込むことで CI/CD コンポーネントを共通化することはできました。しかし処理の細かなオーバーライドができなかったり、CI/CD コンポーネントの導入方法、使用要件を提示しづらかったりと融通の利かない点がありました。GitLab CI/CD Catalog はそのような痒い所に手が届く新しい共通化の機能となっています。

ところで、GitLab CI/CD Catalog は公開されて数ヶ月経ちますが日本語の記事が多くなく導入の仕方もあまりまとめられていません。そこで本記事では、GitLab CI/CD Catalog の作成方法、運用のコツや弊社での活用例についてまとめていきます。記事を通してその利便性に触れてもらうことで、GitLab CI/CD Catalog を普及できたらと思っています。よろしければ最後までお付き合いください！

GitLab CI/CD Catalog とは？

まず、GitLab CI/CD Catalog の概要を簡単に紹介します。GitLab CI/CD Catalog には、「Components」と「Catalog」という 2 つの重要な概念があります。共通化された CI/CD コンポーネントである「Components」を作成し、それを「Catalog」に掲載することで、ユーザーに提供できる仕組みが GitLab CI/CD Catalog です。

Components

Components は次のように定義されます。まず、spec セクションでパラメーターを設定します。次に、ジョブの定義セクション（この例では sample-job）で、そのパラメーターを参照して処理を実行するジョブを記述します。

Components 作成時には、各パラメーターにデフォルト値を設定できますが、外部から呼び出す際にはこれらのデフォルト値を上書きすることもできます。さらに、パラメーターには description や type を指定することができ、必要に応じて配列やタプル型など、複雑なデータ型も使用できます。

# templates/sample-job.yml
spec:
  inputs:
    text:
      description: "表示する文字列"
      default: Hello, GitLab CI/CD Catalog!
      type: string
    stage:
      default: test
    runner_tag:
      default: kubernetes 
---
sample-job:
  script: echo $[[ inputs.text ]]
  stage: $[[ inputs.stage ]]
  tags: 
    - $[[ inputs.runner_tag ]]

Catalog

Components を作成、リリースすると、下図のように Catalog に掲載されます。Components の呼び出し方やパラメーターの説明が Components 定義をもとに自動で表示されます。（※パラメーターの Description、 Type の項目は、GitLab v17.2.0 から表示される模様）また、Readme でコンポーネントの導入方法や使用要件を詳細に提示することができます。

GitLab CI/CD Catalog を使ってみよう！

GitLab CI/CD Catalog の概要に触れたところで、次に、Components の作成から Catalog の利用までの流れを見ていきましょう。

1. Components リポジトリの準備

まず、Components 用のリポジトリを作成していきましょう。リポジトリの作成は通常のプロジェクトと同様に Create project から作成します。

次に、作成したプロジェクトを Components 用のリポジトリとして設定するために、①Project description の記入、②CI/CD Catalog project の有効化の 2 つの設定を行います。

プロジェクト自体の設定は完了したので、Components の中身を作成していきましょう。リポジトリのディレクトリ構造は下記のようになっています。

.
├── .gitlab-ci.yml
├── README.md
└── templates
    └── sample-job.yml
    └── sample-job2.yml

それぞれのファイルに以下の内容をそれぞれ記述します。
.gitlab-ci.yml: Components をリリースするパイプラインの設定（次節で説明）
README.md: Components の詳細（導入方法や使用要件など）
templates/xxx.yml: Components の定義（複数の Component を作成可能）

2. Components のリリース

.gitlab-ci.yml には、Components をリリースするパイプラインを設定します。下記のように記述することで、タグが作成された際に Components をリリースするジョブが実行されます。パイプライン実行時に「Your runner is outdated, please upgrade your runner」というエラーが表示された場合、GitLab Runner を GitLab サーバーと互換性のあるバージョンにアップデートする必要があります。

create-release:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script: echo "Creating release $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH"
  tags:
    - kubernetes # Runner のタグ名

タグを作成するとパイプラインが実行され、Components がリリースされたことが確認できると思います。

3. Catalog の確認

Components を作成しリリースしたことで Catalog に掲載されます。Catalog には、①Search or go to ＞ ②Explore ＞ ③CI/CD Catalog　から遷移することができます。

Catalog に遷移すると、先ほど作成した Components が作成したタグのバージョンで Catalog に掲載されたことが確認できると思います。

4. Catalog の使用

最後に作成した Components を Catalog から使用してみましょう。Components の使用はとても簡単で、Components の詳細に記載してある下記の記述を呼び出し側のリポジトリの .gitlab-ci.yml に記述するだけです。呼び出し時に、inputs 句を用いて、パラメーターのデフォルト値を書き換えることができます。

include:
  - component: $CI_SERVER_FQDN/xxx/yyy/sample-job@0.1.0
    # inputs:
    #   text: "from CI/CD!"

上記の内容をコミットすることで、Components の設定をもとにパイプラインが作成され、ジョブの中で「Hello, GitLab CI/CD Catalog!」という文字列が表示されたことを確認できます。

GitLab CI/CD Catalog 運用のコツ

GitLab CI/CD Catalog を運用する際のコツは、下記の 2 点です！

バージョン管理

Components を呼び出す記述において、バージョン部分は環境変数として定義することができます。下記のようにバージョン部分を $COMPONENT_VERSION のような環境変数名で CI/CD Variables に保持することもできます。

include:
  - component: $CI_SERVER_FQDN/xxx/yyy/@$COMPONENT_VERSION

また、 Components のバージョン指定において、セマンティックバージョニングのマイナーバージョンまで記述すれば、パッチバージョンには自動的に最新（latest）が適用されます。例えば、バージョン 1.0 と指定すれば、1.0.x の x の部分は最新のパッチバージョンが使用されます。マイナーバージョンまで指定した値を CI/CD Variables に定義し、Components にマイナーバージョン以上の更新があった場合にのみ CI/CD Variables を更新する運用を行うことで、効率的にバージョン管理を行うことができるでしょう。

権限管理

Catalog に掲載した Components を特定のユーザーにのみ使用や編集を許可したい場合があるかもしれません。Catalog に掲載された Components は、作成元のプロジェクトやそのプロジェクトが所属するグループの権限に基づいて管理することができます。

例えば、特定の Components を 使用のみ許可する場合、読み取り権限（Guest や Reporter 権限）をユーザーに対して付与します。使用と編集も許可するには、書き込み権限（Developer 以上の権限）を付与します。

使用権限がないユーザーが Components を使用しようとした場合、パイプライン作成時に下図のようなエラーが表示されます。

弊社での活用例

最後に、弊社での GitLab CI/CD Catalog の活用例を紹介します。現在、弊社ではビルド、テスト、デプロイのジョブを共通化するために、GitLab CI/CD Catalog を活用しています。

具体例として、Docker イメージをビルドしてレジストリにプッシュするジョブを紹介します。下記の Components では、before_script セクションでコンテナリポジトリの初期化とログインを行い、script セクションで Docker イメージのビルドおよびプッシュを実行します。（※ジョブ内で使用している環境変数は CI/CD Variables で定義している。）

spec:
  inputs:
    JOB_STAGE:
      description: "ジョブが属するステージ名"
      default: build
      type: string
    RUNNER_TAGS:
      description: "ジョブを実行する Runner のタグ名"
      default: ['kubernetes']
      type: array
    TRIGGERS:
      description: "ジョブが実行されるブランチ/タグ"
      default: ['develop', 'staging', 'master', 'tags']
      type: array
        
---
build-docker-image:
  stage: $[[ inputs.JOB_STAGE ]]
  before_script:
    # Initialize ECR repo
    - aws ecr create-repository --repository-name ${NAMESPACE}/${CI_PROJECT_NAME} --region ${REGISTRY_REGION} --image-tag-mutability ${REPOSITORY_MUTABILITY:-IMMUTABLE} || true
    - aws ecr put-image-tag-mutability --repository-name ${NAMESPACE}/${CI_PROJECT_NAME} --region ${REGISTRY_REGION} --image-tag-mutability ${REPOSITORY_MUTABILITY:-IMMUTABLE}
    # Login ECR
    - aws ecr get-login-password --region ${REGISTRY_REGION} | docker login --username AWS --password-stdin ${ECR_HOST}
  script: 
    # build & push docker image
    - docker build --no-cache=true -t ${CONTAINER_IMAGE_BUILT} .
    - docker push ${CONTAINER_IMAGE_BUILT}
  tags: $[[ inputs.RUNNER_TAGS ]]
  only:
    refs: $[[ inputs.TRIGGERS ]]

呼び出し側のリポジトリで、上記の Components を .gitlab-ci.yml ファイルから include することで、統一された Docker イメージのビルドジョブを利用できるようになります。

include:
  - component: $CI_SERVER_FQDN/xxx/yyy/build-docker-image@${COMPONENT_VERSION}

GitLab CI/CD Catalog を利用することで、複数のプロジェクト間での設定の共有・再利用が容易になります。例えば、上記の Components において aws コマンドの記述方法が変更され、修正が必要になった場合を考えてみましょう。GitLab CI/CD Catalog で共通化されていない場合、すべての呼び出し側リポジトリで記述を一つずつ変更する必要があります。しかし、共通化されている場合は、参照元のテンプレートを修正するだけで済み、CI/CD 管理の効率化やエラーの削減につながります。

さらに、利用者は Components を include するだけでジョブの具体的な処理内容を意識せずに CI/CD ジョブを作成できるため、本来の目的である開発に専念することができます。

おわりに

今回は、GitLab CI/CD の新機能である GitLab CI/CD Catalog の作成方法や、その運用におけるポイントについて紹介しました。
この機能を活用することで、効率的に CI/CD のパイプラインを構築・管理できる点に魅力を感じた方も多いのではないでしょうか。

CI/CD は、開発プロセスの効率化や迅速なリリースサイクルの実現に欠かせません。適切に管理・運用されていれば、チームのアジリティを飛躍的に向上させることができますが、その管理が不十分であると、CI/CD 自体が障害となり、開発スピードを遅らせる原因となってしまいます。

今後も、管理者が効率的に運用でき、使用者にとっても直感的で使いやすい CI/CD 環境の構築を目指していきたいです。最後までご拝読くださりありがとうございました！