설정 관리 플러그인

설정 관리 플러그인 (Config Management Plugins)

Argo CD의 "네이티브" 설정 관리 도구는 Helm, Jsonnet, Kustomize예요. 다른 설정 관리 도구를 사용하거나 Argo CD의 네이티브 도구 지원에 필요한 기능이 없다면 설정 관리 플러그인(CMP)을 사용해야 할 수 있어요. Argo CD의 "repo server" 컴포넌트가 Helm, OCI, Git 리포지토리의 소스 파일을 기반으로 Kubernetes 매니페스트를 만드는 책임을 지는데, 설정 관리 플러그인이 올바르게 구성되면 repo server가 매니페스트 생성 작업을 플러그인에 위임할 수 있답니다.

출처: 문서

본문

이 문서는 플러그인을 생성·설치·사용하는 방법을 설명해요. 추가 지침은 예시 플러그인을 참고하세요.

[!WARNING] 플러그인은 Argo CD 시스템에서 신뢰 수준을 부여받으므로, 플러그인을 안전하게 구현하는 것이 중요해요. Argo CD 관리자는 신뢰할 수 있는 소스의 플러그인만 설치해야 하며, 플러그인의 특정 위험과 이점을 저울질하기 위해 감사해야 해요.

설정 관리 플러그인 설치 (Installing a config management plugin)

사이드카 플러그인 (Sidecar plugin)

운영자는 repo-server의 사이드카를 통해 플러그인 도구를 구성할 수 있어요. 새 플러그인을 구성하려면 다음 변경이 필요해요:

플러그인 구성 파일 작성 (Write the plugin configuration file)

플러그인은 플러그인 컨테이너 안에 위치한 ConfigManagementPlugin 매니페스트를 통해 구성돼요.

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  # The name of the plugin must be unique within a given Argo CD instance.
  name: my-plugin
spec:
  # The version of your plugin. Optional. If specified, the Application's spec.source.plugin.name field
  # must be <plugin name>-<plugin version>.
  version: v1.0
  # The init command runs in the Application source directory at the beginning of each manifest generation. The init
  # command can output anything. A non-zero status code will fail manifest generation.
  init:
    # Init always happens immediately before generate, but its output is not treated as manifests.
    # This is a good place to, for example, download chart dependencies.
    command: [sh]
    args: [-c, 'echo "Initializing..."']
  # The generate command runs in the Application source directory each time manifests are generated. Standard output
  # must be ONLY valid Kubernetes Objects in either YAML or JSON. A non-zero exit code will fail manifest generation.
  # To write log messages from the command, write them to stderr, it will always be displayed.
  # Error output will be sent to the UI, so avoid printing sensitive information (such as secrets).
  generate:
    command: [sh, -c]
    args:
      - |
        echo "{\"kind\": \"ConfigMap\", \"apiVersion\": \"v1\", \"metadata\": { \"name\": \"$ARGOCD_APP_NAME\", \"namespace\": \"$ARGOCD_APP_NAMESPACE\", \"annotations\": {\"Foo\": \"$ARGOCD_ENV_FOO\", \"KubeVersion\": \"$KUBE_VERSION\", \"KubeApiVersion\": \"$KUBE_API_VERSIONS\",\"Bar\": \"baz\"}}}"
  # The discovery config is applied to a repository. If every configured discovery tool matches, then the plugin may be
  # used to generate manifests for Applications using the repository. If the discovery config is omitted then the plugin 
  # will not match any application but can still be invoked explicitly by specifying the plugin name in the app spec. 
  # Only one of fileName, find.glob, or find.command should be specified. If multiple are specified then only the 
  # first (in that order) is evaluated.
  discover:
    # fileName is a glob pattern (https://pkg.go.dev/path/filepath#Glob) that is applied to the Application's source 
    # directory. If there is a match, this plugin may be used for the Application.
    fileName: "./subdir/s*.yaml"
    find:
      # This does the same thing as fileName, but it supports double-star (nested directory) glob patterns.
      glob: "**/Chart.yaml"
      # The find command runs in the repository's root directory. To match, it must exit with status code 0 _and_ 
      # produce non-empty output to standard out.
      command: [sh, -c, find . -name env.yaml]
  # The parameters config describes what parameters the UI should display for an Application. It is up to the user to
  # actually set parameters in the Application manifest (in spec.source.plugin.parameters). The announcements _only_
  # inform the "Parameters" tab in the App Details page of the UI.
  parameters:
    # Static parameter announcements are sent to the UI for _all_ Applications handled by this plugin.
    # Think of the `string`, `array`, and `map` values set here as "defaults". It is up to the plugin author to make 
    # sure that these default values actually reflect the plugin's behavior if the user doesn't explicitly set different
    # values for those parameters.
    static:
      - name: string-param
        title: Description of the string param
        tooltip: Tooltip shown when the user hovers the
        # If this field is set, the UI will indicate to the user that they must set the value.
        required: false
        # itemType tells the UI how to present the parameter's value (or, for arrays and maps, values). Default is
        # "string". Examples of other types which may be supported in the future are "boolean" or "number".
        # Even if the itemType is not "string", the parameter value from the Application spec will be sent to the plugin
        # as a string. It's up to the plugin to do the appropriate conversion.
        itemType: ""
        # collectionType describes what type of value this parameter accepts (string, array, or map) and allows the UI
        # to present a form to match that type. Default is "string". This field must be present for non-string types.
        # It will not be inferred from the presence of an `array` or `map` field.
        collectionType: ""
        # This field communicates the parameter's default value to the UI. Setting this field is optional.
        string: default-string-value
      # All the fields above besides "string" apply to both the array and map type parameter announcements.
      - name: array-param
        # This field communicates the parameter's default value to the UI. Setting this field is optional.
        array: [default, items]
        collectionType: array
      - name: map-param
        # This field communicates the parameter's default value to the UI. Setting this field is optional.
        map:
          some: value
        collectionType: map
    # Dynamic parameter announcements are announcements specific to an Application handled by this plugin. For example,
    # the values for a Helm chart's values.yaml file could be sent as parameter announcements.
    dynamic:
      # The command is run in an Application's source directory. Standard output must be JSON matching the schema of the
      # static parameter announcements list.
      command: [echo, '[{"name": "example-param", "string": "default-string-value"}]']

  # If set to `true` then the plugin receives repository files with original file mode. Dangerous since the repository
  # might have executable files. Set to true only if you trust the CMP plugin authors.
  preserveFileMode: false

  # If set to `true` then the plugin can retrieve git credentials from the reposerver during generate. Plugin authors 
  # should ensure these credentials are appropriately protected during execution
  provideGitCreds: false

[!NOTE] ConfigManagementPlugin은 Kubernetes 객체처럼 보이지만 실제로는 커스텀 리소스가 아니에요. 단지 kubernetes 스타일의 스펙 규칙을 따를 뿐이에요.

generate 명령은 유효한 Kubernetes YAML 또는 JSON 객체 스트림을 stdout으로 출력해야 해요. init과 generate 명령 모두 애플리케이션 소스 디렉터리 안에서 실행돼요.

discover.fileName은 애플리케이션 리포지토리가 플러그인에 의해 지원되는지 결정하는 glob 패턴으로 사용돼요.

  discover:
    find:
      command: [sh, -c, find . -name env.yaml]

discover.fileName이 제공되지 않으면 애플리케이션 리포지토리가 플러그인에 의해 지원되는지 결정하기 위해 discover.find.command가 실행돼요. find 명령은 지원되는 애플리케이션 소스 유형일 때 오류 없는 종료 코드를 반환하고 stdout으로 출력을 생성해야 해요.

사이드카에 플러그인 구성 파일 배치 (Place the plugin configuration file in the sidecar)

Argo CD는 플러그인 구성 파일이 사이드카의 /home/argocd/cmp-server/config/plugin.yaml에 위치하기를 기대해요.

사이드카에 커스텀 이미지를 사용한다면 그 이미지에 파일을 직접 추가할 수 있어요.

WORKDIR /home/argocd/cmp-server/config/
COPY plugin.yaml ./

사이드카에 스톡 이미지를 사용하거나 플러그인 구성을 ConfigMap에서 유지하고 싶다면, ConfigMap의 plugin.yaml 키 아래에 플러그인 config 파일을 중첩하고 그 ConfigMap을 사이드카에 마운트하면 돼요(다음 섹션 참고).

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-plugin-config
data:
  plugin.yaml: |
    apiVersion: argoproj.io/v1alpha1
    kind: ConfigManagementPlugin
    metadata:
      name: my-plugin
    spec:
      version: v1.0
      init:
        command: [sh, -c, 'echo "Initializing..."']
      generate:
        command: [sh, -c, 'echo "{\"kind\": \"ConfigMap\", \"apiVersion\": \"v1\", \"metadata\": { \"name\": \"$ARGOCD_APP_NAME\", \"namespace\": \"$ARGOCD_APP_NAMESPACE\", \"annotations\": {\"Foo\": \"$ARGOCD_ENV_FOO\", \"KubeVersion\": \"$KUBE_VERSION\", \"KubeApiVersion\": \"$KUBE_API_VERSIONS\",\"Bar\": \"baz\"}}}"']
      discover:
        fileName: "./subdir/s*.yaml"

플러그인 사이드카 등록 (Register the plugin sidecar)

플러그인을 설치하려면 argocd-repo-server를 패치해 플러그인 컨테이너를 사이드카로 실행하세요. entrypoint는 argocd-cmp-server여야 해요. 사이드카 이미지로 기성품이든 커스텀 빌드한 플러그인 이미지든 사용할 수 있어요. 예를 들어:

containers:
- name: my-plugin
  command: [/var/run/argocd/argocd-cmp-server] # Entrypoint should be Argo CD lightweight CMP server i.e. argocd-cmp-server
  image: ubuntu # This can be off-the-shelf or custom-built image
  securityContext:
    runAsNonRoot: true
    runAsUser: 999
  volumeMounts:
    - mountPath: /var/run/argocd
      name: var-files
    - mountPath: /home/argocd/cmp-server/plugins
      name: plugins
    # Remove this volumeMount if you've chosen to bake the config file into the sidecar image.
    - mountPath: /home/argocd/cmp-server/config/plugin.yaml
      subPath: plugin.yaml
      name: my-plugin-config
    # Starting with v2.4, do NOT mount the same tmp volume as the repo-server container. The filesystem separation helps 
    # mitigate path traversal attacks.
    - mountPath: /tmp
      name: cmp-tmp
volumes:
- configMap:
    name: my-plugin-config
  name: my-plugin-config
- emptyDir: {}
  name: cmp-tmp

[!IMPORTANT] 다음 항목을 다시 확인하세요

1. entrypoint로 /var/run/argocd/argocd-cmp-server를 사용해야 해요. argocd-cmp-server는 Argo CD가 플러그인과 상호작용할 수 있게 하는 경량 GRPC 서비스예요.
2. 사이드카 컨테이너가 user 999로 실행 중인지 확인하세요.
3. 플러그인 구성 파일이 /home/argocd/cmp-server/config/plugin.yaml에 있는지 확인하세요. configmap으로 볼륨 매핑하거나 이미지에 내장할 수 있어요.

플러그인에서 환경 변수 사용 (Using environment variables in your plugin)

플러그인 명령은 접근할 수 있어요:

1. 사이드카의 시스템 환경 변수
2. 표준 빌드 환경 변수
3. Application spec의 변수 (시스템 및 빌드 변수에 대한 참조는 변숫값에 보간됩니다):

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  source:
    plugin:
      env:
      - name: FOO
        value: bar
      - name: REV
        value: test-$ARGOCD_APP_REVISION

init.command, generate.command, discover.find.command 명령에 도달하기 전에 Argo CD는 사용자 제공 환경 변수(#3)의 앞에 ARGOCD_ENV_를 붙여요. 이렇게 하면 사용자가 잠재적으로 민감한 환경 변수를 직접 설정하는 것을 막아요.

1. Application spec의 파라미터:

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  source:
    plugin:
      parameters:
        - name: values-files
          array: [values-dev.yaml]
        - name: helm-parameters
          map:
            image.tag: v1.2.3

파라미터는 ARGOCD_APP_PARAMETERS 환경 변수에 JSON으로 제공돼요. 위 예시는 다음 JSON을 생성해요:

[{"name": "values-files", "array": ["values-dev.yaml"]}, {"name": "helm-parameters", "map": {"image.tag": "v1.2.3"}}]

[!NOTE] 파라미터 announcement는 기본값을 지정하더라도 ARGOCD_APP_PARAMETERS의 플러그인으로 보내지지 않아요. Application spec에 명시적으로 설정된 파라미터만 플러그인으로 보내져요. UI에 announcement된 것과 같은 기본값을 적용하는 것은 플러그인의 몫이에요.

같은 파라미터는 개별 환경 변수로도 사용할 수 있어요. 환경 변수의 이름은 다음 규칙을 따릅니다:

- name: some-string-param
  string: some-string-value
# PARAM_SOME_STRING_PARAM=some-string-value
- name: some-array-param
  value: [item1, item2]
# PARAM_SOME_ARRAY_PARAM_0=item1
# PARAM_SOME_ARRAY_PARAM_1=item2
- name: some-map-param
  map:
    image.tag: v1.2.3
# PARAM_SOME_MAP_PARAM_IMAGE_TAG=v1.2.3

[!WARNING] 사용자 입력 살균/이스케이프 (Sanitize/escape user input)

Argo CD의 매니페스트 생성 시스템의 일부로서 설정 관리 플러그인은 신뢰 수준을 부여받아요. 악성 입력이 원치 않는 동작을 일으키지 않도록 플러그인에서 사용자 입력을 이스케이프하세요.

Application과 함께 설정 관리 플러그인 사용 (Using a config management plugin with an Application)

plugin 섹션의 name 필드를 비워두면 discovery 규칙에 따라 플러그인이 Application과 자동으로 매칭될 수 있어요. 이름을 언급한다면 ConfigManagementPlugin 스펙에 version이 언급된 경우 <metadata.name>-<spec.version>, 그렇지 않으면 그냥 <metadata.name>이어야 해요. name이 명시적으로 지정되면, 해당 discovery 패턴/명령이 제공된 애플리케이션 repo와 일치하는 경우에만 그 특정 플러그인이 사용돼요.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
    plugin:
      env:
        - name: FOO
          value: bar

환경 변수를 설정할 필요가 없다면 빈 플러그인 섹션을 설정할 수 있어요.

    plugin: {}

[!IMPORTANT] CMP 명령이 너무 오래 실행되면 명령이 종료되고 UI에 오류가 표시돼요. CMP 서버는 argocd-cmd-params-cm의 server.repo.server.timeout.seconds와 controller.repo.server.timeout.seconds 항목이 설정한 타임아웃을 존중해요. 기본값 60s에서 값을 늘리세요.

각 CMP 명령은 CMP 사이드카에 설정된 ARGOCD_EXEC_TIMEOUT에서도 독립적으로 타임아웃돼요. 기본값은 90s예요. repo server 타임아웃을 90s보다 크게 늘리면 사이드카에 ARGOCD_EXEC_TIMEOUT을 설정해야 해요.

[!NOTE] 각 Application은 한 번에 하나의 설정 관리 플러그인만 구성할 수 있어요. argocd-cm ConfigMap을 통해 구성된 기존 플러그인을 사이드카로 변환하는 경우, ConfigManagementPlugin 스펙에서 version이 언급되었다면 플러그인 이름을 <metadata.name>-<spec.version>으로, 그렇지 않으면 그냥 <metadata.name>으로 업데이트해야 해요. 이름을 완전히 제거하고 자동 discovery가 플러그인을 식별하게 할 수도 있어요.

[!NOTE] CMP가 빈 매니페스트를 렌더링하고 prune이 true면, Argo CD는 리소스를 자동으로 제거해요. CMP 플러그인 작성자는 오류가 종료 코드의 일부가 되도록 해야 해요. 일반적으로 kustomize build . | cat 같은 것은 파이프 때문에 오류를 통과시키지 못해요. set -o pipefail을 설정해서 파이프된 것이 실패 시 오류를 통과시키도록 고려하세요.

[!NOTE] CMP 명령이 ARGOCD_EXEC_TIMEOUT에서 정상적으로 종료되지 못하면, ARGOCD_EXEC_FATAL_TIMEOUT의 추가 타임아웃 후 강제로 종료돼요.

CMP 디버깅 (Debugging a CMP)

사이드카 설치 CMP를 적극적으로 개발 중이라면 몇 가지를 명심하세요:

1. ConfigMap에서 plugin.yaml을 마운트한다면, 변경 사항을 플러그인이 인식하도록 repo-server Pod를 재시작해야 해요.
2. 이미지에 plugin.yaml을 내장했다면, 변경 사항을 플러그인이 인식하도록 그 이미지를 빌드·push하고 repo-server Pod에서 재풀(force re-pull)해야 해요. :latest를 사용한다면 Pod는 항상 새 이미지를 풀해요. 다른 정적 태그를 사용한다면 CMP 사이드카 컨테이너에 imagePullPolicy: Always를 설정하세요.
3. CMP 오류는 repo-server가 Redis에 캐시해요. repo-server Pod를 재시작해도 캐시가 지워지지 않아요. CMP를 적극적으로 개발할 때는 항상 "Hard Refresh"를 수행해 최신 출력을 얻으세요.
4. 사이드카가 제대로 시작되었는지 Pod를 보고 두 컨테이너가 실행 중인지 확인하세요: kubectl get pod -l app.kubernetes.io/component=repo-server -n argocd
5. stderr에 로그 메시지를 쓰고 사이드카에 --loglevel=info 플래그를 설정하세요. 그러면 성공적인 명령 실행에서도 stderr에 기록된 모든 것이 출력돼요.

기타 일반적인 오류 (Other Common Errors)

오류 메시지	원인
no matches for kind "ConfigManagementPlugin" in version "argoproj.io/v1alpha1"	ConfigManagementPlugin CRD는 Argo CD 2.4에서 deprecated되고 2.8에서 제거되었어요. 이 오류는 플러그인 구성을 Kubernetes CRD로 직접 넣으려고 했음을 의미해요. 플러그인 구성 파일을 작성하고 사이드카에 올바르게 배치하는 방법은 이 문서의 해당 섹션을 참고하세요.

Plugin tar stream 제외 (Plugin tar stream exclusions)

매니페스트 생성 속도를 높이기 위해 특정 파일과 폴더를 플러그인으로 보내지 않도록 제외할 수 있어요. 필요하지 않다면 .git 폴더를 제외하는 것을 권장해요. Go의 filepatch.Match 문법을 사용하세요. 예를 들어 .git/*는 .git 폴더를 제외해요.

세 가지 방법 중 하나로 설정할 수 있어요:

1. repo server의 --plugin-tar-exclude 인자.
2. argocd-cmd-params-cm을 사용한다면 reposerver.plugin.tar.exclusions 키.
3. repo server에 ARGOCD_REPO_SERVER_PLUGIN_TAR_EXCLUSIONS 환경 변수를 직접 설정.

옵션 1의 경우 플래그를 여러 번 반복할 수 있어요. 옵션 2와 3의 경우 여러 glob을 세미콜론으로 구분해 지정할 수 있어요.

argocd.argoproj.io/manifest-generate-paths를 사용한 애플리케이션 매니페스트 생성 (Application manifests generation using argocd.argoproj.io/manifest-generate-paths)

애플리케이션 매니페스트 생성 과정을 향상시키기 위해 argocd.argoproj.io/manifest-generate-paths 어노테이션의 사용을 활성화할 수 있어요. 이 플래그가 활성화되면, 애플리케이션 매니페스트 생성을 위해 전체 리포지토리를 보내는 대신 이 어노테이션이 지정한 리소스가 CMP 서버로 전달돼요. 특히 monorepo에 유용할 수 있어요.

세 가지 방법 중 하나로 설정할 수 있어요:

1. repo server의 --plugin-use-manifest-generate-paths 인자.
2. argocd-cmd-params-cm을 사용한다면 reposerver.plugin.use.manifest.generate.paths 키.
3. repo server에 ARGOCD_REPO_SERVER_PLUGIN_USE_MANIFEST_GENERATE_PATHS 환경 변수를 true로 직접 설정.

argocd-cm 플러그인에서 마이그레이션 (Migrating from argocd-cm plugins)

argocd-cm ConfigMap을 수정해 플러그인을 설치하는 것은 v2.4부터 deprecated되었고 v2.8부터 완전히 제거되었어요.

CMP 플러그인은 argocd-repo-server에 사이드카를 추가하고 그 사이드카에 /home/argocd/cmp-server/config/plugin.yaml에 위치한 구성을 두는 방식으로 동작해요. argocd-cm 플러그인은 다음 단계로 쉽게 변환할 수 있어요.

ConfigMap 항목을 config 파일로 변환 (Convert the ConfigMap entry into a config file)

먼저 플러그인의 구성을 자체 YAML 파일로 복사하세요. 다음 ConfigMap 항목을 예로 들어요:

data:
  configManagementPlugins: |
    - name: pluginName
      init:                          # Optional command to initialize application source directory
        command: ["sample command"]
        args: ["sample args"]
      generate:                      # Command to generate Kubernetes Objects in either YAML or JSON
        command: ["sample command"]
        args: ["sample args"]
      lockRepo: true                 # Defaults to false. See below.

pluginName 항목은 다음과 같은 config 파일로 변환돼요:

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: pluginName
spec:
  init:                          # Optional command to initialize application source directory
    command: ["sample command"]
    args: ["sample args"]
  generate:                      # Command to generate Kubernetes Objects in either YAML or JSON
    command: ["sample command"]
    args: ["sample args"]

[!NOTE] lockRepo 키는 사이드카 플러그인에는 관련이 없어요. 사이드카 플러그인은 매니페스트를 생성할 때 단일 소스 repo 디렉터리를 공유하지 않기 때문이에요.

다음으로, 이 yaml을 사이드카에 어떻게 추가할지 결정해야 해요. yaml을 이미지에 직접 내장하거나 ConfigMap에서 마운트할 수 있어요.

ConfigMap을 사용한다면 예시는 다음과 같을 거예요:

apiVersion: v1
kind: ConfigMap
metadata:
  name: pluginName
  namespace: argocd
data:
  pluginName.yaml: |
    apiVersion: argoproj.io/v1alpha1
    kind: ConfigManagementPlugin
    metadata:
      name: pluginName
    spec:
      init:                          # Optional command to initialize application source directory
        command: ["sample command"]
        args: ["sample args"]
      generate:                      # Command to generate Kubernetes Objects in either YAML or JSON
        command: ["sample command"]
        args: ["sample args"]

그런 다음 이 파일을 플러그인 사이드카에 마운트해요.

플러그인에 대한 discovery 규칙 작성 (Write discovery rules for your plugin)

사이드카 플러그인은 discovery 규칙이나 플러그인 이름을 사용해 Application을 플러그인에 매칭할 수 있어요. discovery 규칙을 생략하면 앱 스펙에서 플러그인을 이름으로 명시적으로 지정해야 하며, 그렇지 않으면 그 특정 플러그인은 어떤 앱과도 매칭되지 않아요.

플러그인 이름 대신 discovery를 사용해 애플리케이션을 플러그인에 매칭하려면, 위 지침을 사용해 플러그인에 적용되는 규칙을 작성하고 구성을 추가하세요.

discovery 대신 이름을 사용하려면, ConfigManagementPlugin 스펙에서 version이 언급되었다면 애플리케이션 매니페스트의 이름을 <metadata.name>-<spec.version>으로, 그렇지 않으면 그냥 <metadata.name>으로 업데이트하세요. 예를 들어:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  source:
    plugin:
      name: pluginName  # Delete this for auto-discovery (and set `plugin: {}` if `name` was the only value) or use proper sidecar plugin name

플러그인이 필요한 도구에 접근할 수 있는지 확인 (Make sure the plugin has access to the tools it needs)

argocd-cm으로 구성된 플러그인은 Argo CD 이미지에서 실행되었어요. 이것은 그 이미지에 설치된 모든 도구에 기본적으로 접근할 수 있게 해줬어요(Dockerfile에서 베이스 이미지와 설치된 도구 확인).

스톡 이미지(ubuntu, busybox, alpine/k8s 등)를 사용하거나 플러그인에 필요한 도구가 있는 자체 베이스 이미지를 설계할 수 있어요. 보안을 위해 플러그인이 실제로 필요로 하는 것보다 더 많은 바이너리가 설치된 이미지는 피하세요.

플러그인 테스트 (Test the plugin)

위 지침에 따라 플러그인을 사이드카로 설치한 후, 모든 애플리케이션을 사이드카 플러그인으로 마이그레이션하기 전에 몇 가지 애플리케이션에서 테스트해보세요.

테스트가 확인되면 argocd-cm ConfigMap에서 플러그인 항목을 제거하세요.

추가 설정 (Additional Settings)

리포지토리 파일 모드 보존 (Preserve repository files mode)

기본적으로 설정 관리 플러그인은 파일 모드가 재설정된 소스 리포지토리 파일을 받아요. 보안상의 이유로 이렇게 하는 거예요. 원래 파일 모드를 보존하려면 플러그인 스펙에서 preserveFileMode를 true로 설정할 수 있어요:

[!WARNING] 사용 중인 플러그인을 신뢰하는지 확인하세요. preserveFileMode를 true로 설정하면 플러그인이 실행 권한이 있는 파일을 받을 수 있는데, 이는 보안 위험이 될 수 있어요.

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: pluginName
spec:
  init:
    command: ["sample command"]
    args: ["sample args"]
  generate:
    command: ["sample command"]
    args: ["sample args"]
  preserveFileMode: true

Git 자격 증명 제공 (Provide Git Credentials)

기본적으로 설정 관리 플러그인은 매니페스트 생성 중에 접근해야 할 수 있는 추가 Git 리포지토리에 자체 자격 증명을 제공할 책임이 있어요. reposerver는 이 자격 증명을 git creds 저장소에 가지고 있어요. 자격 증명 공유가 허용되면 reposerver가 리포지토리 내용을 복제하는 데 사용하는 git 자격 증명이 설정 관리 플러그인의 실행 수명 동안 공유되며, git의 ASKPASS 메서드를 활용해 설정 관리 사이드카 컨테이너에서 reposerver로 호출해 초기화된 git 자격 증명을 검색해요.

ASKPASS를 활용하면 자격 증명이 선제적으로 공유되는 것이 아니라, 작업이 필요로 할 때만 제공돼요.

ASKPASS는 설정 관리 플러그인과 reposerver 사이에 socket이 공유되어야 해요. 경로 traversal 공격을 완화하려면 전용 볼륨으로 socket을 공유하고 reposerver와 사이드카에 마운트하는 것이 좋아요. socket 경로를 변경하려면 두 컨테이너 모두에 ARGOCD_ASK_PASS_SOCK 환경 변수를 설정해야 해요.

플러그인이 reposerver git 자격 증명에 접근할 수 있게 하려면 플러그인 스펙에서 provideGitCreds를 true로 설정할 수 있어요:

[!WARNING] 사용 중인 플러그인을 신뢰하는지 확인하세요. provideGitCreds를 true로 설정하면 플러그인이 소스 Git 리포지토리를 복제하는 데 사용되는 자격 증명을 받게 돼요.

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: pluginName
spec:
  init:
    command: ["sample command"]
    args: ["sample args"]
  generate:
    command: ["sample command"]
    args: ["sample args"]
  provideGitCreds: true

더 알아보기 (Learn more)

• 표준 빌드 환경 변수 (Standard build environment variables)
• 문서: Config Management Plugins