自己署名証明書またはカスタム認証作成者
GitLab Runner 0.7.0で導入されました。
GitLab Runnerは、TLSピアの検証に使用する証明書を設定するための2つのオプションを提供します：
-
GitLab サーバーへの接続の場合：GitLab サーバーをターゲットとする自己署名証明書のサポートされるオプションのセクションで詳しく説明されているように、証明書ファイルを指定することができます。
これはRunnerを登録する際の
x509: certificate signed by unknown authorityの問題を解決します。既存のRunnerでは、ジョブをチェックしようとすると、Runnerのログに同じエラーが表示されます：
Couldn't execute POST against https://hostname.tld/api/v4/jobs/request: Post https://hostname.tld/api/v4/jobs/request: x509: certificate signed by unknown authority -
ユーザースクリプト、キャッシュサーバーや外部のGit LFSストアへの接続など、他のシナリオもカバーする、より汎用的なアプローチ:DockerとKubernetes ExecutorのTLS証明書を信頼するセクションで詳述されているように、証明書を指定してコンテナにインストールすることができます。
証明書がないGit LFSオペレーションに関するジョブログエラーの例：
LFS: Get https://object.hostname.tld/lfs-dev/c8/95/a34909dce385b85cee1a943788044859d685e66c002dbf7b28e10abeef20?X-Amz-Expires=600&X-Amz-Date=20201006T043010Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=svcgitlabstoragedev%2F20201006%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=012211eb0ff0e374086e8c2d37556f2d8ca4cc948763e90896f8f5774a100b55: x509: certificate signed by unknown authority
GitLab サーバーをターゲットとする自己署名証明書のサポートされるオプション
このセクションは、GitLabサーバーだけがカスタム証明書を必要とする状況について言及しています。他のホスト（プロキシダウンロードを有効にしていないオブジェクトストレージサービスなど）もカスタム認証局(CA) を必要とする場合は、次のセクションをご覧ください。
GitLab Runnerは以下のオプションをサポートしています：
-
デフォルト - システム証明書を読む ：GitLab Runnerはシステム証明書ストアを読み込み、GitLabサーバーをシステムに保存されている証明書作成者(CA) と照合します。システム証明書ストアからの読み取りはWindowsではサポートされていないことに注意してください。
-
カスタム証明書ファイル を指定します：GitLab Runnerは登録時（
gitlab-runner register --tls-ca-file=/path）とconfig.tomlの[[runners]]セクションでtls-ca-fileオプションを公開します。これにより、カスタム証明書ファイルを指定することができます。このファイルはRunnerがGitLabサーバーにアクセスしようとするたびに読み込まれます。GitLab Runner Helm chartを使っている場合は、Providing a custom certificate for accessing GitLabで説明するように証明書を設定する必要があります。 -
PEM 証明書を読み込みます：GitLab Runnerは定義済みのファイルからPEM証明書（DER形式はサポートされていません）を読み込みます：
-
/etc/gitlab-runner/certs/gitlab.example.com.crtGitLabRunnerがrootとして実行されるとき、*nixシステム上。サーバーのアドレスが
https://gitlab.example.com:8443/の場合は、証明書ファイルを以下の場所に作成してください：/etc/gitlab-runner/certs/gitlab.example.com.crt.opensslクライアントを使用して、GitLab インスタンスの証明書を/etc/gitlab-runner/certsにダウンロードできます：openssl s_client -showcerts -connect gitlab.example.com:443 -servername gitlab.example.com < /dev/null 2>/dev/null | openssl x509 -outform PEM > /etc/gitlab-runner/certs/gitlab.example.com.crtファイルが正しくインストールされていることを確認するには、
opensslのようなツールを使います。例えばecho | openssl s_client -CAfile /etc/gitlab-runner/certs/gitlab.example.com.crt -connect gitlab.example.com:443 -servername gitlab.example.com -
~/.gitlab-runner/certs/gitlab.example.com.crtGitLab Runner がroot以外として実行された場合、*nix システム上では。 -
./certs/gitlab.example.com.crtとして実行された場合。GitLab RunnerをWindowsサービスとして実行する場合、これは機能しません。代わりにカスタム証明書ファイルを指定してください。
-
注釈
-
GitLabサーバー証明書があなたのCAによって署名されている場合、あなたのCA証明書を使用してください（GitLabサーバー署名証明書ではありません）。チェーンに中間証明書も追加する必要があるかもしれません。例えば、プライマリ証明書、中間証明書、ルート証明書がある場合、それらを一つのファイルにまとめることができます：
-----BEGIN CERTIFICATE----- (Your primary SSL certificate: your_domain_name.crt) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Your intermediate certificate) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Your root certificate) -----END CERTIFICATE----- - 既存のRunnerの証明書を更新する場合は、Runnerを再起動してください。
- HTTP で既に Runner を設定している場合は、
config.tomlで GitLab インスタンスの新しい HTTPS URL にインスタンスパスを更新してください。 - 一時的で安全でない回避策として、証明書の検証をスキップするには、
.gitlab-ci.ymlファイルのvariables:セクションで、CI 変数GIT_SSL_NO_VERIFYをtrueに設定します。
Gitクローン
Runnerは、CI_SERVER_TLS_CA_FILE を使うことで、足りない証明書を注入してCAチェーンを構築します。これにより、git clone とアーティファクトは、公開されている信頼できる証明書を使わないサーバーでも動作するようになります。
このアプローチはセキュアですが、Runnerを単一の信頼ポイントとします。
DockerとKubernetes ExecutorのTLS証明書の信頼性
コンテナへの証明書の登録を検討する際に考慮する必要があるコンテキストは2つあります：
- それは ユーザー・イメージユーザースクリプトの実行に使用されるユーザーイメージ。このシナリオでは、証明書のインストール方法はイメージ自体に大きく依存するため、ユーザーが所有権を持つ必要があります。
- ランナー Runner ヘルパーイメージこれはGit、アーティファクト、キャッシュオペレーションを処理するために使用されます。このシナリオでは、ユーザーは証明書ファイルを特定の場所（例えば、
/etc/gitlab-runner/certs/ca.crt）で利用できるようにするだけで、Dockerコンテナが自動的にインストールしてくれます。
ユーザースクリプト用の証明書の信頼性
ビルドスクリプトがTLSを通じてピアと通信する必要があり、自己署名証明書またはカスタム作成者に依存する必要がある場合、ビルドジョブで証明書のインストールを実行する必要があります。ユーザースクリプトを実行するDockerコンテナには、デフォルトで証明書ファイルがインストールされていないためです。これは、カスタムキャッシュホストを使用したり、セカンダリgit clone 、またはwget のようなツールを使用してファイルを取得する場合などに必要になることがあります。
証明書をインストールするには、以下の手順に従います：
-
スクリプトを実行するDockerコンテナに見えるように、必要なファイルをDockerボリュームとしてマッピングします。例えば、
config.tomlファイルの[runners.docker]内のそれぞれのキーの内部にボリュームを追加することで行います：-
Linux:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "ubuntu:latest" # Add path to your ca.crt file in the volumes list volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
-
-
Linuxのみ：マップされたファイル(例:
ca.crt)をpre_build_scriptで使用します：- Dockerコンテナ内部の
/usr/local/share/ca-certificates/ca.crt。 -
update-ca-certificates --freshを実行してインストールします。例えば（コマンドは使用しているディストリビューションによって異なります）：-
Ubuntuの場合：
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" # Copy and install CA certificate before each job pre_build_script = """ apt-get update -y > /dev/null apt-get install -y ca-certificates > /dev/null cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt update-ca-certificates --fresh > /dev/null """ -
アルパインで
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" # Copy and install CA certificate before each job pre_build_script = """ apk update >/dev/null apk add ca-certificates > /dev/null rm -rf /var/cache/apk/* cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt update-ca-certificates --fresh > /dev/null """
-
- Dockerコンテナ内部の
使用可能なGitLabサーバーのCA証明書だけが必要な場合は、CI_SERVER_TLS_CA_FILE 変数に格納されているファイルから取得できます：
curl --cacert "${CI_SERVER_TLS_CA_FILE}" ${URL} -o ${FILE}
他のCI/CDステージの証明書を信頼する場合
GitLab 13.3 で導入されました。
Linuxでは/etc/gitlab-runner/certs/ca.crt 、WindowsではC:\GitLab-Runner\certs\ca.crt 、証明書ファイルをマップすることができます。Runnerヘルパーイメージは起動時にこのユーザー定義ca.crt ファイルをインストールし、例えばアーティファクトのクローンやアップロードなどのオペレーションを実行する際に使用します。
Docker
-
Linux:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "ubuntu:latest" # Add path to your ca.crt file in the volumes list volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"] -
Windows:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "mcr.microsoft.com/windows/servercore:21H2" # Add directory holding your ca.crt file in the volumes list volumes = ["c:\\cache", "c:\\path\\to-ca-cert-dir:C:\\GitLab-Runner\\certs:ro"]
Kubernetes
Kubernetesで実行されるジョブに証明書ファイルを提供します：
-
証明書をKubernetesシークレットとしてネームスペースに保存します：
kubectl create secret generic <SECRET_NAME> --namespace <NAMESPACE> --from-file=<CERT_FILE> -
Runnerのボリュームとしてシークレットをマウントし、
<SECRET_NAME>と<LOCATION>を適切な値に置き換えます：gitlab-runner: runners: config: | [[runners]] [runners.kubernetes] namespace = "{{.Release.Namespace}}" image = "ubuntu:latest" [[runners.kubernetes.volumes.secret]] name = "<SECRET_NAME>" mount_path = "<LOCATION>"mount_pathは、証明書が格納されているコンテナ内のディレクトリです。mount_pathとして/etc/gitlab-runner/certs/を使用し、証明書ファイルとしてca.crtを使用した場合、証明書はコンテナ内部の/etc/gitlab-runner/certs/ca.crtで使用できます。 -
ジョブの一部として、マッピングされた証明書ファイルをシステム証明書ストアにインストールします。たとえば、Ubuntuコンテナの場合：
script: - cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ - update-ca-certificates
Kubernetesエクゼキュータによるヘルパーイメージの処理（ENTRYPOINT ）に既知のイシューがあるため、マップされた証明書ファイルはシステム証明書ストアに自動的にインストールされません。
トラブルシューティング
一般的なSSLトラブルシューティングのドキュメントを参照してください。
さらに、tlsctl ツールを使用して、Runner 側から GitLab 証明書をデバッグすることができます。
x509: certificate signed by unknown authority 非公開レジストリから Executor イメージを取得しようとしているとき
このエラーは、RunnerがExecutorをスケジュールするDockerホストまたはKubernetesノードが、非公開レジストリで使用される証明書を信頼していない場合に発生します。このエラーを修正するには、オペレーティングシステムに基づいて、関連するルート認証局証明書をシステムのトラストストアに追加します。