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

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

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

kaniko는 Docker-in-Docker 빌드 방법의 두 가지 문제를 해결합니다.

  • Docker-in-Docker는 기능을 위해 특권 모드를 필요로 하며, 이는 상당한 보안 문제입니다.
  • Docker-in-Docker는 일반적으로 성능 저하를 유발하고 매우 느릴 수 있습니다.

전제 조건

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

kaniko로 Docker 이미지 빌드하기

kaniko 및 GitLab CI/CD를 사용하여 이미지를 빌드할 때 몇 가지 중요한 사항을 고려해야 합니다.

  • kaniko 디버그 이미지(gcr.io/kaniko-project/executor:debug)를 권장합니다. 이미지에 셸이 있어야 하며, 셸은 GitLab CI/CD와 함께 사용되기 때문입니다.
  • 엔트리포인트는 덮어씌우기(override)해야 합니다. 그렇지 않으면 빌드 스크립트가 실행되지 않습니다.

다음 예시에서 kaniko를 사용하여 다음을 수행합니다.

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

작업은 태그가 푸시될 때에만 실행됩니다. config.json 파일은 자동으로 Kaniko 도구에서 필요한 GitLab 컨테이너 레지스트리 자격 증명을 가져와 /kaniko/.docker에 생성됩니다. 이는 GitLab CI/CD에서 자동으로 읽힙니다.

마지막 단계에서 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

의존성 프록시에 대해 인증하는 경우 해당하는 CI/CD 변수를 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를 이에 맞게 설정해야 합니다.

  • 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.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 빌드 Guided Exploration 프로젝트 파이프라인을 안내합니다. 이는 다음에서 테스트되었습니다.

이 예시는 테스트를 위해 사용자의 그룹이나 인스턴스로 복사할 수 있습니다. 프로젝트 페이지에서 무엇을 더 자세히 확인할 수 있는지에 대한 추가 정보가 있습니다.

문제 해결

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

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

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

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 버전)는 문제없이 작동합니다. 가장 좋은 전략은 전반적으로 환경 버전을 자주 테스트하고 업데이트함으로써 새로운 기능과 향상된 보안, 특히 특정 사례에서 호스트의 Docker Engine 업그레이드를 작업에 대해 투명하게 만드는 것입니다.