로컬에서 빌드 및 디버깅

이 페이지에서는 로컬 머신에서 Cloud Build를 사용하는 방법을 설명합니다. 로컬 빌더를 사용하여 다음을 수행할 수 있습니다.

  • 로컬 머신에서 빌드를 더 빠르게 반복할 수 있습니다.
  • 연습 실행을 사용하여 구성 파일을 lint 할 수 있습니다.

로컬 빌더는 Linux 또는 macOS에서만 빌드할 수 있습니다.

시작하기 전에

  1. Google Cloud CLI를 설치하고 초기화합니다.

  2. Docker를 설치합니다. Cloud Build와 동일한 Docker 버전을 사용하는 것이 가장 좋습니다.

  3. 빌드할 소스 코드, 빌드용 빌드 구성 파일, 로컬 머신에서 빌드 단계에 필요한 모든 도구와 종속 항목에 액세스할 수 있는 권한이 필요합니다.

  4. 빌드에 비공개 레지스트리에 대한 액세스 권한이 필요하다면 다음 명령어를 실행하여 Cloud Build용 Docker 사용자 인증 정보 도우미를 설치하고 구성합니다.

    gcloud components install docker-credential-gcr
    gcloud auth configure-docker
    

로컬 빌더 설치

로컬 빌더는 Google Cloud CLI의 gcloud CLI 구성요소입니다. 시스템에 따라 gcloud 명령어, apt-get 또는 yum을 사용하여 설치할 수 있습니다.

로컬 빌더를 설치하려면 다음 명령어를 실행하세요.

gcloud

gcloud components install cloud-build-local

apt-get

sudo apt-get install google-cloud-sdk-cloud-build-local

yum

sudo yum install google-cloud-sdk-cloud-build-local

로컬 빌더가 설치된 후

  • 명령줄 도움말을 보려면 다음 명령어를 실행하세요.

    cloud-build-local --help
    
  • 설치된 로컬 빌더의 버전을 보려면 다음 명령어를 실행하세요.

    cloud-build-local --version
    

로컬에서 빌드

경고: 로컬 머신에서 한 번에 한 빌드만 실행하세요. 여러 빌드를 동시에 실행하면 로컬 빌더가 실패하게 됩니다.

아직 설정된 프로젝트가 없으면 빠른 시작의 구성을 사용하여 로컬 빌더를 테스트할 수 있습니다.

로컬에서 빌드하려면 다음 명령어를 실행하세요.

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

각 항목의 의미는 다음과 같습니다.

  • [BUILD_CONFIG]빌드 구성 파일의 경로와 이름입니다.
    • 예를 들어 구성 파일이 작업 디렉터리에 있고 이름이 cloudbuild.json이면 --config=cloudbuild.json 플래그를 사용합니다.
    • 기본값이 cloudbuild.yaml이므로, 파일이 작업 디렉터리에 있고 이름이 cloudbuild.yaml이면 이 플래그를 추가할 필요가 없습니다.
  • [SOURCE_CODE]는 소스 코드의 경로입니다.
    • Cloud Build와 마찬가지로 현재 작업 디렉터리에 소스 코드가 있을 경우 소스에 .를 사용할 수 있습니다.
    • 빌드에 소스 코드가 필요하지 않으면 [SOURCE_CODE] 위치에 --no-source 플래그를 사용합니다.
  • --dryrun=false를 사용하면 빌드 실행이 허용됩니다. --dryrun 플래그는 기본적으로 true입니다. 기본값으로 실행하면 구성 파일이 lint 되지만 빌드 명령어는 실행되지 않습니다. 빌드를 실행하려면 --dryrun=false를 명시적으로 설정해야 합니다.
  • --push는 결과 이미지 또는 아티팩트를 구성 파일에서 images 또는 artifacts 필드로 정의된 대상으로 푸시합니다. 기본적으로 이미지 및 아티팩트가 빌드되지만 푸시되지는 않습니다.

빌드가 완료되면 Docker를 통해 로컬 머신에서 생성된 이미지를 사용할 수 있습니다. 빌드 명령어에 --push를 추가한 경우 지정된 저장소에서 사용 가능합니다.

중간 아티팩트 보존

빌드 중에 workspace라는 디렉터리에 중간 아티팩트가 배치됩니다. 기본적으로 빌더는 빌드가 끝날 때 작업공간과 그 내용을 삭제합니다.

빌드를 실행하고 작업공간에서 아티팩트를 보존하려면 다음 명령어를 실행하세요.

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

각 항목의 의미는 다음과 같습니다.

  • [BUILD_CONFIG]는 구성 파일의 경로입니다.
  • [SOURCE_CODE]는 소스 코드의 경로입니다.
  • [LOCAL_DIRECTORY_PATH]는 로컬 머신에서 작업공간을 저장할 로컬 디렉터리입니다. 이 디렉터리는 [SOURCE_CODE] 디렉터리 외부에 있어야 합니다.

작업공간을 유지하면 다음을 수행할 수 있습니다.

  • 빌드를 디버깅할 때 중간 아티팩트를 분석합니다.
  • 빌더가 작업공간에서 만든 빌드 결과(예: 바이너리)에 액세스합니다.

빌드에 substitutions 사용

빌드에 대체 항목을 사용하려면 대체하려는 key=value 쌍과 함께 --substitutions 플래그를 사용합니다. 특정 기본 변수와 정의된 변수의 값을 지정할 수 있습니다.

예를 들면 다음과 같습니다.

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

각 항목의 의미는 다음과 같습니다.

  • [BUILD_CONFIG]는 구성 파일의 경로입니다.
  • [SOURCE_CODE]는 소스 코드의 경로입니다.
  • 이 예시에서 _KEYvalue로 대체되고 _FOOfoo로 대체됩니다.

필요한 구문을 포함하여 substitutions에 대한 자세한 내용은 substitutions를 참조하세요.

로컬에서 빌드 디버그

빌드를 디버깅하려면 다음을 수행하면 됩니다.

  • 빌드 연습 실행을 수행하여 구성 파일이 올바른지 확인합니다.
  • 빌드 중에 작업공간에서 생성된 중간 아티팩트를 검사합니다. 이렇게 하려면 위의 중간 아티팩트 보존을 참조하세요.

로컬 빌드는 실행 시 로컬 호스트에서 사용 가능한 권한으로 실행됩니다. Cloud Build에서 빌드 단계는 프로젝트 서비스 계정의 권한으로 실행됩니다. 권한 문제를 디버깅하는 경우 로컬 빌드가 Cloud Build 환경과 최대한 가까운 환경에 있도록 Cloud Build 서비스 계정의 권한과 일치하도록 권한을 설정하세요.

연습 실행으로 빌드 확인

빌드 연습 실행을 수행하면 구성 파일이 lint 되고 문제가 발견될 경우 오류가 발생합니다. 연습 실행으로 빌드가 실행되는 것은 아니므로 빌드 실행에 대한 부담 없이 구성 파일을 확인할 수 있습니다. 로컬 빌더를 사용하는 것이 빌드 연습 실행을 수행하는 유일한 방법입니다.

  1. 다음 명령어를 사용하여 빌드 연습 실행을 수행합니다.

    cloud-build-local --config=[BUILD_CONFIG] [SOURCE_CODE]
    

    각 항목의 의미는 다음과 같습니다.

    • [BUILD_CONFIG]는 구성 파일의 경로입니다.
    • [SOURCE_CODE]는 소스 코드의 경로입니다.
  2. 오류 메시지를 살펴보고 구성 파일의 모든 문제를 해결합니다.

제한

  • 로컬 빌더는 Linux 또는 macOS에서만 빌드할 수 있습니다.
  • 로컬 빌더는 주어진 호스트에서 한 번에 하나의 빌드를 실행합니다. 여러 빌드를 동시에 실행하면 로컬 빌더가 실패하게 됩니다.
  • 로컬 빌더는 호스팅된 Cloud Build 서비스에서 100% 기능 패리티를 지원하지 않습니다. 로컬 빌더에서 지원되지 않는 기능 예시는 다음과 같습니다.
    • 동적 대체 항목
    • 비공개 풀

로컬 빌더와 Cloud Build의 차이점

로컬 빌더는 Cloud Build를 모방하도록 설계되었지만 완전히 상호 운용이 가능하지는 않습니다. 로컬 빌더에서 성공적으로 실행되는 빌드는 Cloud Build에서 비슷한 동작으로 실행되지만 어느 방향에서든 호환성이 보장되지는 않습니다. 로컬 빌더에 구현되지 않았지만 Cloud Build에서 지원되는 기능도 있습니다.

두 빌더 간의 환경적 차이점은 다음과 같습니다.

  • 로컬 빌더는 로컬 머신에서 실행되고, Cloud Build는 Google Cloud Platform에서 실행됩니다.
  • 빌드를 실행하기 위해 로컬 빌더는 개인 계정을 사용하고, Cloud Build는 cloudbuild 서비스 계정 [PROJECT_ID]@cloudbuild.gserviceaccount.com을 사용합니다. 로컬 빌더의 개인 계정에 대한 권한을 설정하는 경우 이러한 권한을 cloudbuild 서비스 계정에 복제하는 것이 좋습니다. 자세한 내용은 서비스 계정 권한 설정을 참조하세요.
  • 빌더가 사용하는 Docker 버전은 다를 수 있습니다. 로컬 빌더는 실행 중에 설치된 Docker 버전이 Cloud Build에서 사용되는 것과 다를 때마다 경고를 출력합니다. Cloud Build에서 사용하는 것과 동일한 Docker 버전을 사용하는 것이 가장 좋습니다.

다음 단계