버전이 있는 불변 Helm 차트 게시

Apollo로 여러 배포 환경에 소프트웨어를 배포하려면 컨테이너 이미지와 그 이미지를 실행하는 배포 정의를 함께 버전으로 관리해야 합니다. Apollo는 레지스트리에 게시된, 버전이 있고 변경되지 않는 Helm 차트를 요구합니다.

컨테이너 이미지가 같아도 리소스 요청량, 기본 구성값이나 네트워크 노출 방식이 달라지면 배포 동작이 달라질 수 있습니다. 불변 차트 패키지는 특정 버전의 실행 정의를 고정하고, 설치본마다 필요한 차이는 Helm Values로 전달합니다.

Helm 차트를 레지스트리에 게시하는 방식

차트에 버전을 부여하고 패키지로 만든 뒤 Helm 차트 저장소에 게시합니다. 이 아티팩트의 버전에는 일반적으로 Semantic Versioning을 사용합니다. Helm은 차트 패키징, 버전 지정과 게시를 지원합니다.

운영자는 특정 차트 버전을 하나 이상의 클러스터에 배포할 수 있으며, 어느 환경에 어떤 버전이 설치되어 있는지 파악할 수 있습니다. 차트가 참조하는 컨테이너 이미지를 제공하는 레지스트리를 차트 게시에도 활용할 수 있습니다.

차트 소스는 Git에서 관리하면서 배포용 결과물은 레지스트리의 불변 패키지로 게시할 수 있습니다.

Git 참조만으로 환경별 배포를 관리하는 방식

Git 브랜치, 태그나 디렉터리를 환경에 대응시키는 방식에는 다음 형태가 있습니다.

방식	배포 정의의 배치	여러 환경을 운영할 때의 특성
환경별 브랜치	하나의 저장소에 차트를 두고 브랜치로 제품 설치본에 적용할 리소스를 선택	차트 버전의 의미가 해당 환경의 브랜치에 묶임
환경별 태그	하나의 저장소에서 태그로 각 설치본에 배포할 리소스를 선택	태그가 가리키는 배포 정의를 환경별로 관리
환경별 폴더	여러 차트를 대상 환경별 폴더로 배치	이미지를 배포하는 정의가 환경마다 따로 존재하며 시간이 지나면서 달라질 수 있음
환경별 저장소	클러스터별 차트나 Kubernetes 매니페스트를 여러 저장소로 분산	공통 배포 정의를 유지하기 어려워지고 클러스터 사이의 차이가 커질 수 있음

이 방식들에서 Git 참조만 사용하고 차트 패키지를 게시하지 않으면, 환경 사이에서 재사용할 불변 차트 버전이 별도로 존재하지 않습니다. 같은 컨테이너 버전을 가리키더라도 같은 차트 정의를 배포하고 있는지 확인하기가 어려워집니다.

Apollo의 릴리스 회수와 버전 추적

Apollo의 릴리스 회수는 어떤 소프트웨어 버전이 어느 환경에 설치되어 있는지 식별할 수 있다는 전제 위에서 동작합니다. 차트나 그 차트가 참조하는 컨테이너에 문제가 발견되면 문제가 있는 릴리스 범위와 조치 방향을 지정할 수 있습니다.

Apollo는 해당 버전의 설치 위치를 파악하고, 설정에 따라 정상 버전으로 자동 전환할 수 있습니다. 운영자가 각 환경에서 개별적으로 같은 작업을 반복하지 않고도 다수 환경에 회수 조치를 적용할 수 있습니다.

새 제품 릴리스를 Apollo에 게시할 때는 Helm 차트 저장소에 있는 차트의 위치를 나타내는 Maven 좌표가 필요합니다. 제품 식별자와 릴리스 버전, 차트 아티팩트의 위치를 연결하여 관리합니다.

버전 정하기

Helm과 Apollo에서 사용할 차트 버전은 Semantic Versioning을 따라야 합니다. Git 참조로 차트를 배포하던 구성에서 전환한다면 Semantic Versioning 2.0.0 값을 Git 태그로 사용하는 방법이 권장됩니다.

기본 형식은 MAJOR.MINOR.PATCH입니다.

변경	올릴 버전 요소
호환되지 않는 API 변경	`MAJOR`
이전 버전과 호환되는 기능 추가	`MINOR`
이전 버전과 호환되는 버그 수정	`PATCH`

사전 릴리스와 빌드 메타데이터를 나타내는 추가 표기도 사용할 수 있습니다.

게시할 커밋에 태그를 지정합니다. 다음은 첫 릴리스에 0.0.1 태그를 붙이는 예시입니다.

git tag 0.0.1 -m "Tagging first version of a release"

빌드 자동화에서는 다음 명령으로 현재 빌드에 대응하는 버전 문자열을 얻을 수 있습니다.

git describe --tags --always --first-parent

차트를 게시하기 전에는 최종 버전 문자열이 사용할 Semantic Versioning 규칙에 맞는지 확인합니다. 아래 게시 예시는 버전 태그가 지정된 릴리스 커밋에서 실행하는 구성을 가정합니다.

OCI 레지스트리에 패키지 게시하기

다음은 가상의 레지스트리 registry.example.com에 차트를 게시하는 Bash 예시입니다. HELM_CHART_NAME은 차트의 Chart.yaml에 지정된 이름과 같아야 합니다. helm-chart는 차트 디렉터리입니다.

레지스트리 사용자 이름과 비밀번호는 HELM_REPOSITORY_USER, HELM_REPOSITORY_PASS 환경 변수에 미리 제공해야 합니다. CI에서 실행한다면 해당 CI의 비밀 정보(Secret) 관리 기능으로 주입합니다. 비밀번호는 명령행 인수 대신 표준 입력으로 전달합니다.

set -euo pipefail

export RELEASE_VERSION="$(git describe --tags --always --first-parent)"
export HELM_REPOSITORY="registry.example.com"
export HELM_CHART_NAME="example-service"

cd helm-chart
helm package . --version "${RELEASE_VERSION}" --app-version "${RELEASE_VERSION}"
printf '%s' "${HELM_REPOSITORY_PASS}" | helm registry login "${HELM_REPOSITORY}" \
  --username "${HELM_REPOSITORY_USER}" --password-stdin
helm push "${HELM_CHART_NAME}-${RELEASE_VERSION}.tgz" "oci://${HELM_REPOSITORY}"

helm package는 차트 이름과 버전으로 .tgz 파일을 만듭니다. 이 예시에서는 차트의 버전과 appVersion에 같은 릴리스 버전을 전달합니다.

helm push의 대상에는 oci://를 붙입니다. 차트 이름과 태그는 패키지의 이름과 버전에서 결정되므로 대상 URL에 다시 붙이지 않습니다. 레지스트리가 네임스페이스나 저장소 경로를 요구한다면 oci://registry.example.com/helm-charts처럼 경로를 포함하고, 해당 저장소를 미리 만들어야 하는지도 확인합니다. 로그인 대상은 레지스트리 호스트입니다.

차트 게시 이후에는 그 차트의 위치와 버전을 Apollo 제품 릴리스에 연결합니다. 차트 패키지 게시와 Apollo에 릴리스 메타데이터를 등록하는 단계는 각각 수행해야 합니다.