Reflector 설치 가이드 (Kustomize 기반)

1. 개요

본 문서는 gitops 저장소의 /reflector 디렉터리 구조를 기반으로 Reflector를 Kubernetes 클러스터에 설치하는 전체 과정을 안내합니다. Reflector는 Kubernetes Secret과 ConfigMap을 다른 네임스페이스로 자동 복제하는 도구입니다. Kustomize, Helm, Makefile을 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

  • Kubernetes 클러스터: v1.19 이상
  • 로컬 도구: kubectl, kustomize, helm 설치 완료
  • 권한: 클러스터에 대한 cluster-admin 권한 (CRD 생성, RBAC 설정 등)
  • 네임스페이스: kube-system 네임스페이스 (또는 원하는 네임스페이스)

3. 디렉터리 구조 및 역할

reflector/
├── Makefile                           # 배포 자동화 스크립트
└── kustomize/
    ├── base/
    │   ├── helm/                      # Reflector Helm Chart
    │   ├── kustomization.yaml         # 기본 Kustomize 구성
    │   └── resources/                 # 추가 리소스
    └── overlays/
        └── dev/
            ├── kustomization.yaml     # 환경별 Kustomize 구성
            └── helm/
                └── helm-chart.yaml    # HelmChartInflationGenerator 설정
  • Makefile: pull, namespace, preview, apply, delete 등 배포 자동화 명령어
  • kustomize/base/helm/reflector/: Reflector Helm Chart (pull 명령어로 다운로드)
  • kustomize/overlays/dev/: dev 환경 특화 설정

4. 설치 단계

4.1. Helm Chart 다운로드

Reflector Helm Chart를 Emberstack 공식 리포지토리에서 다운로드합니다.

make pull

이 명령어는 다음 작업을 수행합니다:

  • Emberstack Helm 리포지토리 추가 및 업데이트
  • Reflector Chart (v9.1.44) 다운로드 및 압축 해제

4.2. Namespace 생성

Reflector가 배포될 네임스페이스를 생성합니다.

make namespace

4.3. 배포 미리보기

Kustomize를 사용하여 생성될 매니페스트를 미리 확인합니다.

make preview

4.4. 배포 실행

Reflector를 클러스터에 배포합니다.

make apply

4.5. 배포 상태 확인

kubectl get pods -n gateway -w

5. 설치 후 검증

5.1. Pod 상태 확인

kubectl get pods -n gateway

확인 사항:

  • reflector-* Pod가 Running 상태
  • Ready 상태: 1/1

5.2. Secret/ConfigMap 복제 테스트

Reflector가 정상 작동하는지 테스트하기 위해 Secret을 생성하고 복제가 되는지 확인합니다.

5.2.1. Annotation을 사용한 복제 설정

Reflector는 Secret/ConfigMap에 특정 annotation을 추가하여 복제 동작을 제어합니다.

주요 annotation:

  • reflector.v1.k8s.emberstack.com/reflection-allowed: "true" - 복제 허용
  • reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "database,monitoring" - 특정 네임스페이스로 복제
  • reflector.v1.k8s.emberstack.com/reflection-auto-enabled: "true" - 자동 복제 활성화

5.2.2. 테스트 Secret 생성 (Annotation 포함)

kubectl create secret generic test-secret \
  --from-literal=key=value \
  --dry-run=client -o yaml | \
kubectl annotate -f - \
  reflector.v1.k8s.emberstack.com/reflection-allowed=true \
  reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces=database,monitoring \
  --local=true --dry-run=client -o yaml | \
kubectl apply -f -

5.2.3. 복제 확인

kubectl get secrets -A | grep test-secret

확인 사항:

  • database와 monitoring 네임스페이스에 test-secret이 복제됨

주의사항:

  • Reflector는 annotation이 있는 원본 리소스를 감시하여 복제본을 생성합니다.
  • 복제본을 수동으로 삭제하더라도, 원본 리소스의 annotation이 변경되지 않는 한 자동으로 다시 생성되지 않습니다.
  • 복제본을 다시 생성하려면 원본 리소스의 annotation을 수정하거나, Reflector를 재시작해야 할 수 있습니다.
  • 원본 리소스의 데이터가 변경되면 Reflector가 복제본을 자동으로 업데이트합니다.

5.2.4. 원본 변경 시 복제본 업데이트 테스트

# 원본 Secret 데이터 변경
kubectl patch secret test-secret -n gateway --type merge -p '{"data":{"key":"bmV3dmFsdWU="}}'  # "newvalue" base64

# 복제본 확인
kubectl get secret test-secret -n database -o yaml
kubectl get secret test-secret -n monitoring -o yaml

확인 사항:

  • 복제본의 데이터가 원본 변경사항으로 업데이트됨

5.3. 로그 확인

kubectl logs -n gateway deployment/reflector

확인 사항:

  • 오류 메시지 없음
  • 정상적인 복제 로그
kubectl logs -n gateway deployment/reflector

확인 사항:

  • 오류 메시지 없음
  • 정상적인 복제 로그

6. 운영 및 Troubleshooting

6.1. 복제 실패

kubectl get secrets -A
kubectl describe secret <secret명> -n <namespace>

주요 원인:

  • 네임스페이스 권한 부족
  • Reflector 설정 오류
  • 리소스 라벨링 문제

6.2. Pod 재시작

kubectl rollout restart deployment/reflector -n gateway

6.3. 로그 수집

kubectl logs -n gateway deployment/reflector --previous

7. 업그레이드

Reflector를 업그레이드하려면:

  1. 새로운 버전의 Chart 다운로드 (make pull)
  2. 배포 적용 (make apply)

8. 제거

8.1. Reflector 삭제

make delete

8.2. 복제된 리소스 정리 (선택사항)

Reflector 제거 후 복제된 Secret/ConfigMap을 수동으로 삭제해야 할 수 있습니다.

8.3. Namespace 삭제 (선택사항)

kubectl delete namespace gateway

9. 부록: 최종 체크리스트

설치 전:

  • Kubernetes 클러스터 준비 (v1.19+)
  • kubectl, kustomize, helm 설치
  • cluster-admin 권한 확인
  • 네임스페이스 생성 계획

설치:

  • make pull 실행
  • make namespace 실행
  • make preview 실행 및 확인
  • make apply 실행

검증:

  • Reflector Pod Running 상태
  • Secret/ConfigMap 복제 확인
  • 로그 오류 없음

운영:

  • 모니터링 설정
  • 복제 정책 검토 /home/ubuntu/devel/github/gitops/reflector/install_guide.md
💬 무료 컨설팅 신청