트러블슈팅

트러블슈팅 (Troubleshooting)

argocd-notifications 알림이 동작하지 않을 때 진단하는 방법입니다. CLI 로 트리거·템플릿을 직접 검증하고, 흔한 오류 메시지의 원인을 찾아볼 수 있어요.

출처: 문서

본문

argocd admin notifications 는 컨트롤러 설정을 구성하고 문제를 트러블슈팅하는 데 도움을 주는 CLI 명령어 그룹입니다. 전체 명령어 세부 정보는 명령어 참조에서 확인할 수 있어요.

전역 플래그 (Global flags)

모든 하위 명령어에 사용할 수 있는 전역 플래그는 다음과 같습니다:

  • --config-map - argocd-notifications-cm ConfigMap 이 담긴 파일 경로. 지정하지 않으면 명령어가 로컬 Kubernetes config 파일을 사용해 argocd-notification-cm ConfigMap 을 로드합니다.

  • --secret - argocd-notifications-secret ConfigMap 이 담긴 파일 경로. 지정하지 않으면 명령어가 로컬 Kubernetes config 파일을 사용해 argocd-notification-secret Secret 을 로드합니다. 추가로 :empty 를 지정하면 알림 서비스 설정이 없는 빈 secret 을 사용할 수 있어요.

예시:

  • 로컬 config map 에 구성된 트리거 목록을 가져옵니다:
argocd admin notifications trigger get \
  --config-map ./argocd-notifications-cm.yaml --secret :empty
  • in-cluster config map 과 secret 을 사용해 알림을 트리거합니다:
argocd admin notifications template notify \
  app-sync-succeeded guestbook --recipient slack:argocd admin notifications

Kustomize

Kustomize 로 argocd-notifications 설정을 관리한다면 --config-map - 플래그를 사용해 kustomize build 의 전체 출력을 stdin 으로 전달할 수 있어요:

kustomize build ./argocd-notifications | \
  argocd-notifications \
  template notify app-sync-succeeded guestbook --recipient grafana:argocd \
  --config-map -

얻는 방법 (How to get it)

노트북에서 (On your laptop)

argocd CLI 는 GitHub release 첨부 파일에서 다운로드할 수 있습니다.

바이너리는 quay.io/argoproj/argocd 이미지에도 있습니다. docker run 과 볼륨 마운트를 사용해 어떤 플랫폼에서든 바이너리를 실행할 수 있어요.

예시:

docker run --rm -it -w /src -v $(pwd):/src \
  quay.io/argoproj/argocd:<version> \
  /app/argocd admin notifications trigger get \
  --config-map ./argocd-notifications-cm.yaml --secret :empty

클러스터에서 (In your cluster)

실행 중인 argocd-notifications-controller pod 에 SSH 로 접속하고 kubectl exec 명령어를 사용해 in-cluster 구성을 검증합니다.

예시:

kubectl exec -it argocd-notifications-controller-<pod-hash> \
  /usr/local/bin/argocd admin notifications trigger get

명령어 (Commands)

다음 명령어가 알림 관련 문제를 디버깅하는 데 도움이 될 수 있어요:

  • argocd admin notifications template get

  • argocd admin notifications template notify

  • argocd admin notifications trigger get

  • argocd admin notifications trigger run

오류 (Errors)

새 설정 파싱 실패 (Failed to parse new settings)

error converting YAML to JSON

YAML 문법이 잘못되었습니다.

잘못된 예:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  service.slack: |
    token: $slack-token
    icon: :rocket:

올바른 예:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  service.slack: |
    token: $slack-token
    icon: ":rocket:" # <- diff here

service type 'xxxx' is not supported

argocd-notifications 컨트롤러 버전을 확인하세요. 예를 들어 Teams 통합 지원은 v1.1.0 부터 시작됐습니다.

알림 수신자에게 실패 (Failed to notify recipient)

notification service 'xxxx' is not supported

xxxx 를 argocd-notifications-cm 에 정의하지 않았거나 파싱이 실패했습니다.

GitHub.repoURL () does not have a / using the configuration

여러 소스를 가진 Application 에 의해 발생할 가능성이 높습니다:

spec:
  sources:  # <- multiple sources
  - repoURL: https://github.com/exampleOrg/first.git
    path: sources/example
  - repoURL: https://github.com/exampleOrg/second.git
    targetRevision: "{{branch}}"

표준 알림 템플릿은 단일 소스({{.app.spec.source.repoURL}}) 만 지원합니다. 배열 안에서 인덱스를 사용해 소스를 지정하세요:

template.example: |
  github:
    repoURLPath: "{{ (index .app.spec.sources 0).repoURL }}"

오류 메시지 POST https://api.github.com/repos/xxxx/yyyy/statuses/: 404 Not Found

이 경우는 이전과 유사합니다. Application 매니페스트에 소스가 여러 개 있는 경우입니다. 기본 revisionPath 템플릿 {{.app.status.operationState.syncResult.revision}} 은 단일 소스를 가진 Application 용입니다.

멀티 소스 애플리케이션은 애플리케이션 상태를 배열로 보고합니다:

status:
  operationState:
    syncResult:
      revisions:
        - 38cfa22edf9148caabfecb288bfb47dc4352dfc6
        - 38cfa22edf9148caabfecb288bfb47dc4352dfc6
첫 번째 revision 을 가져오려면 `index` 함수를 사용하는 게 빠른 수정입니다:
```yaml
template.example: |
  github:
    revisionPath: "{{index .app.status.operationState.syncResult.revisions 0}}"

config referenced xxx, but key does not exist in secret

  • 커스텀 secret 을 사용하고 있다면, secret 이 같은 네임스페이스에 있는지 확인하세요

  • secret 에 app.kubernetes.io/part-of: argocd 라벨을 추가했는지 확인하세요

  • argocd-notifications 컨트롤러를 재시작해 봤는지 확인하세요

예시:

Secret:

apiVersion: v1
kind: Secret
metadata:
  name: argocd-slackbot
  namespace: <the namespace where argocd is installed>
  labels:
    app.kubernetes.io/part-of: argocd
type: Opaque
data:
  slack-token: <base64encryptedtoken>

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  service.slack: |
    token: $argocd-slackbot:slack-token

더 알아보기 (Learn more)