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 Controllerが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 Challengeが失敗する）

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

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

例: 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としてレポートされている場合は、kubectl get events -n <namespace> | grep -i nginxの出力を調べて、Security Context Constraint（SCC）が侵害されたことを示すメッセージを探します。

これは、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 Chartsの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 PersistentVolumeClaimから切り離すために、以前のMinIO PersistentVolumeから.spec.ClaimRefを削除します。
以前の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が作成され、これの追跡を維持しています。