故障排查

UPGRADE FAILED: “$name” has no deployed releases

如果您的初始安装失败，将在您第二次安装/升级时发生此错误。

如果您的初始安装完全失败，并且极狐GitLab 从未运行过，您应该在再次安装之前先清除失败的安装。 

helm uninstall <release-name>

如果相反，初始安装命令超时，但极狐GitLab 仍然成功启动，您可以将 --force 标志添加到 helm upgrade 命令以忽略错误并尝试更新版本。

Error: this command needs 2 arguments: release name, chart path

运行 helm upgrade 时可能会出现这样的错误并且参数中有一些空格。 在以下示例中，错误归咎于 Test Username： 

helm upgrade gitlab gitlab/gitlab --timeout 600s --set global.email.display_name=Test Username ...

要修复它，请在单引号中传递参数： 

helm upgrade gitlab gitlab/gitlab --timeout 600s --set global.email.display_name='Test Username' ...

Application containers constantly initializing

如果您在初始化的状态下遇到 Sidekiq、Webservice 或其它基于 Rails 的容器，您可能正在等待 dependencies 容器通过。

如果您专门针对 dependencies 容器检查给定 Pod 的日志，您可能会看到以下返回： 

Checking database connection and schema version
WARNING: This version of GitLab depends on gitlab-shell 8.7.1, ...
Database Schema
Current version: 0
Codebase version: 20190301182457

这表明 migrations Job 尚未完成。Job 的目的是确保数据库已播种，以及所有相关迁移均已就位。应用程序容器正在尝试等待数据库达到或高于其预期的数据库版本。这是为了确保应用程序不会因不符合代码库期望的模式而出现故障。

  1. 找到 migrations Job。kubectl get job -lapp=migrations
  2. 找到 Job 运行的 Pod. kubectl get pod -ljob-name=<job-name>
  3. 检查输出，检查 STATUS 列。

如果 STATUS 是 Running，继续。如果 STATUS 是 Completed，应用程序容器应该在下一次检查通过后不久启动。

检查此 pod 中的日志。 kubectl logs <pod-name>

应解决 Job 运行期间的任何故障。 这些将阻止应用程序的使用，直到解决为止。可能的问题是：

  • 无法访问或失败的已配置 PostgreSQL 数据库的身份验证
  • 无法访问或失败的已配置 Redis 服务的身份验证
  • 无法访问 Gitaly 实例

应用配置更改

以下命令将执行必要的操作以应用对 gitlab.yaml 所做的任何更新： 

helm upgrade <release name> <chart path> -f gitlab.yaml

GitLab Runner 无法注册

当 GitLab 中的 Runner 注册令牌已更改时，可能会发生这种情况。（这通常发生在您恢复备份后）

  1. 在 GitLab 安装的 admin/runners 网页上找到新的共享 Runner 令牌。

  2. 查找存储在 Kubernetes 中的现有 Runner 令牌 secret 的名称 

    kubectl get secrets | grep gitlab-runner-secret

  3. 删除现有的 secret 

    kubectl delete secret <runner-secret-name>

  4. 创建带有两个键的新 secret（带有共享令牌的 runner-registration-token 和一个空的 runner-token） 

    kubectl create secret generic <runner-secret-name> --from-literal=runner-registration-token=<new-shared-runner-token> --from-literal=runner-token=""

太多重定向

如果在 NGINX Ingress 之前有 TLS 终止，并且在配置中指定了 tls-secrets，就会发生这种情况。

  1. 设置 global.ingress.annotations."nginx.ingress.kubernetes.io/ssl-redirect": "false" 以更新您的值

    通过 values 文件： 

    # values.yaml
global:
  ingress:
    annotations:
      "nginx.ingress.kubernetes.io/ssl-redirect": "false"

    通过 Helm CLI： 

    helm ... --set-string global.ingress.annotations."nginx.ingress.kubernetes.io/ssl-redirect"=false

  2. 应用更改

note当使用外部服务进行 SSL 终止时，该服务负责重定向到 https（如果需要）。

升级因不可变字段错误而失败

spec.clusterIP

在这些 chart 的 3.0.0 版本发布之前，尽管没有实际值（""），spec.clusterIP 属性已被填入到多个服务中。这是一个错误，会导致 Helm 3 的三向属性合并出现问题。

一旦使用 Helm 3 部署了图表，除非从各种服务中收集了 clusterIP 属性并将其填入到提供给 Helm 的值中，或者从 Kubernetes 中删除受影响的服务，否则就没有可能的升级路径。

此 chart 的 3.0.0 版本更正了此错误，但需要手动更正。

可以通过简单地删除所有受影响的服务来解决。

  1. 删除所有受影响的服务： 

    kubectl delete services -lrelease=RELEASE_NAME
  2. 通过 Helm 执行升级。
  3. 以后的升级不会遇到这个错误。
note如果正在使用，这将更改此 chart 中 NGINX Ingress 的LoadBalancer 的任何动态值。 有关 externalIP 的更多详细信息，请参阅 全局 Ingress 设置文档。您可能需要更新 DNS 记录！

spec.selector

Sidekiq pod 在 chart 发布 3.0.0 之前没有收到唯一的选择器。

使用 Helm 升级到 3.0.0 将自动删除旧的 Sidekiq 部署并通过将 -v1 附加到 Sidekiq Deployments、HPA 和 Pods 的名称来创建新的部署。

如果您在安装 3.0.0 时在 Sidekiq 部署上继续遇到此错误，请使用以下步骤解决这些问题：

  1. 删除 Sidekiq 服务 

    kubectl delete deployment --cascade -lrelease=RELEASE_NAME,app=sidekiq

  2. 通过 Helm 执行升级。

cannot patch “RELEASE-NAME-cert-manager” with kind Deployment

从 CertManager 版本 0.10 升级引入了许多重大更改。 必须从 Helm 的跟踪中卸载并删除旧的 CRD，然后重新安装。

默认情况下，Helm chart 会尝试执行此操作，但如果您遇到此错误，则可能需要采取手动操作。

如果遇到此错误消息，则升级需要比正常多一个步骤，以确保新的 CRD 实际应用于部署。

  1. 删除旧的 CertManager Deployment. 

     kubectl delete deployments -l app=cert-manager --cascade

  2. 再次运行升级。这次安装新的 CRD。 

     helm upgrade --install --values - YOUR-RELEASE-NAME gitlab/gitlab < <(helm get values YOUR-RELEASE-NAME)

ImagePullBackOff, Failed to pull image 和 manifest unknown 错误

如果您使用 global.gitlabVersion，请先删除该属性。 检查 chart 和 GitLab 之间的版本映射 并在您的 helm 命令中指定一个兼容版本的 gitlab/gitlab chart。

UPGRADE FAILED: “cannot patch …” after helm 2to3 convert

这是一个已知的问题。 将 Helm 2 版本迁移到 Helm 3 后，后续升级可能会失败。 您可以在 从 Helm v2 迁移到 Helm v3 中找到完整的解释和解决方法。

Restoration failure: ERROR: cannot drop view pg_stat_statements because extension pg_stat_statements requires it

在 Helm chart 实例上恢复备份时，您可能会遇到此错误。 使用以下步骤作为解决方法：

  1. 在 task-runner pod 中打开数据库控制台： 

    /srv/gitlab/bin/rails dbconsole -p

  2. 删除扩展名： 

    DROP EXTENSION pg_stat_statements
  3. 执行恢复过程。

  4. 恢复完成后，在DB控制台重新创建扩展： 

    CREATE EXTENSION pg_stat_statements

如果您遇到与 pg_buffercache 扩展相同的问题，请按照上述相同的步骤删除并重新创建它。

Bundled PostgreSQL pod fails to start: database files are incompatible with server

升级到新版本的 GitLab Helm chart 后，捆绑的 PostgreSQL pod 中可能会出现以下错误消息： 

gitlab-postgresql FATAL:  database files are incompatible with server
gitlab-postgresql DETAIL:  The data directory was initialized by PostgreSQL version 11, which is not compatible with this version 12.7.

要解决此问题，请对 chart 的先前版本执行 Helm 回滚，然后按照升级指南 来升级捆绑的 PostgreSQL 版本。正确升级 PostgreSQL 后，再次尝试升级 GitLab Helm chart。

Increased load on /api/v4/jobs/requests endpoint

如果部署服务/api/*的选项workhorse.keywatcher被设置为false，你可能会遇到这个问题。 使用以下步骤进行验证：

  1. 在服务/api/*的 pod 中访问容器gitlab-workhorse： 

    kubectl exec -it --container=gitlab-workhorse <gitlab_api_pod> -- /bin/bash

  2. 检查文件/srv/gitlab/config/workhorse-config.toml。 可能缺少 [redis] 配置： 

    cat /srv/gitlab/config/workhorse-config.toml | grep '\[redis\]'

如果 [redis] 配置不存在，workhorse.keywatcher 标志在部署期间设置为 false。 从而导致 /api/v4/jobs/requests 端点中的额外负载。 要解决此问题，请在 webservice chart 中启用 keywatcher： 

workhorse:
  keywatcher: true