이번 글에서는 Kubernetes 클러스터에 Argo CD를 설치하고, Gateway API를 이용해 외부에서 접속할 수 있도록 구성하는 과정을 정리합니다.

 

설치는 Helm Chart를 사용했으며, 외부 노출은 Gateway API를 통해 처리했습니다. 로컬 테스트 환경에서는 Argo CD가 생성한 인증서를 별도의 TLS Secret으로 복사해 Gateway에서 사용하도록 구성했습니다.

구성 개요

전체 구성 흐름은 다음과 같습니다.

  1. Helm으로 Argo CD 설치
  2. Gateway에서 사용할 TLS Secret 준비
  3. Gateway와 HTTPRoute를 적용해 Argo CD Server 외부 노출
  4. 초기 admin 계정으로 로그인
  5. Argo CD Application 리소스 생성

이 글에서는 Gateway가 HTTPS를 종료하고, Argo CD Server에는 HTTP로 트래픽을 전달하는 방식을 사용합니다.

1. Argo CD 설치

먼저 Argo CD 설치에 사용할 argocd-values.yaml 파일을 작성합니다.

configs:
  params:
    server.insecure: true

여기서 중요한 설정은 다음 값입니다.

server.insecure: true

이 설정은 Argo CD Server가 자체적으로 HTTPS를 처리하지 않고 HTTP로 동작하도록 만드는 설정입니다.

 

이번 구성에서는 Gateway가 HTTPS TLS Termination을 담당하고, Argo CD Server에는 HTTP 포트인 80으로 요청을 전달합니다. 따라서 Argo CD Server 입장에서는 HTTPS가 아닌 HTTP 요청을 받도록 설정해야 합니다.

 

즉, 역할을 나누면 다음과 같습니다.

  • Gateway: 외부 HTTPS 요청 수신 및 TLS 종료
  • Argo CD Server: Gateway로부터 HTTP 요청 수신

이제 Helm으로 Argo CD를 설치합니다.

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm upgrade --install my-argo-cd argo/argo-cd \
  --version 9.5.15 \
  -n argocd \
  --create-namespace \
  -f argocd-values.yaml

설치가 끝나면 환경에 맞게 Argo CD Server를 외부에 노출해야 합니다.

 

간단한 테스트만 필요하다면 kubectl port-forward를 사용할 수도 있습니다. 이번 구성에서는 Gateway API를 사용해 외부에서 접근할 수 있도록 구성했습니다.

2. Gateway TLS Secret 준비

Gateway API에서 HTTPS Listener를 사용하려면 TLS 인증서 Secret이 필요합니다.

 

Argo CD Helm Chart는 기본적으로 argocd-secret을 생성하며, 이 Secret 안에는 tls.crt, tls.key 데이터가 포함될 수 있습니다. 하지만 argocd-secret의 타입은 일반적으로 Opaque입니다.

 

Gateway API의 certificateRefs에서 사용하는 인증서 Secret은 kubernetes.io/tls 타입이어야 하므로, argocd-secret을 그대로 Gateway의 인증서 Secret으로 사용할 수 없습니다.

 

따라서 로컬 테스트 환경에서는 argocd-secret에 들어 있는 인증서 데이터를 별도의 TLS Secret으로 복사했습니다.

kubectl get secret argocd-secret -n argocd \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/argocd-tls.crt

kubectl get secret argocd-secret -n argocd \
  -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/argocd-tls.key

kubectl create secret tls argocd-gateway-tls \
  -n argocd \
  --cert=/tmp/argocd-tls.crt \
  --key=/tmp/argocd-tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

위 명령어는 다음 순서로 동작합니다.

  1. argocd-secret에서 tls.crt 값을 꺼내 인증서 파일로 저장
  2. argocd-secret에서 tls.key 값을 꺼내 개인키 파일로 저장
  3. 두 파일을 사용해 kubernetes.io/tls 타입의 Secret 생성

생성되는 Secret 이름은 다음과 같습니다.

argocd-gateway-tls

이 Secret은 이후 Gateway의 certificateRefs에서 참조됩니다.

 

운영 환경에서는 이처럼 Argo CD 내부 Secret을 복사하기보다는, 일반적으로 cert-manager나 외부 인증서 관리 방식을 사용하는 것이 좋습니다.

3. Gateway와 HTTPRoute 적용

이제 Gateway API 리소스를 작성해 Argo CD Server를 외부에 노출합니다.

 

먼저 Gateway YAML을 작성합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: argocd-gateway
  namespace: argocd
spec:
  gatewayClassName: eg
  listeners:
    - protocol: HTTPS
      port: 443
      name: argocd-gateway
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: argocd-gateway-tls
            kind: Secret
            group: ""

이 Gateway는 443 포트에서 HTTPS 요청을 받습니다.

주요 설정은 다음과 같습니다.

gatewayClassName: eg

사용할 GatewayClass를 지정합니다. 이 값은 클러스터에 설치된 Gateway Controller에 따라 달라집니다. 예제에서는 eg를 사용했습니다.

tls:
  mode: Terminate

Gateway에서 TLS를 종료한다는 의미입니다. 즉, 외부 클라이언트는 HTTPS로 Gateway에 접근하지만, Gateway 뒤쪽의 Argo CD Server로는 HTTP 요청이 전달됩니다.

certificateRefs:
  - name: argocd-gateway-tls

앞에서 생성한 TLS Secret을 참조합니다.

 

다음으로 HTTPRoute YAML을 작성합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: argocd-http-route
  namespace: argocd
spec:
  parentRefs:
    - name: argocd-gateway
  rules:
    - backendRefs:
        - name: my-argo-cd-argocd-server
          port: 80

이 HTTPRoute는 argocd-gateway로 들어온 요청을 Argo CD Server Service로 전달합니다.

 

여기서 backendRefs.name에는 Argo CD Server Service 이름을 지정합니다.

backendRefs:
  - name: my-argo-cd-argocd-server
    port: 80

Helm 설치 시 release 이름을 my-argo-cd로 지정했기 때문에, Argo CD Server Service 이름은 다음과 같은 형태가 됩니다.

my-argo-cd-argocd-server

실제 Service 이름은 Helm release 이름이나 Chart 버전에 따라 달라질 수 있으므로,
적용 전에 kubectl get svc -n argocd로 확인하는 것이 좋습니다.

작성한 리소스를 적용합니다.

kubectl apply -f k8s/argocd/argocd-gateway.yaml
kubectl apply -f k8s/argocd/argocd-http-route.yaml

적용 후 Gateway와 HTTPRoute 상태를 확인합니다.

kubectl describe gateway argocd-gateway -n argocd
kubectl describe httproute argocd-http-route -n argocd

Gateway와 HTTPRoute가 정상적으로 연결되었다면, Gateway Controller가 할당한 주소를 통해 Argo CD UI에 접근할 수 있습니다.

4. 초기 로그인

Argo CD의 초기 admin 비밀번호는 argocd-initial-admin-secret Secret에 저장되어 있습니다.

다음 명령어로 초기 비밀번호를 확인합니다.

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath='{.data.password}' | base64 -d

기본 계정 정보는 다음과 같습니다.

Username: admin
Password: 위 명령어로 확인한 값

초기 비밀번호로 로그인한 뒤에는 보안을 위해 비밀번호를 변경합니다.

Argo CD UI에서 다음 메뉴로 이동합니다.

User Info -> UPDATE PASSWORD

비밀번호를 변경한 뒤에는 기존 초기 비밀번호 Secret이 더 이상 필요하지 않은지 확인하고, 운영 환경에서는 적절히 정리하는 것이 좋습니다.

5. Application 적용

Argo CD는 Application이라는 Kubernetes CRD를 통해 Git Repository와 배포 대상을 정의합니다.

Application은 UI에서 생성할 수도 있고, YAML로 작성해 Kubernetes에 직접 적용할 수도 있습니다.

 

이번 구성에서는 Application YAML을 작성해 직접 적용했습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: micro-mart-local
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/Hwara/micro-mart.git
    targetRevision: main
    path: k8s/services/overlays/local
  destination:
    server: https://kubernetes.default.svc
    namespace: micro-mart-local
  syncPolicy: {}

각 설정의 의미는 다음과 같습니다.

project: default

Application이 속할 Argo CD Project를 지정합니다. 별도로 Project를 생성하지 않았다면 기본값인 default를 사용할 수 있습니다.

source:
  repoURL: https://github.com/Hwara/micro-mart.git
  targetRevision: main
  path: k8s/services/overlays/local

source는 Argo CD가 추적할 Git 저장소와 배포 대상 매니페스트 위치를 정의합니다.

  • repoURL: Argo CD가 추적할 Git Repository URL
  • targetRevision: 추적할 브랜치, 태그 또는 커밋
  • path: Repository 내부에서 Kubernetes YAML 또는 Kustomize 설정이 위치한 경로

예제에서는 main 브랜치의 k8s/services/overlays/local 경로를 기준으로 배포 상태를 추적합니다.

destination:
  server: https://kubernetes.default.svc
  namespace: micro-mart-local

destination은 배포할 Kubernetes 클러스터와 네임스페이스를 지정합니다.

  • server: 배포 대상 클러스터 주소
  • namespace: 리소스를 배포할 네임스페이스

https://kubernetes.default.svc는 Argo CD가 설치된 현재 클러스터를 의미합니다.

syncPolicy: {}

예제에서는 자동 동기화를 설정하지 않았습니다. 따라서 Git Repository의 변경 사항이 감지되더라도 자동으로 배포되지는 않고, 사용자가 Argo CD UI나 CLI에서 수동으로 Sync를 실행해야 합니다.

 

자동 동기화를 사용하고 싶다면 syncPolicy.automated 설정을 추가할 수 있습니다. 다만 운영 환경에서는 자동 동기화 적용 여부를 신중히 결정하는 것이 좋습니다.

6. Argo CD UI에서 Application 상태 확인 및 수동 Sync

Application YAML을 Kubernetes에 적용했다면, 외부 노출한 Argo CD 주소로 접속합니다.

로그인 후 왼쪽 메뉴 또는 메인 화면의 Applications 탭으로 이동하면, 앞에서 생성한 Application을 확인할 수 있습니다.

 

Application 카드에서는 현재 배포 상태를 간단히 확인할 수 있습니다.

 

주로 확인할 값은 다음과 같습니다.

  • APP HEALTH
    • 애플리케이션이 Kubernetes 클러스터에서 정상 동작 중인지 나타냅니다.
    • 예를 들어 리소스가 정상적으로 실행 중이면 Healthy로 표시됩니다.
  • SYNC STATUS
    • Git Repository에 정의된 상태와 실제 Kubernetes 클러스터 상태가 일치하는지 나타냅니다.
    • Git의 매니페스트와 클러스터 상태가 일치하면 Synced, 차이가 있으면 OutOfSync로 표시됩니다.

생성된 Application을 클릭하면 더 자세한 리소스 상태를 확인할 수 있습니다.

 

상세 화면에서는 Application에 포함된 Kubernetes 리소스들이 어떤 상태인지 시각적으로 확인할 수 있습니다.


이를 통해 특정 리소스가 정상적으로 생성되었는지, Pod가 정상 실행 중인지, Service나 Deployment에 문제가 없는지 확인할 수 있습니다.

수동 Sync 실행

이번 예제에서는 Application YAML에 자동 동기화 설정을 추가하지 않았습니다.

syncPolicy: {}

따라서 Git Repository에 있는 매니페스트를 실제 클러스터에 반영하려면 Argo CD UI에서 수동으로 Sync를 실행해야 합니다.

수동 Sync는 다음 순서로 진행합니다.

  1. Argo CD UI에서 Application을 클릭합니다.
  2. 상단의 SYNC 버튼을 클릭합니다.
  3. Sync할 Revision과 옵션을 확인합니다.
  4. SYNCHRONIZE 버튼을 클릭합니다.

SYNCHRONIZE를 실행하면 Argo CD가 Application에 등록된 GitHub Repository의 파일을 기준으로 Kubernetes 클러스터에 리소스를 배포합니다.

 

즉, 앞에서 작성한 Application의 다음 설정을 기준으로 동작합니다.

source:
  repoURL: https://github.com/Hwara/micro-mart.git
  targetRevision: main
  path: k8s/services/overlays/local
destination:
  server: https://kubernetes.default.svc
  namespace: micro-mart-local

Argo CD는 repoURL의 targetRevision 브랜치에서 path에 있는 Kubernetes 매니페스트를 읽고, destination에 지정된 클러스터와 네임스페이스에 적용합니다.

 

Sync가 완료되면 Application의 상태가 변경됩니다.

 

정상적으로 반영되었다면 다음과 같은 상태를 기대할 수 있습니다.

APP HEALTH: Healthy
SYNC STATUS: Synced

Sync 상태 확인과 롤백

Application 상세 화면에서는 단순히 현재 상태만 확인하는 것이 아니라, Sync 이력과 롤백 기능도 확인할 수 있습니다.

Argo CD UI에서는 다음 메뉴를 통해 배포 상태를 확인할 수 있습니다.

  • SYNC STATUS
    • Git Repository와 실제 클러스터 상태가 일치하는지 확인
  • HISTORY AND ROLLBACK
    • 이전 Sync 이력 확인
    • 특정 Revision으로 롤백 가능

특히 GitOps 방식에서는 Git의 변경 이력이 곧 배포 이력이 되기 때문에, 어떤 Commit 또는 Revision이 클러스터에 반영되었는지 확인하는 것이 중요합니다.

 

문제가 발생했을 때는 HISTORY AND ROLLBACK 메뉴에서 이전에 정상 동작하던 Revision을 확인하고, 필요하다면 해당 Revision으로 롤백할 수 있습니다.

명령어로 Application 상태 확인하기

UI뿐만 아니라 kubectl 명령어로도 Application 상태를 확인할 수 있습니다.

kubectl get application -n argocd

특정 Application의 상세 상태를 확인하려면 다음 명령어를 사용할 수 있습니다.

kubectl describe application micro-mart-local -n argocd

배포 대상 네임스페이스에 실제 리소스가 생성되었는지도 함께 확인합니다.

kubectl get all -n micro-mart-local

Pod 상태를 조금 더 자세히 확인하려면 다음 명령어를 사용할 수 있습니다.

kubectl get pods -n micro-mart-local

특정 Pod에 문제가 있다면 describe 또는 logs 명령어로 원인을 확인합니다.

kubectl describe pod <pod-name> -n micro-mart-local
kubectl logs <pod-name> -n micro-mart-local

이를 통해 Argo CD UI에서 보이는 상태와 실제 Kubernetes 리소스 상태를 함께 비교할 수 있습니다.

정리

이번 글에서는 Helm으로 Argo CD를 설치하고, Gateway API를 통해 외부에서 접근할 수 있도록 구성했습니다.

 

핵심은 Argo CD Server를 server.insecure: true로 설정하고, HTTPS 처리는 Gateway에서 담당하도록 역할을 나누는 것입니다.

 

또한 Gateway API의 certificateRefs는 kubernetes.io/tls 타입 Secret을 요구하므로, 로컬 테스트 환경에서는 Argo CD가 생성한 인증서 데이터를 별도의 TLS Secret으로 복사해 사용했습니다.

 

Argo CD Application 리소스를 생성해 Git Repository의 특정 경로를 Kubernetes 배포 대상으로 등록했습니다.

 

이 구성을 통해 Git에 정의된 Kubernetes 매니페스트를 기준으로 실제 클러스터 상태를 추적하고, 필요할 때 수동으로 Sync할 수 있는 GitOps 기반 배포 환경을 만들 수 있었습니다.

 

application을 생성한 뒤에는 Argo CD UI에서 APP HEALTH와 SYNC STATUS를 통해 배포 상태를 확인할 수 있습니다. 자동 동기화를 설정하지 않은 경우에는 SYNC 버튼을 눌러 수동으로 Git Repository의 매니페스트를 클러스터에 반영해야 합니다.

 

또한 HISTORY AND ROLLBACK 메뉴를 통해 이전 Sync 이력을 확인할 수 있으며, 문제가 발생했을 때 특정 Revision으로 롤백할 수도 있습니다. 이를 통해 Git Repository를 기준으로 Kubernetes 리소스의 배포 상태를 추적하고 관리할 수 있습니다.

References

'Devops > Kubernetes' 카테고리의 다른 글

Kustomize secretGenerator와 Argo CD 동기화 오류 해결하기  (0) 2026.05.26
Kubernetes kubelet의 컨테이너 로그 로테이션 설정 정리  (0) 2026.05.25
Kubernetes 로컬 환경에 Private Registry 배포하고 이미지 Push/Pull 설정하기  (0) 2026.05.20
로컬 Kubernetes에서 MetalLB로 LoadBalancer IP 할당하기  (0) 2026.05.20
Gateway API와 Envoy Gateway로 로컬 Kubernetes 서비스 노출하기  (0) 2026.05.20

티스토리툴바