GitLab Runner Helm Chartを設定する
- プラン: Free、Premium、Ultimate
- 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
オプションの設定をGitLab Runner Helmチャートに追加できます。
設定テンプレートでキャッシュを使用する
設定テンプレートでキャッシュを使用するには、values.yamlで次の変数を設定します:
runners.cache.secretName: オブジェクトストレージプロバイダーのシークレット名。オプションは、s3access、gcsaccess、google-application-credentials、またはazureaccessです。runners.config: TOML形式のキャッシュに関するその他の設定。
Amazon S3
静的認証情報を使用するAmazon S3を設定するには、次の手順に従います:
次の例を
values.yamlに追加します。必要に応じて値を変更してください: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: s3accessaccesskeyとsecretkeyを含むKubernetesのシークレットs3accessを作成します:kubectl create secret generic s3access \ --from-literal=accesskey="YourAccessKey" \ --from-literal=secretkey="YourSecretKey"
Google Cloud Storage（GCS）
Google Cloud Storageは、静的な認証情報を使用して複数の方法で設定できます。
直接設定された静的認証情報
アクセスIDとプライベートキーを含む認証情報を使用してGCSを設定するには、次の手順に従います:
次の例を
values.yamlに追加します。必要に応じて値を変更してください: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: gcsaccessgcs-access-idとgcs-private-keyを含むKubernetesのシークレットgcsaccessを作成します:kubectl create secret generic gcsaccess \ --from-literal=gcs-access-id="YourAccessID" \ --from-literal=gcs-private-key="YourPrivateKey"
GCPからダウンロードしたJSONファイル内の静的認証情報
Google Cloud PlatformからダウンロードしたJSONファイル内の認証情報を使用してGCSを設定するには、次の手順に従います:
次の例を
values.yamlに追加します。必要に応じて値を変更してください: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-credentialsgoogle-application-credentialsという名前のKubernetesのシークレットを作成し、このシークレットを含むJSONファイルを読み込みます。必要に応じてパスを変更します:kubectl create secret generic google-application-credentials \ --from-file=gcs-application-credentials-file=./PATH-TO-CREDENTIALS-FILE.json
Azure
Azure Blob Storageを設定するには、次の手順に従います:
次の例を
values.yamlに追加します。必要に応じて値を変更してください: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: azureaccessazure-account-nameとazure-account-keyを含むKubernetesのシークレットazureaccessを作成します:kubectl create secret generic azureaccess \ --from-literal=azure-account-name="YourAccountName" \ --from-literal=azure-account-key="YourAccountKey"
Helmチャートのキャッシュの詳細については、values.yamlを参照してください。
永続ボリュームクレーム
どのオブジェクトストレージオプションも動作しない場合は、キャッシュに永続ボリュームクレーム（PVC）を使用できます。
PVCを使用するようにキャッシュを設定するには、次のようにします:
ジョブポッドが実行されるネームスペースでPVCを作成します。
複数のジョブポッドが同じキャッシュPVCにアクセスできるようにする場合は、
ReadWriteManyアクセスモードにする必要があります。PVCを
/cacheディレクトリにマウントします:runners: config: | [[runners]] [runners.kubernetes] image = "ubuntu:22.04" [[runners.kubernetes.volumes.pvc]] name = "cache-pvc" mount_path = "/cache"
RBACサポートを有効にする
クラスターでRBAC（ロールベースのアクセス制御）が有効になっている場合、このチャートにより作成されるチャート独自サービスアカウントや自分で作成するサービスアカウントを使用することができます。
チャートにサービスアカウントを作成させるには、
rbac.createをtrueに設定します:rbac: create: true既存のサービスアカウントを使用するには、
serviceAccount.nameを設定します:rbac: create: false serviceAccount: create: false name: your-service-account
Runnerの最大並行処理を制御する
Kubernetesにデプロイされた1つのRunnerは、追加のRunnerポッドを開始することで、複数のジョブを並列実行できます。一度に実行可能なポッドの最大数を変更するには、concurrent設定を編集します。デフォルトは10です:
## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration/#the-global-section
##
concurrent: 10この設定の詳細については、GitLab Runnerの高度な設定のドキュメントのグローバルセクションを参照してください。
GitLab RunnerでDocker-in-Dockerコンテナを実行する
GitLab RunnerでDocker-in-Dockerコンテナを使用するには、次のようにします:
- 有効にするには、Runnerに特権コンテナを使用するを参照してください。
- Docker-in-Dockerの実行方法については、GitLab Runnerのドキュメントを参照してください。
Runnerに特権コンテナを使用する
GitLab CI/CDジョブでDocker実行可能ファイルを使用するには、特権コンテナを使用するようにRunnerを設定します。
前提要件:
- リスクを理解していること。リスクについての説明はGitLab CI/CD Runnerドキュメントに記載されています。
- GitLab RunnerインスタンスがGitLabの特定のプロジェクトに登録されており、そのCI/CDジョブを信頼していること。
values.yamlで特権モードを有効にするには、次の行を追加します:
runners:
config: |
[[runners]]
[runners.kubernetes]
# Run all containers with the privileged flag enabled.
privileged = true
...詳細については、[runners.kubernetes]セクションに関する高度な設定の情報を参照してください。
プライベートレジストリのイメージを使用する
プライベートレジストリのイメージを使用するには、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>"GitLab Runner Helm Chartバージョン0.53.x以降では、
config.tomlでrunners.configに指定されているテンプレートからのimage_pull_secretを設定します:runners: config: | [[runners]] [runners.kubernetes] ## Specify one or more imagePullSecrets ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ ## image_pull_secrets = [your-image-pull-secret]詳細については、KubernetesドキュメントのPull an image from a private registryを参照してください。
GitLab Runner Helmチャートバージョン0.52以前の場合は、
values.yamlでrunners.imagePullSecretsの値を設定します。この値を設定すると、コンテナは--kubernetes-image-pull-secrets "<SECRET_NAME>"をイメージエントリポイントスクリプトに追加します。これにより、Kubernetes executorのconfig.tomlの設定でimage_pull_secretsパラメータを設定する必要がなくなります。runners: imagePullSecrets: [your-image-pull-secret]
imagePullSecretsの値には、nameタグがプレフィックスとして付加されていません。これはKubernetesリソースでの慣例です。1つのレジストリ認証情報のみを使用する場合でも、この値には1つ以上のシークレット名の配列が必要です。
imagePullSecretsの作成方法の詳細については、KubernetesドキュメントのPull an Image from a Private Registryを参照してください。
ジョブポッドの作成時に、GitLab Runnerは自動的にイメージアクセスを次の2つのステップで処理します:
- GitLab Runnerは、既存のDocker認証情報をKubernetes secretsに変換し、レジストリからイメージをプルできるようにします。手動で設定されたimagePullSecretsがクラスター内に実際に存在するかどうかも確認します。静的に定義された認証情報、認証情報ストア、または認証情報ヘルパーの詳細については、プライベートコンテナイメージからのイメージへのアクセスを参照してください。
- GitLab Runnerはジョブポッドを作成し、2種類の認証情報（
imagePullSecretsと変換されたDocker認証情報）をその順にアタッチします。
Kubernetesがコンテナイメージをプルする必要がある場合、機能するものがみつかるまで、認証情報を1つずつ試します。
カスタム証明書を使用してGitLabにアクセスする
カスタム証明書を使用するには、GitLab Runner HelmチャートにKubernetesシークレットを提供します。このシークレットは、コンテナの/home/gitlab-runner/.gitlab-runner/certsディレクトリに追加されます:
証明書を準備する
Kubernetesシークレットの各キー名は、ディレクトリ内のファイル名として使用されます。ファイルの内容は、キーに関連付けられた値です:
- 使用するファイル名の形式は
<gitlab.hostname>.crtである必要があります。たとえばgitlab.your-domain.com.crtなどです。 - 中間証明書を同じファイル内のサーバー証明書に連結します。
- 使用するホスト名は、証明書が登録されているホスト名である必要があります。
Kubernetesのシークレットを作成する
自動生成された自己署名ワイルドカード証明書の手法を使用してGitLab Helmチャートをインストールした場合、シークレットが作成されています。
自動生成された自己署名ワイルドカード証明書を使用してGitLab Helmチャートをインストールしなかった場合は、シークレットを作成します。以下のコマンドは、証明書をシークレットとしてKubernetesに保存し、ファイルとしてGitLab Runnerコンテナに提示します。
証明書が現在のディレクトリに含まれており、
<gitlab.hostname.crt>形式に従っている場合は、必要に応じてこのコマンドを変更します:kubectl create secret generic <SECRET_NAME> \ --namespace <NAMESPACE> \ --from-file=<CERTIFICATE_FILENAME><NAMESPACE>: GitLab RunnerをインストールするKubernetesネームスペース。<SECRET_NAME>: Kubernetesシークレットリソース名（gitlab-domain-certなど）。<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。
チャートにシークレットを提供する
values.yamlで、certsSecretNameを同じネームスペース内のKubernetesシークレットオブジェクトのリソース名に設定します。これにより、GitLab Runnerが使用するカスタム証明書を渡すことができます。前述の例では、リソース名はgitlab-domain-certでした:
certsSecretName: <SECRET NAME>詳細については、GitLabサーバーを対象とする自己署名証明書のサポートされているオプションを参照してください。
ポッドラベルをCI環境変数キーに設定する
values.yamlファイルでは、環境変数をポッドラベルとして使用できません。詳細については、環境変数キーをポッドラベルとして設定できないを参照してください。一時的な解決策として、このイシューに記載されている回避策を使用してください。
Ubuntuベースのgitlab-runner Dockerイメージに切り替える
デフォルトでは、GitLab Runner Helmチャートは、musl libcを使用するgitlab/gitlab-runnerイメージのAlpineバージョンを使用します。glibcを使用するUbuntuベースのイメージに切り替える必要がある場合があります。
そのためには、values.yamlファイルで次の値を使用してイメージを指定します:
# Specify the Ubuntu image, and set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v17.3.0
# Update the security context values to the user ID in the Ubuntu image
securityContext:
fsGroup: 999
runAsUser: 999非rootユーザーで実行する
デフォルトの場合、非rootユーザーではGitLab Runnerのイメージが動作しません。GitLab Runner UBIイメージとGitLab Runner Helper UBIイメージは、このような状況に対応して設計されています。
これらのイメージを使用するには、values.yamlでGitLab RunnerイメージとGitLab Runner Helperイメージを変更します:
image:
registry: registry.gitlab.com
image: gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp
tag: v16.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-v16.11.0"
[runners.kubernetes.pod_security_context]
run_as_non_root = true
run_as_user = 59417run_as_userはnonrootユーザーのユーザーID（59417）を参照していますが、イメージはどのユーザーIDでも機能します。このユーザーIDがルートグループの一部であることが重要です。ルートグループの一部であっても、特定の特権が付与されるわけではありません。
FIPS準拠のGitLab Runnerを使用する
FIPS準拠のGitLab Runnerを使用するには、values.yamlでGitLab RunnerイメージとHelperイメージを変更します:
image:
registry: docker.io
image: gitlab/gitlab-runner
tag: ubi-fips
runners:
config: |
[[runners]]
[runners.kubernetes]
helper_image_flavor = "ubi-fips"設定テンプレートを使用する
KubernetesでGitLab Runnerビルドポッドの動作を設定するには、設定テンプレートファイルを使用します。設定テンプレートでは、Helmチャートと特定のRunner設定オプションを共有せずに、Runnerの任意のフィールドを設定できます。たとえば、以下のデフォルト設定はchartリポジトリのvalues.yamlファイルにあります:
runners:
config: |
[[runners]]
[runners.kubernetes]
image = "ubuntu:22.04"config.tomlがvalues.yamlに埋め込まれているため、config:セクションの値はTOMLを使用する必要があります（<parameter> = <value>ではなく<parameter>: <value>）。
executor固有の設定については、values.yamlファイルを参照してください。