インターネット接続が制限または完全に切断されたエアギャップ環境では、外部のパブリックレジストリ(Docker HubやQuay.ioなど)へのアウトバウンド通信がファイアウォールによって遮断されます。このようなインフラストラクチャにおいてKubesprayを用いたKubernetesクラスタを運用する場合、コンテナイメージの依存解決にパブリックエンドポイントが含まれていると、ビルドパイプラインがタイムアウトや名前解決エラーにより停止することになります。コンテナビルドプロセスの再現性を確保し、意図しない外部ネットワークリクエストを排除するには、内部プライベートレジストリを前提条件とした静的検証ゲートおよび閉域環境専用のパイプライン構成が不可欠となります。
本稿では、内部レジストリである「Harbor」を基盤とし、Kubesprayクラスタへデプロイするワークロードイメージを安全に生成・検証・配布するためのGitLab CI/CDパイプラインの実装仕様を整理します。
パイプライン全体構造と実行基盤パラメータ
対象環境では、GitLab Runner自体も閉域ネットワーク内に配置し、dockerおよびofflineの実行タグによってターゲットノードを制約します。パイプライン全体で使用するグローバル設定は以下の通りです。
stages:
- validate
- build
variables:
HARBOR_REGISTRY: "harbor.devstack.co.kr:8443"
HARBOR_PROJECT: "kubespray"
IMAGE_NAME: "nginx-app"
image: "$HARBOR_REGISTRY/$HARBOR_PROJECT/ci/docker:29.1.4-cli"
設定パラメータの仕様
stages定義:validate(リポジトリ内のDockerfileが内部レジストリのベースイメージを正しく参照しているかを検査する静的検証フェーズ)およびbuild(内部Harborへの認証、コミット情報に基づくイメージタグの生成、コンテナイメージのビルドおよびプッシュ、環境変数のメタデータ出力を行うフェーズ)で構成します。variables定義:HARBOR_REGISTRYにはプライベートHarborのFQDNおよびTLS通信ポート(harbor.devstack.co.kr:8443)を指定し、HARBOR_PROJECTにはKubespray用アーティファクトを分離・収容するプロジェクト名前空間(kubespray)を設定します。またIMAGE_NAMEとして生成対象のワークロードコンテナイメージ名(nginx-app)を定義します。- 実行イメージ (
image): ランナーコンテナ自体もパブリックレジストリに依存せず、harbor.devstack.co.kr:8443/kubespray/ci/docker:29.1.4-cliから取得します。バージョンを29.1.4-cliに固定することで、CLIオプションの挙動差分によるビルド失敗を防止します。
ステージ別ジョブ詳細設計
1. Dockerfileの静的検証ジョブ (validate:dockerfile)
ビルドプロセスに突入する前に、外部レジストリを参照する不正なFROM句が混入していないかを検証します。
validate:dockerfile:
stage: validate
tags:
- docker
- offline
script:
- test -f Dockerfile
- grep -q "$HARBOR_REGISTRY" Dockerfile
- echo "Dockerfile validation passed"
💡 test -f Dockerfile でルートディレクトリにおけるDockerfileの存在を確認し、grep -q “$HARBOR_REGISTRY” Dockerfile によってベースイメージ参照行に harbor.devstack.co.kr:8443 が含まれているかを検査します。外部リポジトリ(例: FROM nginx:latest)を直接指定した記述が存在する場合、終了ステータスが非ゼロとなり、後続のビルドジョブ実行を即時に遮断します。
2. ビルドおよびレジストリ配布ジョブ (build:push)
コンテナのビルド、認証情報の安全な引き渡し、外部リクエストの物理的抑制、動的メタデータのパイプライン連携を担います。
build:push:
stage: build
tags:
- docker
- offline
before_script:
- docker version
- echo "$HARBOR_PASSWORD" | docker login "$HARBOR_REGISTRY" -u "$HARBOR_USER" --password-stdin
script:
- |
if [ -n "$CI_COMMIT_TAG" ]; then
IMAGE_TAG="$CI_COMMIT_TAG"
else
IMAGE_TAG="sha-$CI_COMMIT_SHORT_SHA"
fi
IMAGE_URI="$HARBOR_REGISTRY/$HARBOR_PROJECT/$IMAGE_NAME:$IMAGE_TAG"
echo "IMAGE_TAG=$IMAGE_TAG"
echo "IMAGE_URI=$IMAGE_URI"
docker build --pull=false -t "$IMAGE_URI" .
docker push "$IMAGE_URI"
echo "IMAGE_TAG=$IMAGE_TAG" > build.env
echo "IMAGE_URI=$IMAGE_URI" >> build.env
artifacts:
reports:
dotenv: build.env
expire_in: 7 days
rules:
- if: '$CI_COMMIT_BRANCH == "master"'
- if: '$CI_COMMIT_TAG'
実装上の技術的要点
🛠️ 認証情報の秘匿化: echo “$HARBOR_PASSWORD” | docker login … –password-stdin を使用し、コマンドライン引数経由でのパスワード露出(プロセスツリーやRunnerログへの平文出力)を防止します。
⚙️ 動的タグ判定ロジック: リリースタグ発行時($CI_COMMIT_TAG)はそのタグ名をそのまま採用し、ブランチコミット時は sha-<短縮ハッシュ> 形式でユニークなイミュータブルタグを割り当てます。
⚠️ 外部通信抑制フラグ (–pull=false): 通常の docker build はローカルにキャッシュが存在してもリモートリポジトリへ最新レイヤーの問い合わせを行う挙動をとる場合があります。–pull=false を明示的に指定することで、閉域環境において不要な外部プローブ通信による遅延やタイムアウトエラーを完全に遮断します。
📦 下流パイプラインへの変数伝播: build.env ファイルに IMAGE_TAG と IMAGE_URI を出力し、GitLabの artifacts:reports:dotenv 機能を通じて後続のデプロイパイプライン(KubesprayのPlaybook実行ジョブ等)へ渡します。
統合設定ファイル (.gitlab-ci.yml)
全ジョブを統合した完全なパイプライン構成は以下の通りです。
stages:
- validate
- build
variables:
HARBOR_REGISTRY: "harbor.devstack.co.kr:8443"
HARBOR_PROJECT: "kubespray"
IMAGE_NAME: "nginx-app"
image: "$HARBOR_REGISTRY/$HARBOR_PROJECT/ci/docker:29.1.4-cli"
validate:dockerfile:
stage: validate
tags:
- docker
- offline
script:
- test -f Dockerfile
- grep -q "$HARBOR_REGISTRY" Dockerfile
- echo "Dockerfile validation passed"
build:push:
stage: build
tags:
- docker
- offline
before_script:
- docker version
- echo "$HARBOR_PASSWORD" | docker login "$HARBOR_REGISTRY" -u "$HARBOR_USER" --password-stdin
script:
- |
if [ -n "$CI_COMMIT_TAG" ]; then
IMAGE_TAG="$CI_COMMIT_TAG"
else
IMAGE_TAG="sha-$CI_COMMIT_SHORT_SHA"
fi
IMAGE_URI="$HARBOR_REGISTRY/$HARBOR_PROJECT/$IMAGE_NAME:$IMAGE_TAG"
echo "IMAGE_TAG=$IMAGE_TAG"
echo "IMAGE_URI=$IMAGE_URI"
docker build --pull=false -t "$IMAGE_URI" .
docker push "$IMAGE_URI"
echo "IMAGE_TAG=$IMAGE_TAG" > build.env
echo "IMAGE_URI=$IMAGE_URI" >> build.env
artifacts:
reports:
dotenv: build.env
expire_in: 7 days
rules:
- if: '$CI_COMMIT_BRANCH == "master"'
- if: '$CI_COMMIT_TAG'
Troubleshooting
閉域網環境のCI実行で発生しやすい代表的な障害要因と対処方法を記録します。
1. 非標準ポート(8443)でのTLS/x509証明書検証エラー
障害事象: Harborがポート8443を使用し、社内プライベート認証局(CA)による自己署名証明書で保護されている場合、docker login 実行時に以下のエラーが発生してジョブが停止します。
Error response from daemon: Get "https://harbor.devstack.co.kr:8443/v2/": x509: certificate signed by unknown authority
対処手順: Runnerホスト上のDockerデーモンに内部ルートCA証明書を配置します。Dockerは /etc/docker/certs.d/<レジストリホスト名:ポート>/ca.crt のパスを自動参照します。
sudo mkdir -p /etc/docker/certs.d/harbor.devstack.co.kr:8443
sudo cp /path/to/internal-ca.crt /etc/docker/certs.d/harbor.devstack.co.kr:8443/ca.crt
sudo systemctl restart docker
2. --pull=false 指定時におけるベースレイヤー消失エラー
障害事象: Dockerfile内のベースイメージがRunnerホストのローカルキャッシュに存在しない状態で –pull=false を指定すると、以下のようにビルドが失敗します。
ERROR: failed to solve: harbor.devstack.co.kr:8443/kubespray/base-nginx:1.25: not found: image not present locally and --pull=false set
対処手順: ジョブ実行前に必要なベースイメージをHarborから確実にローカルプールへフェッチする処理を before_script に追加するか、初回ビルド時に明示的なイメージ事前ロードを実施してください。
docker pull harbor.devstack.co.kr:8443/kubespray/base-nginx:1.25
実行検証ログ例
正常に動作したパイプラインノードにおける認証およびプッシュログの記録です。
$ docker version
Client:
Version: 29.1.4
API version: 1.47
Go version: go1.22.8
Git commit: 06f9d74
Built: Wed Nov 12 18:22:10 2026
OS/Arch: linux/amd64
Context: default
Server:
Engine:
Version: 29.1.4
API version: 1.47 (minimum version 1.12)
Go version: go1.22.8
Git commit: a3f9e2b
Built: Wed Nov 12 18:21:45 2026
OS/Arch: linux/amd64
Experimental: false
$ echo "$HARBOR_PASSWORD" | docker login "$HARBOR_REGISTRY" -u "$HARBOR_USER" --password-stdin
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded
$ IMAGE_TAG="sha-3b8c1a9e"
$ IMAGE_URI="harbor.devstack.co.kr:8443/kubespray/nginx-app:sha-3b8c1a9e"
$ docker build --pull=false -t "$IMAGE_URI" .
[+] Building 1.2s (6/6) FINISHED
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 312B
=> [internal] load metadata for harbor.devstack.co.kr:8443/kubespray/base-nginx:1.25
=> [1/2] FROM harbor.devstack.co.kr:8443/kubespray/base-nginx:1.25
=> [2/2] COPY ./html /usr/share/nginx/html
=> exporting to image
=> => exporting layers
=> => writing image sha256:7f4a21e69b0dc881cb31e5f84918e9c60e42fbe5aa65825cfd9d06b12a8ff93a
=> => naming to harbor.devstack.co.kr:8443/kubespray/nginx-app:sha-3b8c1a9e
$ docker push "$IMAGE_URI"
The push refers to repository [harbor.devstack.co.kr:8443/kubespray/nginx-app]
3f8b091fca1e: Pushed
e6b8b0934c22: Layer already exists
sha-3b8c1a9e: digest: sha256:4d7b29a28e7529841f4812a0f6b3e9491ac9480dcbe82f8a50f3b4dc36f018e6 size: 739
Operational Notes
🛠️ GitLab Runnerのタグ管理: 閉域環境のRunnerには必ず docker および offline のタグを付与し、インターネット接続可能な共用Runnerへビルド要求がルーティングされないよう分離を維持してください。
⚠️ dotenvアーティファクトの有効期限: expire_in: 7 days を設定しているため、7日以上経過した過去ジョブのメタデータを再参照するパイプラインを組む場合は、外部KeyValueストアへの保管やGitコミットへのコミットバック機構を検討する必要があります。
💡 Harbor側のクォータ管理: Kubesprayプロジェクトではタグなし中間レイヤーや古いコミットSHAイメージが蓄積しやすいため、Harbor側でタグ保持ポリシー(例: 直近20タグ保持、あるいは一定期間経過後の自動クリーンアップ)を設定しておく必要があります。