K8s Reflector

1 개요

Reflector

리플렉터

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

2 특징

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

3 배포

3.1 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

3.2 수동 배포

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

4 사용법

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

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

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

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

4.1.1 자동 미러링 옵션

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

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

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

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

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

4.3 동작 방식

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

4.4 어노테이션 요약 표

어노테이션 키	대상	설명
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	미러	수동 수정 시 동기화 버전 초기화

4.5 예시: 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:
  ...

4.6 예시: Secret 미러

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

5 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 어노테이션이 포함되어 미러링을 적용할 수 있다.

5.1 예시: 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"

5.2 예시: 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

6 같이 보기

• k8s Secret
• k8s ConfigMap
• cert-manager

7 참고

• https://github.com/emberstack/kubernetes-reflector
• https://artifacthub.io/packages/helm/emberstack/reflector