Secrets

极狐GitLab 需要多种 secret 才能运作:

GitLab 组件:

  • Registry 认证证书
  • GitLab Shell 的主机密钥和证书
  • 各个 GitLab services 的密码
  • GitLab Pages 的 TLS 证书

可选外部服务:

  • SMTP 服务
  • LDAP
  • OmniAuth
  • 用于接收电子邮件的 IMAP(通过 mail_room 服务)
  • 用于服务台电子邮件的 IMAP(通过 mail_room 服务)
  • 用于接收电子邮件的带有 OAuth2 的 Microsoft Graph(通过 mail_room 服务)
  • 带有 OAuth2 的 Microsoft Graph 用于服务台电子邮件(通过 mail_room 服务)
  • 带有 OAuth2 的 Microsoft Graph 用于外发电子邮件
  • S/MIME 认证
  • Smartcard 身份验证
  • OAuth 集成

任何未手动提供的 secret 都将使用随机值自动生成。HTTPS 证书的自动生成由 Let’s Encrypt 提供。

要利用自动生成的 secret,请继续下一步

要指定您自己的 secret,请继续手动创建 secret

手动创建 secret(可选)

如果您按照本文档中的先前步骤操作,请使用 gitlab 作为版本名称。

Registry 认证证书

GitLab 和 Registry 之间的通信发生在 Ingress 之后,因此在大多数情况下使用自签名证书进行通信即可。如果此流量通过网络公开,您应该生成公开有效的证书。

在下面的示例中,我们假设我们需要自签名证书。

生成证书密钥对:

mkdir -p certs
openssl req -new -newkey rsa:4096 -subj "/CN=gitlab-issuer" -nodes -x509 -keyout certs/registry-example-com.key -out certs/registry-example-com.crt

创建一个包含这些证书的 secret。 我们将在 <name>-registry-secret secret 中创建 registry-auth.keyregistry-auth.crt 键。将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-registry-secret --from-file=registry-auth.key=certs/registry-example-com.key --from-file=registry-auth.crt=certs/registry-example-com.crt

这个 secret 由 global.registry.certificate.secret 设置引用。

Registry 敏感通知 headers

查看有关配置 Registry 通知的文档了解更多详细信息。

Secret 内容应该是一个配置项列表,即使它包含单个配置项。 如果内容只是一个字符串,chart 不会根据需要将其转换为列表。

kubectl create secret generic registry-authorization-header --from-literal=value="[RandomFooBar]"

默认情况下,secret 中使用的密钥是“值”。但是,用户可以使用不同的键,但必须确保在 header 映射项下将其指定为“键”。

SSH 主机密钥

生成 OpenSSH 证书密钥对:

mkdir -p hostKeys
ssh-keygen -t rsa  -f hostKeys/ssh_host_rsa_key -N ""
ssh-keygen -t dsa  -f hostKeys/ssh_host_dsa_key -N ""
ssh-keygen -t ecdsa  -f hostKeys/ssh_host_ecdsa_key -N ""
ssh-keygen -t ed25519  -f hostKeys/ssh_host_ed25519_key -N ""

创建包含这些证书的 secret。将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-shell-host-keys --from-file hostKeys

此 secret 由global.shell.hostKeys.secret 设置引用。

如果此密钥被轮换,所有 SSH 客户端都会看到 hostname mismatch 错误。

初始许可证

caution此方法只会在安装时添加许可证。使用 Web 用户界面中的管理中心来续订或升级许可证。

创建一个 Kubernetes secret,用于存储 GitLab 实例的许可证。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-license --from-file=license=/tmp/license.gitlab

然后使用 --set global.gitlab.license.secret=<name>-gitlab-license 将许可证注入到您的配置中。

您还可以使用 global.gitlab.license.key 选项更改指向许可证 secret 中的许可证的默认 license 键。

初始 root 密码

创建用于存储初始 root 密码的 Kubernetes secret。密码长度至少应为 6 个字符。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-initial-root-password --from-literal=password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32)

Redis 密码

为 Redis 生成一个随机的 64 个字符的包含字母和数字的密码。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-redis-secret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

如果使用已有的 Redis 集群部署,请使用 base64 编码的 Redis 集群访问密码,不要使用随机生成的密码。

此 secret 由 global.redis.auth.secret 设置引用。

GitLab Shell secret

为 GitLab Shell 生成一个随机的 64 个字符的包含字母和数字的 secret。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-shell-secret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由global.shell.authToken.secret 设置引用。

Gitaly secret

为 Gitaly 生成一个随机的 64 个字符的包含字母和数字的令牌。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitaly-secret --from-literal=token=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由 global.gitaly.authToken.secret 设置引用。

Praefect secret

为 Praefect 生成一个随机的 64 个字符的包含字母和数字的令牌。将 <name> 替换为发行版的名称:

kubectl create secret generic <name>-praefect-secret --from-literal=token=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由global.praefect.authToken.secret 设置引用。

GitLab Rails secret

<name> 替换为发行版的名称。

cat << EOF > secrets.yml
production:
  secret_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
  otp_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
  db_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
  encrypted_settings_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
  openid_connect_signing_key: |
$(openssl genrsa 2048 | awk '{print "    " $0}')
  ci_jwt_signing_key: |
$(openssl genrsa 2048 | awk '{print "    " $0}')
EOF

kubectl create secret generic <name>-rails-secret --from-file=secrets.yml

此 secret 被global.railsSecrets.secret 设置引用。

noteencrypted_settings_key_base 是在 13.7 版本中添加的,并且在 14.0 版本中是必需的。

不建议轮换此 secret,因为它包含数据库加密密钥。如果 secret 被轮换,结果将与密钥文件丢失时表现相同。

GitLab Workhorse secret

生成 Workhorse secret。必须有 32 个字符的长度并以 base64 编码。将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-workhorse-secret --from-literal=shared_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

此 secret 由 global.workhorse.secret 设置引用。

GitLab Runner secret

<name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-runner-secret --from-literal=runner-registration-token=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由 gitlab-runner.runners.secret 设置引用。

GitLab KAS secret

GitLab Rails 要求存在 KAS 的 secret,即使是在未安装 KAS 子 chart 的情况下部署此 chart 时也是如此。不过,您可以按照以下过程手动创建此 secret,或将其留给 chart 以自动生成 secret。

<name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-kas-secret --from-literal=kas_shared_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

此 secret 由 global.appConfig.gitlab_kas.key 设置引用。

GitLab KAS API secret

您可以使 chart 自动生成密钥,也可以手动创建此密钥(将 <name> 替换为版本名称):

kubectl create secret generic <name>-kas-private-api --from-literal=kas_private_api_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

此 secret 由 gitlab.kas.privateApi.secret 设置引用。

GitLab Suggested Reviewers secret

note建议审核者 secret 自动创建,仅适用于 SaaS。私有化部署实例不需要此 secret。

极狐GitLab Rails 要求存在建议审核者的 secret。您可以将其留给 chart 来自动生成 secret,也可以手动创建此 secret(将 <name> 替换为发布名称):

kubectl create secret generic <name>-gitlab-suggested-reviewers --from-literal=suggested_reviewers_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

此 secret 由 global.appConfig.suggested_reviewers.secret 设置引用。

MinIO secret

为 MinIO 生成一组随机的 20 和 64 个字符的包含字母和数字的密钥。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-minio-secret --from-literal=accesskey=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 20) --from-literal=secretkey=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由 global.minio.credentials.secret 设置引用。

PostgreSQL 密码

生成一个随机的 64 个字符的包含字母和数字的密码。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-postgresql-password \
    --from-literal=postgresql-password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64) \
    --from-literal=postgresql-postgres-password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)

此 secret 由 global.psql.password.secret 设置引用。

更改捆绑的 PostgreSQL 子 chart 的 PostgreSQL 密码

caution默认的 Helm chart 配置不适合用于生产,其中包括捆绑的 PostgreSQL 子 chart。

捆绑的 PostgreSQL 子 chart 仅在最初创建数据库时使用来自 secret 的密码配置数据库。需要采取额外的步骤来更改现有数据库中的密码。

请注意,在进行更改时,此操作将对用户造成干扰。

要轮换 PostgreSQL 密钥:

  1. 完成 PostgreSQL secret 的通用轮换 secret 说明。
  2. 进入 PostgreSQL pod 并更新数据库中的密码:

     # Exec into the PostgreSQL pod
     kubectl exec -it <name>-postgresql-0 -- sh
    
     # Inside the pod, update the passwords in the database
     sed -i 's/^\(local .*\)md5$/\1trust/' /opt/bitnami/postgresql/conf/pg_hba.conf
     pg_ctl reload ; sleep 1
     echo "ALTER USER postgres WITH PASSWORD '$(cat $POSTGRES_POSTGRES_PASSWORD_FILE)' ; ALTER USER gitlab WITH PASSWORD '$(cat $POSTGRES_PASSWORD_FILE)'" | psql -U postgres -d gitlabhq_production -f -
     sed -i 's/^\(local .*\)trust$/\1md5/' /opt/bitnami/postgresql/conf/pg_hba.conf
     pg_ctl reload
    
  3. 使用 kubectl delete pod 命令删除 gitlab-exporterpostgresqltoolboxsidekiqwebservice pod,以便新的 pods 加载新的密码并允许它们连接到数据库。

GitLab Pages secret

生成 GitLab Pages secret。必须有 32 个字符的长度并以 base64 编码。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-gitlab-pages-secret --from-literal=shared_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

此 secret 由 global.pages.apiSecret.secret 设置引用。

Registry HTTP secret

生成所有 Registry pod 共享的随机 64 个字符的包含字母和数字的密钥。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-registry-httpsecret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64 | base64)

此 secret 由 global.registry.httpSecret.secret 设置引用。

Registry notification secret

生成由所有 Registry pod 和 GitLab webservice pod 共享的随机 32 个字符的包含字母和数字的密钥。 将 <name> 替换为发行版的名称。

kubectl create secret generic <name>-registry-notification --from-literal=secret=[\"$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32)\"]

此 secret 由 global.registry.notificationSecret.secret 设置引用。

Praefect DB 密码

生成一个随机的 64 个字符的包含字母和数字的密码。将 <name> 替换为发行版的名称:

kubectl create secret generic <name>-praefect-dbsecret \
    --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64) \

此 secret 由 global.praefect.dbSecret 设置引用。

外部服务

一些 chart 有更多的 secret 来启用无法自动生成的功能。

LDAP 密码

如果您需要密码认证来连接您的 LDAP 服务器,您必须将密码存储在 Kubernetes secret 中。

kubectl create secret generic ldap-main-password --from-literal=password=yourpasswordhere

然后使用 --set global.appConfig.ldap.servers.main.password.secret=ldap-main-password 将密码注入到您的配置中。

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

SMTP 密码

如果您使用的是需要身份验证的 SMTP 服务器,请将密码存储在 Kubernetes secret中。

kubectl create secret generic smtp-password --from-literal=password=yourpasswordhere

然后在你的 Helm 命令中使用 --set global.smtp.password.secret=smtp-password

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

接收电子邮件的 IMAP 密码

让极狐GitLab 可以访问收到的电子邮件 将 IMAP 帐户的密码存储在 Kubernetes secret 中。

kubectl create secret generic incoming-email-password --from-literal=password=yourpasswordhere

然后在 Helm 命令中使用 --set global.appConfig.incomingEmail.password.secret=incoming-email-password 以及在文档中指定的其它必需设置。

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

服务台电子邮件的 IMAP 密码

为了让极狐GitLab 可以访问服务台电子邮件,将 IMAP 帐户的密码存储在 Kubernetes secret 中。

kubectl create secret generic service-desk-email-password --from-literal=password=yourpasswordhere

然后在 Helm 命令中使用 --set global.appConfig.serviceDeskEmail.password.secret=service-desk-email-password 以及文档中指定的其它必需设置。

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

接收电子邮件身份验证令牌

当接收电子邮件配置为使用 webhook 传递方法时,mail_room 服务和 web 服务之间应该有一个共享密钥,其必须具有 32 个字符的长度和 base64 编码。将 <name> 替换为发布版本的名称。

kubectl create secret generic <name>-incoming-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

global.incomingEmail.authToken 设置引用了此 secret。

服务台电子邮件身份验证令牌

当服务台电子邮件配置为使用 webhook 传递方法时,mail_room 服务和 web 服务之间应该有一个共享密钥,其必须具有 32 个字符的长度和 base64 编码。将 <name> 替换为发布版本的名称。

kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)

global.serviceDeskEmail.authToken 设置引用了此 secret。

Zoekt 基础验证密码

您可以让 chart 自动生成 secret,也可以手动创建 secret(将 <name> 替换为版本名称):

password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)
kubectl create secret generic <name>-zoekt-basicauth --from-literal=gitlab_username=gitlab --from-literal=gitlab_password="$password"

此 secret 由 gitlab.zoekt.gateway.basicAuth.secretName 设置引用。

接收电子邮件的 Microsoft Graph 客户端 secret

让极狐GitLab 可以访问接收电子邮件,将 IMAP 帐户的密码存储在 Kubernetes secret 中。

kubectl create secret generic incoming-email-client-secret --from-literal=secret=your-secret-here

然后,在 Helm 命令中使用 --set global.appConfig.incomingEmail.clientSecret.secret=incoming-email-client-secret 以及文档中指定的其它必需设置.

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

服务台电子邮件的 Microsoft Graph 客户端 secret

为了让极狐GitLab 可以访问服务台电子邮件,将 IMAP 帐户的密码存储在 Kubernetes secret 中。

kubectl create secret generic service-desk-email-client-secret --from-literal=secret=your-secret-here

然后在 Helm 命令中使用 --set global.appConfig.serviceDeskEmail.password.secret=service-desk-email-password 以及文档中指定的其它必需设置。

note在配置 Helm 属性时使用 Secret 名称,而不是实际密码。

S/MIME 证书

外发电子邮件可以使用 S/MIME 标准进行数字签名。 S/MIME 证书需要作为 TLS 类型的 secret 存储在 Kubernetes secret 中。

kubectl create secret tls smime-certificate --key=file.key --cert file.crt

如果存在 opaque 类型的现有 secret,则需要针对特定 secret 调整 global.email.smime.keyNameglobal.email.smime.certName 值。

S/MIME 设置可以通过 values.yaml 文件或在命令行上进行设置。使用 --set global.email.smime.enabled=true 启用 S/MIME,使用 --set global.email.smime.secretName=smime-certificate 指定包含 S/MIME 证书的 secret。

Smartcard 验证

Smartcard 验证使用自定义证书颁发机构 (CA) 签署客户端证书。这个自定义 CA 的证书需要注入到 Webservice pod 中,以便它验证客户端证书是否有效。这是作为 k8s secret 提供的。

kubectl create secret generic <secret name> --from-file=ca.crt=<path to CA certificate>

存储证书的 secret 中的键名称必须是 ca.crt

OAuth 集成

要配置各种服务的 OAuth 集成,例如 GitLab Pages,需要包含 OAuth 凭据的 secret。Secret 应该包含一个 App ID(默认情况下,存储在 appid 键下)和一个 App Secret(默认情况下,存储在 appsecret 键下),两者都建议为包含字母和数字的字符串,至少 64 个字符。

kubectl create secret generic oauth-gitlab-pages-secret --from-literal=appid=<app id> --from-literal=appsecret=<app secret>

可以使用 global.oauth.<service name>.secret 设置来指定此 secret。如果使用除 appidappsecret 以外的键,则可以使用 global.oauth.<service name>.appIdKeyglobal.oauth.<service name>.appSecretKey 设置来指定它们。

下一步

生成并存储所有 secret 后,您可以继续部署极狐GitLab

轮换 secrets

如果出于安全目的需要,可以轮换 secrets。

  1. 备份您当前的 secrets
  2. 为方便起见,请按照手动创建 secret 步骤,为您希望轮换的每个 secret,创建以 -v2 为后缀的新 secret(例如 gitlab-shell-host-keys-v2)。
  3. 更新 values.yaml 文件中的密钥指向新的密钥名称。大多数 secret 名称都记录在手动创建 secret 部分。
  4. 使用更新的 values.yaml 文件升级极狐GitLab Chart 版本。
  5. 如果您要轮换 PostgreSQL 密钥,还需要其他步骤
  6. 确认极狐GitLab 正在按预期工作。如果是,删除旧 secrets 应该是安全的。