본문 바로가기
WIKI 기술 지식 베이스

소스 코드에서 Crossplane 설치하기

원문 보기 위키 갱신

소스 코드에서 Crossplane 설치하기 (Install from Source)

소스 코드에서 Crossplane을 빌드하면 빌드 및 설치 과정을 완전히 제어할 수 있어요. Crossplane 컨테이너 이미지와 Helm 차트를 소스 코드에서 직접 빌드하고, 이미지를 자신의 레지스트리에 푸시한 뒤, 자신의 Kubernetes 클러스터에 설치할 수 있어요.

중요: 소스에서 Crossplane을 설치하는 것은 빌드·배포 과정을 완전히 제어해야 하는 사용자를 위한 고급 설치 경로예요. 대부분의 사용자는 표준 설치 지침을 따라야 해요.

이 방식은 다음과 같은 상황에서 유용해요:

  • 전체 빌드·배포 파이프라인을 제어하고 싶을 때
  • 자신의 컨테이너 레지스트리와 클러스터를 사용하고 싶을 때
  • 오프라인 또는 제한된 환경에 배포할 때
  • 특정 커밋이나 브랜치에서 빌드할 때

출처: 문서

본문

사전 요구 사항

소스에서 Crossplane을 빌드하려면 다음이 필요해요:

  • flakes가 활성화된 Nix
  • Docker
  • 대상 클러스터용으로 구성된 kubectl
  • 적극적으로 지원되는 Kubernetes 버전
  • Helm 버전 v3.2.0 이상
  • 컨테이너 레지스트리 접근 (Docker Hub, GHCR, Harbor 또는 OCI 호환 레지스트리)

Crossplane은 빌드 시스템으로 Nix를 사용해요. Nix는 시스템 Go 툴체인이나 기타 언어별 종속성 없이도 재현 가능하고 샌드박스 처리된 빌드를 생성해요.

팁: Nix를 설치할 수 없다면 Crossplane 저장소에 Docker 컨테이너 안에서 Nix를 실행하는 ./nix.sh 래퍼가 포함되어 있어요. 이 가이드에서 nix 를 사용하는 곳마다 ./nix.sh 로 대체하세요. 래퍼는 자격 증명 처리와 빌드 산출물 영속성에 몇 가지 제한이 있으므로 Nix를 네이티브로 설치하는 것이 권장 돼요.

Crossplane 저장소 복제

Crossplane 저장소를 복제하고 선택적으로 특정 릴리스를 체크아웃하세요.

git clone https://github.com/crossplane/crossplane.git
cd crossplane

팁: 특정 릴리스를 빌드하려면 빌드 전에 릴리스 태그를 체크아웃하세요.

git checkout v2.0.2

산출물 대상 결정

빌드한 소프트웨어 산출물을 푸시할 레지스트리와 버전 태그를 정하고 환경 변수에 저장하세요:

export REGISTRY="your-registry.com/your-org"; \
  export VERSION="v2.0.0-yourtag"

${VERSION}은 vMAJOR.MINOR.PATCH[-suffix] 형식을 따라야 해요(예: v2.0.0-yourtag).

빌드는 ${VERSION}을 Crossplane 바이너리에 내장하고 이를 컨테이너 이미지 태그 및 Helm 차트 버전으로 사용해요. Nix의 샌드박스 빌드는 git이 추적하는 파일만 읽으므로, 빌드 전에 ${VERSION}을 flake.nix에 기록해야 해요:

sed -i "s|buildVersion = null;|buildVersion = \"${VERSION}\";|" flake.nix

팁: macOS에서는 sed -i 대신 sed -i ''를 사용하세요:

sed -i '' "s|buildVersion = null;|buildVersion = \"${VERSION}\";|" flake.nix

산출물 빌드

지원되는 모든 플랫폼용으로 Crossplane 바이너리, 컨테이너 이미지, Helm 차트를 빌드하세요:

nix build

첫 실행은 빌드 툴체인을 다운로드하므로 몇 분 걸려요. 이후 실행은 Nix 저장소 캐시를 재사용해 몇 초 내에 완료돼요.

빌드 출력은 ./result/ 아래에 있어요:

  • result/bin/에는 지원되는 각 플랫폼용 crossplane과 crank 바이너리가 들어 있어요.
  • result/charts/crossplane-<version>.tgz는 Helm 차트예요.
  • result/images/linux_<arch>/image.tar.gz는 각 지원 Linux 아키텍처용 컨테이너 이미지 타르볼이에요.

빌드는 로컬 Docker 데몬에 이미지를 로드하지 않아요. 푸시 단계에서 result/images/의 이미지 타르볼을 자동으로 로드해요.

이미지를 레지스트리에 푸시

중요: 레지스트리에 인증이 필요하면 푸시 전에 docker login으로 로그인하세요.

단일 명령으로 아키텍처별 이미지를 푸시하고 멀티 아키텍처 매니페스트를 구성하세요:

nix run .#push-images -- ${REGISTRY}/crossplane

참고: 호스트 Docker가 자격 증명 헬퍼(예: macOS의 Docker Desktop)를 사용한다면, nix run .#push-images가 사용하는 샌드박스 PATH에는 해당 헬퍼가 없어요. 임시 Docker 구성에 인증을 직접 작성해 로그인·푸시 시 헬퍼를 우회하세요:

export DOCKER_CONFIG=$(mktemp -d)
cat > $DOCKER_CONFIG/config.json ...

이 단계는 각 아키텍처 이미지 타르볼을 로드하고, ${REGISTRY}/crossplane:${VERSION}-<arch>로 태그한 뒤 푸시하고, 마지막으로 ${REGISTRY}/crossplane:${VERSION}에 멀티 아키텍처 매니페스트를 생성·푸시해요.

커스텀 이미지로 Crossplane 설치

빌드한 Helm 차트와 커스텀 이미지를 사용해 클러스터에 Crossplane을 설치하세요:

helm install crossplane result/charts/crossplane-${VERSION#v}.tgz \
  --namespace crossplane-system \
  --create-namespace \
  --set image.repository=${REGISTRY}/crossplane \
  --set image.tag=${VERSION} \
  --set image.pullPolicy=IfNotPresent

중요: 레지스트리에 인증이 필요하면 설치 전에 imagePullSecret을 생성하세요.

kubectl create secret docker-registry regcred \
  --docker-server=${REGISTRY} \
  --docker-username=<사용자> \
  --docker-password=<비밀번호> \
  --namespace crossplane-system

helm install 명령에 시크릿 참조를 추가하세요.

--set imagePullSecrets[0].name=regcred

설치 확인

kubectl get pods로 설치된 Crossplane 파드를 확인하세요.

kubectl get pods -n crossplane-system
NAME                                       READY   STATUS    RESTARTS   AGE
crossplane-5644774bd4-zvcwc                1/1     Running   0          72s
crossplane-rbac-manager-84dc89c564-b9x6q   1/1     Running   0          72s

Crossplane 배포가 커스텀 이미지를 사용 중인지 확인하세요.

kubectl get deployment crossplane -n crossplane-system -o jsonpath='{.spec.template.spec.containers[0].image}'
your-registry.com/your-org/crossplane:v2.0.0-yourtag

선택 사항: Crossplane CLI 설치

crossplane CLI는 Crossplane 리소스를 관리하기 위한 명령을 제공해요. 앞선 빌드 단계에서 이미 모든 지원 플랫폼용 CLI 바이너리(crank라는 이름)를 result/bin/ 아래에 생성했어요. 사용자 시스템용 바이너리를 PATH로 복사하세요.

macOS ARM64의 경우:

sudo cp result/bin/darwin_arm64/crank /usr/local/bin/crossplane
chmod +x /usr/local/bin/crossplane

Linux AMD64의 경우:

sudo cp result/bin/linux_amd64/crank /usr/local/bin/crossplane
chmod +x /usr/local/bin/crossplane

설치를 확인하세요.

crossplane version
v2.0.0-yourtag

작업 트리 정리

앞선 sed 단계가 git이 추적하는 flake.nix 파일을 수정했어요. 모든 빌드·푸시·설치 단계가 끝난 뒤 변경을 되돌려 작업 트리를 깨끗하게 유지하세요:

git checkout flake.nix

푸시 또는 설치 단계를 마치기 전에 이 파일을 되돌리면 Nix가 buildVersion = null로 플레이크를 다시 빌드하므로, 이미 빌드한 산출물과 일치하지 않는 다른 버전이 생성돼요.

더 알아보기 (Learn more)