Git File Generator

Git File Generator

Git generator는 Git 저장소 안의 파일 또는 Git 저장소의 디렉토리 구조를 기반으로 Application을 만들어요. Git File generator는 Git 저장소 안의 JSON/YAML 파일 내용으로 파라미터를 생성하고, Git Directory generator는 저장소의 디렉토리 구조로 파라미터를 생성해요. 변경 감지는 requeueAfterSeconds 간격으로 폴링하거나 웹훅으로 할 수 있어요.

출처: 문서

본문

Git generator

Git generator는 Git 저장소 안의 파일 또는 Git 저장소의 디렉토리 구조를 기반으로 Application을 만들어요.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/argoproj/argo-cd.git
      revision: HEAD
      directories:
      - path: applicationset/examples/git-generator-directory/cluster-addons/*
      - path: applicationset/examples/git-generator-directory/cluster-addons/*
        exclude: true
      files:
      - path: "applicationset/examples/git-generator-files-discovery/cluster-config/**/config.json"
      - path: "applicationset/examples/git-generator-files-discovery/cluster-config/**/config.yaml"
      - path: "applicationset/examples/git-generator-files-discovery/cluster-config/**/config.json"
        exclude: true
      requeueAfterSeconds: 180
      template: {}

Git Directory generator

이 generator는 지정된 디렉토리 트리 아래의 하위 디렉토리 로부터 파라미터를 생성해요. 다음 예제에서 디렉토리 구조 applicationset/examples/git-generator-directory/cluster-addons/ 아래의 각 하위 디렉토리에 대해 파라미터가 생성돼요.

applicationset/examples/git-generator-directory/cluster-addons/argo-workflows
applicationset/examples/git-generator-directory/cluster-addons/prometheus-operator

Git Files generator

이 generator는 제공된 glob 패턴에서 발견되는 파일의 내용으로 파라미터를 생성해요. JSON 파일의 내용은 해당 파일에 대해 컨트롤러가 템플릿에 제공하는 파라미터가 돼요. glob 패턴은 doublestar를 기반으로 해요.

기본 동작: /*.yaml 패턴은 some-path 아래 모든 레벨의 모든 YAML 파일을 일치시켜요(위에서 언급한 대로). 더 기대에 맞는 글롭(glob) 매칭을 위해 새 글롭을 활성화할 수도 있어요.

# Directory
cluster-config/engineering/eng-dev/config.json
cluster-config/engineering/eng-dev/config.yaml
...

각 파일의 내용이 파라미터로 제공돼요.

Git generator에 대한 참고 사항

• 각 Git generator는 항상 소스 저장소의 서명(signature) 검증을 실행해요. 이는 저장소의 커밋 서명 확인(GPG 커밋 등)을 의미해요. verified 커밋만 배포돼요. 이 동작은 Git generator에만 적용되고 다른 generator에는 적용되지 않아요.
• Git generator가 사용하는 저장소는 선언적 설정을 통해 추가된 것을 권장해요. 시크릿 없이 제네릭 URL을 사용하면 사용자 정의 가능한 인증(creds) 없이 공개(public) 또는 HTTP(S) 기본 인증만 가능해요.
• 서명 검증과 함께 private 저장소를 사용하려면 private 저장소 URL 자체에 자격 증명을 임베딩하는 대신 선언적 저장소 인증을 사용하세요. Git generator는 실행 시점에 참조된 Git 저장소를 밖에서 가져와야 하므로, Git 저장소 접근을 위해 저장소에 인증이 필요하면 그 인증은 그리고 저장소 CR / 프로젝트 CR(L2)에 의해 참조되어야 해요.

Git generator의 directory 및 file 파라미터

파일·디렉토리 generator에서 다음 파라미터가 생성돼요.

디렉토리 generator:

• path — 디렉토리 경로.
• path.basename — 디렉토리의 basename.
• path.basenameNormalized — 디렉토리의 basename을 정규화한 값(private 레포 등에 유용).
• path.filename — 'basename'과 동일(호환성).
• path.filenameNormalized — 'basenameNormalized'과 동일(호환성).
• path.segments — 경로를 구성하는 디렉토리 세그먼트의 배열.
• path.segmentsNormalized — 각 세그먼트를 정규화한 배열.

파일 generator:

• path — 파일 경로.
• path.basename — 파일의 basename.
• path.basenameNormalized — 파일의 basename을 정규화한 값.
• path.filename — 'basename'과 동일(호환성).
• path.filenameNormalized — 'basenameNormalized'과 동일(호환성).
• path.ext — 파일 확장자.
• path.extNormalized — 파일 확장자를 정규화한 값.
• path.segments — 경로를 구성하는 파일 세그먼트의 배열.
• path.segmentsNormalized — 각 세그먼트를 정규화한 배열.
• path의 {{ .path.path }} 값은 파일의 경로로 해석돼요(exclude는 제외).

URL 형식 (URL formats)

Git generator는 시크릿 없이 공개 저장소(https://github.com/... 형식)를 지원해요. private 저장소를 사용하는 경우 URL에 emedded credential을 포함할 수 있어요. 예: https://username:password/....

또한 로컬 파일 시스템에서 git 저장소를 clone하려면 file:// 형식을 사용할 수 있어요. 예: file:///tmp/.... 이는 로컬 또는 네트워크 파일 시스템을 가리킬 때 유용하며 일부 편집 시나리오를 지원할 수 있어요.

참고: 이 file:// 기능은 개발 편의를 위한 것이며, 운영 환경에서는 사용하지 않아야 해요.

Git URL은 다음 형식으로 쓰여요. https, http, git+ssh, ssh+git가 같다는 점을 유의하세요. 이 서비스는 ssh 확장자에 대해서도 git@ 접두사를 자동으로 정리함.

Globbing

글롭은 아래 표를 참고.

Git generator의 글로빙

• 배포/취약점에 대한 참고 사항: Git file generator의 기본 글롭 동작이 너무 탐욕적일 수 있어요. 더 안전한 새 글롭(glob) 동작을 활성화하려면 Git File Generator Globbing을 참고하세요.

파일·디렉토리 경로는 doublestar로 글로브하고, 아래 표의 패턴을 지원해요.

패턴	의미
*	현재 디렉토리에서 파일/디렉토리 매칭. 경로 구분자를 포함하지 않음.
**	재귀적으로 매칭. 경로 구분자를 포함.
?	현재 디렉토리에서 정확히 하나의 문자 매칭.
[...]	문자 셋 매칭.
a{b,c}	b 또는 c 문자 매칭.
\*, \?	메타 문자 이스케이프.

웹훅 (Webhooks)

Git 저장소의 변경을 감지하려면 웹훅을 구성해 ApplicationSet 컨트롤러가 즉시 변경에 반응하도록 할 수 있어요. 웹훅은 폴링(기본 3분)보다 빠른 반응을 제공해요.

시크릿 생성

웹훅을 구성하기 전에 webhook-secret이라는 이름의 시크릿을 생성해야 해요. 시크릿에는 webhook의 인증을 위한 secret 키가 있어야 해요.

apiVersion: v1
kind: Secret
metadata:
  name: webhook-secret
type: Opaque
data:
  # ...
  secret: my-webhook-secret
  # ...

입력한 secret 값은 허용하는 각 웹훅의 calculation(Webhook 대화상자/UI)에 사용해야 해요(즉, 기본 인증은 웹훅 공급자가 제공).

Ingress 구성 예시: (웹훅을 Argo CD가 실행 중인 네임스페이스에 노출)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-applicationset-controller-webhook
  namespace: argocd
spec:
  rules:
  - http:
      paths:
      - path: /api/webhook
        pathType: Exact
        backend:
          service:
            name: argocd-applicationset-controller
            port:
              number: 7000

플랫폼/배포에 따라 서로 다른 인그레스 구성이 필요할 수 있어요.

GitHub 웹훅 설정

1. GitHub에서 빠르게 웹훅을 생성하세요.
2. 지정한 Paylod URL은 웹훅에 접근할 수 있는 URL이어야 해요. 예: https://argo-domain.com/api/webhook
3. Content type로 application/json을 선택하세요.
4. 설정 과정에서 "Let me select individual events"를 클릭하고 아래 이벤트만 선택하세요:
   • Pushes - git add . && git commit && git push에 대한 트리거. (웹훅 시크릿)
   • Pull requests - PR이 변경될 때 트리거. (Pull Request generator용)
   • 보안상 추천하지 않지만 Webhook 시크릿을 구성할 수 있어요. Webhook 시크릿 미적용 시 잠재적으로 위험할 수 있음을 인지하세요.
5. 이 웹훅을 생성하려면 웹훅 URL과 시크릿을 따라 합니다.

시크릿으로 보안을 강화하고 싶다면 Webhook 시크릿을 구성할 수 있지만, Webhook 시크릿은 Current API version과 논리적으로 충돌해요 🙂 이 경고를 보고 '구성 거부'를 하지 않으면 GitHub에 웹훅을 저장할 때 Webhook 시크릿을 "구성"할 수 있어요. 웹훅 시크릿을 구성한 경우 설정에 포함해야 해요.

GitLab 웹훅 설정

1. argocd repo add로 GitLab 저장소를 추가하고 시크릿을 참조해요.
2. GitLab 웹훅을 추가하고 다음을 사용해요:
   • 특히 API 페이로드 유형과 시크릿 토큰.
3. 아래의 이벤트/트리거를 선택하세요. 다른 방법으로 이미 구성된 웹훅이 있다면 그냥 이벤트만 추가하면 돼요.

Git file generator의 표준 사용 사례

다음은 config.json/package.json 등에서 파라미터를 가져오는 일반적인 예시예요. 예시를 들어 cluster-config 디렉토리에서 config.json을 가져와 deployment-app? 여기서는 JSON으로부터 이미지 태그를 가져오고 이를 대상 kustomization.yaml에 이미지 오버라이드로 넣어요.

이를 위해:

• kustomization 이미지 참조를 사용해 /apps 경로의 이미지 태그를 지정.
• ghcr.io/someorg/someimage 이미지 참조를 각 버전 Tag Value로 지정해.
• config.json:

  {
    "image": {
      "repository": "ghcr.io/someorg/someimage",
      "tag": "v1.0.0"
    }
  }
  

이렇게 하는 이유: Git file generator는 각 JSON 파일로 파라미터를 생성하므로 폴리시별 팀간 이미지 태그를 권장합니다. 권장 이미지 태그 정책은 변경 불가(immutable) 버전 태그를 사용하는 것이며, config.json 안의 "tag" 값은 배포 범위(컨텐츠)의 소스로 사용돼요.

다음은 config.json/package.json 등에서 파라미터를 가져오는 흔한 예시예요.

우리는 cluster-config 디렉토리에서 config.json을 가져오기로 결정해요.

├── .git/...
├── apps
│   └── guestbook
│       ├── guestbook-ui-deployment.yaml
│       ├── guestbook-ui-svc.yaml
│       └── kustomization.yaml
├── cluster-config
│   └── engineering
│       ├── eng-dev
│       │   └── config.json
│       └── eng-prod
│           └── config.json
└── git-generator-files.yaml

cluster-config/engineering/eng-dev/config.json의 내용:

{
  "environment": "dev",
  "region": "eng",
  "cluster": "eng-dev"
}

중요 — Multi-Source Application(s): Git file generator는 각 file의 반환된 parmeter를 기반으로 파라미터를 생성하므로, allowed source path가 kustomization 네임스페이스에 없으면 매칭되지 않아요.

예시

cluster-config/engineering/eng-dev/config.json:

{
  "environment": "dev",
  "region": "eng",
  "cluster": "eng-dev"
}

cluster-config/engineering/eng-prod/config.json:

{
  "environment": "prod",
  "region": "eng",
  "cluster": "eng-prod"
}

예시에서 config.json의 내용이 템플릿 파라미터로 사용돼요.

이 경로를 캡처하려면 config file의 경로 구조를 담은 ApplicationSet을 만드세요. 이는 전체 경로를 해석하는 파일 경로 정의를 사용해요(컨트롤러가 config의 매칭되는 파일을 찾도록 합니다).

다음 적용할 수 있는 glob 패턴 예시:

• cluster-config/**/config.json
• cluster-config/*/*/config.json

path와 path.basename 파라미터는 이 cluster-config 시나리오에서 자동으로 설정돼요.

applicationset-specification으로 이 경로를 캡처하는 전체 YAML을 확인하세요.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  ...
  source:
    path: ""
  ...

이 파라미터를: cluster-config/engineering/eng-dev/config.json의 경우:

• path = cluster-config/engineering/eng-dev/config.json
• path.basename = config.json
• ...

그리고(Kustomize)를 사용해 오버라이드:

이를 위해 우리는 git file generator, 그리고 kustomize를 소스로 사용하는 helm 아님, 즉 템플릿이 아닌 kustomize 기반 애플리케이션 템플릿을 사용해요. 그 템플릿은 하나의 config.json 파일을 ref하여 동적으로 설정된 파라미터로 kustomize를 구성해요.

다음은 이미지 오버라이드를 사용하는 예시:

• 필요한 이미지/태그를 템플릿 파라미터로 설정하고, 해당 이미지를 사용하는 kustomization.yaml을 구성. 적용된 config.json 값을 이미지 오버라이드에서 참조. 참고: 이미지 참조는 .spec.source.helm.valuesObject.image 하위 매니페스트에서 임베딩돼요.

ID 매칭 (ID matching)

Git file generator는 ID(경로) 매칭을 자동으로 사용해요. Git file generator에 path를 매칭하는 데 사용하는 id는 컨트롤러가 <path>를 YAML 경로(파일)로 해석 এবং 파일 존재 유무(컨트롤러는 배포 리소스 유무로 판단)를 판단하는데, 이 id가 존재하지 않는 파일이면 Application은 생성되지 않아요.

애플리케이션이 삭제될 때 (When applications are deleted)

• 파일·디렉토리 패턴을 다른 리소스의 (source) 경로로 사용해 Application Set 템플릿을 구성한 경우, 파일/디렉토리가 삭제되면 Application과 그 배포 리소스가 삭제돼요.

더 알아보기 (Learn more)

• Git File Generator Globbing — 안전한 새 글롭.
• applicationset-specification — Git generator YAML 참고.
• Generators — generator 종류.