v2.3에서 v2.4로 업그레이드

v2.3에서 v2.4로 업그레이드 (v2.3 to 2.4)

v2.4는 project 필터가 projects로 바뀌는 API 변경, KSonnet·Helm 2 지원 제거, 새 exec·logs RBAC 리소스 도입 등 여러 변경이 있어요. RBAC를 명시적으로 정리하고, 사이드카 플러그인의 /tmp 볼륨과 환경 변수 구성을 새 규칙에 맞게 바꿔야 해요.

출처: 문서

본문

알려진 이슈 (Known Issues)

2.4.27 이전의 깨진 `project` 필터

Argo CD 2.4.0은 project 필터를 projects로 이름을 바꾸는, 호환성이 깨지는 API 변경을 도입했어요.

API 클라이언트에 미치는 영향

REST API로 Argo CD API 서버와 통신하는 다른 API 클라이언트에도 비슷한 문제가 적용돼요. 클라이언트가 project 필드를 사용해 프로젝트를 필터링한다면 필터가 적용되지 않아요. 실패하는 project 필터는, 예를 들어 삭제할 Application 목록을 만드는 데 의존한다면 심각한 결과를 초래할 수 있어요.

CLI 클라이언트에 미치는 영향

v2.4.0보다 오래된 CLI 클라이언트는 클라이언트 측 필터링에 의존하므로 이 버그의 영향을 받지 않아요.

문제 해결 방법

Argo CD >=2.4.27, >=2.5.15 또는 >=2.6.6으로 업그레이드하세요. 이 버전의 Argo CD는 project와 projects를 모두 유효한 필터로 받아들여요.

KSonnet 지원 제거

Ksonnet은 2019년에 디프리케이트되었고 더 이상 유지 관리되지 않아요. 이제 Argo CD에서 제거할 때가 됐어요.

Helm 2 지원 제거

Helm 2는 2020년 11월부터 공식적으로 지원되지 않았어요. 원활한 전환을 보장하기 위해 Helm 2 지원이 Argo CD에 유지되어 왔어요. Helm 3가 안정적이라고 판단되므로 이제 Helm 2 지원을 제거할 때예요.

SHA-1 서명 해시 알고리즘을 사용하는 비공개 저장소 SSH 키 지원 제거

참고: 이 변경은 2.3.7과 2.2.12에도 백포트됐어요.

Argo CD 2.4는 베이스 이미지를 Ubuntu 20.04에서 Ubuntu 22.04로 업그레이드했고, 이로 인해 OpenSSH가 8.9로 올라갔어요. 8.8부터 OpenSSH는 ssh-rsa SHA-1 키 서명 알고리즘 지원을 제거했어요.

서명 알고리즘은 키를 생성할 때 사용되는 알고리즘과 다릅니다. 키를 업데이트할 필요는 없어요.

서명 알고리즘은 연결이 설정될 때 SSH 서버와 협상돼요. 클라이언트가 허용되는 서명 알고리즘 목록을 제시하고, 서버에 일치하는 것이 있으면 연결이 진행돼요. 최신 git 제공자의 대부분 SSH 서버에서는 ssh-rsa 외에 허용 가능한 알고리즘을 사용할 수 있어야 해요.

Argo CD 2.4로 업그레이드하기 전에, SSH 인증을 사용하는 git 제공자가 rsa-ssh보다 최신 알고리즘을 지원하는지 확인하세요.

SSH 버전이 >= 8.9 (Argo CD가 사용하는 버전)인지 확인하세요. 아니라면 계속하기 전에 업그레이드하세요.

ssh -V

예시 출력: OpenSSH_8.9p1 Ubuntu-3, OpenSSL 3.0.2 15 Mar 2022

최신 OpenSSH 버전을 갖추면 OpenSSH 8.8 릴리스 노트의 지침을 따르세요:

호스트 인증에 약한 ssh-rsa 공개 키 알고리즘을 사용하는 서버인지 확인하려면, ssh(1)의 허용 목록에서 ssh-rsa 알고리즘을 제거한 뒤 연결을 시도해 보세요: ssh -oHostKeyAlgorithms=-ssh-rsa user@host

호스트 키 검증이 실패하고 다른 지원되는 호스트 키 유형도 없다면, 해당 호스트의 서버 소프트웨어를 업그레이드해야 해요.

서버가 허용 가능한 버전을 지원하지 않으면 다음과 유사한 오류가 발생해요:

$ ssh -oHostKeyAlgorithms=-ssh-rsa vs-ssh.visualstudio.com
Unable to negotiate with 20.42.134.1 port 22: no matching host key type found. Their offer: ssh-rsa

이것은 서버가 지원하는 키 서명 알고리즘을 업데이트해야 하며, Argo CD가 그 서버에 연결하지 못한다는 뜻이에요.

우회 방법 (Workaround)

OpenSSH 8.8 릴리스 노트는 서버의 키 서명 알고리즘 구성을 변경할 수 없을 때 사용할 수 있는 우회 방법을 설명해요.

호환성 문제는 업그레이드되지 않았거나 SSH 프로토콜의 개선을 밀접하게 따라가지 않은 오래된 SSH 구현에 연결할 때 더 자주 발생해요. 이러한 경우에는 HostkeyAlgorithms 및 PubkeyAcceptedAlgorithms 옵션을 통해 RSA/SHA1을 선택적으로 다시 활성화하여 연결 및/또는 사용자 인증을 허용해야 할 수 있어요. 예를 들어 ~/.ssh/config의 다음 스탠자는 단일 대상 호스트에 대한 호스트 및 사용자 인증에서 RSA/SHA1을 활성화해요: Host old-host HostkeyAlgorithms +ssh-rsa PubkeyAcceptedAlgorithms +ssh-rsa

RSA/SHA1은 레거시 구현이 업그레이드되거나 다른 키 유형(예: ECDSA 또는 Ed25519)으로 재구성될 때까지의 임시 조치로만 활성화하는 것이 좋아요.

이를 Argo CD에 적용하려면, 원하는 ssh 구성 파일이 담긴 ConfigMap을 만들고 /home/argocd/.ssh/config에 마운트하면 돼요.

새 `exec` 리소스에 맞춰 RBAC 구성

2.4는 새 exec RBAC 리소스를 도입해요.

2.4로 업그레이드하면, 리소스 필드에 *가 있고 액션 필드에 create 또는 *가 있는 RBAC 정책은 자동으로 exec 권한을 부여해요.

새 권한 부여를 피하려면 기존 정책을 이전 리소스를 명시적으로 나열한 새 정책 목록으로 바꾸세요.

exec 기능은 기본적으로 비활성화되어 있지만, 최소 필요한 권한을 적용하려면 RBAC 구성을 한 번 더 확인하는 것이 좋아요.

예시

p, role:org-admin, *, create, my-proj/*, allow

새로:

p, role:org-admin, clusters, create, my-proj/*, allow
p, role:org-admin, projects, create, my-proj/*, allow
p, role:org-admin, applications, create, my-proj/*, allow
p, role:org-admin, repositories, create, my-proj/*, allow
p, role:org-admin, certificates, create, my-proj/*, allow
p, role:org-admin, accounts, create, my-proj/*, allow
p, role:org-admin, gpgkeys, create, my-proj/*, allow

logs RBAC 강제 적용 활성화

2.4는 logs를 새 RBAC 리소스로 도입했어요. 2.3에서는 applications, get 접근이 있는 사용자는 자동으로 logs 접근을 얻었어요. 2.5에서는 logs, get 접근을 명시적으로 부여해야 해요. logs RBAC 강제 적용은 2.4에서 플래그로 활성화할 수 있어요. 2.5에서 더 쉬운 업그레이드 경험을 위해 지금 플래그를 활성화하는 것을 권장해요.

중요

logs RBAC 강제 적용은 2.5에서 기본적으로 활성화되지 않아요. 이 결정은 logs 리소스 접근을 부여할 메커니즘을 제공하지 않는 Project Roles 아래에서 logs 접근이 깨지는 것을 피하기 위해 내려졌어요.

logs RBAC 강제 적용을 활성화하려면 argocd-cm ConfigMap에 다음을 추가하세요:

server.rbac.log.enforce.enable: "true"

같은 사용자가 계속 logs 접근을 갖게 하려면 applications, get 접근을 부여하는 모든 줄을 찾아 logs, get도 함께 부여하세요.

예시

p, role:staging-db-admins, applications, get, staging-db-admins/*, allow

p, role:test-db-admins, applications, *, staging-db-admins/*, allow

새로:

p, role:staging-db-admins, applications, get, staging-db-admins/*, allow
p, role:staging-db-admins, logs, get, staging-db-admins/*, allow

p, role:test-db-admins, applications, *, staging-db-admins/*, allow
p, role:test-db-admins, logs, get, staging-db-admins/*, allow

Pod Logs UI

2.4.9부터 pod 뷰의 LOGS 탭은 명시적인 allow get logs 정책이 있는 사용자에게만 UI에 표시돼요.

2.4.9 이전의 알려진 pod logs UI 이슈

명시적인 allow get logs 정책이 없는 사용자가 pod 뷰에서 "LOGS" 탭을 누르면, 화면 하단에 빨간 "unable to load data: Internal error"가 표시되고 "Failed to load data, please try again"이 표시돼요.

전용 Service Account로 repo-server 테스트

보안 강화로, argocd-repo-server Deployment는 default 대신 자체 Service Account를 사용해요.

repo-server가 default Service Account를 사용하는 것에 의존하는 커스텀 환경(예: 인증에 Service Account를 사용하는 플러그인)이 있다면, 2.4 업그레이드를 프로덕션에 배포하기 전에 반드시 테스트하세요.

플러그인 (Plugins)

사이드카 플러그인에서 공유 볼륨 제거

보안 강화로, 사이드카 플러그인은 더 이상 repo-server와 /tmp 디렉터리를 공유하지 않아요.

사이드카 플러그인이 하나 이상 활성화되어 있다면, 각 사이드카의 /tmp 볼륨 마운트를 플러그인별로 고유한 볼륨을 사용하도록 바꾸세요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
spec:
  template:
    spec:
      containers:
      - name: your-plugin-name
        volumeMounts:
        - mountPath: /tmp
          name: your-plugin-name-tmp
      volumes:
        # Add this volume.
        - name: your-plugin-name-tmp
          emptyDir: {}

새로 접두사가 붙은 환경 변수를 사용하도록 플러그인 업데이트

사용자가 제공한 환경 변수에 의존하는 플러그인을 사용한다면, Argo CD 2.4와 호환되도록 업데이트해야 해요. 다음은 Application spec의 plugin 섹션에 있는 사용자 제공 환경 변수 예시예요:

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  source:
    plugin:
      env:
        - name: FOO
          value: bar

앞으로 모든 사용자 제공 환경 변수는 플러그인의 init, generate 또는 discover 명령으로 보내지기 전에 ARGOCD_ENV_ 접두사가 붙어요. 이렇게 하면 사용자가 잠재적으로 민감한 환경 변수를 설정하지 못하게 돼요.

사용자 제공 환경 변수를 처리하는 커스텀 플러그인을 작성했다면, 새 접두사를 처리하도록 업데이트하세요.

Argo CD 2.4 지원을 명시적으로 공지하지 않는 타사 플러그인을 사용한다면 접두사가 붙은 환경 변수를 처리하지 못할 수 있어요. Argo CD 2.4로 업그레이드하기 전에 플러그인 작성자에게 이슈를 열고 지원을 확인하세요.

사이드카 플러그인에 필요한 모든 환경 변수가 있는지 확인

< 2.4의 버그로 인해 init과 generate 명령이 메인 repo-server 컨테이너의 환경 변수를 받아서 플러그인 사이드카의 환경 변수보다 우선하게 됐어요.

2.4부터 사이드카 플러그인은 메인 repo-server 컨테이너의 환경 변수를 받지 않아요. 사이드카 플러그인의 기능에 필요한 모든 환경 변수가 사이드카 플러그인에 설정되어 있는지 확인하세요.

argocd-cm 플러그인은 메인 repo-server 컨테이너의 환경 변수를 계속 받아요.

더 알아보기 (Learn more)

이 문서의 원문: v2.3 to 2.4
Argo CD 공식 문서: https://argo-cd.readthedocs.io

v2.3에서 v2.4로 업그레이드