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 업데이트로 인해 레거시 쉼(shimmed) heroku/buildpacks:20 및 heroku/builder-classic:22 이미지는 이제 경고 대신 오류를 생성합니다.

이 문제를 해결하기 위해 heroku/builder:* 빌더 이미지로 마이그레이션해야 합니다. 임시 해결 방법으로 환경 변수 설정을 통해 오류를 건너뛸 수도 있습니다.

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

마이그레이션하기 전에 각 사양 릴리스의 릴리스 노트를 읽어 잠재적인 브레이킹 변경 사항을 확인해야 합니다.
이 경우 관련 빌드팩 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

/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로 배포할 때 다음과 같은 메시지를 볼 수 있습니다:

기존 PostgreSQL 데이터베이스가 사용 중단된 채널 1에 설치되어 있지만 현재 채널은 2로 설정되어 있습니다. 기본 채널은 GitLab 13.0에서 2로 변경되었습니다.
[...]

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

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

이 오류가 발생하면 다음 중 하나의 작업을 수행할 수 있습니다:

  • 경고를 안전하게 무시하고 AUTO_DEVOPS_POSTGRES_CHANNEL을 1로 설정하여 채널 1 PostgreSQL 데이터베이스를 계속 사용할 수 있습니다. 그런 다음 다시 배포하세요.

  • 채널 1 PostgreSQL 데이터베이스를 삭제하고 AUTO_DEVOPS_POSTGRES_DELETE_V1을 비어 있지 않은 값으로 설정하여 새로운 채널 2 데이터베이스를 설치할 수 있습니다. 그 후 다시 배포하세요.

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

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

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

오류: "": 배포 종류에 대한 매칭이 없습니다. 버전 "extensions/v1beta1"에서

Kubernetes 클러스터를 v1.16+로 업그레이드한 후, Auto DevOps로 배포할 때 다음과 같은 메시지를 볼 수 있습니다:

업그레이드 실패
오류: 객체로 디코딩하는 독자가 실패했습니다: "": 배포 종류에 대한 매칭이 없습니다. 버전 "extensions/v1beta1"에서

이 오류는 환경 네임스페이스에서 현재 배포가 Kubernetes v1.16+에 존재하지 않는 사용 중단/제거된 API로 배포된 경우 발생할 수 있습니다. 예를 들어, 클러스터 내 PostgreSQL이 이전 방식으로 설치된 경우, 해당 리소스는 extensions/v1beta1 API를 통해 생성되었습니다. 하지만, 배포 리소스는 v1.16에서 app/v1 API로 이동되었습니다.

이러한 구식 리소스를 복구하려면 현재 배포를 변환하여 구형 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" # auto-depoy-image v2 이상을 사용 중인 경우 "v3"로 지정하세요.

  2. 작업 <environment-name>:map-deprecated-api를 실행합니다. 이 작업이 성공적으로 완료된 후 다음 단계로 진행하세요. 다음과 같은 출력을 볼 수 있습니다:

    2020/10/06 07:20:49 사용 중단되었거나 제거된 Kubernetes API를 찾았습니다:
"apiVersion: extensions/v1beta1
kind: Deployment"
지원되는 API 동등:
"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+에서는 더 이상 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 마이그레이션”에서 확인할 수 있습니다.

오류: release .... 실패: 조건을 기다리는 동안 시간 초과

Auto DevOps를 시작할 때 애플리케이션을 처음 배포할 때 이 오류가 발생할 수 있습니다:

INSTALL FAILED
PURGING CHART
오류: staging release 실패: 조건을 기다리는 동안 시간 초과

이는 배포 과정 중에 시도된 생존성(또는 준비성) 프로브가 실패했기 때문일 가능성이 높습니다. 기본적으로 이러한 프로브는 배포된 애플리케이션의 루트 페이지에 대해 포트 5000에서 실행됩니다. 애플리케이션이 루트 페이지에서 아무 것도 제공하도록 구성되지 않았거나 5000이 아닌 특정 포트에서 실행되도록 구성된 경우, 이 점검이 실패합니다.

실패하면, 관련 Kubernetes 네임스페이스의 이벤트에서 이러한 실패를 볼 수 있어야 합니다. 이러한 이벤트는 다음과 같은 예시로 보입니다:

LAST SEEN   TYPE      REASON                   OBJECT                                            MESSAGE
3m20s       Warning   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
3m32s       Warning   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>
  1. 변경 사항을 커밋합니다.

변경 사항을 커밋한 후, 이후의 프로브는 새로 정의된 포트를 사용해야 합니다. 검사되는 페이지는 livenessProbe.path 및 readinessProbe.path 값을 덮어 씌움으로써 변경할 수 있으며(이 값들은 기본 values.yaml 파일에 표시되어 있음) 같은 방식으로 사용됩니다.