GitLab Runner Helmチャート

GitLab RunnerインスタンスをKubernetesクラスタにデプロイする公式の方法は、gitlab-runner Helmチャートを使うことです。

このチャートはGitLab Runnerを次のように設定します：

  • GitLab RunnerのKubernetes Executorを使用して実行します。
  • GitLab CI/CDから受け取った新しいジョブごとに、指定した名前空間内に新しいポッドをプロビジョニングして実行します。

前提条件

  • GitLabサーバーのAPIがクラスターから到達可能であること。
  • Kubernetes 1.4+でBeta APIが有効になっていること。
  • kubectl CLIがクラスターのためにローカルにインストールされ、認証されていること。
  • ローカルにインストールされたHelmクライアント。

Helm Chartを使ったGitLab Runnerのインストール

GitLab Helm リポジトリを追加します：

helm repo add gitlab https://charts.gitlab.io

Helm 2 を使っている場合は、Helm も初期化する必要があります：

helm init

GitLab Runnerの最新バージョンにアクセスできない場合は、Chartを更新する必要があります。Chartを更新するには、以下を実行してください：

helm repo update gitlab

アクセス可能なGitLab Runnerバージョンのリストを表示するには、以下を実行してください：

helm search repo -l gitlab/gitlab-runner

values.yaml ファイルで GitLab Runner を設定したら、以下を実行してください：

# For Helm 2
helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

# For Helm 3
helm install --namespace <NAMESPACE> gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

どこに：

  • <NAMESPACE> はGitLab RunnerをインストールしたいKubernetesの名前空間です。
  • <CONFIG_VALUES_FILE> はカスタム設定を含むvaluesファイルへのパスです。作成するには、Helm Chartを使用したGitLab Runnerの設定セクションを参照してください。

GitLab Runner Helm Chart の特定のバージョンをインストールしたい場合は、helm install コマンドに--version <RUNNER_HELM_CHART_VERSION> を追加してください。この方法でどのバージョンのChartでもインストールできますが、最近のvalues.yml 、古いバージョンのChartでは動作しないことがあります。

Helm Chart を使った GitLab Runner のアップグレード

GitLab Runner をアップグレードする前に、GitLab で Runner を一時停止し、ジョブが完了していることを確認してください。Runner を一時停止することで、ジョブが完了したときに作成者エラーなどの問題が発生するのを防ぐことができます。

GitLab Runner Chart がインストールされたら、設定の変更やチャートのアップデートはhelm upgrade を使って行ってください：

helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner

どこに：

  • <NAMESPACE> はGitLab RunnerがインストールされているKubernetesの名前空間です。
  • <CONFIG_VALUES_FILE> はカスタム設定を含むvaluesファイルへのパスです。作成するには、Helm Chartを使用したGitLab Runnerの設定セクションを参照してください。
  • <RELEASE-NAME> はインストール時につけたChartの名前です。Installing GitLab Runner using the Helm Chartセクションでは、gitlab-runner としました。

GitLab Runner Helm Chart を最新のものではなく特定のバージョンにアップデートしたい場合は、helm upgrade コマンドに--version <RUNNER_HELM_CHART_VERSION> を追加します。

利用可能な GitLab Runner Helm Chart のバージョンを確認します。

Helm ChartとGitLab Runnerのバージョンは同じではありません。Helm Chart と GitLab Runner のバージョンマッピングを取得するには、以下のコマンドを使用します：

# For Helm 2
helm search -l gitlab/gitlab-runner

# For Helm 3
helm search repo -l gitlab/gitlab-runner

出力例を以下に示します：

NAME                 CHART VERSION APP VERSION DESCRIPTION
gitlab/gitlab-runner 0.51.0        15.10.0     GitLab Runner
gitlab/gitlab-runner 0.50.1        15.9.1      GitLab Runner
gitlab/gitlab-runner 0.50.0        15.9.0      GitLab Runner
gitlab/gitlab-runner 0.49.3        15.8.3      GitLab Runner
gitlab/gitlab-runner 0.49.2        15.8.2      GitLab Runner
gitlab/gitlab-runner 0.49.1        15.8.1      GitLab Runner
gitlab/gitlab-runner 0.49.0        15.8.0      GitLab Runner
...

Helm Chart を使った GitLab Runner の設定

GitLab Runnerの設定用にvalues.yaml 。設定ファイルがデフォルトをどのように上書きするかについては、Helm のドキュメントを参照してください。

デフォルトの設定は常にChartリポジトリのvalues.yaml 。

必要な設定

GitLab Runnerを機能させるためには、設定ファイルに以下を指定する必要があります：

  • gitlabUrl:Runner を登録する GitLab サーバーの完全な URL。例えば、https://gitlab.example.com 。
  • rbac: { enable: true }:GitLab RunnerのRBACルールを作成し、ジョブを実行するポッドを作成します。使用したい既存のserviceAccount がある場合は、rbac: { serviceAccountName: "SERVICE_ACCOUNT_NAME" } も設定してください。serviceAccountに必要な最小限の権限については、Configure runner API permissionsを参照してください。
  • runnerToken:

    - または

  • runnerRegistrationToken (GitLab15.6では非推奨)：

追加の設定が必要でなければ、GitLab Runnerのインストールは完了です。

追加の設定

Helm Chart 0.23.0で設定テンプレートを導入しました。非推奨のイシューを参照してください。

設定テンプレートファイルを使用して、Kubernetes内のGitLab Runnerビルドポッドの動作を設定できます。設定テンプレートを使えば、Helm Chartが特定のRunner設定オプションを意識することなく、Runner上の任意のフィールドを設定することができます。

以下は、Chartリポジトリ内のvalues.yaml ファイル](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/main/values.yaml) にあるデフォルト設定[のスニペットです。values.yamlにconfig.toml を埋め込んでいるため、config: セクションのフォーマットはtoml (<parameter>: <value>の代わりに<parameter> = <value> ) であることに注意してください。

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"

Executor 固有の設定はvalues.yaml に文書化されています。

追加オプションを設定するには、設定テンプレートを使用します。

この機能はGitLab 13.6で非推奨となり、16.0で削除されました。 代わりに設定テンプレートを使って追加オプションを設定してください。

設定テンプレートでキャッシュを使う

設定テンプレートでキャッシュを使用するには、values.yaml で以下の変数を設定します：

  • runners.cache.secretName に、オブジェクト・ストレージ・プロバイダのシークレット名 (s3access,gcsaccess,google-application-credentials, またはazureaccess) を設定します。
  • runners.config をキャッシュのその他の設定に使用します。toml フォーマットを使用します。

S3

例えば、以下は静的な認証情報でS3を設定する例です：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "s3"
        Path = "runner"
        Shared = true
        [runners.cache.s3]
          ServerAddress = "s3.amazonaws.com"
          BucketName = "my_bucket_name"
          BucketLocation = "eu-west-1"
          Insecure = false
          AuthenticationType = "access-key"

  cache:
      secretName: s3access

次に、accesskey とsecretkey を含むs3access Kubernetes シークレットを作成します：

kubectl create secret generic s3access \
    --from-literal=accesskey="YourAccessKey" \
    --from-literal=secretkey="YourSecretKey"

Googleクラウドストレージ(GCS)

静的認証情報を直接設定

次の例では、アクセス ID と秘密鍵を使って GCS を設定する方法を示します：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "gcs"
        Path = "runner"
        Shared = true
        [runners.cache.gcs]
          BucketName = "runners-cache"

  cache:
    secretName: gcsaccess

次に、gcs-access-id とgcs-private-key を含むgcsaccess Kubernetes シークレットを作成します：

kubectl create secret generic gcsaccess \
    --from-literal=gcs-access-id="YourAccessID" \
    --from-literal=gcs-private-key="YourPrivateKey"

GCPからダウンロードしたJSONファイル内の静的認証情報

次の例は、Google Cloud PlatformからダウンロードしたJSONファイル内の資格情報を使用してGCSを設定する方法を示しています：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "gcs"
        Path = "runner"
        Shared = true
        [runners.cache.gcs]
          BucketName = "runners-cache"

  cache:
      secretName: google-application-credentials

secrets:
  - name: google-application-credentials

次に、Kubernetes secretgoogle-application-credentials を作成し、JSONファイルをロードします：

kubectl create secret generic google-application-credentials \
    --from-file=gcs-application-credentials-file=./path-to-your-google-application-credentials-file.json

Azure

次の例は、Azure Blob Storageの設定方法を示しています：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"
      [runners.cache]
        Type = "azure"
        Path = "runner"
        Shared = true
        [runners.cache.azure]
          ContainerName = "CONTAINER_NAME"
          StorageDomain = "blob.core.windows.net"

  cache:
      secretName: azureaccess

次に、azure-account-name とazure-account-key を含むazureaccess Kubernetes シークレットを作成します：

kubectl create secret generic azureaccess \
    --from-literal=azure-account-name="YourAccountName" \
    --from-literal=azure-account-key="YourAccountKey"

Helmチャートのキャッシュについては、values.yaml 。

RBACサポートの有効化

クラスターでRBACが有効になっている場合、Chartに独自のサービスアカウントを作成させるか、自分でアカウントを用意するかを選択できます。

Chartにサービス・アカウントを作成させるには、rbac.create をtrueに設定します：

rbac:
  create: true

既に存在するサービスアカウントを使用するには、次のようにします：

rbac:
  create: false
  serviceAccountName: your-service-account

Runnerの最大同時実行数の制御

Kubernetes上にデプロイされた単一のGitLab Runnerは、追加のRunnerポッドを自動的に起動することで、複数のジョブを並行して実行することができます。concurrent の設定 は、一度に許可されるポッドの最大数を制御するもので、デフォルトは10 です：

## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10

GitLab RunnerでDocker-in-Dockerコンテナを実行します。

有効にする方法についてはrun privileged containers for the runnerを、dind の実行についてはGitLab Runner のドキュメントを参照してください。

ランナー用の特権コンテナの実行

特権コンテナを使って実行するようにGitLab Runnerに指示することができます。GitLab CI/CDジョブの中でDocker実行ファイルを使用する必要がある場合、これを有効にする必要があるかもしれません。

これには、GitLab CI/CD Runnerのドキュメントで読むことができるいくつかのリスクが伴います。

もしそのリスクに問題がなく、GitLab Runner のインスタンスが GitLab の特定のプロジェクトに対して登録されていて、その CI ジョブを信頼しているのであれば、values.yaml で特権モードを有効にすることができます：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        # Run all containers with the privileged flag enabled.
        # See https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerskubernetes-section for details.
        privileged = true
        ...

特権モードを使わないコンテナ構築のベストプラクティス

Docker-in-Dockerでコンテナの中にコンテナをビルドするには、Docker特権モードが必要です。GoogleのKanikoは特権モードなしで動作する代替手段であり、Kubernetes GitLab Runnerでテストされています。

TheLeast Privilege Container Builds with Kaniko on GitLabvideoは、Kaniko Docker Buildの動作例プロジェクトのウォークスルーです。Building images with Kaniko and GitLab CI/CDのドキュメントを活用しています。

このサンプルプロジェクトを自分のグループやインスタンスにコピーしてテストすることができます。他のGitLab CIパターンがどのようなものかについての詳細は、プロジェクトページのKaniko Docker Buildをご覧ください。

非公開レジストリからのイメージの使用

非公開レジストリから画像を使うには、imagePullSecrets の設定が必要です。imagePullSecrets の作成方法の詳細については、ドキュメントを参照してください。

CI/CDジョブで使用するKubernetesネームスペースに1つ以上のシークレットを作成する必要があります。

次のコマンドを使用して、image_pull_secrets で動作するシークレットを作成できます：

kubectl create secret docker-registry <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --docker-server="https://<REGISTRY_SERVER>" \
  --docker-username="<REGISTRY_USERNAME>" \
  --docker-password="<REGISTRY_PASSWORD>"

runners.imagePullSecrets を設定すると、コンテナはイメージエントリポイントスクリプトに--kubernetes-image-pull-secrets "<SECRET_NAME>" を追加します。これにより、Kubernetes Executorconfig.toml 設定でimage_pull_secrets パラメータを設定する必要がなくなります。

runners:
  ## Specify one or more imagePullSecrets
  ##
  ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
  ##
  imagePullSecrets: [your-image-pull-secret]

フォーマットに注意してください。Kubernetesリソースの慣例のように、値の先頭にname タグは付きません。複数のレジストリ認証情報を使用しているかどうかにかかわらず、1つ以上のシークレット名の配列が必要です。

GitLabにアクセスするためのカスタム証明書の提供

GitLab Runner Helm Chart にKubernetes Secretを提供することができ、コンテナの/home/gitlab-runner/.gitlab-runner/certs ディレクトリに入力するために使用されます。

シークレットの各キー名はディレクトリ内のファイル名として使用され、ファイルの内容はキーに関連付けられた値となります：

  • gitlab.your-domain.com.crt使用される鍵/ファイル名は<gitlab.hostname>.crt の形式でなければなりません。
  • 中間証明書は、同じファイル内のサーバー証明書に連結する必要があります。
  • 使用するホスト名は、証明書が登録されているものでなければなりません。

自動生成された自己署名ワイルドカード証明書を使用してGitLab Helm Chartをインストールした場合は、シークレットが作成されます。

## Set the certsSecretName to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /home/gitlab-runner/.gitlab-runner/certs/ directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates-targeting-the-gitlab-server
##
certsSecretName: RELEASE-wildcard-tls-chain

GitLab Runner Helm Chartではシークレットは作成されません。シークレットを作成するには、Kubernetesに証明書をシークレットとして保存し、GitLab Runnerコンテナにファイルとして提示するように指示します。これを行うには、次のコマンドを実行します：

kubectl create secret generic <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --from-file=<CERTIFICATE_FILENAME>

どこに：

  • <NAMESPACE> はGitLab RunnerをインストールしたいKubernetesの名前空間です。
  • <SECRET_NAME> はKubernetesシークレットリソース名です。(例:gitlab-domain-cert.)
  • <CERTIFICATE_FILENAME> はカレントディレクトリにある証明書のファイル名で、シークレットにインポートされます。

ソースファイル<CERTIFICATE_FILENAME> がカレントディレクトリにない場合、または<gitlab.hostname.crt> の形式に従っていない場合は、ターゲットで使用するファイル名を指定する必要があります：

kubectl create secret generic <SECRET_NAME> \
  --namespace <NAMESPACE> \
  --from-file=<TARGET_FILENAME>=<CERTIFICATE_FILENAME>

どこに：

  • <TARGET_FILENAME> は、Runner コンテナに表示される証明書ファイルの名前です。(例:gitlab.hostname.crt.)
  • <CERTIFICATE_FILENAME> は、シークレットにインポートされる、カレントディレクトリからの相対的な証明書のファイル名です。(例:cert-directory/my-gitlab-certificate.crt)。

次に、GitLab Runner Chartにシークレットの名前を提供する必要があります。values.yaml に以下を追加してください：

## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /home/gitlab-runner/.gitlab-runner/certs/ directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
##
certsSecretName: <SECRET NAME>

どこに：

  • <SECRET_NAME> はKubernetes Secretリソース名で、上記の例ではgitlab-domain-cert 。

GitLab Runner がこれらの証明書をどのように使うかについての詳細は、Runner ドキュメントにあります。

CI 環境変数のキーにポッドラベルを設定します。

現時点では、values.yaml ファイル内で環境変数をポッドラベルとして使用することはできません。このイシューで取り組んでいます：環境変数キーをポッドラベルとして設定できません。一時的な解決策として、イシューに記載されている回避策を使用してください。

登録トークンまたはランナートークンをシークレットに保存します。

16.1で導入

GitLab UI で作成した Runner を登録するには、values.yml にrunnerToken を指定します。runnerToken は、ランナーを作成するときに UI に短く表示されます。

values.yml にトークンを格納するのはセキュリティリスクとなる可能性があります。特に、これらのトークンをgit にコミットする場合は注意が必要です。代わりに、これらのトークンの値をKubernetes シークレットの内部に格納し、values.yml のrunners.secret の値をシークレットの名前で更新することができます。

既存の登録ランナーがあり、それを使用したい場合は、runner-token 、そのランナーを識別するために使用するトークンを設定します。新しいランナーを登録したい場合は、runner-registration-token に登録トークン（非推奨。

使用例：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # need to leave as an empty string for compatibility reasons
  runner-token: "REDACTED"

runners:
  secret: gitlab-runner-secret

この例では、シークレットgitlab-runner-secret を使用し、runner-token の値をランナーの登録に使用します。

note
あなたの秘密管理ソリューションがrunner-registration-tokenに空の文字列を設定できない場合、任意の文字列を設定することができます -runner-token が存在する場合は無視されます。

Ubuntuベースのgitlab-runner Dockerイメージへの切り替え

デフォルトでは、GitLab Runner Helm Chart は Alpine 版のgitlab/gitlab-runner イメージを使います。このイメージはmusl libcを使っています。場合によっては、glibc を使う Ubuntu ベースのイメージに切り替えたいこともあるでしょう。

そのためには、values.yaml ファイルを以下の値で更新してください：

# Specify the Ubuntu image. Remember to set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v15.11.0

# Update the security context values to the user ID in the ubuntu image
securityContext:
  fsGroup: 999
  runAsUser: 999

非 root ユーザーでの実行

デフォルトでは、GitLab Runnerイメージは非rootユーザーでは動作しません。GitLab Runner UBIと GitLab Runner Helper UBIイメージはそのシナリオのために設計されています。これらを使用するには、GitLab RunnerとGitLab Runner Helperイメージを変更してください：

note
このイメージは、どのユーザーIDでも使えるように設計されています。このユーザーIDがrootグループの一員であることが重要です。rootグループの一員だからといって特別な権限が与えられるわけではありません。
image: registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp:v15.11.0

securityContext:
    runAsNonRoot: true
    runAsUser: 999

runners:
    config: |
        [[runners]]
          [runners.kubernetes]
            helper_image = "registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:x86_64-v15.11.0"
            [runners.kubernetes.pod_security_context]
              run_as_non_root = true
              run_as_user = 59417

FIPS 準拠の GitLab Runner を使うには

FIPS準拠のGitLab Runnerを使用するには、GitLab RunnerイメージとHelperイメージを以下のように変更します：

image: gitlab/gitlab-runner:ubi-fips

runners:
    config: |
        [[runners]]
          [runners.kubernetes]
            helper_image_flavor = "ubi-fips"

Helm Chartを使用したGitLab Runnerのアンインストール

GitLab Runnerをアンインストールする前に、GitLabでRunnerを一時停止し、ジョブが完了していることを確認してください。Runner を一時停止することで、ジョブが完了したときに作成者エラーなどの問題が発生するのを防ぐことができます。

GitLab Runner Chartをアンインストールするには、以下を実行します：

helm delete --namespace <NAMESPACE> <RELEASE-NAME>

どこに：

  • <NAMESPACE> はGitLab RunnerがインストールされているKubernetesの名前空間です。
  • <RELEASE-NAME> はインストール時につけたChartの名前です。Installing GitLab Runner using the Helm Chartセクションでは、gitlab-runner としました。

Kubernetesインストールのトラブルシューティング

ERROR: Job failed (system failure): secrets is forbidden

以下のようなエラーが表示された場合：

Using Kubernetes executor with image alpine ...
ERROR: Job failed (system failure): secrets is forbidden: User "system:serviceaccount:gitlab:default" cannot create resource "secrets" in API group "" in the namespace "gitlab"

エラーを修正するには、RBACサポートを有効にしてください。

Unable to mount volumes for pod

必要なシークレットに対するマウントボリュームの失敗が表示される場合は、シークレットに登録トークンまたはランナートークンを格納するに従っていることを確認してください。

Google Cloud Storage へのアーティファクトのアップロードが遅い

Google Cloud Storageへのアーティファクトのアップロードは、RunnerヘルパーポッドがCPUに負荷がかかり、パフォーマンスが低下することがあります。これは、帯域幅レートの低下という形で現れます。

これはヘルパーポッドのCPU制限を増やすことで軽減できます：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        helper_cpu_limit = "250m"

PANIC: creating directory: mkdir /nonexistent: permission denied

このエラーを解決するには、UbuntuベースのGitLab Runner Dockerイメージに切り替えてください。

致命的です：名前とエクゼキュータ設定以外のランナー設定は予約されているため（具体的には –locked、–access-level、–run-untagged、–maximum-timeout、–paused、–tag-list、–maintenance-note）、ランナー認証トークンで登録する際に指定できません。この設定はGitLabサーバー上で指定します。これらの引数を指定せずに再試行してください。

GitLab Runner Helm chartをインストールした後、ポッドログにこのエラーが表示されることがあります。認証トークンを使用し、シークレットを通してトークンを提供した場合に発生します。このエラーを修正するには、values YAML ファイルをレビューし、非推奨の値を使用していないことを確認します。非推奨の値の詳細については、Helm chartを使用したGitLab Runnerのインストールを参照してください。