Operatorのトラブルシューティング

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

このドキュメントは、GitLab Operatorのインストール、およびGitLabカスタムリソースからのGitLabインスタンスのデプロイのトラブルシューティングを支援するためのメモとヒントを集めたものです。

インストールの問題

Kubernetes環境でのOperatorのインストールのトラブルシューティングは、他のKubernetesのワークロードのトラブルシューティングとよく似ています。Operatorのマニフェストをデプロイした後、Operatorポッドのkubectl describeまたはkubectl get events -n <namespace>の出力を監視します。これにより、Operatorイメージの取得に関する問題や、Operatorを起動するためのその他の前提条件が示されます。

Operatorが起動しているものの、途中で終了する場合は、Operatorログを調べることで、ポッドの終了原因を特定するための情報が得られます。これは、次のコマンドで実行できます:

kubectl logs deployment/gitlab-controller-manager -c manager -f -n <namespace>

さらに、Operatorは、適切な動作のためにTLS証明書を作成するためにCert Managerに依存しています。TLS証明書はシークレットとして作成され、Operatorポッド上のボリュームとしてマウントされます。TLS証明書の取得に関する問題は、ネームスペースのイベントログに記録されます。

$ kubectl get events -n gitlab-system
...
102s        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    MountVolume.SetUp failed for volume "cert" : secret "webhook-server-cert" not found
107s        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    Unable to attach or mount volumes: unmounted volumes=[cert], unattached volumes=[cert gitlab-manager-token-fc4p9]: timed out waiting for the condition
...

次のステップでは、TLS証明書の作成失敗を示す問題がないか、Cert Managerのログを調べます。

OpenShift固有の問題

OpenShiftにはより制限の厳しいセキュリティモデルがあり、その結果、GitLab Operatorはクラスターの管理者アカウントでインストールする必要があります。デベロッパーアカウントには、Operatorが適切に機能するために必要な権限がありません。

Ingress NGINX Controllerポッドがこの問題で説明されているように無効なSCCパラメータのためにプロビジョニングできない場合、適切な回避策は、Ingress NGINXがOpenShiftクラスターで起動できるように、リポジトリからSCCを更新することです:

GitLab Operatorの最新のOpenShiftマニフェストをフェッチします。gitlab-operator-openshift-VERSION.yamlが必要です

SCCを抽出

yq eval '. | select(.metadata.name | test(".*scc.*"))' gitlab-operator-openshift-VERSION.yaml > scc.yaml

scc.yamlをクラスターに適用します:
```
kubectl apply -f scc.yaml
```

GitLab Operatorリポジトリのリリースページからリリースされたマニフェストからインストールすると、SCCが含まれているため、この問題は発生しません。OperatorHubでサポートされていないオブジェクトに関する関連問題:

GitLabインスタンスのデプロイに関する問題

ここに記載されている情報に加えて、GitLab Helmチャートのトラブルシューティングドキュメントを参照してください。

コアサービスが準備できていません

GitLab Operatorは、Redis、PostgreSQL、Gitalyのインスタンスのインストールに依存しており、これらはコアサービスとして知られています。GitLabカスタマーリソースをデプロイした後、コアサービスが準備できていないことを示すOperatorログメッセージが過剰に表示される場合は、これらのサービスのいずれかが動作不能になっている問題が発生しています。

特に、これらの各サービスのエンドポイントをチェックして、サービスのポッドに接続されていることを確認してください。これは、クラスターにGitLabインスタンスをサポートするのに十分なリソースがなく、追加のノードをクラスターに追加する必要がある可能性も示しています。

イシュー#305が作成され、どのコアサービスがGitLabインスタンスのデプロイを停止させているかのレポートを追跡しています。

GitLab UIに到達できない（Ingressにアドレスがない、またはCertManager Challengesが失敗する）

GitLab OperatorのインストールマニフェストとHelmチャートは、nameOverrideがHelmの値で指定されていない限り、gitlabをすべてのリソース名のプレフィックスとしてデフォルトで使用します。

その結果、NGINX IngressClassの名前はgitlab-nginxになります。gitlab以外のリリース名がmetadata.nameのGitLabカスタムリソースで指定されている場合は、デフォルトのIngressClass名をglobal.ingress.classで明示的に設定する必要があります:

例: metadata.nameがdemoに設定されている場合は、global.ingress.class=gitlab-nginxを設定します:

apiVersion: apps.gitlab.com/v1beta1
kind: GitLab
metadata:
  name: demo
spec:
  chart:
    version: "X.Y.Z"
    values:
      global:
        ingress:
          # Use the correct IngressClass name.
          class: gitlab-nginx

この明示的な設定がない場合、Ingressはdemo-nginxという名前のIngressを検索しようとしますが、これは存在しません。

NGINX Ingress Controllerポッドが見つからない

OpenShift環境では、NGINX Ingress Controllerが、GitLabインスタンス（HTTPSとSSHの両方）へのトラフィックを転送するために、OpenShiftルートの代わりに使用されます。GitLabインスタンスへの接続で問題が発生している場合は、まず、NGINX Ingress Controllerのデプロイがあることを確認してください。

デプロイが存在する場合は、kubectl get deploy出力のREADY列を確認してください。READYステータスが0/0としてレポートされている場合は、セキュリティコンテキスト制約（SCC）が違反していることを示すメッセージがないか、kubectl get events -n <namespace> | grep -i nginxの出力を調べてください。

これは、OpenShiftのNGINX RBACリソースがデプロイされなかったことを示しています。OpenShift用のOperatorマニフェストは、次のコマンドで再適用する必要があります:

kubectl apply -f https://gitlab.com/api/v4/projects/18899486/packages/generic/gitlab-operator/<VERSION>/gitlab-operator-openshift.yaml

マニフェストが適用されたら、SCCを適切に取得し、Ingressコントローラーがポッドを正しく作成できるようにするために、Ingressコントローラーデプロイを削除する必要がある場合があります。

水平ポッドオートスケーラーがスケールしていません

水平ポッドオートスケーラー（HPA）が、トラフィック負荷に応じてポッド数をスケールしないことが判明した場合は、Metrics Serverのインストールを確認してください。Kubernetesクラスターでは、Metrics Serverはインストールする必要がある追加のコンポーネントです。インストールプロセスは、インストールドキュメントに記載されています。

OpenShiftクラスターにはMetrics Serverが組み込まれているため、HPAは正しく動作するはずです。

PersistentVolumeClaimの設定が変更された場合のデータの復元

データの永続化のためにMinIOなどのコンポーネントを使用する場合は、以前のPersistentVolumeに再接続する必要がある場合があります。

たとえば、!419は、Operatorで定義されたMinIOコンポーネントを、GitLab HelmチャートのMinIOコンポーネントに置き換えました。この変更の一環として、オブジェクト名が変更され、PersistentVolumeClaimも含まれます。その結果、OperatorにバンドルされたMinIOインスタンスを使用している人は、永続化されたデータを含む以前のPersistentVolumeに再接続するために、追加の手順を実行する必要がありました。

GitLab Operator 0.6.4にアップグレードしたら、次の手順を完了して、新しいPersistentVolumeClaimを以前のPersistentVolumeに接続します:

$RELEASE_NAME-minio-secretシークレットを削除します。シークレットの内容は0.6.4のアップグレードで変更されますが、シークレット名は変更されません。
以前のMinIO PersistentVolumeを編集し、.spec.persistentVolumeReclaimPolicyをDeleteからRetainに変更します。
以前のMinIO StatefulSet $RELEASE_NAME-minioを削除します。
以前のMinIO PersistentVolumeから.spec.ClaimRefを削除して、以前のMinIO PersistentVolumeClaimから関連付けを解除します。
以前のMinIO PersistentVolumeClaim export-gitlab-minio-0を削除します。
以前のPersistentVolumeステータスがAvailableになったことを確認します。
GitLabカスタムリソースに次の値を設定します: minio.persistence.volumeName=<previous PersistentVolume name>。
GitLabカスタムリソースを適用します。
新しいMinIO PersistentVolumeClaim（およびMinIOポッド）を削除して、PersistentVolumeClaimがアンバインドされ、削除できるようにします。OperatorはPersistentVolumeClaimを再作成します。これは、.specフィールドがイミュータブルであるために必要です。
以前のMinIO PersistentVolumeが新しいMinIO PersistentVolumeClaimにバインドされていることを確認します。
データが復元されたことを確認するには、GitLab UIでイシュー、アーティファクトなどを参照します。

以前のPersistentVolumeへの再接続の詳細については、永続ボリュームドキュメントを参照してください。

念のため、バンドルされたMinIOインスタンスは本番環境での使用は推奨されていません。

複数のデータベース接続を設定する

GitLab 16.0では、GitLabはデフォルトで、同じPostgreSQLデータベースを指す2つのデータベース接続を使用するようになっています。

単一データベース接続に戻す場合は、複数データベース接続の設定を参照してください。

コンポーネントの無効化または名前変更

リソースの名前変更と無効化は、nameOverrideへの変更とさまざまな*.enable: false値の組み合わせによって可能ですが、GitLab Operatorは不要になったKubernetesリソースを自動的に削除しません。その結果、上記の操作では、不要になったリソースの手動管理が必要になります。

ただし、GitLabカスタムリソースのインスタンスを削除すると、予想どおり、そのインスタンスに関連付けられているすべてのリソースが削除されます。

イシュー!889が作成され、これを追跡しています。