自動DevOpsのトラブルシューティング

このドキュメント ページでは、Auto DevOps を使用する際によく発生するエラーと、利用可能な回避策について説明します。

Helm コマンドのトレース

CI/CD変数TRACE を任意の値に設定すると、Helmコマンドは冗長な出力を生成します。この出力を使用して、Auto DevOpsデプロイの問題を診断できます。

高度なAuto DevOps設定変数を変更することで、Auto DevOpsデプロイのいくつかの問題を解決できます。AutoDevOpsのCI/CD変数のカスタマイズについてはこちらをご覧ください。

ビルドパックを選択できません

自動ビルドと自動テストが言語またはフレームワークの検出に失敗し、次のエラーが表示されることがあります：

Step 5/11 : RUN /bin/herokuish buildpack build
 ---> Running in eb468cd46085
    -----> Unable to select a buildpack
The command '/bin/sh -c /bin/herokuish buildpack build' returned a non-zero code: 1

次のような原因が考えられます：

  • アプリケーションに buildpack が探しているキーファイルがない可能性があります。RubyアプリはGemfile.NET Frameworkなしで書くことができますが、正しく検出 Gemfileされるためには.NET Frameworkが必要です。
  • ビルドパックが存在しない可能性があります。カスタムビルドパックを指定してみてください。

Auto DevOps を拡張するパイプラインは失敗します。

パイプラインが以下のメッセージで失敗した場合：

Unable to create pipeline

  jobs:test config key may not be used with `rules`: only

このエラーは、インクルードされたジョブのルール設定がonly またはexcept 構文で上書きされている場合に表示されます。このイシューを修正するには、次のいずれかを実行する必要があります：

Kubernetesネームスペースの作成に失敗しました。

GitLab がプロジェクトの Kubernetes ネームスペースとサービスアカウントを作成できない場合、自動デプロイは失敗します。このイシューのデバッグについては、失敗したデプロイジョブのトラブルシューティングを参照してください。

既存の PostgreSQL データベースを検出しました。

GitLab 13.0にアップグレードした後、Auto DevOpsでデプロイする際にこのメッセージが表示されることがあります：

Detected an existing PostgreSQL database installed on the
deprecated channel 1, but the current channel is set to 2. The default
channel changed to 2 in of GitLab 13.0.
[...]

Auto DevOpsはデフォルトで、アプリケーションと一緒にクラスタ内のPostgreSQLデータベースをインストールします。GitLab 13.0ではデフォルトのインストール方法が変更され、既存のデータベースをアップグレードするにはユーザーが関与する必要があります。2つのインストール方法があります：

  • チャネル1（非推奨）：関連するHelm Chartの依存関係としてデータベースを取り込みます。バージョン1.15までのKubernetesのみをサポートします。
  • チャネル2（現行）：データベースを独立したHelmチャートとしてインストールします。Kubernetesバージョン1.16以上でクラスタ内データベース機能を使用する場合に必要です。

このエラーが表示された場合は、次のいずれかのアクションを実行できます：

  • 警告を安全に無視し、AUTO_DEVOPS_POSTGRES_CHANNEL を1 に設定して再デプロイすることで、チャネル1の PostgreSQL データベースを使い続けることができます。

  • AUTO_DEVOPS_POSTGRES_DELETE_V1 を空でない値に設定し、再デプロイすることで、チャネル1の PostgreSQL データベースを削除し、新しいチャネル2のデータベースをインストールすることができます。

    caution
    チャネル1のPostgreSQLデータベースを削除すると、既存のチャネル1のデータベースとそのすべてのデータが永久に削除されます。データベースのバックアップとアップグレードの詳細については、PostgreSQLのアップグレードを参照してください。

  • クラスタ内データベースを使用していない場合は、POSTGRES_ENABLED をfalse に設定してデプロイし直すことができます。このオプションは特に、Chart内のPostgreSQLに依存しないカスタムChartのユーザに関係します。データベースの自動検出はリリースのpostgresql.enabled Helm値に基づいて行われます。この値はPOSTGRES_ENABLED CI/CD 変数に基づいて設定され、チャートがその変数を使用しているかどうかにかかわらず、Helm によって永続化されます。

caution
POSTGRES_ENABLED をPOSTGRES_ENABLED に設定すると、環境の既存のチャンネル1データベースが永久に削除されます。

Error: unable to recognize "": no matches for kind "Deployment" in version "extensions/v1beta1"

Kubernetesクラスターをv1.16+にアップグレードした後、Auto DevOpsでデプロイする際にこのメッセージが表示されることがあります：

UPGRADE FAILED
Error: failed decoding reader into objects: unable to recognize "": no matches for kind "Deployment" in version "extensions/v1beta1"

これは、現在の環境ネームスペース上のデプロイが、Kubernetes v1.16+には存在しない非推奨/削除されたAPIでデプロイされた場合に発生する可能性があります。例えば、クラスタ内のPostgreSQLがレガシーな方法でインストールされていた場合、リソースはextensions/v1beta1 API経由で作成されていました。しかし、デプロイリソースはv1.16でapp/v1 APIに移動しました。

このような古いリソースを復旧させるには、レガシーAPIを新しいAPIにマッピングすることで、現在のデプロイを変換する必要があります。この問題に対応するmapkubeapis というヘルパー ツールがあります。Auto DevOpsでツールを使用するには、以下の手順に従ってください：

  1. .gitlab-ci.yml を修正します：

    include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/shinya.maeda/ci-templates/-/raw/master/map-deprecated-api.gitlab-ci.yml
   
variables:
  HELM_VERSION_FOR_MAPKUBEAPIS: "v2" # If you're using auto-depoy-image v2 or above, please specify "v3".

  2. ジョブの実行<environment-name>:map-deprecated-api.次のステップに進む前に、このジョブが成功したことを確認してください。次のような出力が表示されるはずです：

    2020/10/06 07:20:49 Found deprecated or removed Kubernetes API:
"apiVersion: extensions/v1beta1
kind: Deployment"
Supported API equivalent:
"apiVersion: apps/v1
kind: Deployment"

  3. .gitlab-ci.yml を以前のバージョンに戻してください。補足テンプレートmap-deprecated-api を含める必要はなくなりました。

  4. 通常どおりデプロイを続行します。

Error: error initializing: Looks like "https://kubernetes-charts.storage.googleapis.com" is not a valid chart repository or cannot be reached

CNCFの公式ブログポストで発表されているように、安定版のHelmチャートリポジトリは2020年11月13日に非推奨となり削除されました。それ以降にこのエラーが発生する可能性があります。

GitLabのいくつかの機能は安定版Chartに依存していました。影響を軽減するために、新しい公式リポジトリかGitLab がメンテナンスしている Helm 安定版アーカイブリポジトリを使用するように変更しました。Auto Deploy には修正例が含まれています。

Auto Deploy では、auto-deploy-image のv1.0.6+ で、helm コマンドに非推奨の安定リポジトリが追加されなくなりました。カスタム Chart を使用していて、それが非推奨の安定リポジトリに依存している場合は、この例のように古いauto-deploy-image を指定してください：

include:
  - template: Auto-DevOps.gitlab-ci.yml

.auto-deploy:
  image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5"

この方法は、安定版リポジトリが削除されると機能しなくなるので、最終的にはカスタムチャートを修正しなければならないことを覚えておいてください。

カスタムチャートを修正するには

  1. Chartディレクトリで、requirements.yaml ファイルのrepository の値を ：

    repository: "https://kubernetes-charts.storage.googleapis.com/"

    に変更してください：

    repository: "https://charts.helm.sh/stable"
  2. Chartディレクトリで、Auto DevOpsと同じHelmメジャーバージョンを使用してhelm dep update . 。
  3. requirements.yaml ファイルの変更をコミットします。
  4. 以前にrequirements.lock ファイルが requirements.lockあったrequirements.lock 場合は、 requirements.lockそのファイルの変更をコミットしてください。以前にChartにファイルを持ってrequirements.lock いなかった requirements.lock場合は、新しいファイルをコミットする必要はありません。このファイルはオプションですが、存在する場合、ダウンロードされた依存関係のインテグリティを検証するために使用されます。

詳細はイシュー#263778「安定版HelmリポジトリからのPostgreSQLマイグレーション」を参照してください。

Error: release .... failed: timed out waiting for the condition

Auto DevOps を使い始めると、アプリケーションを最初にデプロイするときにこのエラーに遭遇することがあります：

INSTALL FAILED
PURGING CHART
Error: release staging failed: timed out waiting for the condition

これは、デプロイプロセス中に試行された Liveness (または Readiness) Probe が失敗したことが原因である可能性が高いです。デフォルトでは、これらのプローブはデプロイされたアプリケーションのルートページに対してポート 5000 で実行されます。アプリケーションがルートページで何かを提供するように設定されていないか、5000以外の特定のポートで実行するように設定されている場合、このチェックは失敗します。

失敗した場合、関連するKubernetesネームスペースのイベントにこれらの失敗が表示されるはずです。これらのイベントは次の例のようになります：

LAST SEEN   TYPE      REASON                   OBJECT                                            MESSAGE
3m20s       Warning   Unhealthy                pod/staging-85db88dcb6-rxd6g                      Readiness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused
3m32s       Warning   Unhealthy                pod/staging-85db88dcb6-rxd6g                      Liveness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused

生存性チェックに使用するポートを変更するには、Auto DevOpsで使用するHelmチャートにカスタム値を渡します：

  1. リポジトリのルートに.gitlab/auto-deploy-values.yaml という名前のディレクトリとファイルを作成します。

  2. このファイルに以下の内容を入力し、ポートの値をアプリケーションが使用するように設定されている実際のポート番号に置き換えてください：

    service:
  internalPort: <port_value>
  externalPort: <port_value>

  3. 変更をコミットしてください。

変更をコミットすると、以降のプローブでは新しく定義されたポートが使用されるようになります。プローブされるページは、livenessProbe.path とreadinessProbe.path の値（デフォルトのvalues.yaml ファイルに示されています）を同じ方法で上書きすることによっても変更できます。