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를 사용하려면 다음 실행자 중 하나를 가진 러너가 필요합니다:

kaniko로 Docker 이미지 빌드하기

kaniko와 GitLab CI/CD를 사용하여 이미지를 빌드할 때는
몇 가지 중요한 세부사항을 알아야 합니다:

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

다음 예제에서는 kaniko를 사용하여:

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

작업은 태그가 푸시될 때만 실행됩니다.
필요한 GitLab 컨테이너 레지스트리 자격 증명이 포함된 config.json 파일이
/kaniko/.docker 아래에 생성됩니다.
이 자격 증명은 정의된 CI/CD 변수에서 가져옵니다.
이 변수들은 Kaniko 도구가 자동으로 읽습니다.

마지막 단계에서는, 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을 제거하므로
이미지를 참조할 때 이를 포함하지 않아도 됩니다.

프록시 뒤에서 카니코로 이미지 빌드하기

http(s) 프록시 뒤에 있는 맞춤형 GitLab Runner를 사용하는 경우, 카니코를 적절하게 설정해야 합니다. 이는 다음을 의미합니다:

  • 이미지 빌드 시 Dockerfile 지침이 프록시를 사용할 수 있도록 http_proxy 환경 변수를 빌드 인수로 전달합니다.

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

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

이는 CA의 인증서를 카니코 인증서 저장소에 추가하여 해결할 수 있습니다:

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

작동 예제 비디오 워크스루

GitLab에서 Kaniko로 최소 권한 컨테이너 빌드 비디오는 Kaniko Docker Build 가이드 탐색 프로젝트 파이프라인에 대한 워크스루입니다. 다음에서 테스트되었습니다:

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

문제 해결

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

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

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

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

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

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

kaniko는 컨테이너 내에서만 실행되어야 하며, 계속 진행할 것인지 확신하는 경우 --force 플래그로 실행하세요.

이 문제를 해결하려면 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의 업그레이드를 작업에 투명하게 만듭니다.