GitOps – Argo CD 구축 가이드(Helm)

개요

이 글은 Helm 기반으로 Argo CD를 설치하고, GitOps 적용을 시작하기 위한 최소 구성을 정리합니다.
설치 이후 운영에 필요한 핵심 설정(Repository 연결, Application 생성, Sync 동작 확인)까지를 범위로 합니다.

테스트 환경 기준으로 설치 절차를 단계별로 정리하고, 실무 적용 시 필요한 최소 설정까지 함께 정리합니다.

환경

본 문서 작성 시점에 사용한 도구 및 버전은 다음과 같습니다.

• Template Rendering Tool: Helm
• OS: Linux, macOS
• Argo CD: 3.17 
• Routing 방식 : NodePort 
  • 테스트로 바로 접근해야 하며 Cloud환경이 아니기 때문에 NodePort로 설치하여 접속하겠습니다.
• HA여부 : Non-HA (추후 HA로 구성할 수 있는 Argocd에 대해서도 글로 작성해 설명드리겠습니다.)

Window 환경은 가정하지 않으며 Window라면 WSL이라고 가정하겠습니다.

 

ArgoCD를 설치할 수 있는 방법

Argocd는 하단과 같은 방법으로 설치할 수 있고 크게 3가지로 나눌 수 있습니다.

1. Helm
2. kubectl (공식 install.yaml 적용)
3. curl을 통한 매니페스트 다운로드 (install.yaml을 받아오는 수단)

ArgoCD 설치방법 ( Curl, Kubectl)

Helm에 앞서 Kubectl, Curl로 Argocd를 설치하는 방법에 대해 소개드리겠습니다.

Curl을 통해 설치하는 방법

curl -sSL \
  https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml \
  -o install.yaml

kubectl apply -n argocd -f install.yaml

 

Kubectl을 통해 설치하는 방법

# Argocd가 설치될 Argocd NameSpace 생성
kubectl create namespace argocd

# k8s에 argocd 설치
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.1.7/manifests/install.yaml

 

curl, kubectl 모두 공통의 진행사항은 다음과 같습니다.

# http insecure 설정 후 argocd-server 파드 재시작
kubectl patch configmap argocd-cmd-params-cm -n argocd --patch '{"data": {"server.insecure": "true"}}'
kubectl rollout restart deployment argocd-server -n argocd

 

Argocd는 최초 설치되면 LoadBalancer 타입으로 Service를 설정하려 하기 때문에 하단과 같이 설정해 NodePort로 수정하여 배포한다면 설정한 포트로 Argocd 접속이 가능합니다.

argocd-server-nodeport.yaml
---
apiVersion: v1
kind: Service
metadata:
  annotations:
  labels:
    app.kubernetes.io/component: server
    app.kubernetes.io/name: argocd-server
    app.kubernetes.io/part-of: argocd
  name: argocd-server-nodeport
  namespace: argocd
spec:
  ports:
  - name: http
    nodePort: 31000
    port: 80
    protocol: TCP
    targetPort: 8080
  - name: https
    nodePort: 31443
    port: 443
    protocol: TCP
    targetPort: 8080
  selector:
    app.kubernetes.io/name: argocd-server
  sessionAffinity: None
  type: NodePort
---
kubectl apply -f argocd-server-nodeport.yaml

 

Argocd의 최초 로그인 아이디는 ADMIN이며 랜덤 하게 설정된 비밀번호는 하단의 명령어로 확인해 접속할 수 있습니다.

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

 

ArgoCD 설치방법 (Helm)

helm을 설치하지 않았다면 OS별 명령어로 helm을 설치합니다.

# linux
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# MacOS
brew install helm

 

Argo CD Helm Chart를 사용하기 위해 argo Helm repository를 추가하고 최신 Chart 목록을 가져오도록 업데이트합니다.

설치 가능한 Argo CD Helm chart 버전을 확인하고 사용할 버전을 선택합니다.

Helm chart(argo/argo-cd)를 사용해 Argo CD를 지정한 namespace에 설치합니다.

 

Helm에서의 차트와 Argocd 버전은 하이퍼링크 목록에서 확인할 수 있으며 예제의 차트별 버전은 다음 사진에서 확인 가능합니다.

 

그렇게 접속한다면 다음과 같은 ArgoCD 접속 페이지가 확인 가능하며 초기엔 Application이 설치되어 있지 않아 두 번째 사진처럼 확인 가능합니다.

 

 

각 설치 방법별 비교표

주 용도	Kubernetes 리소스 직접 제어·조회	HTTP API 단일 요청 검증	Kubernetes 리소스 패키지 단위 배포·관리
사용 대상	클러스터 내부 리소스	API 서버 / 애플리케이션 엔드포인트	애플리케이션 + 관련 리소스 전체
추상화 수준	낮음 (리소스 단위)	매우 낮음 (요청 단위)	높음 (Chart 단위)
선언형 지원	부분적 (apply)	미지원	지원 (values.yaml)
재현성	낮음 (명령 순서 의존)	매우 낮음	높음
GitOps 적합성	낮음	부적합	높음
운영 환경 사용	디버깅 / 임시 조치	헬스체크 / 테스트	배포 / 운영 표준
실무에서의 위치	테스트도구	테스트도구	최종 배포 수단

 

위 설치 방법들에 대한 최종 비교표이며 Helm이 테스트 시 단순하게 설치하기 어려워 보이고 이해도가 필요하지만 설치해야 한다면 Helm으로 해야 하는 이유는 위 표를 참고해 확인이 가능합니다.

실무에서 도움 될 설치가이드 (Helm)

실무에선 Helm 기반으로 ArgoCD를 설치하게 될 텐데 그때에 도움이 될 values.yml을 다음과 같이 보여드리겠습니다.

server:
  extraArgs:
    - --insecure

  service:
    type: NodePort
    nodePortHttp: 30080

configs:
  cm:
    kustomize.buildOptions: --enable-helm
  secret:
    argocdServerAdminPassword: <base64로 인코딩한 비밀번호>
  params:
    server.insecure: true
    server.rootpath: <basepath>

  repositories:
    - name: <name>
      url: <url>
      type: <type>
      username: <id>
      password: <password>

certificate:
  enabled: false

 

위 항목을 채워 ArgoCD 배포 시 Helm values argument로 전달하게 된다면 다음과 같은 부분이 코드화되어 전달될 수 있습니다.

 

1. 최초 로그인 비밀번호 
2. ArgoCD에서 Git 등으로 연결할 저장소의 인증정보
3. ArgoCD의 Helm 사용 시 전달할 파라미터 
4. ArgoCD의 Service Type 변경과 포트 지정
5. ArgoCD를 basePath방식으로 url을 통해 접속한다면 server.rootPath로 코드화해 전달해야만 초기 설정 시 설정됩니다.

 

정리/회고

이 글을 통해 각 방법으로 ArgoCD를 설치하는 방법에 대해 알아보았습니다.

 

 

• Argo CD 설치는 kubectl apply(원격 manifest)로도 가능하지만, 실무 기준으로는 Helm 기반 설치가 재현성과 변경 관리 측면에서 더 나으므로 Helm기반 설치로 테스트하는 것을 권장드립니다.
• 테스트 단계에서도 설치 경로를 Helm으로 맞춰두면, 이후 운영 전환 시 설치·업데이트·롤백 절차를 동일한 방식으로 가져갈 수 있습니다.
• 초기 접속(초기 비밀번호 확인, 서비스 노출 등)까지는 문서에 정리한 절차로 확인 가능합니다.
• 실무 적용을 고려해 Argo CD Helm Chart 기준의 values.yaml 예시를 함께 정리하며, Chart 버전은 Artifact Hub에서 확인한 값을 기준으로 확인하여 작성하였습니다.
• 다음 단계는 Argo CD의 배포 최소 단위인 Application을 기준으로, Repository 연결과 Sync 동작을 정리하여 설명드리겠습니다.

 

GitOps를 구현한 좋은 도구인 ArgoCD를 사용해보시지 않았다면 이 글과 함께 설치까지 빠르게 진행하셔서 친숙해지고 테스트할 수 있으시는데 도움이 될 수 있었으면 좋겠습니다.

 

그럼 이 글을 봐주셔서 감사합니다.