Auto Deploy는 애플리케이션을 Kubernetes 클러스터에 배포하는 기능입니다. 다음과 같은 여러 의존성으로 구성됩니다.

• Auto Deploy 템플릿은 auto-deploy-image를 사용하는 파이프라인 job과 스크립트 모음입니다.
• auto-deploy-image는 Kubernetes 클러스터와 통신하는 실행 가능한 이미지입니다.
• auto-deploy-app chart는 애플리케이션을 배포하기 위한 Helm 차트입니다.

auto-deploy-image와 auto-deploy-app 차트는 시맨틱 버전 관리를 사용합니다. 기본적으로 Auto DevOps 프로젝트는 안정적이고 호환성이 깨지지 않는 버전을 계속 사용합니다. 하지만 이러한 의존성은 GitLab 메이저 버전 릴리스에서 호환성이 깨지는 변경 사항과 함께 업그레이드될 수 있으며, 이 경우 배포를 업그레이드해야 합니다.

이 가이드는 새롭거나 다른 메이저 버전의 Auto Deploy 의존성으로 배포를 업그레이드하는 방법을 설명합니다.

의존성 버전 확인#

현재 버전을 확인하는 절차는 사용 중인 템플릿에 따라 다릅니다. 먼저 어떤 템플릿을 사용하고 있는지 확인합니다.

• GitLab Self-Managed 인스턴스의 경우 GitLab 패키지에 번들된 안정적인 Auto Deploy 템플릿 을 사용합니다.
• GitLab.com 안정적인 Auto Deploy 템플릿 은 다음 중 하나에 해당하면 사용됩니다.
  • Auto DevOps 프로젝트에 .gitlab-ci.yml 파일이 없는 경우.
  • Auto DevOps 프로젝트에 .gitlab-ci.yml 파일이 있고 포함하는 Auto-DevOps.gitlab-ci.yml 템플릿을 사용하는 경우.
• 최신 Auto Deploy 템플릿 은 다음 두 가지에 모두 해당하면 사용됩니다.
  • Auto DevOps 프로젝트에 .gitlab-ci.yml 파일이 있고 포함하는 Auto-DevOps.gitlab-ci.yml 템플릿을 사용하는 경우.
  • 최신 Auto Deploy 템플릿도 함께 포함하는 경우

사용 중인 템플릿을 알고 있다면 다음과 같이 확인합니다.

• auto-deploy-image 버전은 템플릿 안에 있습니다(예: auto-deploy-image:v1.0.3).
• auto-deploy-app 차트 버전은 auto-deploy-image 리포지터리 에 있습니다(예: version: 1.0.3).

호환성#

다음 표는 GitLab과 Auto Deploy 의존성 간 버전 호환성을 설명합니다.

auto-deploy-image의 현재 안정 버전은 Auto Deploy 안정 템플릿에서 확인할 수 있습니다.

업그레이드 가이드#

Auto DevOps를 사용하는 프로젝트는 GitLab이 관리하는 수정되지 않은 차트를 사용해야 합니다. 커스터마이즈한 차트는 지원되지 않습니다.

v1 auto-deploy-image로 배포 업그레이드#

v1 차트는 v0 차트와 하위 호환되므로 설정을 변경할 필요가 없습니다.

v2 auto-deploy-image로 배포 업그레이드#

v2 auto-deploy-image에는 여러 의존성 및 아키텍처 변경 사항이 포함되어 있습니다. Auto DevOps 프로젝트에 v1 auto-deploy-image로 배포된 활성 환경이 있다면 다음 업그레이드 가이드를 진행합니다. 그렇지 않다면 이 절차를 건너뛰어도 됩니다.

Kubernetes 1.16 이상#

v2 auto-deploy-image는 Kubernetes 1.15 이하에 대한 지원을 중단합니다. Kubernetes 클러스터를 업그레이드해야 한다면 클라우드 공급자의 안내를 따릅니다. GKE 예시를 참고합니다.

Helm v3#

auto-deploy-image는 Helm 바이너리를 사용해 릴리스를 조작합니다. 이전에는 auto-deploy-image가 클러스터에서 Tiller를 사용하는 Helm v2를 사용했습니다. v2 auto-deploy-image에서는 더 이상 Tiller가 필요 없는 Helm v3을 사용합니다.

Auto DevOps 프로젝트에 v1 auto-deploy-image로 배포된 활성 환경이 있다면 다음 단계에 따라 Helm v3을 사용하는 v2로 업그레이드합니다.

1. 다음 CI/CD 변수를 설정합니다.

   • MIGRATE_HELM_2TO3를 true로 설정합니다. 이 변수가 없으면 마이그레이션 job이 실행되지 않습니다.

   • AUTO_DEVOPS_FORCE_DEPLOY_V2를 1로 설정합니다.

   • 선택 사항: BACKUP_HELM2_RELEASES를 1로 설정합니다. 이 변수를 설정하면 마이그레이션 job이 helm-2-release-backups라는 job 아티팩트에 백업을 1주일간 저장합니다. 준비되기 전에 실수로 Helm v2 릴리스를 삭제한 경우 kubectl apply -f $backup 명령으로 이 백업을 Kubernetes 매니페스트 파일에서 복원할 수 있습니다.

     [!warning] 공개 파이프라인을 사용하는 경우 이 옵션을 사용하지 않습니다. 이 아티팩트에는 시크릿이 포함될 수 있으며, job을 볼 수 있는 모든 사용자에게 노출됩니다.

2. 파이프라인을 실행하고 <environment-name>:helm-2to3:migrate job을 트리거합니다.

3. 평소와 같이 환경을 배포합니다. 이 배포는 Helm v3을 사용합니다.

4. 배포가 성공하면 <environment-name>:helm-2to3:cleanup을 안전하게 실행할 수 있습니다. 이 작업은 네임스페이스에서 모든 Helm v2 릴리스 데이터를 삭제합니다.

5. MIGRATE_HELM_2TO3 CI/CD 변수를 제거하거나 false로 설정합니다. 환경 스코프를 사용하면 환경별로 하나씩 이 작업을 수행할 수 있습니다.

클러스터 내 PostgreSQL Channel 2#

v2 auto-deploy-image는 레거시 클러스터 내 PostgreSQL에 대한 지원을 중단합니다. Kubernetes 클러스터가 여전히 이를 사용하고 있다면 v1 auto-deploy-image로 데이터를 업그레이드하고 마이그레이션합니다.

카나리 배포 및 점진적 롤아웃의 트래픽 라우팅 변경#

Auto Deploy는 카나리 배포와 점진적 롤아웃과 같은 고급 배포 전략을 지원합니다.

이전에는 auto-deploy-image가 레플리카 비율을 변경해 unstable 트랙과 stable 트랙 간 트래픽 균형을 맞추는 서비스 하나를 생성했습니다. v2 auto-deploy-image에서는 Canary Ingress로 트래픽을 제어합니다.

자세한 내용은 v2 auto-deploy-app 차트 리소스 아키텍처를 참고합니다.

Auto DevOps 프로젝트의 production 환경에 v1 auto-deploy-image로 배포된 활성 canary 또는 rollout 트랙 릴리스가 있다면 다음 단계에 따라 v2로 업그레이드합니다.

1. 프로젝트가 v1 auto-deploy-image를 사용하고 있는지 확인합니다. 사용하고 있지 않다면 버전을 지정합니다.
2. canary 또는 rollout 배포를 진행 중이라면 먼저 production으로 승격해 unstable 트랙을 삭제합니다.
3. 프로젝트가 v2 auto-deploy-image를 사용하고 있는지 확인합니다. 사용하고 있지 않다면 버전을 지정합니다.
4. GitLab CI/CD 설정에서 값이 true인 AUTO_DEVOPS_FORCE_DEPLOY_V2 CI/CD 변수를 추가합니다.
5. 새 파이프라인을 생성하고 production job을 실행해 v2 auto-deploy-app chart로 리소스 아키텍처를 갱신합니다.
6. AUTO_DEVOPS_FORCE_DEPLOY_V2 변수를 제거합니다.

특정 버전의 Auto Deploy 의존성 사용#

특정 버전의 Auto Deploy 의존성을 사용하려면 원하는 버전의 auto-deploy-image와 auto-deploy-app이 포함된 이전 Auto Deploy 안정 템플릿을 지정합니다.

예를 들어 템플릿이 GitLab 19.2에 번들되어 있다면 .gitlab-ci.yml을 다음과 같이 변경합니다.

include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v19.2.0-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml

경고 무시하고 배포 계속하기#

새 차트 버전을 배포해도 안전하다고 확신한다면 AUTO_DEVOPS_FORCE_DEPLOY_V<major-version-number> CI/CD 변수를 추가해 배포를 강제로 계속할 수 있습니다.

예를 들어 이전에 v0.17.0 차트를 사용하던 배포에 v2.0.0 차트를 배포하려면 AUTO_DEVOPS_FORCE_DEPLOY_V2를 추가합니다.

얼리 어답터#

최신 베타 버전이나 unstable 버전의 auto-deploy-image를 사용하려면 .gitlab-ci.yml에 최신 Auto Deploy 템플릿을 포함합니다.

include:
  - template: Auto-DevOps.gitlab-ci.yml
  - template: Jobs/Deploy.latest.gitlab-ci.yml

auto-deploy-app 차트의 리소스 아키텍처#

v0 및 v1 차트 리소스 아키텍처#

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD;
accTitle: v0 and v1 chart resource architecture
accDescr: Shows the relationships between the components of the v0 and v1 charts.
subgraph gl-managed-app
Z[Nginx Ingress]
end
Z[Nginx Ingress] --> A(Ingress);
Z[Nginx Ingress] --> B(Ingress);
subgraph stg namespace
B[Ingress] --> H(...);
end
subgraph prd namespace
A[Ingress] --> D(Service);
D[Service] --> E(Deployment:Pods:app:stable);
D[Service] --> F(Deployment:Pods:app:canary);
D[Service] --> I(Deployment:Pods:app:rollout);
E(Deployment:Pods:app:stable)---id1[(Pods:Postgres)]
F(Deployment:Pods:app:canary)---id1[(Pods:Postgres)]
I(Deployment:Pods:app:rollout)---id1[(Pods:Postgres)]
end

v2 차트 리소스 아키텍처#

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD;
accTitle: v2 chart resource architecture
accDescr: Shows the relationships between the components of the v2 chart.
subgraph gl-managed-app
Z[Nginx Ingress]
end
Z[Nginx Ingress] --> A(Ingress);
Z[Nginx Ingress] --> B(Ingress);
Z[Nginx Ingress] --> |If canary is present or incremental rollout/|J(Canary Ingress);
subgraph stg namespace
B[Ingress] --> H(...);
end
subgraph prd namespace
subgraph stable track
A[Ingress] --> D[Service];
D[Service] --> E(Deployment:Pods:app:stable);
end
subgraph canary track
J(Canary Ingress) --> K[Service]
K[Service] --> F(Deployment:Pods:app:canary);
end
E(Deployment:Pods:app:stable)---id1[(Pods:Postgres)]
F(Deployment:Pods:app:canary)---id1[(Pods:Postgres)]
end

문제 해결#

메이저 버전 불일치 경고#

이전 버전과 메이저 버전이 다른 차트를 배포하는 경우 새 차트가 올바르게 배포되지 않을 수 있습니다. 이는 아키텍처 변경 때문일 수 있습니다. 이 경우 배포 job이 다음과 유사한 메시지와 함께 실패합니다.

*************************************************************************************
                                   [WARNING]
Detected a major version difference between the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0).
A new major version might not be backward compatible with the current release (production). The deployment could fail or be stuck in an unrecoverable status.
...

이 오류 메시지를 해결하고 배포를 재개하려면 다음 중 하나를 수행해야 합니다.

• 수동으로 차트 버전을 업그레이드합니다.
• 특정 차트 버전을 사용합니다.

오류: missing key "app.kubernetes.io/managed-by": must be set to "Helm"#

클러스터에 v1 auto-deploy-image로 배포된 배포가 있다면 다음과 같은 오류가 발생할 수 있습니다.

• Error: rendered manifests contain a resource that already exists. Unable to continue with install: Secret "production-postgresql" in namespace "<project-name>-production" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "production-postgresql"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "<project-name>-production"

이는 이전 배포가 Helm3과 호환되지 않는 Helm2로 배포되었기 때문입니다. 이 문제를 해결하려면 업그레이드 가이드를 따릅니다.