Cluster Generator

Cluster Generator

Argo CD에서 관리되는 클러스터는 Argo CD 네임스페이스의 Secrets 내부에 저장돼요. ApplicationSet 컨트롤러는 그 같은 Secrets를 사용해 사용 가능한 클러스터를 식별하고 타겟팅할 파라미터를 생성해요.

출처: 문서

본문

Argo CD에 등록된 각 클러스터에 대해 Cluster generator는 클러스터 시크릿 안에서 찾은 항목 목록을 기반으로 파라미터를 생성해요.

각 클러스터에 대해 Application 템플릿에 다음 파라미터 값을 자동으로 제공해요:

• name
• nameNormalized (소문자 영숫자, - 또는 .만 포함하도록 정규화된 'name')
• server
• project (Secret의 'project' 필드, 있으면; 없으면 기본값 '')
• metadata.labels.<key> (Secret의 각 라벨에 대해)
• metadata.annotations.<key> (Secret의 각 어노테이션에 대해)

[!NOTE] 클러스터 이름에 밑줄(underscore)처럼 Kubernetes 리소스 이름에 유효하지 않은 문자가 들어 있다면 nameNormalized 파라미터를 사용하세요. 이러면 my_cluster-app1 같은 유효하지 않은 Kubernetes 리소스 이름이 렌더링되는 것을 막고, 대신 my-cluster-app1으로 변환돼요.

Argo CD 클러스터 Secrets 안에는 클러스터를 설명하는 데이터 필드가 있어요:

kind: Secret
data:
  # Within Kubernetes these fields are actually encoded in Base64; they are decoded here for convenience.
  # (They are likewise decoded when passed as parameters by the Cluster generator)
  config: "{'tlsClientConfig':{'insecure':false}}"
  name: "in-cluster2"
  server: "https://kubernetes.default.svc"
metadata:
  labels:
    argocd.argoproj.io/secret-type: cluster
# (...)

Cluster generator는 Argo CD에 정의된 클러스터를 자동으로 식별하고 클러스터 데이터를 파라미터로 추출해요:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters: {} # Automatically use all clusters defined within Argo CD
  template:
    metadata:
      name: '{{.name}}-guestbook' # 'name' field of the Secret
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{.server}}' # 'server' field of the secret
        namespace: guestbook

(전체 예시.)

이 예시에서 클러스터 시크릿의 name과 server 필드는 Application 리소스의 name과 server를 채우는 데 사용되며, 이 값은 그 같은 클러스터를 타겟팅하는 데 사용돼요.

라벨 셀렉터 (Label selector)

라벨 셀렉터를 사용해 대상 클러스터의 범위를 특정 라벨과 일치하는 것만으로 좁힐 수 있어요:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          staging: "true"
        # The cluster generator also supports matchExpressions.
        #matchExpressions:
        #  - key: staging
        #    operator: In
        #    values:
        #      - "true"
  template:
  # (...)

이것은 다음을 포함하는 Argo CD 클러스터 시크릿과 일치해요:

apiVersion: v1
kind: Secret
data:
  # (... fields as above ...)
metadata:
  labels:
    argocd.argoproj.io/secret-type: cluster
    staging: "true"
# (...)

클러스터 셀렉터는 여러 핵심 Kubernetes 리소스가 사용하는 set 기반 요구사항도 지원해요.

로컬 클러스터에 배포 (Deploying to the local cluster)

Argo CD에서 '로컬 클러스터'는 Argo CD(와 ApplicationSet 컨트롤러)가 설치된 클러스터를 말해요. 이는 선언적으로 또는 Argo CD CLI로 Argo CD에 추가된 '원격 클러스터'와 구분하기 위함이에요.

Cluster generator는 클러스터 셀렉터와 일치하는 모든 클러스터에 대해 로컬과 비로컬(원격) 클러스터를 자동으로 타겟팅해요.

Application으로 원격 클러스터만 타겟팅하려면(예: 로컬 클러스터 제외) 라벨이 있는 클러스터 셀렉터를 사용하세요. 예를 들어:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          argocd.argoproj.io/secret-type: cluster
        # The cluster generator also supports matchExpressions.
        #matchExpressions:
        #  - key: staging
        #    operator: In
        #    values:
        #      - "true"

이 셀렉터는 기본 로컬 클러스터에 Secret이 없으므로(따라서 그 시크릿에 argocd.argoproj.io/secret-type 라벨이 없음) 기본 로컬 클러스터와 일치하지 않아요. 그 라벨을 선택하는 어떤 클러스터 셀렉터든 자동으로 기본 로컬 클러스터를 제외해요.

그러나 로컬과 비로컬 클러스터를 모두 타겟팅하면서 라벨 매칭도 사용하려면 Argo CD 웹 UI 내에서 로컬 클러스터용 시크릿을 만들 수 있어요:

1. Argo CD 웹 UI에서 Settings 를 선택한 다음 Clusters 를 선택하세요.
2. 보통 in-cluster라는 이름의 로컬 클러스터를 선택하세요.
3. Edit 버튼을 클릭하고 클러스터의 NAME 을 다른 값으로 변경하세요. 예를 들어 in-cluster-local. 여기서 다른 값이어도 상관없어요.
4. 다른 모든 필드는 그대로 두세요.
5. Save 를 클릭하세요.

이 단계들은 직관에 반하는 것처럼 보일 수 있지만, 로컬 클러스터의 기본 값 중 하나를 변경하는 행위는 Argo CD 웹 UI가 이 클러스터용 새 시크릿을 만들게 해요. Argo CD 네임스페이스에서 이제 argocd.argoproj.io/secret-type": "cluster" 라벨이 있는 cluster-(cluster suffix)라는 Secret 리소스가 보일 거예요. 웹 UI 대신 로컬 클러스터 시크릿을 선언적으로 만들거나 CLI로 argocd cluster add "(context name)" --in-cluster를 사용해 만들 수도 있어요.

K8s 버전 기반 클러스터 가져오기 (Fetch clusters based on their K8s version)

Kubernetes 버전으로 클러스터를 가져올 수도 있어요. 이렇게 하려면 클러스터 시크릿에서 argocd.argoproj.io/auto-label-cluster-info 라벨을 true로 설정해야 해요. 설정되면 컨트롤러는 클러스터 시크릿에 실행 중인 Kubernetes 버전을 동적으로 라벨링해요. 그 값을 가져오려면 아래 예시처럼 argocd.argoproj.io/kubernetes-version을 사용해야 해요:

spec:
  goTemplate: true
  generators:
  - clusters:
      selector:
        matchLabels:
          argocd.argoproj.io/kubernetes-version: v1.28.1
        # matchExpressions are also supported.
        #matchExpressions:
        #  - key: argocd.argoproj.io/kubernetes-version
        #    operator: In
        #    values:
        #      - "v1.27.1"
        #      - "v1.28.1"

values 필드로 추가 key-value 쌍 전달 (Pass additional key-value pairs via values field)

클러스터 generator의 values 필드로 추가적이고 임의의 문자열 key-value 쌍을 전달할 수 있어요. values 필드로 추가된 값은 values.(field)로 추가돼요.

이 예시에서는 클러스터 시크릿의 라벨 매칭을 기반으로 revision 파라미터 값을 전달해요:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          type: 'staging'
      # A key-value map for arbitrary parameters
      values:
        revision: HEAD # staging clusters use HEAD branch
  - clusters:
      selector:
        matchLabels:
          type: 'production'
      values:
        # production uses a different revision value, for 'stable' branch
        revision: stable
  template:
    metadata:
      name: '{{.name}}-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        # The cluster values field for each generator will be substituted here:
        targetRevision: '{{.values.revision}}'
        path: guestbook
      destination:
        server: '{{.server}}'
        namespace: guestbook

이 예시에서 generators.clusters 필드의 revision 값은 values.revision으로 템플릿에 전달되며, 어느 generator가 파라미터 집합을 생성했는지에 따라 HEAD 또는 stable을 담아요.

[!NOTE] values. 프리픽스는 항상 generators.clusters.values 필드를 통해 제공된 값 앞에 붙어요. template의 파라미터 이름에 이 프리픽스를 포함해야 해요.

values에서는 다음 파라미터 값도 보간할 수 있어요(즉 이 페이지 처음에 제시된 같은 값들):

• name
• nameNormalized (소문자 영숫자, - 또는 .만 포함하도록 정규화된 'name')
• server
• metadata.labels.<key> (Secret의 각 라벨에 대해)
• metadata.annotations.<key> (Secret의 각 어노테이션에 대해)

위 예시를 확장해 이런 일을 할 수 있어요:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          type: 'staging'
      # A key-value map for arbitrary parameters
      values:
        # If `my-custom-annotation` is in your cluster secret, `revision` will be substituted with it.
        revision: '{{index .metadata.annotations "my-custom-annotation"}}'
        clusterName: '{{.name}}'
  - clusters:
      selector:
        matchLabels:
          type: 'production'
      values:
        # production uses a different revision value, for 'stable' branch
        revision: stable
        clusterName: '{{.name}}'
  template:
    metadata:
      name: '{{.name}}-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        # The cluster values field for each generator will be substituted here:
        targetRevision: '{{.values.revision}}'
        path: guestbook
      destination:
        # In this case this is equivalent to just using {{name}}
        server: '{{.values.clusterName}}'
        namespace: guestbook

클러스터 정보를 플랫 리스트로 수집 (Gather cluster information as a flat list)

클러스터마다 애플리케이션 하나를 배포하지 않고 클러스터 정보를 수집해야 할 때가 있을 수 있어요. 그럴 때 클러스터 generator에서 flatList 옵션을 사용할 수 있어요.

이 옵션을 사용하는 클러스터 generator 예시:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          type: 'staging'
      flatList: true
  template:
    metadata:
      name: 'flat-list-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        # The cluster values field for each generator will be substituted here:
        targetRevision: 'HEAD'
        path: helm-guestbook
        helm:
          values: |
            clusters:
            {{- range .clusters }}
              - name: {{ .name }}
            {{- end }}
      destination:
        # In this case this is equivalent to just using {{name}}
        server: 'my-cluster'
        namespace: guestbook

cluster1과 cluster2라는 이름을 가진 두 클러스터 시크릿이 일치한다면, 이는 단일 Application을 생성해요:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: flat-list-guestbook
  namespace: guestbook
spec:
  project: "my-project"
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps/
    targetRevision: 'HEAD'
    path: helm-guestbook
    helm:
      values: |
        clusters:
          - name: cluster1
          - name: cluster2

각각 flatList 옵션이 있는 여러 클러스터 generator를 사용하는 경우, 각 generator의 값과 템플릿이 다를 수 있어 단순히 병합할 수 없으므로 클러스터 generator마다 Application 하나가 생성돼요.

더 알아보기 (Learn more)

• ApplicationSet 소개 — ApplicationSet 개요.
• 문서: Cluster Generator