kaniko를 사용하여 Docker 이미지 빌드하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

kaniko는 컨테이너 내부 또는 Kubernetes 클러스터에서 Dockerfile을 사용하여 컨테이너 이미지를 빌드하는 도구입니다.

전제 조건

GitLab에서 kaniko를 사용하려면 다음 실행자 중 하나를 사용하는 러너(runner)가 필요합니다:

kaniko를 사용하여 Docker 이미지 빌드

kaniko 및 GitLab CI/CD를 사용하여 이미지를 빌드할 때 몇 가지 중요한 세부 사항을 인식해야 합니다:

  • kaniko 디버그 이미지(gcr.io/kaniko-project/executor:debug) 사용을 권장합니다. 이는 GitLab CI/CD에서 이미지를 사용하려면 셸이 필요하기 때문입니다.
  • entrypoint는 재정의되어야 합니다. 그렇지 않으면 빌드 스크립트가 실행되지 않습니다.

다음 예에서 kaniko는 다음을 수행합니다:

  1. Docker 이미지를 빌드합니다.
  2. 그런 다음 해당 이미지를 GitLab 컨테이너 레지스트리에 푸시합니다.

작업은 태그가 푸시될 때에만 실행됩니다. config.json 파일은 프로젝트의 루트 디렉터리 아래 /kaniko/.docker에 만들어지며, GitLab CI/CD에서 제공하는 사전 정의 CI/CD 변수에서 필요한 GitLab 컨테이너 레지스트리 자격 증명을 자동으로 읽습니다. 마지막으로 kaniko는 프로젝트의 루트 디렉터리 아래의 Dockerfile을 사용하여 Docker 이미지를 빌드하고 해당 이미지를 프로젝트의 컨테이너 레지스트리에 푸시하면서 해당 이미지를 Git 태그로 태깅합니다. 

build:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:v1.14.0-debug
    entrypoint: [""]
  script:
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_TAG}"
  rules:
    - if: $CI_COMMIT_TAG

의존성 프록시에 대한 인증을 수행하는 경우, 해당 인증을 config.json 파일에 추가해야 합니다: 

- echo "{\"auths\":{\"${CI_REGISTRY}\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$(echo -n $CI_DEPENDENCY_PROXY_SERVER | awk -F[:] '{print $1}')\":{\"auth\":\"$(printf "%s:%s" ${CI_DEPENDENCY_PROXY_USER} "${CI_DEPENDENCY_PROXY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json

이 명령은 CI_DEPENDENCY_PROXY_SERVER에서 포트(예: :443)를 제거하여 이미지를 참조할 때 포트를 포함하지 않아도 되도록 합니다.

프록시 뒤에 있는 kaniko를 사용하여 이미지 빌드

사용자 지정 GitLab 러너가 http(s) 프록시 뒤에 있는 경우, kaniko를 해당 설정에 맞게 설정해야 합니다. 즉,

  • 빌드 명령에서 http_proxy 환경 변수를 전달하여 Dockerfile 명령이 이미지를 빌드할 때 프록시를 사용할 수 있도록 합니다.

이전 예제는 다음과 같이 확장할 수 있습니다: 

build:
  stage: build
  variables:
    http_proxy: <your-proxy>
    https_proxy: <your-proxy>
    no_proxy: <your-no-proxy>
  image:
    name: gcr.io/kaniko-project/executor:v1.14.0-debug
    entrypoint: [""]
  script:
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --build-arg http_proxy=$http_proxy
      --build-arg https_proxy=$https_proxy
      --build-arg no_proxy=$no_proxy
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_TAG}"
  rules:
    - if: $CI_COMMIT_TAG

다중 아키텍처 이미지 빌드

manifest-tool을 사용하여 컨테이너 내에서 다중 아키텍처 이미지를 빌드할 수 있습니다.

다중 아키텍처 이미지를 빌드하는 자세한 가이드는 권한 없는 컨테이너에서 다중 아키텍처 컨테이너 이미지 빌드를 참조하세요.

사용자 정의 인증서가 있는 레지스트리 사용

사용자 정의 CA로 서명된 인증서를 사용하는 Docker 레지스트리에 푸시하려고 할 때 다음 오류가 발생할 수 있습니다: 

$ /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --no-push
INFO[0000] Downloading base image registry.gitlab.example.com/group/docker-image
error building image: getting stage builder for stage 0: Get https://registry.gitlab.example.com/v2/: x509: certificate signed by unknown authority

이를 해결하기 위해 kaniko 인증서 리포지터리에 해당 CA의 인증서를 추가해야 합니다: 

before_script:
  - |
    echo "-----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----" >> /kaniko/ssl/certs/ca-certificates.crt

작동하는 예제의 비디오 안내

GitLab의 Kaniko를 사용한 최소 권한 컨테이너 빌드 비디오는 Kaniko Docker 빌드 안내 탐색 프로젝트 파이프라인의 안내 내용입니다. 이는 다음에서 테스트되었습니다:

이 예제는 테스트를 위해 사용자의 그룹 또는 인스턴스로 복사할 수 있습니다. 프로젝트 페이지에서 더 자세한 GitLab CI 패턴을 확인할 수 있습니다.

문제 해결

403 오류: “푸시 권한 확인 오류”

이 오류가 발생하면 외부 프록시 때문일 수 있습니다. http_proxy와 https_proxy 환경 변수를 설정하면 문제가 해결될 수 있습니다.

오류: kaniko should only be run inside of a container, run with the --force flag if you are sure you want to continue

Docker Engine 20.10에서 소개된 알려진 호환성 문제가 있습니다.

호스트가 Docker Engine 20.10 이상을 사용하는 경우, 버전 v1.9.0 이전의 gcr.io/kaniko-project/executor:debug 이미지는 예상대로 작동하지 않습니다.

이미지를 빌드하려고 하면 Kaniko가 다음과 같이 실패합니다. 

kaniko should only be run inside of a container, run with the --force flag if you are sure you want to continue

이 문제를 해결하려면 gcr.io/kaniko-project/executor:debug 컨테이너를 v1.9.0 이상의 버전으로 업데이트하세요. 예를 들어 gcr.io/kaniko-project/executor:v1.14.0-debug입니다.

반대 구성(호스트의 Docker Engine 버전이 19.06.x 또는 이전이고 gcr.io/kaniko-project/executor:v1.14.0-debug 이미지를 사용하는 경우)은 문제없이 작동합니다. 가장 좋은 전략은 작업 환경 버전을 자주 테스트하고 업데이트하여 가능한 최신으로 유지하는 것입니다. 이렇게 하면 새로운 기능을 제공하고 보안을 개선하며 특정 사례(이 경우)에서는 러너 호스트의 기본 Docker Engine을 업그레이드해도 작업에 대해 투명하게 유지되게 합니다.