소스 하이드레이터

소스 하이드레이터 (Source Hydrator)

Helm이나 Kustomize 같은 도구는 매니페스트를 간결·재사용 가능하게 표현해 주지만, 실제 클러스터에 적용되는 Kubernetes 매니페스트가 무엇인지 가려버리기도 해요. 소스 하이드레이터는 실제로 적용될 매니페스트(하이드레이션된 매니페스트)를 클러스터에 동기화하기 전에 git으로 먼저 밀어 넣어, 적용되는 실제 Kubernetes 매니페스트를 확인할 수 있게 해주는 기능입니다.

출처: 문서

본문

Warning

베타 기능 (v3.5.0부터)

클러스터에 동기화하기 전에 하이드레이션된 매니페스트를 git으로 밀어 넣는 베타 품질 기능입니다.

Helm과 Kustomize 같은 도구는 사용자가 Kubernetes 매니페스트를 더 간결하고 재사용 가능하게 표현할 수 있게 해줍니다(DRY - Don't Repeat Yourself 원칙). 그러나 이러한 도구는 클러스터에 실제로 적용되는 Kubernetes 매니페스트를 가릴 수 있습니다.

렌더링된 매니페스트 패턴(rendered manifest pattern) 은 Argo CD의 기능으로, 하이드레이션된 매니페스트를 클러스터에 동기화하기 전에 git으로 밀어 넣을 수 있게 해줍니다. 이를 통해 사용자는 클러스터에 적용되는 실제 Kubernetes 매니페스트를 확인할 수 있습니다.

소스 하이드레이터 활성화 (Enabling the Source Hydrator)

소스 하이드레이터는 기본적으로 비활성화되어 있습니다.

소스 하이드레이터를 활성화하려면 "commit server" 컴포넌트를 활성화하고 argocd-cmd-params-cm ConfigMap의 hydrator.enabled 필드를 "true"로 설정해야 합니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
  namespace: argocd
data:
  hydrator.enabled: "true"

Important

ConfigMap을 갱신한 후 변경 사항을 적용하려면 Argo CD controller와 API server를 반드시 재시작해야 합니다.

Argo CD 설치에 *-install.yaml 매니페스트 중 하나를 사용한다면 대신 해당 파일의 *-install-with-hydrator.yaml 버전을 사용할 수 있습니다.

예를 들어,

Without hydrator: https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
With hydrator:    https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install-with-hydrator.yaml

Important

*-install-with-hydrator.yaml 매니페스트는 소스 하이드레이터가 기본 활성화되거나 제거될 때 결국 제거될 것입니다. 업그레이드 가이드에서 install-with-hydrator.yaml 매니페스트가 더 이상 제공되지 않는다는 사실을 알려줄 것입니다.

소스 하이드레이터 사용하기 (Using the Source Hydrator)

소스 하이드레이터를 사용하려면 먼저 push 시크릿과 pull 시크릿을 설치해야 합니다. 이 예제는 인증에 GitHub App을 사용하지만, Argo CD가 저장소 접근에 지원하는 어떤 인증 방식이라도 사용할 수 있습니다.

apiVersion: v1
kind: Secret
metadata:
  name: my-push-secret
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository-write
type: Opaque
stringData:
  url: "https://github.com//"
  type: "git"
  githubAppID: ""
  # githubAppInstallationID is optional and will be auto-discovered if omitted
  githubAppInstallationID: "" # Optional
  githubAppPrivateKey: |
    
---
apiVersion: v1
kind: Secret
metadata:
  name: my-pull-secret
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  url: "https://github.com//"
  type: "git"
  githubAppID: ""
  # githubAppInstallationID is optional and will be auto-discovered if omitted
  githubAppInstallationID: ""  # Optional
  githubAppPrivateKey: |

위 시크릿들 사이의 유일한 차이점은 리소스 이름 외에, push 시크릿이 argocd.argoproj.io/secret-type: repository-write 라벨을 포함한다는 것입니다. 이 라벨로 인해 해당 시크릿이 git에서 pull하는 대신 git으로 매니페스트를 push하는 데 사용됩니다. Argo CD는 더 나은 격리를 위해 push와 pull에 서로 다른 시크릿을 요구합니다.

시크릿이 설치되면 Application의 spec.sourceHydrator 필드를 설정하세요. 예를 들어:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: helm-guestbook
      targetRevision: HEAD
    syncSource:
      targetBranch: environments/dev
      path: helm-guestbook

이 예제에서 하이드레이션된 매니페스트는 argocd-example-apps 저장소의 environments/dev 브랜치로 push됩니다. drySource 필드는 원래의 렌더링되지 않은 구성이 어디 있는지 Argo CD에 알려줍니다. 이는 Helm 차트, Kustomize 디렉터리 또는 일반 매니페스트일 수 있습니다. Argo CD는 이 소스를 읽고, 그로부터 최종 Kubernetes 매니페스트를 렌더링한 다음, 그 하이드레이션된 매니페스트를 syncSource.path가 지정하는 위치에 기록합니다.

별도의 대상 저장소 (Separate destination repository)

기본적으로 하이드레이션된 매니페스트는 dry 소스와 동일한 git 저장소에 기록됩니다. 다른 저장소에 하이드레이션하려면 syncSource.repoURL을 설정하세요. syncSource.repoURL을 생략하면 drySource.repoURL로 기본 설정됩니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/my-org/config
      path: helm-guestbook
      targetRevision: HEAD
    syncSource:
      repoURL: https://github.com/my-org/deployments
      targetBranch: environments/dev
      path: helm-guestbook

두 저장소 모두 애플리케이션의 AppProject(spec.sourceRepos)에서 허용되어야 합니다. 하이드레이터는 dry 소스 저장소에 대한 읽기 권한과 대상 저장소에 대한 쓰기 권한(repository-write 시크릿, 위 push 시크릿 예제 참조)이 필요합니다.

Note

hydrateTo는 저장소와 경로를 syncSource에서 상속합니다. syncSource.repoURL이 별도의 저장소를 가리킬 때, 스테이징된 매니페스트는 해당 저장소로도 push됩니다.

소스 하이드레이션을 사용할 때 syncSource.path 필드는 필수이며 항상 저장소의 루트가 아닌 디렉터리를 가리켜야 합니다. 경로를 저장소 루트(예: "." 또는 "")로 설정하는 것은 지원되지 않습니다. 이는 하이드레이션이 항상 전용 하위 디렉터리로 범위가 제한되도록 보장하여, 저장소 루트에 존재할 수 있는 파일을 실수로 덮어쓰거나 삭제하는 것을 방지합니다.

각 하이드레이션 실행 동안 Argo CD는 애플리케이션의 구성된 경로에 자체적으로 생성한 파일(예: manifest.yaml)을 덮어쓰지만, 해당 경로에 이미 존재하는 다른 파일을 삭제하지는 않습니다. 이전 하이드레이션에서 생성되었으나 덮어쓰지 않은 오래된 파일은 출력 디렉터리에 남아 있게 됩니다.

생성된 manifest.yaml은 매 실행마다 완전히 다시 쓰여지므로, dry 소스에서 제거된 리소스는 그 안에서 사라지고(prune 동기화 옵션이 활성화된 경우) 다음 동기화 때 정리됩니다. 그러나 추가로 남은 파일들은 자동으로 제거되지 않습니다.

저장소 루트는 절대 쓰이지 않으므로, CI/CD 구성, README 파일 등 루트 수준의 자산은 그대로 유지됩니다.

애플리케이션의 경로가 변경되면 이전 디렉터리는 자동으로 제거되지 않습니다. 마찬가지로 애플리케이션이 삭제되어도 출력 경로는 저장소에 남게 되며, 원한다면 저장소 소유자가 수동으로 정리해야 합니다. 애플리케이션이 재구성되거나 제거될 때 파일의 실수 삭제를 방지하고, 저장소에 공존할 수 있는 CI 파이프라인 같은 중요한 파일을 보호하기 위한 의도적인 설계입니다.

Note

하이드레이터는 dry 소스에 새 커밋이 감지될 때만 트리거됩니다. 애플리케이션을 추가하거나 제거하는 것만으로는 하이드레이션이 실행되지 않습니다. 애플리케이션 집합이 변경되어도 dry-source 커밋이 변경되지 않으면, 하이드레이션은 다음 커밋까지 대기합니다.

이는 의도적인 설계입니다. 하이드레이터는 dry-source 커밋당 하나의 하이드레이션을 생성하고, 대상을 공유하는 애플리케이션들 간의 원자성을 유지합니다. 이미 하이드레이션된 dry-source 커밋에 의존하는 애플리케이션(예: ApplicationSet으로 생성된 애플리케이션)을 추가한다면, dry 소스에 빈 커밋을 push하여 새 애플리케이션이 하이드레이션되도록 하세요.

Important

프로젝트 범위 저장소 (Project-Scoped Repositories)

Repository 시크릿은 project 필드를 포함할 수 있으며, 이로 인해 해당 시크릿은 그 프로젝트의 애플리케이션만 사용할 수 있게 됩니다. 소스 하이드레이터는 동일한 저장소·브랜치에 쓰는 모든 애플리케이션이 같은 프로젝트에 있을 때만 프로젝트 범위 저장소를 지원합니다. 서로 다른 프로젝트의 애플리케이션이 같은 저장소·브랜치에 쓴다면, 소스 하이드레이터는 프로젝트 범위 저장소 시크릿을 사용할 수 없고 전역 저장소 시크릿이 필요하게 됩니다. 이 동작은 향후 변경될 수 있습니다.

저장소에 대해 여러 repository-write 시크릿이 사용 가능하다면, 소스 하이드레이터는 일치하는 시크릿 중 하나를 비결정적으로 선택하고 "Found multiple credentials for repoURL" 경고를 기록합니다.

소스 구성 옵션 (Source Configuration Options)

소스 하이드레이터는 drySource 필드의 인라인 구성 옵션을 통해 다양한 소스 유형을 지원합니다. 이를 통해 환경별 구성으로 Helm 차트, Kustomize 애플리케이션, 디렉터리 및 플러그인을 사용할 수 있습니다.

Helm 차트 (Helm Charts)

drySource에 helm 필드를 지정하여 Helm 차트를 사용할 수 있습니다:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-helm-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: helm-guestbook
      targetRevision: HEAD
      helm:
        valueFiles:
          - values-prod.yaml
        parameters:
          - name: image.tag
            value: v1.2.3
        releaseName: my-release
    syncSource:
      targetBranch: environments/prod
      path: helm-guestbook-hydrated

Kustomize 애플리케이션 (Kustomize Applications)

Kustomize 애플리케이션에는 kustomize 필드를 사용하세요:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-kustomize-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: kustomize-guestbook
      targetRevision: HEAD
      kustomize:
        namePrefix: prod-
        nameSuffix: -v1
        images:
          - gcr.io/heptio-images/ks-guestbook-demo:0.2
    syncSource:
      targetBranch: environments/prod
      path: kustomize-guestbook-hydrated

디렉터리 애플리케이션 (Directory Applications)

특정 옵션이 있는 일반 디렉터리 애플리케이션에는 directory 필드를 사용하세요:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-directory-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: guestbook
      targetRevision: HEAD
      directory:
        recurse: true
    syncSource:
      targetBranch: environments/prod
      path: guestbook-hydrated

구성 관리 플러그인 (Config Management Plugins)

plugin 필드를 지정하여 Config Management Plugins도 사용할 수 있습니다:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-plugin-app
spec:
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: my-plugin-app
      targetRevision: HEAD
      plugin:
        name: my-custom-plugin
        env:
          - name: ENV_VAR
            value: prod
    syncSource:
      targetBranch: environments/prod
      path: my-plugin-app-hydrated

Feature Parity

소스 하이드레이터는 일반 Application 소스 필드와 동일한 구성 옵션을 지원합니다. 이러한 소스 유형을 각각의 구성 옵션과 함께 조합하여 애플리케이션의 요구에 맞출 수 있습니다.

"스테이징" 브랜치로 push하기 (Pushing to a "Staging" Branch)

소스 하이드레이터를 사용해 하이드레이션된 매니페스트를 syncSource 브랜치 대신 "스테이징" 브랜치로 push할 수 있습니다. 이는 어떤 선행 조건이 충족될 때까지 하이드레이션된 매니페스트가 클러스터에 적용되지 않도록 하는 방법을 제공합니다(사실상 Pull Request를 통한 환경 승격 처리 방법을 제공).

"스테이징" 브랜치로 push하려면 Application의 spec.sourceHydrator.hydrateTo 필드를 설정하세요. 예를 들어:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  project: my-project
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  sourceHydrator:
    drySource:
      repoURL: https://github.com/argoproj/argocd-example-apps
      path: helm-guestbook
      targetRevision: HEAD
    syncSource:
      targetBranch: environments/dev
      path: helm-guestbook
    hydrateTo:
      targetBranch: environments/dev-next

이 예제에서 하이드레이션된 매니페스트는 environments/dev-next 브랜치로 push되고, Argo CD는 무엇인가가 이를 environments/dev 브랜치로 옮길 때까지 변경 사항을 동기화하지 않습니다.

CI 작업을 사용해 하이드레이션된 매니페스트를 hydrateTo 브랜치에서 syncSource 브랜치로 옮길 수 있습니다. 게이팅 메커니즘을 도입하려면 hydrateTo 브랜치에서 syncSource 브랜치로 변경 사항을 병합하도록 Pull Request를 열도록 요구할 수 있습니다.

Argo CD는 hydrateTo 브랜치에만 변경 사항을 push하며, PR을 생성하거나 변경 사항을 syncSource 브랜치로 옮기는 것을 돕지 않습니다. 변경 사항을 hydrateTo 브랜치에서 syncSource 브랜치로 옮기려면 자체 도구를 사용해야 합니다.

커밋 추적 (Commit Tracing)

CI나 다른 도구가 코드 변경 후 DRY 매니페스트 변경 사항을 push하는 것은 흔한 일입니다. 사용자가 하이드레이션된 커밋을 하이드레이션을 유발한 원래 코드 변경으로 추적할 수 있는 것은 중요합니다.

Source Hydrator는 이 추적을 돕기 위해 일부 커스텀 git commit trailer를 사용합니다. 이미지를 빌드하고 DRY 매니페스트에 이미지 버프를 push하는 CI 작업은 다음 커밋 trailer를 사용해 하이드레이션된 커밋을 코드 커밋에 연결할 수 있습니다.

git commit -m "Bump image to v1.2.3" \
  # Must be an RFC 5322 name
  --trailer "Argocd-reference-commit-author: Author Name " \
  # Must be a hex string 5-40 characters long
  --trailer "Argocd-reference-commit-sha: " \
  # The subject is the first line of the commit message. It cannot contain newlines.
  --trailer "Argocd-reference-commit-subject: Commit message of the code commit" \
   # The body must be a valid JSON string, including opening and closing quotes
  --trailer 'Argocd-reference-commit-body: "Commit message of the code commit\n\nSigned-off-by: Author Name "' \
   # The repo URL must be a valid URL
  --trailer "Argocd-reference-commit-repourl: https://git.example.com/owner/repo" \
  # The date must by in ISO 8601 format
  --trailer "Argocd-reference-commit-date: 2025-06-09T13:50:18-04:00"

Note

커밋 trailer에는 줄바꿈이 포함되어서는 안 됩니다.

전체 CI 스크립트는 대략 다음과 같을 수 있습니다:

# Clone code repo
git clone https://git.example.com/owner/repo.git
cd repo

# Build the image and get the new image tag
# 

# Get the commit information
author=$(git show -s --format="%an ")
sha=$(git rev-parse HEAD)
subject=$(git show -s --format='%s')
body=$(git show -s --format='%b')
jsonbody=$(jq -n --arg body "$body" '$body')
repourl=$(git remote get-url origin)
date=$(git show -s --format='%aI')

# Clone the dry source repo
git clone https://git.example.com/owner/deployment-repo.git
cd deployment-repo

# Bump the image in the dry manifests
# 

# Commit the changes with the commit trailers
git commit -m "Bump image to v1.2.3" \
  --trailer "Argocd-reference-commit-author: $author" \
  --trailer "Argocd-reference-commit-sha: $sha" \
  --trailer "Argocd-reference-commit-subject: $subject" \
  --trailer "Argocd-reference-commit-body: $jsonbody" \
  --trailer "Argocd-reference-commit-repourl: $repourl" \
  --trailer "Argocd-reference-commit-date: $date"

커밋 메타데이터는 하이드레이션된 커밋의 루트 hydrator.metadata 파일에 나타납니다:

{
  "author": "CI ",
  "subject": "chore: bump image to b82add2",
  "date": "2025-06-09T13:50:08-04:00",
  "body": "Signed-off-by: CI \n",
  "drySha": "6cb951525937865dced818bbdd78c89b2d2b3045",
  "repoURL": "https://git.example.com/owner/manifests-repo",
  "references": [
    {
      "commit": {
        "author": {
          "name": "Author Name",
          "email": "[email protected]"
        },
        "sha": "b82add298aa045d3672880802d5305c5a8aaa46e",
        "subject": "chore: make a change",
        "body": "make a change\n\nSigned-off-by: Author Name ",
        "repoURL": "https://git.example.com/owner/repo",
        "date": "2025-06-09T13:50:18-04:00"
      }
    }
  ]
}

최상위 "body" 필드는 subject 줄과 references에 사용된 Argocd-reference-commit-* trailer를 뺀 DRY 커밋의 커밋 메시지를 포함합니다. 인식되지 않거나 유효하지 않은 trailer는 body에 보존됩니다.

references는 배열이지만, 소스 하이드레이터는 현재 단일 관련 커밋만 지원합니다. trailer가 두 번 이상 지정되면 마지막 것이 사용됩니다.

모든 trailer는 선택적입니다. trailer가 지정되지 않으면 해당 필드는 메타데이터에서 생략됩니다.

커밋 메시지 템플릿 (Commit Message Template)

커밋 메시지는 Go text/template으로 생성되며, 선택적으로 argocd-cm ConfigMap을 통해 사용자가 구성할 수 있습니다. 템플릿은 hydrator.metadata의 값으로 렌더링됩니다. 템플릿은 여러 줄일 수 있어 subject 줄, body 및 선택적 trailer를 정의할 수 있습니다. 커밋 메시지 템플릿을 정의하려면 argocd-cm ConfigMap에 sourceHydrator.commitMessageTemplate 필드를 설정해야 합니다.

템플릿은 Sprig 함수 라이브러리의 함수를 호출할 수 있습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  sourceHydrator.commitMessageTemplate: |
    {{.metadata.drySha | trunc 7}}: {{ .metadata.subject }}
    {{- if .metadata.body }}

    {{ .metadata.body }}
    {{- end }}
    {{ range $ref := .metadata.references }}
    {{- if and $ref.commit $ref.commit.author }}
    Co-authored-by: {{ $ref.commit.author }}
    {{- end }}
    {{- end }}
    {{- if .metadata.author }}
    Co-authored-by: {{ .metadata.author }}
    {{- end }}

README 템플릿 (README Template)

하이드레이션 README는 Go text/template으로 생성되며, 선택적으로 argocd-cm ConfigMap을 통해 사용자가 구성할 수 있습니다. 템플릿은 hydrator.metadata의 값으로 렌더링되고, 구조화된 문서를 정의하기 위해 여러 줄일 수 있습니다. 이를 통해 사용자는 하이드레이션 프로세스와 참조가 어떻게 문서화되는지 사용자 정의할 수 있습니다.

README 템플릿을 정의하려면 argocd-cm ConfigMap에 sourceHydrator.readmeMessageTemplate 필드를 설정하세요.

템플릿은 Sprig 함수 라이브러리의 함수도 사용할 수 있습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  sourceHydrator.readmeMessageTemplate: |
    # Manifest Hydration

    To hydrate the manifests in this repository, run the following commands:

    ```shell
    git clone {{ .RepoURL }}
    git checkout {{ .DrySHA }}
    {{ range $command := .Commands }}
    {{ $command }}
    {{ end }}
    ```

    {{ if .References }}
    ## References

    {{ range $ref := .References }}
    {{ if $ref.Commit }}
    * [{{ $ref.Commit.SHA | trunc 7 }}]({{ $ref.Commit.RepoURL }}): {{ $ref.Commit.Subject }} ({{ $ref.Commit.Author }})
    {{ end }}
    {{ end }}
    {{ end }}

커밋 작성자 구성 (Commit Author Configuration)

하이드레이션된 매니페스트를 커밋할 때 소스 하이드레이터가 사용하는 git 커밋 작성자 이름과 이메일을 사용자 정의할 수 있습니다. 이는 argocd-cm ConfigMap을 통해 구성됩니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  commit.author.name: "GitOps Bot"
  commit.author.email: "[email protected]"

구성 키 (Configuration Keys):

  • commit.author.name: git 커밋 작성자 이름(설정하지 않으면 "Argo CD" 기본값)
  • commit.author.email: git 커밋 작성자 이메일(설정하지 않으면 "[email protected]" 기본값)

두 값 모두 선택적입니다. 하나만 구성하면 구성된 값이 사용되고 다른 값은 기본값을 사용합니다.

자격 증명 템플릿 (Credential Templates)

자격 증명 템플릿(credential templates)은 단일 자격 증명을 여러 저장소에 사용할 수 있게 해줍니다. 소스 하이드레이터는 자격 증명 템플릿을 지원합니다. 예를 들어 URL 접두사 https://github.com/argoproj에 대해 자격 증명 템플릿을 설정하면, 자체 자격 증명이 구성되지 않은 이 URL을 접두사로 하는 모든 저장소(예: https://github.com/argoproj/argocd-example-apps)에 이 자격 증명이 사용됩니다. 자세한 내용은 자격 증명 템플릿을 참조하세요. repo-write-creds 시크릿의 예입니다.

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-write-creds
stringData:
  type: git
  url: https://github.com/argoproj
  password: my-password
  username: my-username

git note 기반 하이드레이션 상태 추적 (Git Note-based Hydration State Tracking)

Source Hydrator는 커밋이 하이드레이션된 매니페스트에 영향을 주지 않으면 DRY 커밋에 대해 새 하이드레이션 커밋을 생성하지 않습니다. 대신 하이드레이션 상태(마지막으로 하이드레이션된 DRY SHA)는 전용 source-hydrator 네임스페이스의 git note를 사용해 추적됩니다.

실행마다 하이드레이터는:

  • 마지막으로 하이드레이션된 DRY SHA의 git note를 확인합니다.
  • 해당 SHA 이후 매니페스트가 변경되지 않았다면 note만 갱신합니다.
  • 매니페스트가 변경되었다면 새 매니페스트를 커밋하고 note도 갱신합니다.

이로써 효율성이 향상되고 저장소의 커밋 노이즈가 줄어듭니다.

하이드레이션 실패와 재시도 (Hydration failures and retries)

하이드레이션이 실패하면 애플리케이션은 Failed 단계에 남고 오류 메시지는 status.sourceHydrator.currentOperation에 유지되어 문제를 진단할 수 있습니다.

Note

실패한 하이드레이션 후 controller는 무인 하이드레이션을 자동으로 재시도하기 전에 약 2분을 기다립니다. 이 간격은 ARGOCD_RECONCILIATION_TIMEOUT(애플리케이션 controller의 --app-resync 주기, 기본 120초)과 일치합니다.

다음 경우에는 쿨다운을 기다릴 필요가 없습니다:

  • 수동 또는 API 갱신(또는 dry-source 웹훅)을 트리거하면 하이드레이션을 즉시 재시도합니다.
  • status.sourceHydrator.lastComparedDryRevision에 dry 리비전 기준선이 이미 기록되어 있는 동안 새 dry 커밋이 감지됩니다(예: 매니페스트가 해결된 후 커밋 단계에서 하이드레이션이 실패한 경우).

첫 하이드레이션 시도가 dry 리비전이 기록되기 전에 실패하면, 쿨다운 중 새 커밋의 자동 감지가 쿨다운 만료 또는 수동 갱신까지 지연될 수 있습니다.

매니페스트 생성 경로 (Manifest Generate Paths)

소스 하이드레이터는 불필요한 하이드레이션을 피하기 위해 manifest-generate-paths 어노테이션을 존중합니다. 어노테이션이 설정되면, 주석된 경로(drySource 경로에 상대적으로 해석됨)를 건드리지 않는 새 dry-source 커밋은 재하이드레이션을 트리거하지 않습니다.

이는 웹훅 기반 및 주기적 재조정 갱신 모두에 적용됩니다:

  • dry 소스에 대한 웹훅은 변경된 파일이 주석된 경로와 일치할 때만 하이드레이션을 트리거합니다.
  • sync 소스에 대한 웹훅(예: 외부 승격 프로세스가 hydrateTo 브랜치를 syncSource 브랜치로 병합할 때)은 하이드레이션된 매니페스트의 일반 갱신 및 동기화를 트리거합니다.

어노테이션의 경로 필터링은 dry 소스에 적용됩니다. sync 소스는 항상 구성된 syncSource.path에서 감시되며, 어노테이션 값은 sync 소스에 적용되지 않습니다.

제한 사항 (Limitations)

서명 검증 (Signature Verification)

현재 상태: 알파 (v3.5부터)

하이드레이터는 매니페스트를 생성하기 전에 DRY 리비전에 대해 프로젝트의 SourceIntegrity 정책(예: GPG 서명 검증)을 적용합니다. 프로젝트가 검증을 요구하는데 DRY 커밋이 실패(또는 검증되지 않음)하면 하이드레이션이 거부됩니다. 검증은 AppProject에 .spec.sourceIntegrity를 구성하여 프로젝트별로 선택합니다. 설정 방법은 소스 무결성 검증을 참조하세요(예: Git GnuPG 검증 사용).

하이드레이터는 git에 push하는 커밋에 서명하지 않습니다. 따라서 하이드레이션된 브랜치에 대해 서명 검증이 활성화되어 있으면, Argo CD가 하이드레이션된 매니페스트를 동기화할 때 해당 커밋은 검증에 실패합니다.

프로젝트 범위 push 시크릿 (Project-Scoped Push Secrets)

주어진 대상 repo/브랜치에 대한 모든 애플리케이션이 같은 프로젝트 아래에 있으면, 하이드레이터는 사용 가능한 프로젝트 범위 push 시크릿을 사용합니다. 어떤 repo/브랜치에 대한 두 애플리케이션이 서로 다른 프로젝트에 있으면 하이드레이터는 프로젝트 범위 push 시크릿을 사용할 수 없고 전역 push 시크릿이 필요합니다.

한 브랜치로 하이드레이션하는 여러 Argo CD 인스턴스 (Multiple Argo CD Instances Hydrating to One Branch)

하이드레이션된 저장소와 브랜치는 단일 Argo CD 인스턴스가 소유해야 합니다. 동일한 drySource를 공유하면서 하이드레이션된 매니페스트를 같은 syncSource 저장소·브랜치에 쓰는 두 개의 별도 Argo CD 인스턴스는 지원되지 않습니다. 하이드레이터는 대상 브랜치의 dry-커밋당 git note에 하이드레이션 상태를 기록하므로, 한 인스턴스가 커밋을 기록하면 다른 인스턴스는 단락(short-circuit)되어 매니페스트가 오래된 상태로 남게 됩니다. 대신 각 인스턴스를 자체 브랜치로 하이드레이션하세요.

사전 요구 사항 (Prerequisites)

대상 클러스터의 시크릿 처리 (Handle Secrets on the Destination Cluster)

하이드레이션 프로세스의 일부로 매니페스트에 시크릿을 주입하는 도구(예: SOPS를 사용하는 Helm이나 Argo CD Vault Plugin)와 함께 소스 하이드레이터를 사용하지 마세요. 이러한 시크릿은 git에 커밋될 것입니다. 대신 대상 클러스터에서 시크릿 값을 채우는 시크릿 오퍼레이터(secrets operator)를 사용하세요.

모범 사례 (Best Practices)

하이드레이션을 결정적으로 만들기 (Make Hydration Deterministic)

소스 하이드레이터는 결정적이어야 합니다. 주어진 dry 소스 커밋에 대해 하이드레이터는 항상 동일한 하이드레이션된 매니페스트를 생성해야 합니다. 이는 하이드레이터가 git에 저장되지 않은 외부 상태나 구성에 의존하지 않아야 함을 의미합니다.

비결정적 하이드레이션의 예:

  • 고정되지 않은(pinned) 의존성을 사용하는 Helm 차트
  • randAlphaNum이나 lookup 같은 비결정적 템플릿 함수를 사용하는 Helm 차트
  • 시크릿 같은 비-git 상태를 가져오는 Config Management Plugins
  • 고정되지 않은 원격 베이스를 참조하는 Kustomize 매니페스트

브랜치 보호 활성화 (Enable Branch Protection)

하이드레이션된 브랜치에 하이드레이션된 매니페스트를 push하는 것은 Argo CD만이 해야 합니다. 다른 도구나 사용자가 하이드레이션된 브랜치에 push하지 못하게 하려면 SCM에서 브랜치 보호를 활성화하세요.

하이드레이션된 브랜치에 environments/ 같은 공통 접두사를 붙이는 것이 모범 사례입니다. 이렇게 하면 대상 저장소에서 브랜치 보호 규칙을 구성하기가 쉬워집니다.

Note

Hydrator 출력의 재현성과 결정성을 유지하기 위해, 하이드레이션 중에는 Argo CD 특정 메타데이터(예: argocd.argoproj.io/tracking-id)가 git에 기록되지 않습니다. 이러한 어노테이션은 애플리케이션 동기화·비교 중에 동적으로 추가됩니다.

애플리케이션 경로 정리 동작 (Application Path Cleaning Behavior)

Source Hydrator는 새 매니페스트를 쓰기 전에 애플리케이션의 구성된 출력 경로에서 파일을 정리(제거)하지 않습니다. 이는 이전에 하이드레이션으로 생성되었거나(또는 다른 방식으로 존재하는) 새 하이드레이션 실행에서 덮어쓰이지 않은 파일이 출력 디렉터리에 남아 있게 됨을 의미합니다.

더 알아보기 (Learn more)