Harbor 스택 — 하나의 release로 배포되는 컨테이너 레지스트리
이 예제는 Developer가 작성한 하나의 Aggregate로부터 실제 컨테이너 레지스트리를
Kubernetes 매니페스트로 컴파일합니다.
컨테이너 레지스트리는 여러 서비스가 협력하는 구조입니다. API와 토큰 서비스로 이루어진 컨트롤 플레인, OCI blob 저장소와 그 컨트롤러, 웹 콘솔, 비동기 워커 계층, 취약점 스캐너, 관계형 백엔드, 키-값 캐시, 그리고 이들 앞단의 리버스 프록시가 있습니다. 카탈로그는 이 모두를 하나의 Component로 기술합니다. 레지스트리의 메인테이너가 서비스에 필요한 순서대로 전체를 하나의 release로 배포하는 Helm 차트를 직접 배포하기 때문입니다. Component는 레지스트리를 선언하고, Recipe는 그 차트를 감쌉니다.
레지스트리는 모듈로 가져옵니다. 모듈은 Component를 구성하고 그 게시된 주소를 내보내는 재사용 가능한 하위 aggregate입니다. 최상위 Aggregate는 이름으로 모듈을 가져와 레지스트리의 키 세 개를 전달하며, 운영자는 Release에서 모듈의 component 크기를 지정합니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer 의도: 컨테이너 레지스트리 모듈(core/harbor)을 가져오고, 자체 parameters에서 레지스트리의 키 세 개를 모듈에 전달합니다. |
manifest-helm-synth.yaml | 레지스트리의 component 유형을 해당 Helm 차트를 감싸는 Recipe에 매핑하고, 자격 증명 Feature를 네임스페이스에 이미 있는 Secret을 읽는 구현에 매핑합니다. 단, 관리자 비밀번호는 예외로, 모듈의 parameter에서 Secret을 생성하는 구현에 이름으로 바인딩합니다. |
release-helm-synth.yaml | Kubernetes 대상을 위한 운영자 레코드입니다. Aggregate가 전달하는 세 키를 담은 Secret의 이름을 지정하고, 모듈 범위 ID로 모듈의 component 크기를 정하며, 토큰 서명 키, 서비스 공유 시크릿, 저장된 자격 증명을 암호화하는 키를 각각 담은 Secret의 이름을 지정하여 이를 해당 component에 연결합니다. 그 밖의 모든 것은 스키마 기본값에 맡깁니다. |
보여 주는 내용
- 하나의 Component로 구성된 다중 서비스 제품. 레지스트리를 여러 개가 아닌 하나의 Component로 만드는 것은 크기가 아니라 배선이 유지되는 위치입니다. 리버스 프록시 라우팅, 컨트롤 플레인이 모든 pull과 push를 검증하는 토큰 서비스 키, 각 서비스가 백엔드와 캐시에 대해 읽는 연결 설정, 서비스들의 캐시 키스페이스를 분리하는 논리 데이터베이스 분할, 시작 순서 — 이 모두를 제품을 출시하는 사람들이 차트 안에서 제품과 맞춰 유지합니다. 소비자는 레지스트리를 선언하면 서로 일치하는 이 설정들을 얻습니다.
- 래핑된 차트. Recipe는
source:에 차트를 지정하고 그 위에valuesMapping:을 덧씌웁니다. values 템플릿이 구현의 전부이며, Helm provider가 이를 기준으로 차트 자체의 템플릿을 렌더링합니다. 여기서는 workload를 합성하지 않습니다. - 고정된 외부 입력. 차트는 빌드가 가져오는 입력이므로 다른 의존성과 마찬가지로
고정됩니다. lockfile은
source_artifacts아래에 차트의 버전, 확인된 URL, tarball의 다이제스트를 기록합니다. 채워진 lockfile로 실행하는 빌드는 콘텐츠 저장소에서 차트를 제공하고 해당 다이제스트로 검증합니다. - 플랫폼 전체에 하나의 게시 주소. 차트의 리버스 프록시는
브라우저 경로
/를 콘솔로, 레지스트리 및 API 경로 (/v2/,/api/,/service/,/c/)를 컨트롤 플레인으로 라우팅하므로, 컨테이너 클라이언트는 브라우저가 콘솔에 접속하는 것과 같은 호스트로 로그인, push, pull을 합니다. 이 Service가provides.host가 게시하는 대상이며, 소비자는 어느 경로 집합에 접근하든 두 번째 주소가 필요하지 않습니다. - 하나의 주소에 대한 두 개의 공개 이름. 모듈은 그 하나의 주소를 이미지 클라이언트와 API가 통신하는
엔드포인트인
registry와 웹 엔드포인트인ui로 내보냅니다. 두 이름 모두 두 경로 집합을 제공하는 주소로 해석되므로, 소비자는 자신의 의도를 나타내는 이름에 연결하면 됩니다. - 운영자의 모듈 component 크기 지정. Release는 모듈의
component를 모듈 범위 ID(
harbor.registry)로 지정하여 컴퓨팅 자원을 설정하며, 개발자의 Aggregate가 물리적 크기를 다시 기술할 필요가 없습니다. - 그룹화된 값에 대한 완전성 규칙.
infra.compute는 CPU 키와 메모리 키를 가지며, Recipe는 둘 중 어느 하나라도 비워 둔 그룹에서 중단됩니다. CPU 제한만 있고 메모리 제한이 없이 렌더링된 컨트롤 플레인은 Component의 선언된 기본값이 설명하는 것과 실질적으로 다르며, 렌더링된 출력 어디에도 그 사실이 드러나지 않습니다. 따라서 빌드는 대신 중단하고 누락된 키를 알려 줍니다. 그룹에서 생략한 키에는 Component의 기본값이 적용됩니다. - 기본값이 없는 여섯 개의 키. 토큰 서비스가 레지스트리의 토큰에 서명하는 키와 그 인증서, 레지스트리 자체 서비스들이 서로 인증하고 업로드 상태에 서명하는 데 쓰는 세 개의 시크릿, 요청 위조 방지 키, 그리고 컨트롤 플레인이 저장된 자격 증명을 암호화하는 키에는 기본값이 없습니다. 카탈로그를 읽는 모든 사람이 가진 키라면 누구나 레지스트리가 신뢰하는 토큰을 발행하거나 저장된 내용을 읽을 수 있기 때문입니다. 이 Component는 해당 슬롯을 필수로 선언하므로, 하나라도 비워 둔 빌드는 중단되고 그 슬롯을 알려 줍니다. 빌드는 여섯 값 중 어느 것도 읽지 않고 렌더링하지도 않으며, 모든 workload는 각 값을 자신이 지정한 Secret에서 읽습니다.
- Release가 연결하는 세 개의 키. 모듈은 토큰 서명 키,
컨트롤 플레인의 공유 시크릿, 저장된 자격 증명을 암호화하는 키 중 어느 것도 연결하지
않으므로, Release가 세 개 모두를 모듈의 component에
token_key,core_secret,secret_key로 연결합니다. 각각은core/referenced-secret을 통해 연결되고infra.origin이 Secret을 지정하며, Manifest는 Feature를k8s-existing-secret에 바인딩합니다. 컨트롤 플레인은 토큰 서명 키와 암호화 키를 지정된 Secret에서 마운트하고, 서비스들은 공유 시크릿을 각자의 Secret에서 읽습니다. - 모듈이 채우는 자격 증명. 관리자 계정의 비밀번호,
사이트 간 요청 위조 방지 키, 워커 계층의 공유 시크릿, blob 저장소의 업로드 상태
시크릿도 Component의 자격 증명 슬롯이며, 모듈은 각 슬롯을 자체 파라미터
(
admin_password,csrf_key,jobservice_secret,registry_http_secret)로core/referenced-secret자격 증명 Feature를 통해 채웁니다. 따라서 모든 workload는 이를 이름으로 지정된 Secret에서 읽습니다. 모듈이 그 Feature를 연결하므로 Manifest가 이를 매핑합니다. 세 개의 키는 모듈에도 기본값이 없으므로, Aggregate는 자체 파라미터를 선언하여aggregates.harbor.parameters를 통해 전달하고, Release가 이를 채우며,k8s-existing-secret은 각 값을 네임스페이스에 이미 존재하는 Secret의 이름으로 읽습니다. 값을 제공하지 않는 Release는 해당 파라미터를 알리며 빌드를 중단합니다. 이 예제는 관리자 비밀번호를 모듈의 개발용 기본값으로 두며, Manifest는 그 하나의 연결을 이름으로k8s-secret-from-parameter에 바인딩하여 이를 담은 Secret을 내보냅니다. 나머지 비밀번호는 Release가 렌더링하는 구성에 기록되므로 대신infra를 설정하여 교체합니다. 설정하지 않으면 각각 Recipe가 명시한 개발용 값을 사용합니다. - 그대로 두면 자료를 생성하는 차트에 대한 결정적 출력. 이 차트는 그대로 두면 시크릿이 제공되지 않을 때 스스로 시크릿을 발행합니다. 컨트롤 플레인의 공유 시크릿과 토큰 서명 시크릿, 워커 계층과 blob 저장소의 시크릿, 요청 위조 방지 키, 그리고 렌더링할 때마다 새 솔트로 다시 해시하는 blob 저장소의 해시된 비밀번호입니다. 이들은 모두 대신 제공됩니다. 여섯 개의 키는 항상 Release가 지정한 Secret에서, 비밀번호는 슬롯이 채워진 경우 연결된 자격 증명에서 이름으로, 채워지지 않은 경우 고정된 개발용 값에서 제공되므로, 동일한 입력을 두 번 렌더링하면 바이트 단위로 동일한 결과가 나옵니다.
- 재현 가능한 이미지. 레지스트리가 실행하는 모든 이미지는 명시적인
태그로 고정됩니다. 제품은 모든 이미지를 하나의 태그로 출시하므로
infra.engine_version이 모든 이미지를 한 번에 선택합니다.infra.overrides.image는 단일 서비스의 고정을 교체하며,infra.overrides.image_prefix는 미러에서 pull하는 Release를 위해 이미지 전체를 함께 옮깁니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example harbor-stack그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd harbor-stack빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며, 카탈로그 플래그가 필요하지 않습니다. Recipe가 차트를 가져오므로 먼저 의존성을 lockfile로 해석합니다:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yaml렌더링된 아티팩트는 dist/ 아래에 생성됩니다.
적용하기 전에, 레지스트리가 배포되는 네임스페이스에 Release가 지정하는 Secret 여섯 개를 생성합니다: 데이터 키 tls.key 아래에 RSA 개인 키를, tls.crt 아래에 그 키에 대한 인증서를 담은 harbor-token-key,
데이터 키 secret 아래에 16자 시크릿을 담은 harbor-core-secret,
secretKey 아래에 16자 키를 담은 harbor-secret-key,
CSRF_KEY 아래에 32자 키를 담은 harbor-csrf-key, 그리고
JOBSERVICE_SECRET과 REGISTRY_HTTP_SECRET 아래에 각각 16자 시크릿을 담은 harbor-jobservice-secret과 harbor-registry-http-secret입니다. 예를 들면 다음과 같습니다:
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"서비스가 이 Secret들을 찾지 못하는 레지스트리는 시작되지 않습니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `harbor-stack` 폴더가 없으면 `example`을 `harbor-stack`으로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `harbor-stack` 폴더에 씁니다. 그런 다음 `workspace_root`를 `harbor-stack`으로, `release`를 `release-helm-synth.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 쓴 파일을 알려 주십시오. 파일은 `harbor-stack/dist/` 아래에 있습니다.구성된 레지스트리의 모습
빌드는 이 구성에 대해 차트가 정의하는 리소스를 출력합니다.
리버스 프록시, 콘솔, 컨트롤 플레인, 워커 계층, 블롭 저장소에 대한 Deployment, 백엔드, 캐시, 스캐너에 대한 StatefulSet, 블롭 저장소와 워커 계층의 로그에 대한 퍼시스턴트 볼륨 클레임, 각 서비스가 읽는 ConfigMap과 Secret, 그리고 이들 앞에 놓이는 Service입니다. 이와 함께 자격 증명 Feature가 Secret 하나,
harbor-zdregistry-admin-password를 출력합니다. 이 Secret에는 관리자 비밀번호에 대한 모듈의 개발용 기본값이 담기며, 컨트롤 플레인은 차트 자체의 Secret이 아니라 이 Secret에서 비밀번호를 읽습니다. 여섯 개의 키에 대해서는 Secret이 출력되지 않습니다.
컨트롤 플레인은 토큰 서명 키를 harbor-token-key에서, 암호화 키를 harbor-secret-key에서 마운트하고, 서비스들은 나머지를 Release가 지정하는 Secret인
harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret,
harbor-registry-http-secret에서 읽습니다.
이 Service 중 정확히 하나가 소비자가 연결하는 주소입니다.
dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:
apiVersion: v1kind: Servicemetadata: name: harbor-zdregistry [… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]spec: type: ClusterIP ports: - name: http port: 80 targetPort: 8080 selector: release: harbor-zdregistry app: "harbor" component: nginx이 Service의 셀렉터는 리버스 프록시를 지정하며, 이것이 레지스트리에 하나의 주소를 부여합니다. port는 infra.port를 따릅니다. 그 뒤의 프록시는 차트가 고정한 포트에서 수신하고 Service가 그 포트로 전달하므로, infra.port를 바꾸면 리스너가 아니라 게시된 주소가 바뀝니다.
이름 지정: 주소를 게시하는 설정값은 리소스 이름을 정하는 설정값이 아닙니다
이 차트는 대부분의 리소스 이름을 최상위 이름 설정값에서 도출한 뒤 접미사를 붙입니다. 컨트롤 플레인의 Service는 <instance>-core, 콘솔의 Service는 <instance>-portal, 블롭 저장소의 Service는 <instance>-registry이며, 워커 계층, 스캐너, 백엔드, 캐시도 마찬가지입니다. 접미사 없는 이름 그대로 지정되는 것은 없습니다.
게시되는 Service의 이름은 별도의, 노출 범위에 속한 설정값으로 정해지며, 이 설정값의 기본값은 최상위 이름과 무관한 고정 리터럴입니다. 최상위 설정값만 고정하는 Recipe는 어떤 Service도 응답하지 않는 주소를 게시하게 되며, 한 네임스페이스의 두 인스턴스가 모두 그 고정 리터럴로 Service를 생성하여 충돌합니다. 따라서 Recipe는 두 설정값을 모두 인스턴스 ID로 설정하며, 이 때문에 위에서 생성된 Service가 인스턴스 이름을 따르고 provides.host가 실제로 존재하는 주소를 가리키게 됩니다.
이 점은 어떤 플랫폼 차트를 감쌀 때든 주의 깊게 살펴볼 만합니다. provides.host는 차트가 실제로 생성하는 Service를 가리켜야 하며, 어떤 설정값이 그것을 결정하는지는 차트들 사이의 관례가 아니라 해당 차트의 속성입니다.
이 구성에 포함되지 않는 것
Component는 외부 호스트 이름이 아니라 클러스터 내부 주소를 게시하므로, 차트의 Ingress는 꺼 둔 채로 두고 대신 리버스 프록시를 클러스터 내부 Service로 노출합니다. 단일 외부 엔드포인트는 ingress 계층에서 구성되며, 이 모듈이 내보내는 주소로 라우팅합니다. 전송 보안은 꺼져 있습니다. 차트 자체의 인증서 소스가 렌더링 시점에 인증 기관과 서명된 인증서를 생성하는데, 동일한 입력을 두 번 렌더링해도 이를 재현하지 못하기 때문입니다. Prometheus-operator 모니터도 꺼져 있습니다.
레지스트리의 메트릭도 꺼져 있습니다. Component의 values.metrics_enabled는 컨트롤 플레인, 워커 계층, blob 저장소 및 추가된 exporter에 대해 메트릭을 켜고, 스크레이퍼가 발견할 수 있도록 네 개의 Service를 게시합니다. 그런데 같은 차트 설정은 blob 저장소의 디버그 리스너 — 프로파일링, 실행 추적, 런타임 변수를 호출자 확인 없이 제공 — 도 모든 클러스터 내부 호출자에게 엽니다. 모듈은 이 값을 기본값인 false로 두므로 이 예제는 메트릭을 렌더링하지 않습니다. Component를 직접 선언하는 Aggregate는 이 값을 설정할 수 있습니다. 그렇더라도 exporter의 이미지는 나머지 이미지와 함께 고정되어 있습니다.