Kubernetes executorのトラブルシューティング
Kubernetes executorの使用時に発生する一般的なエラーを以下に示します。
Job failed (system failure): timed out waiting for pod to start
クラスターがpoll_timeoutで定義されたタイムアウトになる前にビルドポッドをスケジュールできない場合、ビルドポッドはエラーを返します。Kubernetesスケジューラは、それを削除できる必要があります。
このイシューを修正するには、config.tomlファイルのpoll_timeout値を大きくします。
context deadline exceeded
ジョブログのcontext deadline exceededエラーは通常、Kubernetes APIクライアントが特定のクラスターAPIリクエストでタイムアウトになったことを示しています。
兆候がないか、kube-apiserverクラスターコンポーネントのメトリクスをチェックします:
- 応答レイテンシーの増加。
- ポッド、シークレット、ConfigMap、その他のコア（v1）リソースに対する一般的な作成または削除操作のエラー率。
kube-apiserver操作からのタイムアウト駆動型エラーのログは、次のように表示される場合があります:
Job failed (system failure): prepare environment: context deadline exceeded
Job failed (system failure): prepare environment: setting up build pod: context deadline exceeded場合によっては、kube-apiserverエラー応答は、そのサブコンポーネントの障害（Kubernetesクラスターのetcdserverなど）に関する追加の詳細を提供する場合があります:
Job failed (system failure): prepare environment: etcdserver: request timed out
Job failed (system failure): prepare environment: etcdserver: leader changed
Job failed (system failure): prepare environment: Internal error occurred: resource quota evaluates timeoutこれらのkube-apiserverサービス障害は、ビルドポッドの作成中、および完了後のクリーンアップ試行中に発生する可能性があります:
Error cleaning up secrets: etcdserver: request timed out
Error cleaning up secrets: etcdserver: leader changed
Error cleaning up pod: etcdserver: request timed out, possibly due to previous leader failure
Error cleaning up pod: etcdserver: request timed out
Error cleaning up pod: context deadline exceededDial tcp xxx.xx.x.x:xxx: i/o timeout
これはKubernetesのエラーで、通常、RunnerマネージャーからKubernetes APIサーバーに到達できないことを示します。この問題を解決するには:
- ネットワークセキュリティポリシーを使用する場合は、通常、ポート443またはポート6443、あるいはその両方で、Kubernetes APIへのアクセスを許可してください。
- Kubernetes APIが実行されていることを確認してください。
Kubernetes APIとの通信を試みるときに接続が拒否されました
GitLab RunnerがKubernetes APIにリクエストを送信して失敗した場合、kube-apiserverが過負荷状態で、APIリクエストを受け付けられない、または処理できないことが原因である可能性があります。
Error cleaning up podとJob failed (system failure): prepare environment: waiting for pod running
Kubernetesがジョブポッドをタイムリーにスケジュールできない場合、次のエラーが発生します。GitLab Runnerはポッドの準備ができるのを待ちますが、失敗するとポッドのクリーンアップを試みますが、これも失敗する可能性があります。
Error: Error cleaning up pod: Delete "https://xx.xx.xx.x:443/api/v1/namespaces/gitlab-runner/runner-0001": dial tcp xx.xx.xx.x:443 connect: connection refused
Error: Job failed (system failure): prepare environment: waiting for pod running: Get "https://xx.xx.xx.x:443/api/v1/namespaces/gitlab-runner/runner-0001": dial tcp xx.xx.xx.x:443 connect: connection refusedトラブルシューティングを行うには、Kubernetesのプライマリノードと、kube-apiserverインスタンスを実行するすべてのノードを確認してください。クラスター上でスケールアップしたいターゲットポッド数を管理するために必要なすべてのリソースがそれらに備わっていることを確認してください。
GitLab RunnerがポッドがReadyステータスに達するまで待機する時間を変更するには、poll_timeout設定を使用します。
ポッドがどのようにスケジュールされるか、または時間どおりにスケジュールされない理由をよりよく理解するには、Kubernetesスケジューラについてお読みください。
request did not complete within requested timeout
ビルドポッドの作成中に観測されたメッセージrequest did not complete within requested timeoutは、Kubernetesクラスターで構成されたアドミッションコントロールWebhookがタイムアウトしていることを示します。
アドミッションコントロールWebhookは、スコープが設定されているすべてのAPIリクエストに対するクラスターレベルの管理制御インターセプトであり、時間内に実行されない場合、障害を引き起こす可能性があります。
アドミッションコントロールWebhookは、傍受するAPIリクエストとネームスペースネームスペースソースをきめ細かく制御できるフィルターをサポートしています。GitLab RunnerからのKubernetes API呼び出しがアドミッションコントロールWebhookを通過する必要がない場合は、GitLab Runnerネームスペースを無視するようにWebhookのセレクター/フィルターの構成を変更するか、GitLab Runner Helmチャートvalues.yamlでpodAnnotationsまたはpodLabelsを構成して、GitLab Runnerポッドに除外ラベル/注釈を適用できます。
たとえば、DataDogアドミッションコントロールWebhookがGitLab Runnerマネージャーポッドによって行われたAPIリクエストを傍受しないようにするには、次を追加できます:
podLabels:
admission.datadoghq.com/enabled: falseKubernetesクラスターのアドミッションコントロールWebhookを一覧表示するには、次を実行します:
kubectl get validatingwebhookconfiguration -o yaml
kubectl get mutatingwebhookconfiguration -o yamlアドミッションコントロールWebhookがタイムアウトすると、次の形式のログが確認できます:
Job failed (system failure): prepare environment: Timeout: request did not complete within requested timeout
Job failed (system failure): prepare environment: setting up credentials: Timeout: request did not complete within requested timeoutアドミッションコントロールWebhookからの障害は、代わりに次のように表示される場合があります:
Job failed (system failure): prepare environment: setting up credentials: Internal error occurred: failed calling webhook "example.webhook.service"エラーCould not resolve host: example.com
ヘルパーイメージのalpineフレーバーを使用している場合、AlpineのmuslのDNSリゾルバーに関連するDNSイシューが発生する可能性があります。エラーは次のように表示される場合があります:
fatal: unable to access 'https://gitlab-ci-token:token@example.com/repo/proj.git/': Could not resolve host: example.com
このイシューを解決するには、helper_image_flavor = "ubuntu"オプションを使用します。
docker: Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running?
このエラーは、Docker-in-Dockerを使用している場合に、DINDサービスが完全に起動する前にアクセスしようとすると発生する可能性があります。詳細については、このイシューを参照してください。
curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443
このエラーは、Docker-in-Dockerを使用している場合に、DINDの最大転送ユニット（MTU）がKubernetesオーバーレイネットワークよりも大きい場合に発生する可能性があります。DINDはデフォルトのMTU 1500を使用しますが、これはデフォルトのオーバーレイネットワーク全体をルーティングするには大きすぎます。DIND MTUは、サービス定義内で変更できます:
services:
- name: docker:dind
command: ["--mtu=1450"]MountVolume.SetUp failed for volume "kube-api-access-xxxxx" : chown is not supported by windows
CI/CDジョブを実行すると、次のようなエラーが発生する可能性があります:
MountVolume.SetUp failed for volume "kube-api-access-xxxxx" : chown c:\var\lib\kubelet\pods\xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\volumes\kubernetes.io~projected\kube-api-access-xxxxx\..2022_07_07_20_52_19.102630072\token: not supported by windowsこのイシューは、ノードセレクターを使用して、異なるオペレーティングシステムとアーキテクチャを持つノードでビルドを実行する場合に発生します。
このイシューを修正するには、Runnerマネージャーポッドが常にLinuxノードでスケジュールされるようにnodeSelectorを構成します。たとえば、values.yamlファイルには、次のものが含まれている必要があります:
nodeSelector:
kubernetes.io/os: linuxビルドポッドにRunner IAMロールではなく、ワーカーノードのIAMロールが割り当てられています
このイシューは、ワーカーノードのIAMロールに正しいロールを引き受ける権限がない場合に発生します。これを修正するには、sts:AssumeRole権限をワーカーノードのIAMロールの信頼関係に追加します:
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::<AWS_ACCOUNT_NUMBER>:role/<IAM_ROLE_NAME>"
},
"Action": "sts:AssumeRole"
}エラー: pull_policy ([Always]) defined in GitLab pipeline config is not one of the allowed_pull_policies
このイシューは、.gitlab-ci.ymlでpull_policyを指定したが、Runnerの構成ファイルに構成されたポリシーがない場合に発生します。エラーは次のように表示される場合があります:
Preparation failed: invalid pull policy for image 'image-name:latest': pull_policy ([Always]) defined in GitLab pipeline config is not one of the allowed_pull_policies ([])
このイシューを修正するには、Dockerプルポリシーの制限に従って、構成にallowed_pull_policiesを追加します。
バックグラウンドプロセスによりジョブがハングアップし、タイムアウトになります
ジョブの実行中に開始されたバックグラウンドプロセスは、ビルドジョブが終了するのを防ぐことができます。これを回避するには、次のことができます:
- プロセスをダブルフォークします。例:
command_to_run < /dev/null &> /dev/null &。 - ジョブスクリプトを終了する前にプロセスを強制終了します。
キャッシュ関連のpermission deniedエラー
ジョブで生成されるファイルとフォルダーには、特定のUNIX所有権と権限があります。ファイルとフォルダーがアーカイブまたは抽出されると、UNIXの詳細が保持されます。ただし、ファイルとフォルダーは、ヘルパーイメージのUSER構成と一致しない場合があります。
Creating cache ...ステップで権限関連のエラーが発生した場合は、次のことができます:
- 解決策として、ソースデータが変更されているかどうかを調査します。たとえば、キャッシュされたファイルを作成するジョブスクリプトなどです。
- 回避策として、一致するchownコマンドとchmodコマンドを追加します。 (
before_/after_)script:ディレクティブへ。
初期化システムを備えたビルドコンテナ内の明らかに冗長なシェルプロセス
プロセスツリーには、次のいずれかの場合にシェルプロセスが含まれる場合があります:
FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGYがfalseで、FF_USE_DUMB_INIT_WITH_KUBERNETES_EXECUTORがtrueの場合。- ビルドイメージの
ENTRYPOINTは、初期化システム（tini-initやdumb-initなど）です。
UID PID PPID C STIME TTY TIME CMD
root 1 0 0 21:58 ? 00:00:00 /scripts-37474587-5556589047/dumb-init -- sh -c if [ -x /usr/local/bin/bash ]; then .exec /usr/local/bin/bash elif [ -x /usr/bin/bash ]; then .exec /usr/bin/bash elif [ -x /bin/bash ]; then .exec /bin/bash elif [ -x /usr/local/bin/sh ]; then .exec /usr/local/bin/sh elif [ -x /usr/bin/sh ]; then .exec /usr/bin/sh elif [ -x /bin/sh ]; then .exec /bin/sh elif [ -x /busybox/sh ]; then .exec /busybox/sh else .echo shell not found .exit 1 fi
root 7 1 0 21:58 ? 00:00:00 /usr/bin/bash <---------------- WHAT IS THIS???
root 26 1 0 21:58 ? 00:00:00 sh -c (/scripts-37474587-5556589047/detect_shell_script /scripts-37474587-5556589047/step_script 2>&1 | tee -a /logs-37474587-5556589047/output.log) &
root 27 26 0 21:58 ? 00:00:00 \_ /usr/bin/bash /scripts-37474587-5556589047/step_script
root 32 27 0 21:58 ? 00:00:00 | \_ /usr/bin/bash /scripts-37474587-5556589047/step_script
root 37 32 0 21:58 ? 00:00:00 | \_ ps -ef --forest
root 28 26 0 21:58 ? 00:00:00 \_ tee -a /logs-37474587-5556589047/output.logこのシェルプロセスは、sh、bash、またはbusyboxの可能性があり、PPIDが1、PIDが6または7の場合、初期化システムによって実行されるシェル検出スクリプトによって開始されるシェルです（上記のPID 1）。このプロセスは冗長ではなく、ビルドコンテナが初期化システムで実行されている場合の典型的な操作です。
Runnerポッドは、登録が成功したにもかかわらず、ジョブの結果を実行できず、タイムアウトになります
RunnerポッドはGitLabに登録すると、ジョブの実行を試みますが、実行されず、最終的にジョブはタイムアウトになります。次のエラーが報告されます:
There has been a timeout failure or the job got stuck. Check your timeout limits or try again.
This job does not have a trace.この場合、Runnerは次のエラーを受け取る可能性があります。
HTTP 204 No content response code when connecting to the `jobs/request` API.このイシューのトラブルシューティングを行うには、APIにPOSTリクエストを手動で送信して、TCP接続がハングしているかどうかを検証します。TCP接続がハングしている場合、RunnerはCIジョブペイロードをリクエストできない可能性があります。
failed to reserve container name (gcs-fuse-csi-driverが使用されている場合)
gcs-fuse-csi-driver csiドライバーは、initコンテナのボリュームのマウントをサポートしていません。これにより、このドライバーを使用するときにinitコンテナの起動が失敗する可能性があります。Kubernetes 1.28で導入された機能は、このバグを解決するために、ドライバーのプロジェクトでサポートされている必要があります。
エラー: only read-only root filesystem container is allowed
読み取り専用でマウントされたルートファイルシステム上でコンテナを実行するように強制するアドミッションコントロールポリシーを持つクラスターでは、このエラーは次の場合に表示される可能性があります:
- GitLab Runnerをインストールします。
- GitLab Runnerがビルドポッドをスケジュールしようとします。
これらのアドミッションコントロールポリシーは通常、GatekeeperやKyvernoなどのアドミッションコントロールコントローラーによって適用されます。たとえば、読み取り専用のルートファイルシステム上でコンテナを実行するように強制するポリシーは、readOnlyRootFilesystem Gatekeeperポリシーです。
この問題を解決するには:
- クラスターにデプロイされたすべてのポッドは、アドミッションコントロールコントローラーがポッドをブロックしないように、
securityContext.readOnlyRootFilesystemをコンテナのtrueに設定して、アドミッションコントロールポリシーに準拠する必要があります。 - ルートファイルシステムが読み取り専用でマウントされていても、コンテナは正常に実行され、ファイルシステムに書き込むことができる必要があります。
GitLab Runnerの場合
GitLab Runner HelmチャートでGitLab Runnerがデプロイされている場合、次のものを持つようにGitLabチャートの構成を更新する必要があります:
適切な
securityContext値:<...> securityContext: readOnlyRootFilesystem: true <...>ポッドが書き込める場所にマウントされた書き込み可能なファイルシステム:
<...> volumeMounts: - name: tmp-dir mountPath: /tmp volumes: - name: tmp-dir emptyDir: medium: "Memory" <...>
ビルドポッドの場合
ビルドポッドを読み取り専用のルートファイルシステムで実行するには、config.tomlで異なるコンテナのセキュリティコンテキストを構成します。ビルドポッドに渡されるGitLabチャート変数runners.configを設定できます:
runners:
config: |
<...>
[[runners]]
[runners.kubernetes.build_container_security_context]
read_only_root_filesystem = true
[runners.kubernetes.init_permissions_container_security_context]
read_only_root_filesystem = true
[runners.kubernetes.helper_container_security_context,omitempty]
read_only_root_filesystem = true
# This section is only needed if jobs with services are used
[runners.kubernetes.service_container_security_context,omitempty]
read_only_root_filesystem = true
<...>ビルドポッドとそのコンテナを読み取り専用ファイルシステム上で正常に実行するには、ビルドポッドが書き込める場所に書き込み可能なファイルシステムが必要です。少なくとも、これらの場所はビルドおよびホームディレクトリです。ビルドプロセスに、必要に応じて他の場所への書き込みアクセス権があることを確認してください。
一般に、ホームディレクトリは、プログラムが正常な実行に必要な構成やその他のデータを保存できるように、書き込み可能である必要があります。gitバイナリは、ホームディレクトリに書き込むことができると予想されるプログラムの一例です。
異なるコンテナイメージでのパスに関係なく、ホームディレクトリを書き込み可能にするには:
- （どのビルドイメージを使用しているかに関係なく）安定したパスにボリュームをマウントします。
- すべてのビルドに対して、環境変数
$HOMEをグローバルに設定して、ホームディレクトリを変更します。
GitLabチャート変数runners.configの値を更新することにより、config.tomlでビルドポッドとそのコンテナを構成できます。
runners:
config: |
<...>
[[runners]]
environment = ["HOME=/build_home"]
[[runners.kubernetes.volumes.empty_dir]]
name = "repo"
mount_path = "/builds"
[[runners.kubernetes.volumes.empty_dir]]
name = "build-home"
mount_path = "/build_home"
<...>emptyDirの代わりに、他のサポートされているボリュームタイプを使用できます。明示的に処理され、ビルド成果物として保存されないすべてのファイルは通常一時的であるため、ほとんどの場合emptyDirが機能します。
AWS EKS: ポッドのクリーンアップエラー: 「Runner - **」が見つからない、またはステータスが「失敗」
Amazon EKSゾーンのリバランシング機能は、オートスケールグループ内のAvailability Zoneのバランスを取ります。この機能は、あるAvailability Zoneのノードを停止し、別のAvailability Zoneで作成する可能性があります。
Runnerジョブを停止して別のノードに移動することはできません。このエラーを解決するには、Runnerジョブに対してこの機能を無効にします。
Windowsコンテナではサポートされていないサービス
Windowsノードでサービスを使用しようとすると、次のエラーで失敗する可能性があります:
ERROR: Job failed (system failure): prepare environment: admission webhook "windows.common-webhooks.networking.gke.io" denied the request: spec.hostAliases: Invalid value: []v1.HostAlias{v1.HostAlias{IP:"127.0.0.1", Hostnames:[]string{"<your windows image>"}}}: Windows does not support this field.
Kubernetesランタイムによっては、エラーが報告されるか、黙って無視される可能性があります。たとえば、GKEはエラーを報告します。
サービスは、Kubernetes executorのhostAliasを使用して実装されます。これは、Windowsコンテナではサポートされていません。