OpenShiftでのGitLab Runnerの設定

このドキュメントでは、OpenShiftでGitLab Runnerを設定する方法について説明します。

GitLab Runner Operatorへのプロパティの引き渡し

Runnerを作成する際、そのspecにプロパティを設定することで、それを設定できます。たとえば、runnerが登録されているGitLab URLや、登録トークンを含むシークレットの名前を指定できます:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret # Name of the secret containing the Runner token

使用可能なすべてのプロパティについては、Operatorのプロパティをお読みください。

Operatorのプロパティ

次のプロパティをOperatorに渡すことができます。

一部のプロパティは、より新しいバージョンのOperatorでのみ使用できます。

キャッシュプロパティ

S3キャッシュ

gcs キャッシュ

Azureキャッシュ

プロキシ環境の設定

プロキシ環境を作成するには:

1. custom-env.yamlファイルを編集します。次に例を示します:

   apiVersion: v1
   data:
     HTTP_PROXY: example.com
   kind: ConfigMap
   metadata:
     name: custom-env

2. OpenShiftを更新して変更を適用します。

   oc apply -f custom-env.yaml

3. gitlab-runner.ymlファイルを更新してください。

   apiVersion: apps.gitlab.com/v1beta2
   kind: Runner
   metadata:
     name: dev
   spec:
     gitlabUrl: https://gitlab.example.com
     token: gitlab-runner-secret # Name of the secret containing the Runner token
     env: custom-env

プロキシがKubernetes APIにアクセスできない場合は、CI/CDジョブでエラーが発生する可能性があります:

ERROR: Job failed (system failure): prepare environment: setting up credentials: Post https://172.21.0.1:443/api/v1/namespaces/<KUBERNETES_NAMESPACE>/secrets: net/http: TLS handshake timeout. Check https://docs.gitlab.com/runner/shells/#shell-profile-loading for more information

このエラーを解決するには、Kubernetes APIのIPアドレスをcustom-env.yamlファイルのNO_PROXY設定に追加します:

   apiVersion: v1
   data:
     NO_PROXY: 172.21.0.1
     HTTP_PROXY: example.com
   kind: ConfigMap
   metadata:
     name: custom-env

Kubernetes APIのIPアドレスは、次を実行して確認できます:

oc get services --namespace default --field-selector='metadata.name=kubernetes' | grep -v NAME | awk '{print $3}'

config.tomlを設定テンプレートでカスタマイズする

設定テンプレートを使用して、Runnerのconfig.tomlファイルをカスタマイズできます。

1. カスタム設定テンプレートファイルを作成します。たとえば、RunnerにEmptyDirボリュームをマウントし、cpu_limitを設定するように指示します。custom-config.tomlファイルを作成します:

   [[runners]]
     [runners.kubernetes]
       cpu_limit = "500m"
       [runners.kubernetes.volumes]
         [[runners.kubernetes.volumes.empty_dir]]
           name = "empty-dir"
           mount_path = "/path/to/empty_dir"
           medium = "Memory"

2. custom-config.tomlファイルからcustom-config-tomlという名前のConfigMapを作成します:

    oc create configmap custom-config-toml --from-file config.toml=custom-config.toml

3. Runnerのconfigプロパティを設定します:

   apiVersion: apps.gitlab.com/v1beta2
   kind: Runner
   metadata:
     name: dev
   spec:
     gitlabUrl: https://gitlab.example.com
     token: gitlab-runner-secret
     config: custom-config-toml

既知の問題のため、次の設定を変更するには、設定テンプレートの代わりに環境変数を使用する必要があります:

カスタムTLS証明書の設定

1. カスタムTLS証明書を設定するには、キーtls.crtを持つシークレットを作成します。この例では、ファイルの名前はcustom-tls-ca-secret.yamlです:

   apiVersion: v1
   kind: Secret
   metadata:
       name: custom-tls-ca
   type: Opaque
   stringData:
       tls.crt: |
           -----BEGIN CERTIFICATE-----
           MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix
           .....
           7vQMfXdGsRrXNGRGnX+vWDZ3/zWI0joDtCkNnqEpVn..HoX
           -----END CERTIFICATE-----

2. シークレットを作成します:

   oc apply -f custom-tls-ca-secret.yaml

3. runner.yamlのcaキーを、シークレットの名前と同じ名前に設定します:

   apiVersion: apps.gitlab.com/v1beta2
   kind: Runner
   metadata:
     name: dev
   spec:
     gitlabUrl: https://gitlab.example.com
     token: gitlab-runner-secret
     ca: custom-tls-ca

RunnerポッドのCPUおよびメモリサイズの設定

カスタムconfig.tomlファイルでCPU制限とメモリ制限を設定するには、このトピックの手順に従ってください。

クラスターリソースに基づいて、Runnerごとのジョブの並行処理を設定します

Runnerリソースのconcurrentプロパティを設定します:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  concurrent: 2

ジョブの並行処理は、プロジェクトの要件によって決まります。

1. まず、CIジョブを実行するために必要なコンピューティングリソースとメモリリソースを特定します。
2. クラスター内のリソースを考慮して、そのジョブを何回実行できるかを計算します。

高い並行処理値を設定すると、Kubernetesエグゼキューターは可能な限りすぐにジョブを処理します。ただし、ジョブがスケジュールされるタイミングは、Kubernetesクラスターのスケジューラ容量によって決まります。

GitLab Runnerマネージャーのサービスアカウント

新規インストールの場合は、これらのRBACロールバインディングリソースが存在しない場合、GitLab Runnerはrunnerマネージャーポッド用にgitlab-runner-app-saという名前のKubernetes ServiceAccountを作成します:

• gitlab-runner-app-rolebinding
• gitlab-runner-rolebinding

ロールバインディングのいずれかが存在する場合、GitLabは、ロールバインディングで定義されているsubjectsとroleRefからロールとサービスアカウントを解決します。

両方のロールバインディングが存在する場合、gitlab-runner-app-rolebindingはgitlab-runner-rolebindingよりも優先されます。

トラブルシューティング

ルートと非ルート

GitLab Runner OperatorとGitLab Runnerポッドは、非ルートユーザーとして実行されます。そのため、ジョブで使用されるビルドイメージは、正常に完了できるように、非ルートユーザーとして実行する必要があります。これにより、ジョブは最小限の権限で正常に実行されることが保証されます。

これを機能させるには、CI/CDジョブに使用されるビルドイメージが以下であることを確認してください:

• 非ルートとして実行
• 制限されたファイルシステムに書き込まない

OpenShiftクラスター上のほとんどのコンテナファイルシステムは読み取り専用ですが、次の例外があります:

• マウントされたボリューム
• /var/tmp
• /tmp
• tmpfsとしてルートファイルシステムにマウントされたその他のボリューム

HOME環境変数のオーバーライド

カスタムビルドイメージを作成するか、環境変数をオーバーライドする場合は、HOME環境変数が/に設定されていないことを確認してください。これは読み取り専用になります。特に、ジョブがホームディレクトリにファイルを書き込む必要がある場合。たとえば、/homeの下にディレクトリ（/home/ciなど）を作成し、DockerfileでENV HOME=/home/ciを設定できます。

Runnerポッドの場合、HOMEが/home/gitlab-runnerに設定されることが予想されます。この変数が変更された場合、新しい場所には適切な権限が必要です。これらのガイドラインは、Red Hatコンテナプラットフォームのドキュメントにも記載されています。

locked変数のオーバーライド

Runnerトークンを登録するときに、locked変数をtrueに設定すると、エラーRunner configuration other than name, description, and exector is reserved and cannot be specifiedが表示されます。

  locked: true # REQUIRED
  tags: ""
  runUntagged: false
  protected: false
  maximumTimeout: 0

詳細については、イシュー472を参照してください。

セキュリティコンテキスト制約に注意してください

デフォルトでは、新しいOpenShiftプロジェクトにインストールすると、GitLab Runner Operatorは非ルートとして実行されます。defaultプロジェクトなどの一部のプロジェクトは、すべてのサービスアカウントがanyuidアクセス権を持っている例外です。その場合、イメージのユーザーはrootです。これは、ジョブなど、コンテナShell内でwhoamiを実行することで確認できます。Red Hatコンテナプラットフォームのドキュメントのセキュリティコンテキスト制約の詳細をご覧ください。

anyuidセキュリティコンテキストの制約として実行

CI/CDジョブをルートユーザーとして実行したり、ルートファイルシステムに書き込んだりするには、gitlab-runner-app-saサービスアカウントにanyuidセキュリティコンテキスト制約を設定します。GitLab Runnerコンテナは、このサービスアカウントを使用します。

OpenShift 4.3.8以前:

oc adm policy add-scc-to-user anyuid -z gitlab-runner-app-sa -n <runner_namespace>

# Check that the anyiud SCC is set:
oc get scc anyuid -o yaml

OpenShift 4.3.8以降:

oc create -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: scc-anyuid
  namespace: <runner_namespace>
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - anyuid
  resources:
  - securitycontextconstraints
  verbs:
  - use
EOF

oc create -f - <<EOF
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: sa-to-scc-anyuid
  namespace: <runner_namespace>
subjects:
  - kind: ServiceAccount
    name: gitlab-runner-app-sa
roleRef:
  kind: Role
  name: scc-anyuid
  apiGroup: rbac.authorization.k8s.io
EOF

ヘルパーコンテナとビルドコンテナのユーザーIDとグループIDのマッチング

GitLab Runner Operatorデプロイでは、registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocpがデフォルトのヘルパーイメージとして使用されます。このイメージは、セキュリティコンテキストによって明示的に変更されない限り、ユーザーIDとグループID 1001:1001で実行されます。

ビルドコンテナのユーザーIDがヘルパーイメージのユーザーIDと異なる場合、ビルド中に権限関連のエラーが発生する可能性があります。一般的なエラーメッセージを次に示します:

fatal: detected dubious ownership in repository at '/builds/gitlab-org/gitlab-runner'

このエラーは、リポジトリがユーザーID 1001（ヘルパーコンテナ）によってクローンされたことを示していますが、ビルドコンテナ内の別のユーザーIDがそれにアクセスしようとしています。

解決策:

ヘルパーコンテナのユーザーIDとグループIDに合わせて、ビルドコンテナのセキュリティコンテキストを設定します:

[runners.kubernetes.build_container_security_context]
run_as_user = 1001
run_as_group = 1001

Additional notes（追加の注意）*

• これらの設定により、リポジトリをクローンするコンテナと、それをビルドするコンテナの間で、一貫したファイルの所有権が保証されます。
• 異なるユーザーIDまたはグループIDでヘルパーイメージをカスタマイズした場合は、これらの値をそれに応じて調整します。
• OpenShiftデプロイの場合は、これらのセキュリティコンテキスト設定がクラスターのセキュリティコンテキスト制約（SCCS）に準拠していることを確認してください。

SETFCAPの設定

Red Hat OpenShiftコンテナプラットフォーム（RHOCP）4.11以降を使用している場合は、次のエラーメッセージが表示されることがあります:

error reading allowed ID mappings:error reading subuid mappings for user

一部のジョブ（buildahなど）では、正しく実行するためにSETFCAP機能が付与されている必要があります。このイシューを解決するには、次の手順に従います:

1. GitLab Runnerが使用しているセキュリティコンテキスト制約にSETFCAP機能を追加します（GitLab Runnerポッドに割り当てられているセキュリティコンテキスト制約をgitlab-sccに置き換えます）:

   oc patch scc gitlab-scc --type merge -p '{"allowedCapabilities":["SETFCAP"]}'

2. config.tomlを更新し、kubernetesセクションの下にSETFCAP機能を追加します:

   [[runners]]
     [runners.kubernetes]
     [runners.kubernetes.pod_security_context]
       [runners.kubernetes.build_container_security_context]
       [runners.kubernetes.build_container_security_context.capabilities]
         add = ["SETFCAP"]

3. GitLab Runnerがデプロイされているネームスペースで、このconfig.tomlを使用してConfigMapを作成します:

   oc create configmap custom-config-toml --from-file config.toml=config.toml

4. 修正するRunnerを修正し、最近作成したConfigMapを指すようにconfig:パラメータを追加します（my-runnerを正しいRunnerポッド名に置き換えます）。

   oc patch runner my-runner --type merge -p '{"spec": {"config": "custom-config-toml"}}'

詳細については、Red Hatのドキュメントを参照してください。

FIPS準拠のGitLab Runnerを使用する

FIPS準拠のGitLab Runnerヘルパーを使用するには、次のようにヘルパーイメージを変更します:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  helperImage: gitlab/gitlab-runner-helper:ubi-fips
  concurrent: 2

自己署名証明書を使用したGitLab Runnerの登録

自己署名証明書をGitLab Self-Managedで使用するには、秘密証明書の署名に使用したCA証明書を含むシークレットを作成します。

シークレットの名前は、Runner仕様セクションでCAとして指定されます:

KIND:     Runner
VERSION:  apps.gitlab.com/v1beta2

FIELD:    ca <string>

DESCRIPTION:
     Name of tls secret containing the custom certificate authority (CA)
     certificates

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

oc create secret generic mySecret --from-file=tls.crt=myCert.pem -o yaml

IPアドレスを指す外部URLでGitLab Runnerを登録します

Runnerが自己署名証明書とホスト名を一致させることができない場合、エラーメッセージが表示される場合があります。この問題は、ホスト名の代わりにIPアドレス（###.##.##.##など）を使用するようにGitLab Self-Managedを設定した場合に発生します:

[31;1mERROR: Registering runner... failed               [0;m  [31;1mrunner[0;m=A5abcdEF [31;1mstatus[0;m=couldn't execute POST against https://###.##.##.##/api/v4/runners:
Post https://###.##.##.##/api/v4/runners: x509: cannot validate certificate for ###.##.##.## because it doesn't contain any IP SANs
[31;1mPANIC: Failed to register the runner. You may be having network problems.[0;m

このイシューを解決するには、次の手順に従います:

1. GitLab Self-Managedサーバーで、subjectAltNameパラメータにIPアドレスを追加するようにopensslを変更します:

   # vim /etc/pki/tls/openssl.cnf
   
   [ v3_ca ]
   subjectAltName=IP:169.57.64.36 <---- Add this line. 169.57.64.36 is your GitLab server IP.

2. 次に、次のコマンドを使用して自己署名CAを再生成します:

   # cd /etc/gitlab/ssl
   # openssl req -x509 -nodes -days 3650 -newkey rsa:4096 -keyout /etc/gitlab/ssl/169.57.64.36.key -out /etc/gitlab/ssl/169.57.64.36.crt
   # openssl dhparam -out /etc/gitlab/ssl/dhparam.pem 4096
   # gitlab-ctl restart

3. この新しい証明書を使用して、新しいシークレットを生成します。

パッチの構造

各仕様パッチは、次のプロパティで構成されています:

同じ仕様の設定で、patchFileとpatchの両方を設定することはできません。

Runnerポッドテンプレートのパッチ

ポッド仕様のパッチを使用すると、オペレーターが生成したKubernetesデプロイにパッチを適用することで、GitLab Runnerのデプロイ方法をカスタマイズできます。パッチは、ポッドテンプレートの仕様（deployment.spec.template.spec）に適用されます。

次のようなポッドレベルの設定を制御できます:

• リソースのリクエストと制限
• セキュリティコンテキスト
• ボリュームのマウントとボリューム
• 環境変数
• ノードセレクターとアフィニティルール
• Tolerations（トレランス）
• ホスト名とDNS設定

Runnerデプロイテンプレートのパッチ

デプロイメント仕様のパッチを使用すると、オペレーターが生成したKubernetesデプロイにパッチを適用することで、GitLab Runnerのデプロイ方法をカスタマイズできます。パッチは、デプロイ仕様（deployment.spec）に適用されます。

次のようなデプロイレベルの設定を制御できます:

• レプリカ数
• デプロイメント戦略（RollingUpdate、Recreate）
• リビジョン履歴制限
• 進捗期限秒数
• ラベルと注釈

パッチの順序

デプロイメント仕様のパッチは、ポッド仕様のパッチの前に適用されます。つまり、デプロイメントとポッドの仕様が同じフィールドを変更した場合、ポッドの仕様が優先されます。

例

ポッド仕様のパッチの例

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  podSpec:
    - name: "set-hostname"
      patch: |
        hostname: "custom-hostname"
      patchType: "merge"
    - name: "add-resource-requests"
      patch: |
        containers:
        - name: build
          resources:
            requests:
              cpu: "500m"
              memory: "256Mi"
      patchType: "strategic"

デプロイメント仕様のパッチの例

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  deploymentSpec:
    - name: "set-replicas"
      patch: |
        replicas: 3
      patchType: "strategic"
    - name: "configure-strategy"
      patch: |
        strategy:
          type: RollingUpdate
          rollingUpdate:
            maxUnavailable: 25%
            maxSurge: 50%
      patchType: "strategic"
    - name: "set-revision-history"
      patch: |
        [{"op": "add", "path": "/revisionHistoryLimit", "value": 10}]
      patchType: "json"

ベストプラクティス

• 本番環境へのデプロイに適用する前に、非本番環境でパッチをテストします。
• 個々のポッド設定ではなく、デプロイの動作に影響する設定には、デプロイレベルのパッチを使用します。
• ポッド仕様のパッチは、競合するフィールドのデプロイメント仕様のパッチをオーバーライドすることに注意してください。