K8s Reflector

개요

Reflector
리플렉터

Reflector는 쿠버네티스 애드온으로, Secret과 ConfigMap 리소스의 변화를 감시하고 동일 네임스페이스 혹은 다른 네임스페이스의 미러 리소스에 변화를 반영한다.
이를 통해 중앙에서 관리하는 설정이나 인증 정보가 변경될 때, 여러 네임스페이스에 일관되게 전파할 수 있다.

특징

Secret 및 ConfigMap 변경 실시간 감시
네임스페이스 간 자동 동기화 (자동 미러링)
충돌 방지: 동일 이름의 리소스가 이미 존재하는 경우 해당 네임스페이스는 건너뜀
cert-manager와 통합 지원 (Secret 자동 생성 및 미러링 지원)
다중 아키텍처 지원: amd64, arm, arm64
오픈소스 (MIT 라이선스)

배포

Helm을 통한 배포 (권장)

$ helm upgrade --install reflector oci://ghcr.io/emberstack/helm-charts/reflector

또는

$ helm repo add emberstack https://emberstack.github.io/helm-charts
$ helm repo update
$ helm upgrade --install reflector emberstack/reflector

수동 배포

$ kubectl -n kube-system apply -f \
  https://github.com/emberstack/kubernetes-reflector/releases/latest/download/reflector.yaml

사용법

Reflector는 리소스를 복제하기 위해 원본 리소스와 미러 리소스에 각각 어노테이션을 추가하는 방식으로 동작한다.

원본 리소스에 어노테이션 추가

원본(Secret이나 ConfigMap)은 “복제 허용”을 표시해야 한다.

reflector.v1.k8s.emberstack.com/reflection-allowed: 복제를 허용할지 여부 (true/false)
reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: 복제를 허용할 네임스페이스 목록 (콤마 구분 또는 정규식)

자동 미러링 옵션

Reflector가 자동으로 미러를 생성·삭제하도록 지정할 수 있다.

reflector.v1.k8s.emberstack.com/reflection-auto-enabled: 자동 미러링 여부
reflector.v1.k8s.emberstack.com/reflection-auto-namespaces: 자동 미러 생성할 네임스페이스 목록

미러 리소스에 어노테이션 추가

미러(Secret이나 ConfigMap)는 자신이 어떤 원본을 반영하는지 표시해야 한다.

reflector.v1.k8s.emberstack.com/reflects: 원본 리소스의 namespace/name 지정
reflector.v1.k8s.emberstack.com/reflected-version: (선택) 수동 수정 시 동기화 버전 초기화

동작 방식

Secret → data 필드만 동기화
ConfigMap → data, binaryData 동기화
원본이 삭제되면 자동 생성된 미러도 함께 삭제됨

어노테이션 요약 표

어노테이션 키	대상	설명
reflector.v1.k8s.emberstack.com/reflection-allowed	원본	해당 리소스를 미러링할 수 있도록 허용 (true/false)
reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces	원본	허용된 네임스페이스 지정 (콤마 구분 또는 정규식)
reflector.v1.k8s.emberstack.com/reflection-auto-enabled	원본	자동으로 미러 생성 여부
reflector.v1.k8s.emberstack.com/reflection-auto-namespaces	원본	자동 미러 생성할 네임스페이스 목록
reflector.v1.k8s.emberstack.com/reflects	미러	참조할 원본의 네임스페이스/이름
reflector.v1.k8s.emberstack.com/reflected-version	미러	수동 수정 시 동기화 버전 초기화

예시: Secret 원본

apiVersion: v1
kind: Secret
metadata:
  name: source-secret
  annotations:
    reflector.v1.k8s.emberstack.com/reflection-allowed: "true"
    reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "namespace-1,namespace-2"
data:
  ...

예시: Secret 미러

apiVersion: v1
kind: Secret
metadata:
  name: mirror-secret
  annotations:
    reflector.v1.k8s.emberstack.com/reflects: "default/source-secret"
data:
  ...

cert-manager 연계

Reflector는 cert-manager에서 생성하는 인증서 관련 Secret을 자동으로 미러링할 수 있도록 지원한다. 이를 통해 하나의 네임스페이스에서 발급받은 인증서를 다른 네임스페이스에도 동일하게 반영하여, 여러 애플리케이션이 같은 인증서를 공유할 수 있다.

cert-manager 1.5 이상: Certificate 리소스의 secretTemplate에 Reflector 어노테이션을 지정하면, 해당 Certificate로부터 생성되는 Secret이 자동으로 미러링 대상이 된다.
cert-manager 1.15 이상: Ingress 리소스에 cert-manager.io/secret-template 어노테이션을 추가하면, cert-manager가 생성하는 Secret에 Reflector 어노테이션이 포함되어 미러링을 적용할 수 있다.

예시: Certificate 리소스

아래 예시는 cert-manager가 my-cert-secret Secret을 생성할 때, Reflector가 이를 감지하여 staging과 prod 네임스페이스에 자동으로 미러링하도록 설정한 것이다.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-cert
  namespace: default
spec:
  secretName: my-cert-secret
  dnsNames:
    - example.com
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  secretTemplate:
    annotations:
      reflector.v1.k8s.emberstack.com/reflection-allowed: "true"
      reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "staging,prod"

예시: Ingress 리소스

아래 예시는 Ingress 리소스가 TLS 인증서를 발급받을 때, cert-manager가 생성하는 Secret에 Reflector 어노테이션을 자동으로 추가하는 방식이다. 이를 통해 인증서 Secret이 생성되자마자 Reflector가 감지하여 다른 네임스페이스로 복제할 수 있다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    cert-manager.io/secret-template: |
      {
        "annotations": {
          "reflector.v1.k8s.emberstack.com/reflection-allowed": "true",
          "reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces": "staging,prod"
        }
      }
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 80
  tls:
    - hosts:
        - example.com
      secretName: my-cert-secret