CE版GitlabからGCPへのCI/CDパイプライン

2023.12.18 XIMIX Takai

H2を使用すると自動的にここに目次が入ります　　　　　　　　

はじめに

こんにちは。日本情報通信の髙井です。

この記事では、self-managedのGitlab(CE)から、GCPのアプリケーションプラットフォームへのデプロイパイプラインを構成する機会があったため、その際の手順を備忘としてブログにしたいと思います。

パイプライン構成

今回は以下の構成でCI/CDパイプラインを構成しています。前提として、使用するすべてのGCPサービスは同一のGCPプロジェクト、リージョンは asia-northeast1 で統一して構築しています。また、使用するGCPサービスは下記になります。

Cloud Source Repositries: リポジトリサービス
Cloud Build: CI/ CD プラットフォーム
Google App Engine: アプリケーションプラットフォーム

はじめに、GitlabからGCPのCloud Source Repositriesにリポジトリをミラーリングしています。その後、Cloud BuildでSource Repositriesの更新をキャッチしてビルドトリガーを起動し、目的のプラットフォームへのデプロイを実現しています。

構築

GitlabからSource Repositriesへのミラーリング

今回の構成では、GitlabのリポジトリをSource RepositriesへミラーリングしてからCloud Buildでリポジトリ参照を行っています。GithubかBitBucketまたは、GitlabがEEかSaaS版であれば、Cloud Buildコンソールから直接リポジトリを接続することも可能です。

1. Source Repositriesに空のリポジトリを作成

Source Repositriesのコンソール画面にアクセスし、画面右上のから新規リポジトリ作成画面に移動します。続けて、新しいリポジトリを作成にチェックが入っている状態で続行をクリックします。

リポジトリ名を記載し、プロジェクトを選択（または新規GCPプロジェクトを作成）してリポジトリを作成します。これでミラーリング用のリポジトリが準備できました。

2. Gitの認証情報を生成

手順 1 で空のリポジトリを作成すると、コードを追加する方法を選択する画面が表示されるので、手動で生成した認証情報タブを選択します。そうすると下記の画面が表示されるため、「Git 認証情報を生成して保存します。」のリンクをクリックします。（リポジトリにコードを push するオプションを選択は今回の手順では関係ないため、どちらを選択した状態でも構いません。）

アカウントへのアクセス権限の確認が表示されるため許可します。

アクセス許可を実施すると、次のような画面が表示されます。こちらには、Git認証情報を生成するためのコマンドが表示されています。2つのコマンド枠が表示されていますが、上がWindows(Powershell)、下がLinux系(bash or zsh)のコマンドとなるため、どちらか一方をコピーします。

※ これらのコマンドは今回の手順では実行する必要はありません。ただし、ローカルからSource Repositriesへ直接ソースコードをプッシュしたい場合などに、ローカルのgit設定に認証情報を登録するために実行が必要となります。

ローカルでエディタを起動し、コピーしたコマンドをペーストし、下記の USERNAME と PASSWORD の情報を確認してそれぞれを控えます。

Powershell

git config --global http.cookiefile "%USERPROFILE%\.gitcookies"
powershell -noprofile -nologo -command Write-Output "source.developers.google.com`tFALSE`t/`tTRUE`t2147483647`to`t%USERNAME%=%PASSWORD%" >>"%USERPROFILE%\.gitcookies"

※ USERNAME の直前の `t は特殊文字のため含めないようご注意ください。

bash / zsh

eval 'set +o history' 2>/dev/null || setopt HIST_IGNORE_SPACE 2>/dev/null
 touch ~/.gitcookies
 chmod 0600 ~/.gitcookies

 git config --global http.cookiefile ~/.gitcookies

 tr , \\t <<\__END__ >>~/.gitcookies
source.developers.google.com,FALSE,/,TRUE,2147483647,o,${USERNAME}=${PASSWORD}
__END__
eval 'set -o history' 2>/dev/null || unsetopt HIST_IGNORE_SPACE 2>/dev/null

3. Gitlabに認証情報を登録してミラーリングを実行

ミラーリングするGitlabリポジトリのコンソール画面にアクセスし、設定 > リポジトリを開きます。

下記情報を入力し、ミラーリングを実施します。

項目	値	備考
Git リポジトリ URL	https://${USERNAME}@source.developers.google.com/p/${PROJECT_ID}/r/${REPO_NAME}	${USERNAME}: 手順 2 でメモした USERNAME ${PROJECT_ID}: GCPのプロジェクトID ${REPO_NAME}: Source Repositries側のリポジトリ名
パスワード	手順 2 でメモした PASSWORD
Keep divergent refs	任意	リモート側で個別更新されたコミットを保持するかどうか（参照）
Mirror only protected branches	任意	リモートにミラーするブランチを保護されたブランチのみに限定するかどうか（参照）

ミラーリング設定が完了すると、下記のようにミラーリング状態が表示されるようになります。ここで、最後の成功した更新が正しく表示されればSource Repositriesとの接続は成功です。今後は、GitlabのリポジトリにプッシュするたびにSource Repositries側のリポジトリへ更新がミラーリングされるようになります。また、こちらの画面で強制的にプッシュしたり、ミラーリング設定を削除したりすることが可能です。

Source Repositries側のリポジトリにミラーリングされていることが確認できます。
（Gitlab: test-gitlab-repo → Source Repositries: test-gitlab-mirrored-repo）

Cloud Buildトリガー

続いて、Cloud Buildでデプロイトリガーを構成する手順について説明します。Cloud Buildは、様々なGCPでサービスへのデプロイ管理に特化した CI/CDパイプラインを提供するサービスです。今回は、デプロイ先のプラットフォームサービスとしてGoogle App Engineを選択していますが、その他にもGoogle Cloud RunやGoogle Cloud Functions, Google Compute Engineなど多くのサービスへのCI/CDパイプラインを構成できます。

1. トリガーの作成

まずはじめに、Cloud Buildコンソール画面のトリガーへアクセスします。

をクリックし、トリガー作成画面へ移動します。こちらの画面で、下記の設定を入力します。今回はビルド構成ファイルに Cloud Build 構成ファイル（yaml または json）を選択することを前提とします。

項目	説明	備考
名前	トリガーの名称
リージョン	トリガーを構成するリージョンの指定	この記事では asia-northeast1 (東京)
説明	トリガーの説明
タグ	GCPで管理するためのタグ付け	リポジトリのタグではないので注意
イベント	どのイベントが発生した場合にトリガーを起動するか	リポジトリイベントだけではなく、Pub/Subからの起動なども可能この記事ではブランチに push するを選択
ソース-リポジトリの生成	リポジトリ種別の選択	このケースでは第１世代の選択が必須
ソース-リポジトリ	デプロイを実施する対象のリポジトリを指定	この記事では作成したSource Repositriesリポジトリを指定
ソース-ブランチ	デプロイを実施する対象のブランチを指定	正規表現での指定が可能例: prod-が先頭につくものすべて → ^prod-.*$ この記事では ^main$ を指定(mainブランチのみ)
構成-形式	ビルド構成ファイルをどの種類で行うか指定	この記事ではCloud Build 構成ファイルを選択
構成-ロケーション	ビルド構成ファイルの配置場所を指定	リポジトリ: ソースコードに一緒に配置インライン: トリガー画面で構成この記事ではリポジトリを選択
Cloud Build 構成ファイルの場所	構成-形式でCloud Build 構成ファイル、構成-ロケーションでリポジトリを選択した場合、ソースコードでのビルド構成ファイル配置位置をパスで指定	構成ファイル名が/cloudbuild.yamlかつ rootに配置の場合: /cloudbuild.yaml
代入変数	構成-形式でCloud Build 構成ファイルを指定した場合、後述するcloudbuild.yaml(またはjson)で参照可能な変数を設定	ソースコードに含めたくない情報やビルド時だけに使用したい変数のために使用
承認	トリガー起動後、ビルドを実施する前に承認を必要とするか否かを選択	承認はCloud Build 承認者ロールを持つユーザーが可能
サービスアカウント	ビルドを実行するサービスアカウントを指定	今回の構成だと以下のロールがあれば十分 - App Engine サービス管理者 - App Engine デプロイ担当者 - Cloud Build サービスアカウント - サービスアカウントユーザー

作成が完了すると、このようにトリガーが表示されます。あとは、指定したイベントを発生させることで選択したブランチからビルドが実行されます。

2. cloudbuild.yaml(json)

手順 1 でビルドトリガーの作成はできましたが、この状態でトリガーを実行してもビルド構成ファイルが正しく設定されていないとビルドエラーが発生してしまいます。そのため、この節ではビルド構成ファイルの形式である、cloudbuild.yaml(json)ファイルについて説明します。（この記事では yaml 形式を使用しています。）

cloudbuild.yaml は下記のようなフォーマットで記載します。この構成では .env ファイルをビルド環境変数から作成し、そのファイルを含めてGAEへのデプロイを行っています。

steps:
  # .env を作成する
  - id: set_build_env_vars
    name: 'bash'
    script: |
      #!/usr/bin/env bash
      set -eEuo pipefail
      cat <<EOF > ./.env
      BUILD_ENV_VAR1="$_BUILD_ENV_VAR1"
      BUILD_ENV_VAR2="$_BUILD_ENV_VAR2"
      EOF
    # GAE デプロイ
  - id: deploy_app
    name: 'gcr.io/cloud-builders/gcloud'
    args: ['app', 'deploy', 'app.yaml', '--project=$PROJECT_ID', '--quiet']
timeout: 900s
options:
  automapSubstitutions: true
  logging: CLOUD_LOGGING_ONLY #ログ保存先を制限

今回使用したフィールドの概要を下記に記載します。記載していないものも多くあるためフィールド一覧はこちらを参照ください。

フィールド名	概要	備考
steps	Cloud Build で実行するビルドステップを管理するフィールドファイルの先頭に記述
id	ステップの id を指定 waitFor を使用してステップ順序を指定する場合に必要	省略可
name	タスクを実行するコンテナイメージを指定	コンテナイメージ一覧 bash や python などスクリプト実行を指定することも可能（参照）
args, script	nameフィールドで指定したビルダーに渡され、コマンドとして実行される
timeout	ビルドの実行が許可される時間	デフォルトで 60 分ここでは 15 分を指定
options	様々なオプション引数を指定可能	オプション引数一覧ここでは、bashスクリプト内でビルド変数を参照できるようにするオプションと、ログ出力をロギングのみに制限するオプションを使用

ビルド環境変数の置換は ${VARIABLE_NAME} で指定でき（{}は省略可能）、手順 1 で設定した変数の他に組み込みで用意されているものもあります。なお、ユーザーがトリガー作成画面で設定する変数は変数名が必ず_（アンダースコア）から開始となります。（組み込みの変数は_が頭につかないものが多い）

3. ビルドの実行

ここまでの手順でCloud Buildのトリガーを実行するための準備はできているため、残すはビルドを実行し、アプリをデプロイするのみです。それではGitlabリポジトリの main ブランチにpushしてみます。

注意: ビルドの実行には事前に特定のAPIを有効化している必要があります。
有効化が必要なAPIは公式ドキュメントを参照ください。

Identity and Access Management (IAM) API
デプロイ対象サービスの管理API: GAEの場合 → App Engine Admin API

ソースのpush後、Cloud Buildコンソール画面のビルド履歴で実行ログを確認することができます。これでビルドが正しく完了していることが確認できます。これにCI/CDパイプラインの構成は完了です。以下、appendixにCloud Buildで使用できる便利機能について少しまとめていますので、参考にしていただければと思います。

appendix

秘密情報の管理

アプリデプロイをする際に、ソースコードには直接含められないデータを扱う場合が多々あると思います。（例えば、連携サービスのAPIキーや認証情報など）そういう場合は、Cloud Key Management System(KMS)を利用して秘匿情報を管理することが可能です。KMSで管理しているデータは、cloudbuild.yaml に設定を追加して容易に呼び出すことができます。

  # Read key from KMS
  - id: read_key_from_kms
    name: gcr.io/cloud-builders/gcloud
    args:
    [
       "kms",
       "decrypt",
        "--ciphertext-file=$_KMS_ENCFILE",
        "--plaintext-file=$_OUTPUT_FILE",
        "--location=$_LOCATION",
        "--keyring=$_KEYRING",
        "--key=$_KEYNAME",
    ]
  # Deploy
  - id: deploy_app
  ...

上記の例では、$_OUTPUT_FILE に複合化されたキー情報を出力しています。

テスト自動化

cloudbuild.yaml にテストステップを追加してテストをパイプライン上で自動化することができます。下記の例はNode.jsでの例になります。テストエラーがあった場合はデプロイフローを中断します。

  # Node Package Install
  - id: install_npm_packages 
    name: "gcr.io/cloud-builders/npm:${_NODE_VERSION}"
    args: ["install"]
  # Test
  - id: test
    name: "gcr.io/cloud-builders/npm:${_NODE_VERSION}"
    args: ["test"]
  # Deploy
  - id: deploy_app
  ...

まとめ

この記事では、self-managedのGitlab(CE)からGCPのアプリケーションプラットフォームへCI/CDを構成する方法について説明しました。この方法はその他、EEやSaaS版のGitlabでも同様に構成することが可能です。ざっくり要点をまとめると下記2点抑えてもらえれば大丈夫かと思います。

GitlabからSource Repositriesにリポジトリのミラーリングを行う
Cloud BuildでCI/CDパイプラインを構成する

今回の内容は単純なフローでの説明となってしまいましたが、紹介にとどめた自動テストなどについても（知見が溜まれば）実践的な例を紹介できればと思います。
また、GitHubをリポジトリサービスとして利用する場合は、Google Cloud DeployとGitHub Actionsが連携したこともあり、こちらの構成についても機会があれば記事にしたいです。