Auto DevOps 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 문서 페이지의 정보는 Auto DevOps를 사용할 때 발생하는 일반적인 오류와 가능한 대처 방법을 설명합니다.

Helm 커맨드 추적

CI/CD 변수 TRACE를 어떤 값이든 설정하여 Helm 커맨드가 자세한 출력을 생성하도록 할 수 있습니다. 이 출력을 사용하여 Auto DevOps 배포 문제를 진단할 수 있습니다.

일부 Auto DevOps 배포 문제는 고급 Auto DevOps 구성 변수를 변경하여 해결할 수 있습니다. Auto DevOps CI/CD 변수 사용자 정의에 대해 더 읽어보세요.

빌드팩 선택 불가능

다음 오류와 함께 Auto Test가 언어나 프레임워크를 감지하지 못하면 실패할 수 있습니다. 

Step 5/11 : RUN /bin/herokuish buildpack build
 ---> Running in eb468cd46085
    -----> Unable to select a buildpack
The command '/bin/sh -c /bin/herokuish buildpack build' returned a non-zero code: 1

다음은 가능한 이유입니다:

  • 애플리케이션이 빌드팩이 찾고 있는 핵심 파일이 누락되었을 수 있습니다. Ruby 애플리케이션은 올바르게 감지되려면 ‘Gemfile’이 필요하지만 ‘Gemfile’ 없이 Ruby 앱을 작성하는 것도 가능합니다.
  • 애플리케이션에 대한 빌드팩이 없을 수 있습니다. 사용자 정의 빌드팩을 지정해 보세요.

빌더 선셋 오류

이 Heroku 업데이트로 인해 레거시의 heroku/buildpacks:20 및 heroku/builder-classic:22 이미지는 경고가 아닌 오류를 생성합니다.

이 문제를 해결하려면 heroku/builder:* 빌더 이미지로 마이그레이션해야 합니다. 일시적으로 해결 방법으로 에러를 건너뛸 수도 있습니다.

heroku/builder:*로 마이그레이션

마이그레이션하기 전에 각 spec 릴리즈를 위한 릴리스 노트를 읽어 잠재적인 파괴적 변경 사항을 결정해야 합니다. 이 경우, 관련된 빌드팩 API 버전은 0.6 및 0.7입니다. 이러한 파괴적 변경은 특히 빌드팩 유지 관리자들에게 중요합니다.

변경 사항에 대한 자세한 정보는 스펙 자체를 비교하여 확인할 수 있습니다.

에러 건너뛰기

일시적으로 에러를 건너뛰려면 ALLOW_EOL_SHIMMED_BUILDER 환경 변수를 설정하고 전달해야 합니다. 

variables:
  ALLOW_EOL_SHIMMED_BUILDER: "1"
  AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES: ALLOW_EOL_SHIMMED_BUILDER

/ only except를 사용한 Auto DevOps 확장 파이프라인 실패

파이프라인이 다음 메시지와 함께 실패하면: 

Unable to create pipeline

  jobs:test config key may not be used with `rules`: only

이 오류는 포함된 작업의 규칙 구성이 only 또는 except 구문으로 재정의되었을 때 나타납니다. 이 문제를 해결하려면 다음 중 하나를 수행해야 합니다:

Kubernetes 네임스페이스 생성 실패

GitLab이 프로젝트를 위해 Kubernetes 네임스페이스와 서비스 계정을 생성하지 못하면 Auto Deploy가 실패합니다. 이 문제에 대한 디버깅 도움은 배포 작업 실패 해결을 참조하세요.

기존 PostgreSQL 데이터베이스 감지

GitLab 13.0으로 업그레이드한 후 Auto DevOps로 배포할 때 이 메시지를 만날 수 있습니다. 

Detected an existing PostgreSQL database installed on the
deprecated channel 1, but the current channel is set to 2. The default
channel changed to 2 in GitLab 13.0.
[...]

Auto DevOps는 기본적으로 클러스터 내 PostgreSQL 데이터베이스를 애플리케이션과 함께 설치합니다. 기본 설치 방법이 GitLab 13.0에서 변경되었으며 기존 데이터베이스를 업그레이드하려면 사용자의 개입이 필요합니다. 두 가지 설치 방법은 다음과 같습니다:

  • 채널 1 (deprecated): 연관된 Helm 차트의 종속성으로 데이터베이스를 가져옵니다. Kubernetes 버전 1.15까지만 지원합니다.
  • 채널 2 (현재): 데이터베이스를 독립적인 Helm 차트로 설치합니다. Kubernetes 버전 1.16 이상에서 클러스터 내 데이터베이스 기능을 사용하려면 필요합니다.

이 오류를 받으면 다음 조치 중 하나를 취할 수 있습니다:

  • 경고를 안전하게 무시하고 계속해서 채널 1 PostgreSQL 데이터베이스를 사용하도록 AUTO_DEVOPS_POSTGRES_CHANNEL을 1로 설정하고 재배포합니다.

  • 채널 1 PostgreSQL 데이터베이스를 삭제하고 새로운 채널 2 데이터베이스를 설치할 수 있습니다. AUTO_DEVOPS_POSTGRES_DELETE_V1에 비어 있지 않은 값을 설정하고 재배포합니다.

    경고: 채널 1 PostgreSQL 데이터베이스를 삭제하면 기존의 채널 1 데이터베이스와 그 데이터가 영구적으로 삭제됩니다. 더 많은 정보 및 데이터베이스 백업 및 업그레이드에 대한 정보는 PostgreSQL 업그레이드를 참조하세요.

  • 클러스터 내 데이터베이스를 사용하지 않는 경우 POSTGRES_ENABLED를 false로 설정하고 재배포할 수 있습니다. 이 옵션은 클러스터 내 PostgreSQL 종속성이 없는 사용자 정의 차트 사용자에게 특히 유용합니다. 데이터베이스 자동 감지는 릴리스의 postgresql.enabled Helm 값을 기반으로 하며, 차트가 해당 변수를 사용하더라도 이 값은 POSTGRES_ENABLED CI/CD 변수에 따라 설정되고 Helm에 의해 유지됩니다.

경고: POSTGRES_ENABLED를 false로 설정하면 환경의 기존 채널 1 데이터베이스가 영구적으로 삭제됩니다.

“Error: unable to recognize “”: no matches for kind “Deployment” in version “extensions/v1beta1””

Kubernetes 클러스터를 v1.16+로 업그레이드한 후 Auto DevOps로 배포할 때 이 메시지가 나타날 수 있습니다. 

UPGRADE FAILED
Error: failed decoding reader into objects: unable to recognize "": no matches for kind "Deployment" in version "extensions/v1beta1"

현재 배포에 사용된 리소스가 v1.16+의 Kubernetes에 존재하지 않는 단순화된/제거된 API로 생성된 경우 발생할 수 있습니다. 예를 들어, 클러스터 내 PostgreSQL이 이전 방식으로 설치된 경우, 리소스가 extensions/v1beta1 API를 사용하여 생성되었습니다. 그러나 v1.16에서 배포 리소스는 app/v1 API로 옮겨졌습니다.

이러한 낡은 리소스를 복구하려면 현재 배포를 새로운 API와 매핑하여 전환해야 합니다. 이 문제에 대한 mapkubeapis라는 도우미 도구가 있습니다. Auto DevOps에서 이 도구를 사용하려면 다음 단계를 따르세요:

  1. 다음 내용으로 .gitlab-ci.yml을 수정하세요: 

    include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/shinya.maeda/ci-templates/-/raw/master/map-deprecated-api.gitlab-ci.yml

variables:
  HELM_VERSION_FOR_MAPKUBEAPIS: "v2" # 만약 자동 배포 이미지 v2 이상을 사용 중이라면 "v3"로 지정하세요.

  2. <environment-name>:map-deprecated-api 작업을 실행하세요. 이 작업이 성공했는지 확인한 후 다음 단계로 이동해야 합니다. 다음과 유사한 출력이 표시됩니다: 

    2020/10/06 07:20:49 Found deprecated or removed Kubernetes API:
"apiVersion: extensions/v1beta1
kind: Deployment"
Supported API equivalent:
"apiVersion: apps/v1
kind: Deployment"

  3. 이전 버전의 .gitlab-ci.yml로 복귀하세요. 더 이상 보충 템플릿 map-deprecated-api를 포함할 필요가 없습니다.

  4. 보통대로 배포를 계속하세요.

오류: 유효한 차트 저장소가 아니거나 연결할 수 없습니다

공식 CNCF 블로그 게시물에서 발표된 대로, 안정화된 Helm 차트 저장소는 2020년 11월 13일에 사용 중지되고 제거되었습니다. 이 날짜 이후에 다음 오류를 만날 수 있습니다: 

오류: 초기화 오류: "https://kubernetes-charts.storage.googleapis.com"이(가) 유효한 차트 저장소가 아니거나 연결할 수 없는 것으로 보입니다

일부 GitLab 기능은 안정화된 차트에 의존했습니다. 영향을 완화하기 위해, 이를 새로운 공식 저장소로 변경하거나 GitLab이 유지 관리하는 Helm Stable Archive 저장소를 사용하도록 변경했습니다. Auto Deploy에는 예제 수정이 포함되어 있습니다.

Auto Deploy에서는 v1.0.6+의 auto-deploy-image에서 더 이상 사용되지 않는 안정화된 저장소를 helm 명령에 추가하지 않습니다. 사용자 지정 차트를 사용하고 이전에 사용하던 안정화된 저장소에 의존하는 경우 다음 예와 같이 이전 auto-deploy-image를 지정하세요: 

include:
  - template: Auto-DevOps.gitlab-ci.yml

.auto-deploy:
  image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5"

이 접근 방식은 안정화된 저장소가 제거되면 작동을 중지하므로 최종적으로 사용자 정의 차트를 수정해야 합니다.

사용자 정의 차트를 수정하려면:

  1. 차트 디렉터리에서 requirements.yaml 파일의 repository 값을 다음과 같이 수정하세요: 

    repository: "https://kubernetes-charts.storage.googleapis.com/"

    다음으로 변경: 

    repository: "https://charts.helm.sh/stable"
  2. 차트 디렉터리에서 Auto DevOps와 동일한 Helm 주 버전을 사용하여 helm dep update .를 실행하세요.
  3. requirements.yaml 파일의 변경 사항을 커밋하세요.
  4. 이전에 requirements.lock 파일이 있는 경우 파일의 변경 사항을 커밋하세요. 차트에 이전에 requirements.lock 파일이 없는 경우 새 파일을 커밋할 필요가 없습니다. 이 파일은 선택 사항이지만 존재하는 경우 다운로드된 종속성의 무결성을 확인하는 데 사용됩니다.

자세한 내용은 이슈 #263778, “안정화된 Helm 저장소에서 PostgreSQL로 이주”에서 확인할 수 있습니다.

오류: 릴리스 ... 실패: 조건을 기다리는 동안 시간이 초과됨

Auto DevOps를 시작할 때 응용 프로그램을 처음 배포할 때 이 오류를 만날 수 있습니다: 

설치 실패
차트 삭제 중
오류: 릴리스 staging 실패: 조건을 기다리는 동안 시간이 초과됨

이는 배포 프로세스 중에 실패한 liveness(또는 readiness) 프로브로 인한 가능성이 가장 높습니다. 기본적으로 이러한 프로브는 배포된 애플리케이션의 루트 페이지에서 5000번 포트에 대해 실행됩니다. 애플리케이션이 루트 페이지에서 서비스를 구성하지 않았거나 5000번 포트 외의 특정 포트에서 실행되도록 구성된 경우 이 확인이 실패합니다.

이 실패가 발생하면 관련된 Kubernetes 네임스페이스의 이벤트에서 다음 예와 유사한 실패를 확인할 수 있어야 합니다: 

마지막 확인 시간   유형      이유                   개체                                                     메시지
3분20초       경고      Unhealthy                pod/staging-85db88dcb6-rxd6g                      Readiness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused
3분32초       경고      Unhealthy                pod/staging-85db88dcb6-rxd6g                      Liveness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused

릴리얼이된 포트를 변경하려면 Auto DevOps에서 사용되는 Helm 차트에 사용자 지정 값을 전달하세요:

  1. 리포지토리 루트에 .gitlab/auto-deploy-values.yaml이라는 디렉터리 및 파일을 생성하세요.

  2. 파일에 다음 내용을 입력하고 실제 애플리케이션이 사용하는 포트 번호로 포트 값을 변경하세요: 

    service:
  internalPort: <port_value>
  externalPort: <port_value>

  3. 변경 사항을 서브밋하세요.

변경 사항을 서브밋한 후 이후 프로브는 새로 정의된 포트를 사용해야 합니다. 프로브되는 페이지는 동일한 방식으로 기본 values.yaml 파일에 표시된 livenessProbe.path 및 readinessProbe.path 값을 오버라이딩하여 변경할 수 있습니다.