클라우드 네이티브 어플리케이션 플랫폼 공통 설치 가이드

• 1. 개요
• 2. 설치 환경 구성
  • 2.1 Kubernetes 설치
  • 2.2 GitOps 도구 설치
• 3. 설치 순서
  • 3.1 네트워크 및 인증서 관리
  • 3.2 데이터베이스 플랫폼
• 3.3 인증 및 트래픽 관리 플랫폼
  • 3.4 CI/CD 플랫폼
  • 3.5 관측성 플랫폼
  • 3.6 애플리케이션
• 4. 모듈 배포
  • 4.1 GitOps 모듈 폴더 구조
  • 4.2 모듈 배포 설정
  • 4.3 기본 구성 변경
  • 4.4 배포 전 확인 사항
  • 4.5 배포 방법
• 5. GPG 키 생성 및 설정 (SOPS용)
• 6. 도메인 및 인증서 구성
  • 6.1 도메인 등록
  • 6.2 TLS 인증서 구성
• 7. Keycloak 클라이언트 설정
  • 7.1 Client Scopes 설정 (공통)
  • 7.2 각 클라이언트 생성
• 8. 참고 자료

1. 개요

클라우드 네이티브 어플리케이션 플랫폼 설치을 위해 GitOps로 구성된 모듈을 배포하는 방법에 대해 가이드합니다. Kustomize와 Helm 차트를 활용하여 Kubernetes 클러스터에 자동 배포할 수 있으며, 모든 모듈을 설치함으로써 완전한 GitOps 기반 개발 및 배포 플랫폼을 구성할 수 있습니다. 이를 통해 마이크로 서비스 기반의 애플리케이션을 GitOps 방식으로 개발하고 배포할 수 있습니다.

관련 소스 코드는 Private Repository로 관리되고 있으며, 접근이 필요한 경우 별도로 권한을 요청해 주시면 GitHub Repository를 통해 제공해 드립니다.

2. 설치 환경 구성

2.1 Kubernetes 구축

본 가이드의 모든 모듈은 AWS EKS 1.33과 Kind 1.34 환경에서 기능이 검증되었으며, Kubernetes 버전 1.30 이상을 권장합니다. 클러스터는 고가용성을 위해 노드 3개 이상으로 구성하는 것이 좋습니다.

Kubernetes 클러스터가 없는 경우, Kind(Kubernetes in Docker)를 사용하여 로컬 환경에 경량 클러스터를 구성할 수 있습니다. kind 폴더로 이동하여 README.md 파일을 참조하여 Kind 클러스터를 설치합니다.

2.2 GitOps 도구 설치

먼저 SOPS, Kubecel Helm, Kustomize를 다운로드 받아 /usr/local/bin에 설치합니다.

# Architecture: amd64, arm64
ARCH=amd64 

# SOPS  다운로드 및 설치
curl -LO https://github.com/getsops/sops/releases/download/v3.9.0/sops-v3.9.0.linux.${ARCH}
sudo mv sops-v3.9.0.linux.${ARCH} /usr/local/bin/sops
sudo chmod +x /usr/local/bin/sops

# Kubectl 다운로드 및 설치
KUBECTL_VERSION="v1.30.0"
curl -sLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/${ARCH}/kubectl"
sudo mv kubectl /usr/local/bin/
sudo chmod +x /usr/local/bin/kubectl

# Helm 다운로드 및 설치
HELM_VERSION="v3.17.1"
curl -sLo  helm.tar.gz https://get.helm.sh/helm-${HELM_VERSION}-linux-${ARCH}.tar.gz
tar -xzf helm.tar.gz
sudo mv linux-arm64/helm /usr/local/bin/helm
sudo chmod +x /usr/local/bin/helm
helm version

# kustomize 다운로드 및 설치
KUSTOMIZE_VERSION="v5.6.0"
curl -sLo kustomize.tar.gz https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2F${KUSTOMIZE_VERSION}/kustomize_${KUSTOMIZE_VERSION}_linux_${ARCH}.tar.gz
tar -xzf kustomize.tar.gz
sudo mv kustomize /usr/local/bin/
sudo chmod +x /usr/local/bin/kustomize
kustomize version

# Kustomize SopsSecretGenerator 설치
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kustomize/plugin/goabout.com/v1beta1/sopssecretgenerator"
cd "${XDG_CONFIG_HOME:-$HOME/.config}/kustomize/plugin/goabout.com/v1beta1/sopssecretgenerator"


curl -kL -o SopsSecretGenerator \
  https://github.com/goabout/kustomize-sopssecretgenerator/releases/download/v1.6.0/SopsSecretGenerator_1.6.0_linux_${ARCH}

chmod +x SopsSecretGenerator

3. 설치 순서

GitOps 모듈들은 상호 의존성이 있으므로 다음 순서대로 설치하는 것을 권장합니다.

먼저 GitHub Repository에서 소스코드를 다운로드합니다.

git clone https://github.com/cnapcloud/gitops.git
cd gitops

메트릭 수집을 위해 모든 모듈이 공통으로 사용하는 Prometheus CRD를 다음과 같이 설치합니다.

cd prometheus && make crd && cd ..

3.1 네트워크 및 인증서 관리

• Refactor - 네이스페이스간 인증서 복사 [설치 가이드]
• cert-manager - TLS 인증서 자동 관리 [설치 가이드]
• NGINX Ingress Controller - HTTP/HTTPS 트래픽 라우팅 [설치 가이드]

※ AWS EKS로 인프라를 구성한 경우, Ingress Controller 설치는 생략 가능합니다.

3.2 데이터베이스 플랫폼

• Redis HA Proxy, Sentinel - 고가용성 Redis 클러스터 [설치 가이드]
• Minio - 객체 스토리지 시스템 [설치 가이드]
• CNPG PostgreSQL - 관계형 데이터베이스 [설치 가이드]
• MaxScale MariaDB - 관계형 데이터베이스 프록시 [설치 가이드]
• Elasticsearch, Kibana - 로그 검색 및 분석 엔진 [설치 가이드]

3.3 인증 및 트래픽 관리 플랫폼

• Keycloak - 통합 ID 및 액세스 관리 (IAM) [설치 가이드]
• OAuth2 Proxy - 애플리케이션 수준 인증 프록시 [설치 가이드]
• Kong Gateway - API 관리 및 보안 정책 적용 [설치 가이드]
• Istio - 서비스 메시 및 마이크로서비스 트래픽 관리 [[설치 가이드]]

3.4 CI/CD 플랫폼

• Jenkins - CI/CD 오케스트레이션 [설치 가이드]
• Harbor - 컨테이너 이미지 레지스트리 [설치 가이드]
• ArgoCD - GitOps 기반 CD 도구 [설치 가이드]
• SonarQube - 코드 품질 및 보안 분석 [[설치 가이드]]

3.5 관측성 플랫폼

• Prometheus, Grafana, AlertManager - 메트릭 수집/시각화/알림 [설치 가이드]
• Jaeger - 분산 트레이싱 [[설치 가이드]]
• Alerta - 통합 알림 대시보드 [[설치 가이드]]
• Fluentd - 로그 수집 및 전달 [[설치 가이드]]

3.6 애플리케이션

• Spring MSA Demo - 마이크로 서비스 데모(/guide/spring-msa/)

참고: 각 모듈의 Makefile을 사용하여 make apply로 배포하며, Keycloak 클라이언트는 Keycloak 설치 후 생성해야 합니다.

4. 모듈 배포

4.1 GitOps 모듈 폴더 구조

Helm + Kustomize를 통해 배포되는 GitOps 모듈을 실제 환경에 맞게 배포하기 전에, 기본 설정을 사용자 환경에 맞게 변경해야 합니다. 이 섹션에서는 배포 전에 확인하고 수정해야 할 핵심 항목들을 안내합니다.

module/                            # 모듈 루트 디렉토리
├── install_guide.md               # 설치 및 구성 가이드 문서
├── Makefile                       # 배포, 빌드, 테스트 자동화 스크립트
├── kustomize/                     # Kustomize 기반 Kubernetes 매니페스트 관리
│   ├── base/                      # 공통 기본 설정 (모든 환경에서 공유)
│   │   ├── configmap/             # ConfigMap 리소스 파일들
│   │   ├── helm/                  # Helm 차트 템플릿 및 기본 values
│   │   ├── patches/               # 패치 파일 (리소스 수정)
│   │   ├── resources/             # 추가 Kubernetes 리소스 (Deployment, Service 등)
│   │   ├── secrets/               # 시크릿 리소스 (SOPS로 암호화된 민감 정보)
│   │   └── kustomization.yaml     # Kustomize 기본 구성 파일
│   └── overlays/                  # 환경별 오버레이 설정
│       └── dev/                   # 개발 환경 전용 설정
│           ├── configmap/         # 개발 환경 ConfigMap 오버라이드
│           ├── helm/              # 개발 환경 Helm values 오버라이드
│           ├── patches/           # 개발 환경 패치 (호스트 별칭, 리소스 제한 등)
│           ├── resources/         # 개발 환경 추가 리소스
│           ├── secrets/           # 개발 환경 시크릿 오버라이드
│           └── kustomization.yaml # 개발 환경 Kustomize 구성 (베이스 병합)
└── (기타 파일들)                     # 기타 구성 파일 (예: Dockerfile, scripts 등)

4.2 모듈 배포 설정

각 모듈 배포 전에 다음 파일들을 환경에 맞게 수정하세요. 기본 구성은 데모용으로 설정되어 있으므로, 보안과 호환성을 위해 반드시 변경해야 합니다.

1. Helm Values 파일 (dev/helm/values.yaml)
   이 파일에서 애플리케이션의 주요 설정을 조정합니다.

   • Ingress 도메인 변경:

     • ingress.hostname을 실제 도메인으로 수정 (예: keycloak.cnapcloud.com → keycloak.yourdomain.com)
     • TLS 시크릿 이름도 도메인에 맞게 변경 (secretName: yourdomain.com-tls)

   • 비밀번호 및 인증 정보:

     • auth.adminPassword, postgresql.auth.password 등 기본 비밀번호(password)를 강력한 비밀번호로 변경
     • Keycloak 연동 시 oidc.clientId, oidc.clientSecret를 Keycloak에서 생성한 값으로 설정

   • Persistence 및 리소스:

     • postgresql.primary.persistence.size 등 스토리지 크기를 환경에 맞게 조정 (기본: 4Gi)
     • CPU/메모리 limits/requests 설정

   • 기타 설정:

     • 이미지 태그, 레지스트리 등 필요 시 변경

2. Patches 파일 (dev/patches/)
   환경별로 추가해야 할 패치를 적용합니다.

   • Host Aliases: 클러스터 내부 DNS 해석을 위해 IP와 호스트네임을 추가 (예: ArgoCD의 add-host-alias.yaml)
   • Resource Overrides: CPU/메모리 제한 추가
   • Config Patches: 특정 설정 오버라이드

3. Secrets 파일 (base/secrets/sops/ 또는 dev/secrets/)
   민감한 정보를 SOPS로 암호화하여 관리합니다.

   • SOPS 암호화 파일: .enc.yaml 파일들을 GPG 키로 복호화 → 편집 → 재암호화
   • 주요 암호화 대상: 데이터베이스 비밀번호, API 키, TLS 인증서 등

4. Kustomization 파일 (dev/kustomization.yaml)
   Kustomize 설정을 확인합니다.

   • 네임스페이스: namespace 필드가 올바른 네임스페이스로 설정되어 있는지 확인
   • 이미지 태그: images 섹션에서 최신 태그로 업데이트
   • 패치 적용: patchesStrategicMerge 또는 patchesJson6902가 올바르게 참조하는지 확인

4.3 기본 구성 변경

• 도메인: 모듈명.cnapcloud.com (예: keycloak.cnapcloud.com)
• 비밀번호: password (모든 서비스 공통, 강력한 비밀번호로 변경)
• Keycloak Realm: cnap
• Persistence 크기: 4Gi (환경에 맞게 조정)
• 데이터베이스: PostgreSQL 내장 사용, 별도 DB 사용 시 비활성화

4.4 배포 전 확인 사항

• make preview 명령으로 변경 사항을 dry-run하여 확인
• DNS가 도메인을 올바르게 해석하는지 확인
• TLS 인증서가 준비되어 있는지 확인 (Cert-Manager 사용 시)
• Keycloak 클라이언트가 생성되어 있고, 시크릿이 올바르게 설정되었는지 확인
• GPG 키가 SOPS 복호화에 사용 가능하도록 설정

4.5 배포 방법

각 모듈은 Makefile을 사용하여 다음과 같이 배포할 수 있습니다.

cd <모듈명>        # 배포할 모듈 디렉토리로 이동

make namespace   # 네임스페이스 생성
make pull        # Helm Chart Download
make preview     # manifests 출력 (dry-run)
make apply       # Kubernetes 클러스터에 실제 배포

5. GPG 키 생성 및 설정 (SOPS용)

Makefile이나 ArgoCD에서 배포할 때 SOPS로 암호화된 secrets를 복호화하려면 GPG 키가 필요합니다.

«sops, sopsgeneratpor 설치 추가»

1. GPG 키 생성 (새 키가 없는 경우):

export KEY_NAME="master"
export KEY_COMMENT="master key for sops"

gpg --batch --full-generate-key <<EOF
%no-protection
Key-Type: 1
Key-Length: 4096
Subkey-Type: 1
Subkey-Length: 4096
Expire-Date: 0
Name-Comment: ${KEY_COMMENT}
Name-Real: ${KEY_NAME}
EOF

# 키 내보내기
mkdir -p .gpg
gpg --export-secret-keys > .gpg/private-master.asc
gpg --export > .gpg/public-master.asc

2. GPG 키 등록 (기존 키가 있는 경우):

gpg --import .gpg/public-master.asc
gpg --import .gpg/private-master.asc

3. Fingerprint 확인 및 .sops.yaml 설정:

gpg --list-keys --keyid-format long
# 출력에서 40자리 Fingerprint 확인

# .sops.yaml (프로젝트 루트)
creation_rules:
  - path_regex: .*\.enc\.(yaml|yml|env)$
    pgp: <GPG_FINGERPRINT>

4. ArgoCD에 키 복사:

# ArgoCD repo-server가 SOPS 복호화를 위해 접근할 수 있도록 GPG 키를 복사합니다.
mkdir -p argocd/kustomize/base/secrets/.gpg
cp -r .gpg argocd/kustomize/base/secrets/.gpg

.gpg/ 폴더는 .gitignore에 추가하여 Git에 커밋되지 않도록 하세요. 개인 키는 절대 공개 저장소나 원격에 업로드하지 마세요.

6. 도메인 및 인증서 구성

GitOps 플랫폼의 각 모듈에 필요한 도메인 설정과 TLS 인증서 구성을 안내합니다. 도메인 등록을 통해 서비스 접근을 설정하고, wildcard TLS 인증서를 발급하여 HTTPS 보안을 구성합니다.

6.1 도메인 등록

다음 표는 각 도메인의 용도와 해당하는 GitOps 모듈을 정리한 것입니다. 프로덕션 환경에서는 DNS 서버를 통해 도메인을 등록하세요. 도메인을 변경할 경우, 각 모듈의 Ingress 설정과 TLS 시크릿 이름을 함께 수정해야 합니다.

로컬 DNS를 사용하는 경우는, 호스트 머신의 /etc/hosts 파일에 Ingress IP를 추가하여 도메인을 해석하세요.

Ingress IP가 127.0.0.1인 경우

sudo vi /etc/hosts
127.0.0.1 harbor.cnapcloud.com
127.0.0.1 keycloak.cnapcloud.com
127.0.0.1 jenkins.cnapcloud.com
127.0.0.1 argocd.cnapcloud.com
127.0.0.1 prometheus.cnapcloud.com
127.0.0.1 grafana.cnapcloud.com
127.0.0.1 kibana.cnapcloud.com
127.0.0.1 minio.cnapcloud.com
127.0.0.1 oauth2-proxy.cnapcloud.com
127.0.0.1 kong-manager.cnapcloud.com
127.0.0.1 kong-admin.cnapcloud.com
127.0.0.1 kong-proxy.cnapcloud.com
127.0.0.1 httpbin.cnapcloud.com
127.0.0.1 msa-demo.cnapcloud.com

클러스터 내부 DNS 설정 (CoreDNS)

로컬 DNS를 사용하는 경우, Kubernetes 클러스터 내부에서 Keycloak 인증을 위해 CoreDNS에 Ingress IP를 사용하여 keycloak.cnapcloud.com을 호스트 별칭으로 추가하세요.

1. Ingress IP 확인:

   kubectl get svc -n ingress-nginx
   

2. CoreDNS ConfigMap 편집:

   kubectl -n kube-system edit configmap coredns
   

3. data.Corefile 섹션에 다음을 추가 (예: Ingress IP가 10.0.0.1인 경우):

   .:53 {
       hosts {
         10.0.0.1 keycloak.cnapcloud.com
         10.0.0.1 harbor.cnapcloud.com         
         fallthrough
       }
       ...
   }
   

4. 변경 후 CoreDNS Pod 재시작:

   kubectl -n kube-system rollout restart deployment coredns
   

6.2 TLS 인증서 구성

모든 GitOps 모듈들은 HTTPS를 위해 wildcard TLS 인증서를 공유하도록 구성되어 있습니다. 이를 위해 cert-manager를 통해 Cloudflare와 연동하여 Let’s Encrypt Wildcard 인증서(현재 구성으로 *.cnapcloud.com, 사용자 환경에 맞게 변경)를 미리 발급받아야 합니다. 이후 Reflector를 사용하여 각 모듈의 네임스페이스에 자동으로 복제하여 사용합니다. 따라서 모든 모듈 설치 전에 인증서가 준비되어 있어야 합니다.

1. 인증서 발급 절차

   Wildcard 인증서 발급은 cert-manager 모듈 배포 시 관련 파일을 변경하여 수행합니다. Cloudflare DNS-01 ClusterIssuer 배포 시, 기존에 활성화된 프로세스가 있으면 먼저 제거하고 진행합니다.

   • ClusterIssuer: Cloudflare API로 Let’s Encrypt 인증서 발급 설정
   • Certificate: Wildcard 인증서(현재 구성으로 *.cnapcloud.com, 사용자 환경에 맞게 변경) 발급, Reflector로 네임스페이스 복제 (cnapcloud-certificate.yaml)
   • 참조: 각 모듈 Ingress에서 secretName: cnapcloud.com-tls 사용 (도메인 변경 시 함께 수정)
   • 확인: kubectl get certificate -n security

2. 인증서 변경 시 주의사항

   • 도메인을 변경할 경우, Certificate 리소스의 dnsNames와 Ingress의 secretName을 일괄 수정하세요.
   • Cloudflare API 토큰은 안전하게 관리하고, SOPS로 암호화하여 저장하세요.
   • 인증서 발급 실패 시, DNS 설정과 API 토큰을 확인하세요.

7. Keycloak 통합 인증 구성

GitOps 모듈 중 Argo CD, Jenkins, Harbor, Kong, OAuth2 Proxy, Grafana는 Keycloak과 연동하여 SSO(Single Sign-On)를 구성합니다. Keycloak 배포 완료 후, 각 서비스의 클라이언트를 Keycloak에서 생성해야 합니다.

7.1 Client Scopes 설정 (공통)

권한 관리를 위해 groups 스코프를 생성합니다.

1. Keycloak 관리 콘솔에 로그인하여 원하는 Realm을 선택합니다.
2. 좌측 메뉴에서 Client scopes를 클릭합니다.
3. Create client scope 버튼을 클릭합니다.
   • Name: groups
   • Type: Default
   • Include in token scope: 체크 ✓
   • Save 버튼을 클릭합니다.
4. 생성된 groups 스코프를 선택한 후 Mappers 탭을 클릭합니다.
5. Configure a new mapper 버튼을 클릭하고 Group Membership을 선택합니다.
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off
   • Save 버튼을 클릭합니다.

7.2 각 클라이언트 생성

다음 클라이언트들을 생성합니다. 각 클라이언트의 설정은 표로 정리합니다.

생성 절차 (각 클라이언트별로 반복):

1. General settings 탭:

   • Client Type: OpenID Connect
   • Client ID: 위 표의 클라이언트 ID 입력
   • Next 버튼을 클릭합니다.

2. Capability config 탭:

   • Client authentication: On
   • Standard flow: 체크 ✓
   • Direct access grants: 체크 ✓
   • Next 버튼을 클릭합니다.

3. Login settings 탭:

   • Home URL: 위 표의 값 입력
   • Valid redirect URIs: *
   • Valid post logout redirect URIs: +
   • Web origins: 위 표의 값 입력
   • Save 버튼을 클릭합니다.

4. 생성 후 Credentials 탭에서 Client secret을 복사하여 안전하게 저장합니다 (해당 서비스의 Helm values.yaml에서 사용).

참고: 모든 클라이언트 생성이 완료된 후 각 서비스를 배포할 때, 복사한 Client secret을 해당 서비스의 설정에 입력해야 합니다.

참고 자료

• Kustomize Documentation
• Helm Charts
• ArgoCD
• Cert-Manager
• ECK
• Harbor
• Ingress-Nginx
• Jenkins
• Kong Gateway
• Keycloak
• MinIO
• OAuth2-Proxy
• PostgreSQL
• Prometheus
• Redis
• Reflector
• KinD - Kubernetes in Docker