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

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

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

kaniko는 다음과 같은 두 가지 문제를 해결합니다. Docker-in-Docker 빌드 방식에서 발생하는 다음과 같은 문제점 때문에 사용됩니다:

  • Docker-in-Docker는 기능을 사용하기 위해 중요한 보안 문제인 권한 부여 모드를 필요로 합니다.
  • Docker-in-Docker는 일반적으로 성능에 부정적인 영향을 미치고 상당히 느릴 수 있습니다.

사전 조건

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

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

kaniko와 GitLab CI/CD로 이미지를 빌드할 때 몇 가지 중요한 사항을 알고 있어야 합니다.

  • kaniko 디버그 이미지 (gcr.io/kaniko-project/executor:debug)를 권장합니다. 이는 이미지가 GitLab CI/CD와 함께 사용되기 위해 셸이 필요하기 때문입니다.
  • 엔트리 포인트를 재정의해야 하는데, 그렇지 않으면 빌드 스크립트가 실행되지 않습니다.

다음 예제에서는 kaniko를 사용하여 다음을 수행합니다. 1. Docker 이미지를 빌드합니다. 1. 그런 다음 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.23.2-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 파일에 인증을 위한 해당 CI/CD 변수를 추가해야 합니다. 

- 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)를 제거하므로 이미지를 참조할 때 이를 포함할 필요가 없습니다.

proxy 뒤에 있는 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.23.2-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

작동 예제의 비디오 안내

Least Privilege Container Builds with Kaniko on GitLab 동영상은 Kaniko Docker Build 가이드 탐색 프로젝트 파이프라인에 대한 안내입니다. 이는 다음에서 테스트되었습니다.

이 예제는 자체 그룹이나 인스턴스로 복사하여 테스트할 수 있습니다. 프로젝트 페이지에서 무엇이 또 다른 GitLab CI 패턴을 데모하는지에 대한 자세한 내용을 확인할 수 있습니다.

문제 해결

403 오류: “push 권한 확인 오류”

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

오류: kaniko는 컨테이너 내에서만 실행되어야 합니다

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

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

이미지를 빌드하려고 하면 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.23.2-debug처럼 사용합니다.

반대 구성(gcr.io/kaniko-project/executor:v1.23.2-debug 이미지 및 호스트에서 Docker Engine의 버전이 19.06.x 이하)은 문제없이 작동합니다. 최상의 전략으로, 새로운 기능을 가져오고, 개선된 보안을 제공하며, 특히 이 경우에는 러너 호스트의 기밀 Docker Engine을 업그레이드하기 쉽도록 하는 가장 최신 버전의 작업 환경을 자주 테스트하고 업데이트해야 합니다.