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

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

kaniko는 Docker 파일 내에서 컨테이너나 Kubernetes 클러스터 내에서 컨테이너 이미지를 빌드하기 위한 도구입니다.

kaniko는 다음과 같은 두 가지 문제를 해결합니다. - Docker-in-Docker 빌드 메서드(Docker-in-Docker build)를 사용하는 것과 관련된 권한 부여 모드가 필요한데, 이는 중요한 보안 문제입니다. - Docker-in-Docker는 일반적으로 성능 저하가 발생하며 상당히 느릴 수 있습니다.

준비 사항

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

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

GitLab CI/CD에서 이미지를 빌드할 때, 몇 가지 중요한 사항을 고려해야 합니다.

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

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

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

해당 작업은 태그가 푸시될 때에만 실행됩니다. config.json 파일은 GitLab CI/CD에서 제공하는 사전 정의된 CI/CD 변수에서 필요한 GitLab 컨테이너 레지스트리 자격 증명을 가져와 자동으로 Kaniko 도구에서 읽습니다. 마지막 단계에서 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

작동 예제의 비디오 안내

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

이 예제는 귀하의 그룹이나 인스턴스로 복사하여 테스트할 수 있습니다. 기타 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

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

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