• インストールの問題
  • OpenShift 固有の問題
• GitLab インスタンスのデプロイに関する問題
  • Core サービスが準備できていません
  • GitLab UIに到達できない（Ingressesにアドレスがない、またはCertManager Challengesが失敗する）
  • NGINX Ingress Controller ポッドがありません。
  • 水平ポッド自動スケーラがスケーリングされません。
  • PersistentVolumeClaim設定変更時のデータのリストア
  • 複数のデータベース接続の設定
  • コンポーネントの無効化または名前の変更

オペレーターのトラブルシューティング

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

インストールの問題

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

オペレータが起動しているにもかかわらず、早期に終了する場合、オペレータ ログを調べることで、Pod の終了原因を特定するための情報を得ることができます。これは次のコマンドで実行できます：

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

さらに、オペレータは、適切なオペレーションのためにTLS証明書を作成するためにCert Managerに依存します。TLS証明書はシークレットとして作成され、オペレータのポッドにボリュームとしてマウントされます。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
...

次のステップでは、Cert Manager のログを調べて、TLS 証明書の作成に失敗したことを示すイシューを探します。

OpenShift 固有の問題

OpenShiftはセキュリティモデルがより制限されており、その結果、GitLabオペレーターはクラスター管理者アカウントでインストールする必要があります。開発者アカウントには、オペレータが適切に機能するために必要な権限がありません。

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

1. GitLab オペレータの最新の OpenShift マニフェストを取得します。以下のものが必要ですgitlab-operator-openshift-VERSION.yaml

2. SCCを抽出

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

3. scc.yaml をクラスターに適用します：

   kubectl apply -f scc.yaml
   

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

• IngressClass CRのサポートを追加しました - Issue #5491 - operator-framework/operator-sdk - GitHub
• OpenShift の SCC のサポートを追加 - Issue #2847 - operator-framework/operator-lifecycle-manager - GitHub

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

ここで紹介する情報に加えて、GitLab Helm chart のトラブルシューティングドキュメントを参照する必要があります。

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

GitLab Operatorは、Redis、PostgreSQL、Gitalyのインスタンスをインストールすることに依存しています。これらは Core サービスとして知られています。GitLabカスタマーリソースをデプロイした後に、コアサービスが準備できていないというオペレーターログメッセージが大量に表示される場合は、これらのサービスのいずれかに問題がある可能性があります。

具体的には、それぞれのサービスのエンドポイントをチェックして、サービスのポッドに接続されていることを確認してください。これは、GitLabインスタンスをサポートするのに十分なリソースがクラスターにないことを示している可能性もあります。

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

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

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

その結果、NGINX IngressClass はgitlab-nginx という名前になります。GitLab CustomResource で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 環境では、OpenShift Routes の代わりにNGINX Ingress Controllerを使用して GitLab インスタンスへのトラフィックを誘導します（HTTPS と SSH の両方）。GitLab インスタンスへの接続に問題がある場合は、まず NGINX Ingress Controller のデプロイがあることを確認してください。

デプロイが存在する場合、kubectl get deploy 出力のREADY 列を確認します。READY のステータスが0/0とレポートされた場合、kubectl get events -n <namespace> | grep -i nginx の出力から、セキュリティコンテキスト制約(SCC) に違反したメッセージを探します。

これは OpenShift 用の NGINX RBAC リソースがデプロイされていないことを示しています。OpenShift 用のオペレーション・マニフェストは、以下のコマンドで再適用する必要があります：

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

マニフェストが適用された後、SCC を適切に取得し、Ingress コントローラーがポッドを正しく作成できるようにするには、Ingress コントローラーのデプロイメントを削除する必要があるかもしれません。

水平ポッド自動スケーラがスケーリングされません。

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

OpenShiftクラスターにはMetrics Serverが組み込まれており、結果としてHPAは正しくオペレーションされるはずです。

PersistentVolumeClaim設定変更時のデータのリストア

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

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

GitLab Operator0.6.4 にアップグレードした後、新しいPersistentVolumeClaimを以前のPersistentVolumeに接続するには、次の手順を実行します：

1. $RELEASE_NAME-minio-secret シークレットを削除します。0.6.4 アップグレードによってシークレットの内部は変更されますが、シークレット名は変更されません。
2. 以前のMinIO PersistentVolumeを編集し、.spec.persistentVolumeReclaimPolicy をDelete からRetain に変更します。
3. 前の MinIO StatefulSet（$RELEASE_NAME-minio ）を削除します。
4. 以前の MinIO PersistentVolume から.spec.ClaimRef を削除して、以前の MinIO PersistentVolumeClaim から関連付けを解除します。
5. 前の MinIO PersistentVolumeClaim、export-gitlab-minio-0 を削除します。
6. 以前のPersistentVolumeのステータスがAvailable 。
7. GitLab CustomResourceに以下の値を設定します：minio.persistence.volumeName=<previous PersistentVolume name>.
8. GitLab CustomResourceを適用します。
9. 新しい MinIO PersistentVolumeClaim (および MinIO ポッド。PersistentVolumeClaim はバインドされていないため、削除できます) を削除します。オペレーションにより、PersistentVolumeClaim が再作成されます。これは、.spec フィールドが不変であるために必要です。
10. 以前の MinIO PersistentVolume が新しい MinIO PersistentVolumeClaim にバインドされていることを確認します。
11. GitLab UIでイシューやアーティファクトなどに移動して、データが復元されていることを確認します。

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

注意事項として、バンドルされているMinIOインスタンスは、本番環境での使用には推奨されません。

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

GitLab 16.0では、GitLabはデフォルトで同じPostgreSQLデータベースを指す2つのデータベース接続を使用します。

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

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

nameOverride 、様々な*.enable: false 値の組み合わせの変更によってリソースの名前の変更や無効化は可能ですが、GitLab Operatorは不要になったKubernetesリソースを自動的に削除することはありません。そのため、上記のオペレーションを行うには、残ったリソースを手動で管理する必要があります。

しかし、GitLabカスタムリソースのインスタンスを削除すると、期待通りにそのインスタンスに関連付けられたすべてのリソースが削除されます。

Issue!889が作成されました。