새 Auto Deploy 의존성에 대한 배포 업그레이드

Tier: Free, Premium, Ultimate

Offering: GitLab.com, Self-managed, GitLab Dedicated

Auto Deploy는 애플리케이션을 Kubernetes 클러스터에 배포하는 기능입니다.

여러 의존성으로 구성되어 있습니다:

auto-deploy-image와 auto-deploy-app 차트는 Semantic Versioning을 사용합니다.

기본적으로, 귀하의 Auto DevOps 프로젝트는 안정적이고 비파괴적인 버전을 사용합니다.

그러나 이러한 의존성은 GitLab의 주요 버전 릴리스에서 파괴적인 변경 사항과 함께 업그레이드될 수 있으므로,

배포를 업그레이드해야 할 수 있습니다.

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

의존성 버전 확인

현재 버전을 확인하는 과정은 사용 중인 템플릿에 따라 다릅니다.

먼저 사용 중인 템플릿을 확인하세요:

어떤 템플릿이 사용되는지 아는 경우:

  • auto-deploy-image 버전은 템플릿에 있습니다(예: auto-deploy-image:v1.0.3).

  • auto-deploy-app 차트 버전은 auto-deploy-image 저장소에 있습니다(예: version: 1.0.3).

호환성

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

GitLab 버전 auto-deploy-image 버전 비고
v10.0 to v14.0 v0.1.0 to v2.0.0 v0 및 v1 auto-deploy-image는 이전 버전과 호환됩니다.
v13.4 및 이후 v2.0.0 및 이후 v2 auto-deploy-image에는 업그레이드 가이드에서 설명된 대로 파괴적인 변화가 포함되어 있습니다.

현재 안정적인 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. Helm 2to3 마이그레이션 CI/CD 템플릿을 포함하십시오:

    • GitLab.com을 사용 중이거나 GitLab 14.0.1 이상인 경우, 이 템플릿은 이미 Auto DevOps에 포함되어 있습니다.

    • 다른 GitLab 버전에서는 .gitlab-ci.yml을 수정하여 템플릿을 포함할 수 있습니다:

      include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Jobs/Helm-2to3.gitlab-ci.yml

  2. 다음 CI/CD 변수를 설정하십시오:

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

    • 선택 사항: BACKUP_HELM2_RELEASES를 1로 설정합니다. 이 변수를 설정하면 마이그레이션 작업이 helm-2-release-backups라는 작업 아티팩트로 1주일 동안 백업을 저장합니다.

      헬름 v2 릴리스를 삭제하기 전에 준비가 되지 않았다면, $backup를 사용하여 Kubernetes 매니페스트 파일에서 이 백업을 복원할 수 있습니다.

      경고:

      공개 파이프라인을 사용하는 경우 사용하지 마십시오.

      이 아티팩트는 비밀을 포함할 수 있으며

      작업을 볼 수 있는 모든 사용자에게 표시됩니다.

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

  4. 환경을 평소처럼 배포합니다. 이 배포는 Helm v3을 사용합니다.

  5. 배포가 성공하면 안전하게 <environment-name>:helm-2to3:cleanup를 실행할 수 있습니다.

    이 명령은 네임스페이스에서 모든 Helm v2 릴리스 데이터를 삭제합니다.

  6. MIGRATE_HELM_2TO3 CI/CD 변수를 제거하거나 false로 설정합니다.

    환경 범위를 사용하여 한 번에 하나의 환경에서 이 작업을 수행할 수 있습니다. 환경 범위를 참조하십시오.

클러스터 내 PostgreSQL 채널 2

v2 자동 배포 이미지에서는 구형 클러스터 내 PostgreSQL에 대한 지원이 중단됩니다.

Kubernetes 클러스터가 여전히 이를 의존하고 있다면, 데이터를 업그레이드하고 마이그레이션하세요 v1 자동 배포 이미지를 사용하여.

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

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

이전에는 auto-deploy-image가 안정적인 트랙과 불안정한 트랙 간의 트래픽을 균형 조절하기 위해 하나의 서비스를 생성하여 복제 비율을 변경했습니다. v2 auto-deploy-image에서는 Canary Ingress로 트래픽을 제어합니다.

자세한 내용은 v2 auto-deploy-app 차트 리소스 아키텍처를 참조하세요.

자동 DevOps 프로젝트에 활성 canary 또는 rollout 트랙 릴리스가 v1 auto-deploy-image로 배포된 production 환경에 있는 경우, v2로 업그레이드하기 위해 다음 단계를 따르세요:

  1. 프로젝트가 v1 auto-deploy-image를 사용하고 있는지 확인하세요. 그렇지 않다면, 버전을 지정하세요.

  2. canary 또는 rollout 배포를 진행 중이라면, 먼저 이를 production으로 승격하여 불안정한 트랙을 삭제하세요.

  3. 프로젝트가 v2 auto-deploy-image를 사용하고 있는지 확인하세요. 그렇지 않다면, 버전을 지정하세요.

  4. GitLab CI/CD 설정에서 true 값으로 AUTO_DEVOPS_FORCE_DEPLOY_V2 CI/CD 변수를 추가하세요.

  5. 새 파이프라인을 생성하고 production 작업을 실행하여 v2 auto-deploy-app chart로 리소스 아키텍처를 갱신하세요.

  6. AUTO_DEVOPS_FORCE_DEPLOY_V2 변수를 제거하세요.

자동 배포 종속성의 특정 버전 사용

자동 배포 종속성의 특정 버전을 사용하려면, 원하는 auto-deploy-image와 auto-deploy-app의 버전을 지정하는 이전 자동 배포 안정 템플릿을 지정하세요.

예를 들어, 템플릿이 GitLab 16.10에 번들되어 있다면, .gitlab-ci.yml을 다음과 같이 변경하세요:

include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v16.10.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를 추가하세요.

초기 사용자

최신 베타 또는 불안정한 버전의 auto-deploy-image를 사용하려면, 최신 Auto Deploy 템플릿을 .gitlab-ci.yml에 포함하세요:

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

경고: 베타 또는 불안정한 auto-deploy-image를 사용하면 환경에 되돌릴 수 없는 손상을 초래할 수 있습니다. 중요한 프로젝트나 환경에서 테스트하지 마세요.

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

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

%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD; accTitle: v0 및 v1 차트 리소스 아키텍처 accDescr: v0 및 v1 차트의 구성 요소 간의 관계를 보여줍니다. subgraph gl-managed-app Z[Nginx Ingress] end Z[Nginx Ingress] --> A(Ingress); Z[Nginx Ingress] --> B(Ingress); subgraph stg 네임스페이스 B[Ingress] --> H(...); end subgraph prd 네임스페이스 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 차트 리소스 아키텍처 accDescr: v2 차트의 구성 요소 간의 관계를 보여줍니다. subgraph gl-managed-app Z[Nginx Ingress] end Z[Nginx Ingress] --> A(Ingress); Z[Nginx Ingress] --> B(Ingress); Z[Nginx Ingress] --> |Canary가 존재하거나 점진적 배포/|J(Canary Ingress); subgraph stg 네임스페이스 B[Ingress] --> H(...); end subgraph prd 네임스페이스 subgraph 안정 트랙 A[Ingress] --> D[Service]; D[Service] --> E(Deployment:Pods:app:stable); end subgraph 카나리 트랙 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

문제 해결

주요 버전 불일치 경고

이전과 다른 주요 버전을 가진 차트를 배포하면, 새 차트가 제대로 배포되지 않을 수 있습니다. 이는 아키텍처 변경으로 인한 것일 수 있습니다. 그런 경우, 배포 작업이 다음과 유사한 메시지와 함께 실패합니다:

*************************************************************************************
                                   [경고]
현재 배포 중인 차트(auto-deploy-app-v0.7.0)와 이전에 배포된 차트(auto-deploy-app-v1.0.0) 간의 주요 버전 차이가 감지되었습니다.
새 주요 버전은 현재 버전(프로덕션)과의 하위 호환성이 없을 수 있습니다. 배포가 실패하거나 되돌릴 수 없는 상태에 갇힐 수 있습니다.
...

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

오류: 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"

이는 이전 배포가 Helm2로 배포되었기 때문이며, Helm3와 호환되지 않습니다.

문제를 해결하려면 업그레이드 안내서를 따르세요.