TLS 구성
TLS 구성 (TLS configuration)
Argo CD는 세 개의 인바운드 TLS 엔드포인트를 제공하며 각각 인증서를 구성할 수 있어요. 기본값은 자체 서명 인증서지만, 운영 환경에서는 cert-manager 같은 도구나 자체 CA를 사용해 명시적으로 구성하는 것이 일반적이에요.
출처: 문서
본문
[!TIP] repo-server 컴포넌트 간 상호 TLS가 필요하신가요? repo-server용 상호 TLS (mTLS)를 참고하세요.
Argo CD는 구성할 수 있는 세 개의 인바운드 TLS 엔드포인트를 제공해요:
argocd-server워크로드의 사용자 대면(user-facing) 엔드포인트. UI와 API를 제공해요.argocd-repo-server의 엔드포인트.argocd-server와argocd-application-controller워크로드가 리포지토리 작업을 요청하기 위해 접근해요.argocd-dex-server의 엔드포인트.argocd-server가 OIDC 인증을 처리하기 위해 접근해요.
기본적으로 그리고 추가 구성 없이 이 엔드포인트들은 자동 생성된 자체 서명 인증서를 사용하도록 설정돼요. 하지만 대부분의 사용자는 cert-manager 같은 자동화 수단이나 자체 전용 Certificate Authority를 사용해서 이 TLS 엔드포인트의 인증서를 명시적으로 구성하고 싶어할 거예요.
TLS 구성 빠른 참조 (TLS Configuration Quick Reference)
인증서 구성 개요 (Certificate Configuration Overview)
| 컴포넌트 | Secret 이름 | 핫 리로드 | 기본 인증서 | 필수 SAN 항목 |
|---|---|---|---|---|
argocd-server |
argocd-server-tls |
✅ 예 | 자체 서명 | 외부 호스트 이름 (예: argocd.example.com) |
argocd-repo-server |
argocd-repo-server-tls |
❌ 재시작 필요 | 자체 서명 | DNS:argocd-repo-server, DNS:argocd-repo-server.argocd.svc |
argocd-dex-server |
argocd-dex-server-tls |
❌ 재시작 필요 | 자체 서명 | DNS:argocd-dex-server, DNS:argocd-dex-server.argocd.svc |
컴포넌트 간 TLS (Inter-Component TLS)
| 연결 | 권장 파라미터 | 레거시 파라미터 (deprecated) | 평문 파라미터 | 기본 동작 |
|---|---|---|---|---|
argocd-server → argocd-repo-server |
--repo-server-ca-cert-path |
--repo-server-strict-tls |
--repo-server-plaintext |
비검증 TLS |
argocd-server → argocd-dex-server |
— | --dex-server-strict-tls |
--dex-server-plaintext |
비검증 TLS |
argocd-application-controller → argocd-repo-server |
--repo-server-ca-cert-path |
--repo-server-strict-tls |
--repo-server-plaintext |
비검증 TLS |
argocd-applicationset-controller → argocd-repo-server |
--repo-server-ca-cert-path |
--repo-server-strict-tls |
--repo-server-plaintext |
비검증 TLS |
argocd-notifications-controller → argocd-repo-server |
--argocd-repo-server-ca-cert-path |
--argocd-repo-server-strict-tls |
--argocd-repo-server-plaintext |
비검증 TLS |
인증서 우선순위 (argocd-server 전용)
argocd-server-tlssecret (권장)argocd-secretsecret (deprecated)- 자동 생성된 자체 서명 인증서
argocd-server용 TLS 구성 (Configuring TLS for argocd-server)
argocd-server의 인바운드 TLS 옵션 (Inbound TLS options for argocd-server)
argocd-server 워크로드에 대한 특정 TLS 옵션은 커맨드라인 파라미터를 설정해서 구성할 수 있어요. 사용 가능한 파라미터는 다음과 같아요:
| 파라미터 | 기본값 | 설명 |
|---|---|---|
--insecure |
false |
TLS를 완전히 비활성화 |
--tlsminversion |
1.2 |
클라이언트에 제공할 최소 TLS 버전 |
--tlsmaxversion |
1.3 |
클라이언트에 제공할 최대 TLS 버전 |
--tlsciphers |
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_RSA_WITH_AES_256_GCM_SHA384 |
클라이언트에 제공할 콜론으로 구분된 TLS cipher suite 목록 |
argocd-server가 사용하는 TLS 인증서 (TLS certificates used by argocd-server)
argocd-server가 사용하는 TLS 인증서를 구성하는 방법은 두 가지가 있어요:
argocd-server-tlssecret의tls.crt와tls.key키를 설정해 인증서와 해당 개인 키의 PEM 데이터를 보관하는 것.argocd-server-tlssecret은tls유형일 수 있지만 그럴 필요는 없어요.argocd-secretsecret의tls.crt와tls.key키를 설정해 인증서와 해당 개인 키의 PEM 데이터를 보관하는 것. 이 방법은 deprecated로 간주되며 역호환성 목적으로만 존재해요. 더 이상argocd-secret을 변경해서 TLS 인증서를 덮어쓰는 데 사용해서는 안 돼요.
Argo CD는 argocd-server 엔드포인트에 사용할 TLS 인증서를 다음과 같이 결정해요:
argocd-server-tlssecret이 존재하고tls.crt와tls.key키에 유효한 키 쌍을 포함하면, 이 키가argocd-server엔드포인트의 인증서로 사용돼요.- 그렇지 않고
argocd-secretsecret이tls.crt와tls.key키에 유효한 키 쌍을 포함하면, 이 키가argocd-server엔드포인트의 인증서로 사용돼요. - 언급된 두 secret 중 어느 것에서도
tls.crt와tls.key키를 찾지 못하면, Argo CD는 자체 서명 인증서를 생성해argocd-secretsecret에 저장해요.
argocd-server-tls secret은 argocd-server가 사용할 TLS 구성 정보만 포함하며 cert-manager나 SealedSecrets 같은 타사 도구로 관리해도 안전해요.
기존 키 쌍에서 이 secret을 수동으로 만들려면 kubectl을 사용할 수 있어요:
kubectl create -n argocd secret tls argocd-server-tls \
--cert=/path/to/cert.pem \
--key=/path/to/key.pem
Argo CD는 argocd-server-tls secret의 변경을 자동으로 감지하며, 갱신된 인증서를 사용하기 위해 재시작이 필요하지 않아요.
argocd-repo-server용 인바운드 TLS 구성 (Configuring inbound TLS for argocd-repo-server)
argocd-repo-server의 인바운드 TLS 옵션 (Inbound TLS options for argocd-repo-server)
argocd-repo-server 워크로드에 대한 특정 TLS 옵션은 커맨드라인 파라미터를 설정해서 구성할 수 있어요. 사용 가능한 파라미터는 다음과 같아요:
| 파라미터 | 기본값 | 설명 |
|---|---|---|
--disable-tls |
false |
TLS를 완전히 비활성화 |
--tlsminversion |
1.2 |
클라이언트에 제공할 최소 TLS 버전 |
--tlsmaxversion |
1.3 |
클라이언트에 제공할 최대 TLS 버전 |
--tlsciphers |
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_RSA_WITH_AES_256_GCM_SHA384 |
클라이언트에 제공할 콜론으로 구분된 TLS cipher suite 목록 |
argocd-repo-server가 사용하는 인바운드 TLS 인증서 (Inbound TLS certificates used by argocd-repo-server)
argocd-repo-server 워크로드가 사용하는 TLS 인증서를 구성하려면, Argo CD가 실행 중인 네임스페이스에 tls.crt와 tls.key 키에 인증서 키 쌍이 저장된 argocd-repo-server-tls라는 secret을 만드세요. 이 secret이 존재하지 않으면 argocd-repo-server는 자체 서명 인증서를 생성해 사용해요.
이 secret을 만들려면 kubectl을 사용할 수 있어요:
kubectl create -n argocd secret tls argocd-repo-server-tls \
--cert=/path/to/cert.pem \
--key=/path/to/key.pem
인증서가 자체 서명된 경우 CA 인증서 내용으로 ca.crt를 secret에 추가해야 해요.
argocd-server와 달리 argocd-repo-server는 이 secret의 변경을 자동으로 감지할 수 없다는 점을 유의하세요. 이 secret을 만들거나(업데이트하면) argocd-repo-server 파드를 재시작해야 해요.
또한 인증서는 argocd-repo-server에 대한 올바른 SAN 항목으로 발급되어야 합니다. 워크로드가 리포지토리 서버에 연결하는 방식에 따라 최소한 DNS:argocd-repo-server와 DNS:argocd-repo-server.argo-cd.svc 항목을 포함해야 해요.
argocd-dex-server용 인바운드 TLS 구성 (Configuring inbound TLS for argocd-dex-server)
argocd-dex-server의 인바운드 TLS 옵션 (Inbound TLS options for argocd-dex-server)
argocd-dex-server 워크로드에 대한 특정 TLS 옵션은 커맨드라인 파라미터를 설정해서 구성할 수 있어요. 사용 가능한 파라미터는 다음과 같아요:
| 파라미터 | 기본값 | 설명 |
|---|---|---|
--disable-tls |
false |
TLS를 완전히 비활성화 |
argocd-dex-server가 사용하는 인바운드 TLS 인증서 (Inbound TLS certificates used by argocd-dex-server)
argocd-dex-server 워크로드가 사용하는 TLS 인증서를 구성하려면, Argo CD가 실행 중인 네임스페이스에 tls.crt와 tls.key 키에 인증서 키 쌍이 저장된 argocd-dex-server-tls라는 secret을 만드세요. 이 secret이 존재하지 않으면 argocd-dex-server는 자체 서명 인증서를 생성해 사용해요.
이 secret을 만들려면 kubectl을 사용할 수 있어요:
kubectl create -n argocd secret tls argocd-dex-server-tls \
--cert=/path/to/cert.pem \
--key=/path/to/key.pem
인증서가 자체 서명된 경우 CA 인증서 내용으로 ca.crt를 secret에 추가해야 해요.
argocd-server와 달리 argocd-dex-server는 이 secret의 변경을 자동으로 감지할 수 없다는 점을 유의하세요. 이 secret을 만들거나(업데이트하면) argocd-dex-server 파드를 재시작해야 해요.
또한 인증서는 argocd-dex-server에 대한 올바른 SAN 항목으로 발급되어야 합니다. 워크로드가 저장소 서버에 연결하는 방식에 따라 최소한 DNS:argocd-dex-server와 DNS:argocd-dex-server.argo-cd.svc 항목을 포함해야 해요.
Argo CD 컴포넌트 간 TLS 구성 (Configuring TLS between Argo CD components)
argocd-repo-server로의 TLS 구성 (Configuring TLS to argocd-repo-server)
argocd-server, argocd-application-controller, argocd-notifications-controller, argocd-applicationset-controller 컴포넌트는 TLS 위의 gRPC API를 사용해 argocd-repo-server와 통신해요. 기본적으로 argocd-repo-server는 시작 시 gRPC 엔드포인트에 사용할 비영구적(non-persistent) 자체 서명 인증서를 생성해요. argocd-repo-server는 K8s 컨트롤 플레인 API에 연결할 수단이 없으므로 이 인증서는 확인을 위해 외부 소비자에게 제공되지 않아요. 그래서 이 컴포넌트들은 argocd-repo-server에 비검증 연결을 사용해요.
이 동작을 보다 안전하게 변경해 이 컴포넌트들이 argocd-repo-server 엔드포인트의 TLS 인증서를 검증하도록 하려면 다음 단계를 수행해야 해요:
- 위에서 보여준 것처럼
argocd-repo-server가 사용할 영구 TLS 인증서를 만드세요 argocd-repo-server파드(들)를 재시작하세요argocd-server,argocd-application-controller,argocd-applicationset-controller의 파드 시작 파라미터를 CA 인증서 파일을 가리키는--repo-server-ca-cert-path파라미터를 포함하도록 수정하세요argocd-notifications-controller의 파드 시작 파라미터를 CA 인증서 파일을 가리키는--argocd-repo-server-ca-cert-path파라미터를 포함하도록 수정하세요
이제 argocd-server, argocd-application-controller, argocd-notifications-controller, argocd-applicationset-controller 워크로드는 제공된 CA 인증서로 argocd-repo-server의 TLS 인증서를 검증할 거예요.
[!NOTE] 레거시 경로 vs 권장 경로
--repo-server-strict-tls(notifications 컨트롤러의 경우--argocd-repo-server-strict-tls)는 레거시 경로예요. 설정되면 컴포넌트가argocd-repo-server-tlsKubernetes secret에서 repo-server 인증서를 자동 발견해요. 이 플래그는 deprecated이며 향후 릴리스에서 제거될 수 있어요.
--repo-server-ca-cert-path(notifications 컨트롤러의 경우--argocd-repo-server-ca-cert-path)는 권장 명시적 경로예요. CA 인증서 파일의 경로를 직접 제공해요. 이것은 mTLS 설정에 필요하며 어떤 CA를 신뢰할지 완전히 제어할 수 있게 해줘요. 자세한 내용은 repo-server용 상호 TLS (mTLS)를 참고하세요.
[!NOTE] 인증서 만료 (Certificate expiry)
인증서가 적절한 수명을 갖도록 하세요. 인증서를 교체할 때는 모든 워크로드를 재시작해야 인증서를 적용하고 제대로 동작한다는 점을 기억하세요.
argocd-dex-server로의 TLS 구성 (Configuring TLS to argocd-dex-server)
argocd-server는 TLS 위의 HTTPS API를 사용해 argocd-dex-server와 통신해요. 기본적으로 argocd-dex-server는 시작 시 HTTPS 엔드포인트에 사용할 비영구적 자체 서명 인증서를 생성해요. argocd-dex-server는 K8s 컨트롤 플레인 API에 연결할 수단이 없으므로 이 인증서는 확인을 위해 외부 소비자에게 제공되지 않아요. 그래서 argocd-server는 argocd-dex-server에 비검증 연결을 사용해요.
이 동작을 보다 안전하게 변경해 argocd-server가 argocd-dex-server 엔드포인트의 TLS 인증서를 검증하도록 하려면 다음 단계를 수행해야 해요:
- 위에서 보여준 것처럼
argocd-dex-server가 사용할 영구 TLS 인증서를 만드세요 argocd-dex-server파드(들)를 재시작하세요argocd-server의 파드 시작 파라미터를--dex-server-strict-tls파라미터를 포함하도록 수정하세요
이제 argocd-server 워크로드는 argocd-dex-server-tls secret에 저장된 인증서를 사용해 argocd-dex-server의 TLS 인증서를 검증할 거예요.
[!NOTE] 인증서 만료 (Certificate expiry)
인증서가 적절한 수명을 갖도록 하세요. 인증서를 교체할 때는 모든 워크로드를 재시작해야 인증서를 적용하고 제대로 동작한다는 점을 기억하세요.
argocd-repo-server로의 TLS 비활성화 (Disabling TLS to argocd-repo-server)
사이드카 프록시를 통한 mTLS가 관여하는 일부 시나리오(예: 서비스 메시)에서는 argocd-server, argocd-application-controller, argocd-notifications-controller, argocd-applicationset-controller에서 argocd-repo-server로의 연결이 TLS를 전혀 사용하지 않도록 구성하고 싶을 수 있어요.
이 경우 다음을 해야 해요:
- gRPC API에서 TLS를 비활성화하도록 pod 컨테이너의 시작 인자에
--disable-tls파라미터를 지정해argocd-repo-server를 구성하세요. 또한--listen 127.0.0.1파라미터를 지정해 수신 주소를 루프백 인터페이스로 제한하는 것을 고려하세요. 그래야 비보안 엔드포인트가 파드의 네트워크 인터페이스에 노출되지 않고 사이드카 컨테이너에는 계속 사용 가능해요. - pod 컨테이너의 시작 인자에
--repo-server-plaintext파라미터를 지정해argocd-server,argocd-application-controller,argocd-applicationset-controller가argocd-repo-server로의 연결에 TLS를 사용하지 않도록 구성하세요 argocd-notifications-controller의 파드 시작 파라미터를--argocd-repo-server-plaintext파라미터를 포함하도록 수정하세요--repo-server <address>파라미터로 주소를 지정해argocd-server와argocd-application-controller가argocd-repo-server서비스에 직접 연결하는 대신 사이드카에 연결하도록 구성하세요
이 변경 후 argocd-server, argocd-application-controller, argocd-notifications-controller, argocd-applicationset-controller는 argocd-repo-server의 TLS 사이드카 프록시에 대한 TLS의 모든 측면을 처리할 사이드카 프록시에 평문 연결을 사용할 거예요.
argocd-dex-server로의 TLS 비활성화 (Disabling TLS to argocd-dex-server)
사이드카 프록시를 통한 mTLS가 관여하는 일부 시나리오(예: 서비스 메시)에서는 argocd-server에서 argocd-dex-server로의 연결이 TLS를 전혀 사용하지 않도록 구성하고 싶을 수 있어요.
이 경우 다음을 해야 해요:
- HTTPS API에서 TLS를 비활성화하도록 pod 컨테이너의 시작 인자에
--disable-tls파라미터를 지정해argocd-dex-server를 구성하세요 - pod 컨테이너의 시작 인자에
--dex-server-plaintext파라미터를 지정해argocd-server가argocd-dex-server로의 연결에 TLS를 사용하지 않도록 구성하세요 --dex-server <address>파라미터로 주소를 지정해argocd-server가argocd-dex-server서비스에 직접 연결하는 대신 사이드카에 연결하도록 구성하세요
이 변경 후 argocd-server는 argocd-dex-server의 TLS 사이드카 프록시에 대한 TLS의 모든 측면을 처리할 사이드카 프록시에 평문 연결을 사용할 거예요.