테넌트 구성

zuul.conf 구성이 완료되면 Zuul 컴포넌트 서버를 시작할 수 있습니다. 그러나 Zuul이 실제 동작을 수행하려면 테넌트 구성이 필요합니다. 테넌트 구성 파일은 Zuul이 어떤 프로젝트에 대해 동작할지를 지정합니다. 이러한 저장소는 테넌트 단위로 그룹화됩니다. 각 테넌트의 구성은 서로 완전히 분리되며, 파이프라인, 잡 등은 테넌트 간에 공유되지 않습니다.

하나의 프로젝트는 둘 이상의 테넌트에 포함될 수 있습니다. 이는 여러 테넌트에서 공통 잡 정의를 사용하려는 경우 유용합니다.

일반적으로 Zuul 운영자만 수행할 수 있는 작업은, 해당 테넌트에 admin 규칙이 정의되어 있는 경우 특정 사용자가 Zuul의 REST API를 통해 수행할 수 있습니다. 인증 규칙 또한 테넌트 구성 파일에 정의됩니다.

테넌트 구성 파일은 zuul.conf 의 scheduler.tenant_config 설정으로 지정합니다. 이 파일은 YAML 형식이며, 다른 Zuul 구성 파일과 마찬가지로 구성 객체의 목록으로 이루어집니다. 단, 여기서는 아래에 설명된 일부 유형의 객체만 지원합니다 .

또는 scheduler.tenant_config_script 에 실행 파일 경로를 지정할 수 있습니다. 이 경우 해당 실행 파일이 실행되며, 그 표준 출력이 테넌트 구성으로 사용됩니다. 실행 파일은 유효한 테넌트 YAML 형식의 출력을 반환해야 합니다.

스케줄러가 시작될 때마다 테넌트 구성의 변경 여부를 확인하며, 변경 사항은 자동으로 반영됩니다. 운영 중 테넌트 구성이 변경된 경우, 스케줄러에 신호를 보내 재시작 없이 업데이트된 상태를 읽고 적용할 수 있습니다. 자세한 내용은 재구성 (Reconfiguration) 을 참조. 이상적으로는 구성 관리 시스템을 통해 테넌트 구성을 배포할 때, 파일이 교체되면 smart-reconfigure가 자동으로 실행되도록 구성하는 것이 좋습니다.

테넌트

테넌트는 동일한 Zuul 구성을 공유하는 프로젝트들의 집합입니다. 다음은 테넌트 정의의 예시입니다.

- tenant:
    name: my-tenant
    max-nodes-per-job: 5
    exclude-unprotected-branches: false
    source:
      gerrit:
        config-projects:
          - common-config
          - shared-jobs:
              include: job
        untrusted-projects:
          - zuul/zuul-jobs:
              shadow: common-config
          - project1
          - project2:
              exclude-unprotected-branches: true

- tenant:
    name: my-tenant
    admin-rules:
      - acl1
      - acl2
    source:
      gerrit:
        config-projects:
          - common-config
        untrusted-projects:
          - exclude:
              - job
              - semaphore
              - project
              - project-template
              - nodeset
              - secret
            projects:
              - project1
              - project2:
                  exclude-unprotected-branches: true

tenant

지원되는 속성은 다음과 같습니다:

tenant.name (required)

테넌트의 이름. 이 값은 URL, 경로, 모니터링 필드 등에 표시될 수 있으므로 URL에 적합한 문자(ASCII 문자, 숫자, 하이픈, 언더스코어)로 제한해야 합니다. 특별한 경우가 아니라면 변경하지 않는 것이 좋습니다.

tenant.source (required)

프로젝트를 조회할 소스들의 딕셔너리. 하나의 테넌트는 여러 소스의 프로젝트를 포함할 수 있으며, 각 소스와 해당 소스가 지원하는 프로젝트를 여기에 명시해야 합니다. connection 의 이름이 딕셔너리의 키로 사용되며 (예: 위 예시의 gerrit ), 값은 아래에 설명된 키를 포함하는 또 다른 딕셔너리입니다.

다음 두 속성인 config-projects 와 untrusted-projects 는 테넌트 구성의 핵심 정보를 제공합니다. 이들은 Zuul이 동작할 모든 프로젝트를 나열합니다.

테넌트에 나열된 프로젝트의 순서는 중요합니다. 한 프로젝트에서 정의된 잡은 다른 프로젝트에서 다시 정의할 수 없습니다. 따라서 어떤 잡이 특정 프로젝트에 한 번 정의되면, 그 이후에 나열된 프로젝트에서는 동일한 이름의 잡을 정의할 수 없습니다. 또한 프로젝트 구성의 일부 항목(예: 병합 모드(merge mode))은 프로젝트 정의가 처음 등장할 때만 설정할 수 있습니다.

Zuul은 나열된 순서대로 모든 config-projects 에서 구성을 로드한 후, untrusted-projects 에서도 순서대로 구성을 로드합니다.

tenant.config-projects

이 테넌트에서 config projects 로 처리될 프로젝트의 목록입니다. config 프로젝트의 잡은 신뢰할 수 있는 실행 컨텍스트에서 실행되며, 추가 권한을 가집니다. 제안된 변경에 대해 구성이 동적으로 로드되지 않으며, Zuul 구성 파일은 master 브랜치에서만 검색됩니다.

목록의 항목은 untrusted-projects 에서 설명한 것과 동일한 형식을 따릅니다.

tenant.config-projects.<project>

config-projects에는 선택적으로 지정할 수 있는 추가 구성 옵션이 있습니다.

tenant.config-projects.<project>.load-branch
Default: master

config 프로젝트에서 어떤 브랜치를 로드할지 정의합니다. 기본적으로 config-projects는 master 브랜치에서만 Zuul 구성을 로드합니다.

tenant.untrusted-projects

이 테넌트에서 신뢰할 수 없는 프로젝트로 처리될 프로젝트의 목록입니다. untrusted-project 는 Zuul이 일반적으로 동작하는 기본 프로젝트 유형입니다. 이 프로젝트의 잡은 더 제한적인 환경에서 실행되며, 파이프라인을 정의할 수 없습니다. 또한 제안된 변경에 따라 구성이 동적으로 변경되며, Zuul은 해당 프로젝트의 모든 브랜치에서 구성 파일을 읽습니다.

tenant.untrusted-projects.<project>

목록의 항목은 프로젝트 이름을 나타내는 단순 문자열이거나, 프로젝트 이름을 키로 하고 아래 값을 가지는 딕셔너리일 수 있습니다:

tenant.untrusted-projects.<project>.include

기본적으로 Zuul은 해당 프로젝트 유형(config 또는 untrusted)에 적합한 구성 항목 (Configuration Items) 를 모두 로드합니다. 그러나 일부 항목만 로드하려는 경우 include 속성을 사용하여 지정한 항목만 로드하도록 설정할 수 있습니다. 문자열 또는 문자열 목록 형태로 지정합니다.

다음 구성 항목(configuration items) 을 인식합니다:

• 파이프라인

• 잡

• 세마포어

• 프로젝트

• 프로젝트 템플릿

• 노드셋

• 시크릿

• 이미지

• 플레이버

• 레이블

• 섹션

• 제공자(provider)

tenant.untrusted-projects.<project>.exclude

구성 항목 중 로드하지 않아야 할 항목의 목록입니다.

tenant.untrusted-projects.<project>.include-provider-config
Type: bool

로드할 항목 집합에 제공자 구성과 관련된 구성 항목을 추가합니다. 기본적으로 untrusted projects 는 이러한 항목을 로드하지 않지만, config projects 는 로드합니다. 신뢰할 수 없는 프로젝트에서도 이를 허용하려면(또는 include 사용 후 해당 항목을 다시 추가하려면) 이 속성을 true 로 설정합니다. 이 설정은 include 이후, exclude 이전에 적용됩니다.

다음 구성 항목 은 제공자 구성(provider config) 으로 간주됩니다:

• 이미지

• 플레이버

• 레이블

• 섹션

• 제공자(provider)

tenant.untrusted-projects.<project>.shadow

일반적으로 Zuul에서는 특정 잡에 대한 정의가 하나의 프로젝트에만 존재할 수 있습니다. 구성에서 앞에 나열된 프로젝트가 정의한 잡을 뒤에 나열된 프로젝트가 다시 정의하면, 뒤의 정의는 오류로 간주되며 허용되지 않습니다. 프로젝트의 shadow 속성은, 이 프로젝트의 잡 정의 중 지정된 프로젝트와 충돌하는 항목을 무시하고 지정된 프로젝트의 정의를 대신 사용하도록 지정합니다. 지정된 프로젝트는 여전히 구성에서 앞에 위치해야 합니다. 위 예시에서 common-config 와 zuul-jobs 프로젝트 모두에 동일한 잡 정의가 있다면, common-config 의 정의가 사용됩니다.

tenant.untrusted-projects.<project>.exclude-unprotected-branches

보호되지 않은 브랜치를 처리할지 여부를 정의합니다. 기본값은 테넌트 전체 설정인 exclude-unprotected-branches를 따릅니다. 현재 이 설정은 GitHub 및 GitLab 프로젝트에만 적용됩니다.

tenant.untrusted-projects.<project>.exclude-locked-branches

잠긴 브랜치를 처리할지 여부를 정의합니다. 기본값은 테넌트 전체 설정인 exclude-locked-branches를 따릅니다. 현재 이 설정은 GitHub 프로젝트에만 적용됩니다.

tenant.untrusted-projects.<project>.include-branches

처리할 브랜치를 매칭하는 정규 표현식 목록입니다. 생략하면 모든 브랜치가 포함됩니다. exclude-unprotected-branches 및 exclude-locked-branches 이후에 적용되므로, 브랜치 집합을 추가로 제한하는 데 사용할 수 있습니다(확장할 수는 없습니다).

*exclude-branches*보다 우선합니다.

tenant.untrusted-projects.<project>.exclude-branches

처리할 브랜치를 매칭하는 정규 표현식 목록입니다. 생략하면 모든 브랜치가 포함됩니다. exclude-unprotected-branches 및 exclude-locked-branches 이후에 적용되므로, 브랜치 집합을 추가로 제한하는 데 사용할 수 있습니다(확장할 수는 없습니다).

이미 *include-branches*에 매칭된 브랜치는 제외하지 않습니다.

tenant.untrusted-projects.<project>.always-dynamic-branches

모든 변경이 새로운 동적 Zuul 구성을 제안하는 것처럼 처리할 브랜치를 매칭하는 정규 표현식 목록입니다. 즉, 이러한 브랜치와 관련된 구성은 해당 브랜치에 대한 제안된 변경에 대해 잡을 실행하는 동안에만 반영됩니다.

이는 거의 사용되지 않는 기능 브랜치가 매우 많은 경우에 유용할 수 있지만, 해당 브랜치에서 사용할 수 있는 Zuul 기능이 크게 제한됩니다는 단점이 있습니다.

여기에 나열된 모든 정규 표현식은 암묵적으로 *exclude-branches*에도 포함됩니다. 따라서 Zuul은 해당 브랜치에서 저장소 내 정적 구성을 로드하지 않습니다. 또한 이러한 브랜치는 저장소 체크아웃을 재정의하는 데 사용할 수 없으며, Zuul이 *required-projects*를 위해 준비하는 Git 저장소에도 포함되지 않습니다(단, 해당 브랜치의 의존성 트리에 변경이 있는 경우는 예외).

특히 이는 이러한 브랜치에 대해 지정할 수 있는 잡이 사전 병합 및 게이팅 잡(예: check, gate)으로 제한됨을 의미합니다. post-merge 잡이나 주기적 잡은 이러한 브랜치에서 실행되지 않습니다.

이 설정을 사용하면 이러한 브랜치에 제출되는 각 변경에 대해 추가 처리가 발생합니다. 변경이 실제로 구성을 수정하지 않더라도, Zuul은 해당 변경이 zuul.yaml 파일을 수정한 것처럼 구성 레이아웃을 다시 계산해야 합니다.

이러한 주의 사항을 고려하더라도, 거의 사용되지 않는 브랜치가 많은 저장소의 경우에는 유용할 수 있습니다. 대부분의 상황에서 해당 브랜치의 구성을 생략하고, 실제로 사용될 때에만 추가 브랜치의 구성을 계산하도록 할 수 있기 때문입니다.

tenant.untrusted-projects.<project>.implied-branch-matchers

이 값은 불리언(boolean)입니다. 설정되면 잡 및 프로젝트 템플릿 정의에 암묵적 브랜치 매처를 추가할지 여부를 제어할 수 있습니다(true 는 활성화, false 는 비활성화). 기본적으로 Zuul은 job.branches 에 설명된 휴리스틱을 기반으로 이를 결정하지만, 이 속성은 해당 동작을 재정의합니다.

이 프로젝트의 브랜치 설정으로 인해 로드해야 할 브랜치 수가 예측하기 어려운 경우 유용합니다. 이 값을 명시적으로 설정하면 브랜치가 로드 대상에 추가되거나 제거될 때 발생할 수 있는 예기치 않은 동작 변화를 방지할 수 있습니다.

pragma.implied-branch-matchers 프라그마가 존재하는 경우, 여기의 설정보다 우선합니다.

잡에 명시적인 브랜치 매처가 포함되어 있는 경우, 여기에서 지정한 값과 관계없이 해당 매처가 사용됩니다.

tenant.untrusted-projects.<project>.extra-config-paths

기본적으로 Zuul은 다음 경로 중 첫 번째에서 저장소 내 구성을 로드합니다:

• zuul.yaml

• zuul.d/*

• .zuul.yaml

• .zuul.d/*

이 옵션이 지정되면, 일반적인 로드 절차가 완료된 후 여기에 지정된 파일이나 경로에서 발견된 구성도 추가로 로드합니다. 문자열 또는 목록으로 지정할 수 있습니다. 여러 항목의 목록인 경우, Zuul은 목록에 있는 모든 항목에서 구성을 로드하며 (추가 구성을 처음 발견한 지점에서 중단하지 않습니다). 디렉터리는 끝에 / 를 붙여서 지정해야 합니다. 예:

extra-config-paths:
  - zuul-extra.yaml
  - zuul-extra.d/

이 기능은 주로 공유 잡이나 롤을 보관하는 프로젝트가 자체 테스트를 위해 추가적인 저장소 내 구성을 포함하도록 할 때 유용합니다(해당 구성은 다른 사용자에게는 관련이 없을 수 있습니다).

tenant.untrusted-projects.<project>.allow-reporter-jobs
Type: bool

이 프로젝트가 자신의 변경(또는 tenant.untrusted-projects.<project>.configure-projects 를 통해 구성 권한이 허용된 다른 프로젝트의 변경)에 대해 reporter 잡을 실행하도록 허용하려면 true 로 설정합니다. 이 동작은 일반적으로 config projects 에만 허용됩니다.

tenant.untrusted-projects.<project>.configure-projects

이 프로젝트가 구성할 수 있도록 허용된 프로젝트 이름의 목록(또는 프로젝트 이름과 일치하는 regular expressions )입니다. 이 설정을 사용하면, 여기에서 지정된 신뢰할 수 없는 프로젝트에 적용되는 project 절을 이 프로젝트에서 정의할 수 있습니다. 이는 한 프로젝트가 다른 프로젝트에서 특정 잡을 실행하도록 유도할 수 있으므로 고급이며 잠재적으로 위험한 구성 설정입니다. 일반적으로 이 동작은 config projects 에만 허용됩니다.

이 설정은 해당 프로젝트와 구성 권한이 허용된 프로젝트 사이에 강한 신뢰 관계가 있는 경우에만 사용해야 합니다.

tenant.untrusted-projects.<project-group>

목록의 항목은 다음 속성을 가지는 딕셔너리다. 구성 항목 정의는 프로젝트 목록에 적용됩니다.

tenant.untrusted-projects.<project-group>.include

구성 항목 중 로드해야 할 항목의 목록입니다.

tenant.untrusted-projects.<project-group>.exclude

구성 항목 중 로드하지 않아야 할 항목의 목록입니다.

tenant.untrusted-projects.<project-group>.projects

프로젝트 항목의 목록입니다.

tenant.max-dependencies

이 설정은 테넌트 내 모든 파이프라인에서 변경을 큐에 추가할 때 고려할 의존성의 최대 개수를 제한하는 데 사용됩니다. 설정하는 경우, 예상되는 최대 의존성 수보다 큰 값으로 지정해야 합니다. 변경을 큐에 추가할 때 의존성이 이 값을 초과합니다고 감지되면, Zuul은 해당 변경을 큐에 추가하지 않으며 사용자에게 별도의 피드백을 제공하지 않습니다. 이는 과도한 의존성으로 인해 Zuul 서버의 리소스가 고갈되는 것을 방지하기 위한 보호 장치입니다. 기본값(미설정)은 제한 없음입니다. 값 0 은 이 옵션을 비활성화하는 것이 아니라, 의존성을 0개로 제한하는 것을 의미합니다. 이는 <gerrit connection>.max_dependencies 와 별개의 설정입니다.

tenant.max-changes-per-pipeline

이 테넌트의 개별 파이프라인에서 허용되는 변경 수(큐 항목이 아니라 변경 수)입니다. 라이브 변경, 의존성에 사용되는 비라이브 변경, 의존성 순환에 포함된 변경이 모두 집계됩니다. 하나의 변경이 둘 이상의 큐 항목에 포함된 경우, 각각 별도로 계산됩니다.

예를 들어 이 값이 100으로 설정된 경우, Zuul은 다음과 같은 경우를 허용합니다(그 이상은 허용하지 않음):

• 개별 큐 항목에 포함된 100개의 변경

• 의존성 순환에 포함된 100개 변경으로 구성된 하나의 큐 항목

• 순환에 포함된 99개 변경이 있는 하나의 큐 항목과, 그 순환에 의존하는 추가 1개 항목

이 값은 해당 파이프라인의 모든 큐에 걸쳐 변경을 집계합니다. 따라서 하나의 큐에 있는 프로젝트 집합이 동일한 테넌트 내 다른 큐에 영향을 줄 수 있습니다.

이 값은 기본적으로 설정되어 있지 않으며, 이는 제한이 없음을 의미합니다. 일반적으로 파이프라인 윈도우 구성이 과도한 리소스 사용을 방지하는 데 충분할 것으로 예상됩니다. 그러나 의존성 순환이 큰 일부 상황에서는 이 값을 설정하는 것이 유용할 수 있습니다. 값 0 은 이 옵션을 비활성화하는 것이 아니라, 변경을 0개로 제한하는 것을 의미합니다.

tenant.max-nodes-per-job
Default: 5

잡이 요청할 수 있는 노드의 최대 개수입니다. 값 ‘-1’은 제한을 제거합니다.

tenant.max-job-timeout
Default: 10800

잡의 최대 타임아웃 값입니다. 값 ‘-1’은 제한을 제거합니다.

tenant.max-oidc-ttl
Default: 10800

이 테넌트에서 OpenID Connect(OIDC) 시크릿의 ttl 속성에 설정할 수 있는 최대 값입니다. 양의 정수여야 합니다.

tenant.default-oidc-ttl
Default: 3600

시크릿 구성에서 지정하지 않은 경우 적용되는 ID 토큰의 기본 ttl 값입니다. 양의 정수여야 하며 tenant.max-oidc-ttl 보다 클 수 없습니다.

tenant.allowed-oidc-issuers
Default: []

이 테넌트에서 OIDC 토큰의 iss 클레임을 재정의할 수 있도록 허용된 발급자 목록입니다.

tenant.exclude-unprotected-branches
Default: false

공유 저장소에서 브랜치 및 풀 요청 모델을 사용하는 경우, 일반적으로 게이팅이 적용되는 하나 이상의 보호된 브랜치와, 풀 요청의 소스가 되는 개인 또는 기능 브랜치가 존재합니다. 이러한 브랜치에는 손상된 Zuul 구성이 포함될 수 있으며, 그로 인해 테넌트 전체 구성이 영향을 받을 수 있습니다. 이를 방지하기 위해 Zuul의 동작을 게이팅이 적용된 보호 브랜치로 제한할 수 있습니다. 이는 테넌트 전체 설정이며 프로젝트별로 재정의할 수 있습니다. 현재 이 설정은 GitHub 및 GitLab 프로젝트에만 적용됩니다.

tenant.exclude-locked-branches
Default: false

일부 코드 리뷰 시스템은 읽기 전용, 즉 “locked” 브랜치를 지원합니다. 이 설정을 활성화하면 Zuul은 이러한 브랜치를 무시합니다. 이는 테넌트 전체 설정이며 프로젝트별로 재정의할 수 있습니다. 현재 이 설정은 GitHub 및 GitLab 프로젝트에만 적용됩니다.

tenant.default-parent
Default: base

잡이 명시적인 job.parent 속성 없이 정의된 경우, 이 잡이 해당 잡의 부모 잡으로 구성됩니다. 이를 통해 관리자는 노드 설정이나 아티팩트 게시와 같은 로컬 정책을 구현하기 위한 기본 베이스 잡을 구성할 수 있습니다.

tenant.default-ansible-version

버전을 명시하지 않은 잡에 사용할 기본 Ansible 버전. 자세한 내용은 job.ansible-version 을 참조.

tenant.allowed-triggers
Default: all connections

테넌트가 트리거로 사용할 수 있는 연결 목록. 설정된 경우, 테넌트가 트리거로 사용할 수 있는 연결을 제한할 수 있습니다. 이 설정이 없으면 테넌트는 모든 연결을 트리거로 사용할 수 있습니다.

tenant.allowed-reporters
Default: all connections

테넌트가 리포터로 사용할 수 있는 연결 목록. 설정된 경우, 테넌트가 리포터로 사용할 수 있는 연결을 제한할 수 있습니다. 이 설정이 없으면 테넌트는 모든 연결에 대해 리포트할 수 있습니다.

tenant.allowed-labels
Default: []

참고

이 옵션은 Nodepool과 함께 사용할 때만 적용됩니다. 현재 사용 중단 상태이며, 향후 Zuul 버전에서 제거될 예정입니다.

테넌트가 잡의 노드셋에서 사용할 수 있는 레이블(문자열 또는 regular expressions ) 목록입니다. 설정된 경우, 테넌트가 사용할 수 있는 레이블을 제한할 수 있습니다. 이 설정이 없으면 테넌트는 모든 레이블을 사용할 수 있습니다.

tenant.disallowed-labels
Default: []

참고

이 옵션은 Nodepool과 함께 사용할 때만 적용됩니다. 현재 사용 중단 상태이며, 향후 Zuul 버전에서 제거될 예정입니다.

테넌트가 잡의 노드셋에서 사용이 금지된 레이블(문자열 또는 regular expressions ) 목록입니다. 설정된 경우, 테넌트가 사용할 수 있는 레이블을 추가로 제한할 수 있습니다. 이 설정이 없으면 테넌트는 tenant.allowed-labels 에서 허용된 모든 레이블을 사용할 수 있습니다. 이 검사는 allowed-labels 검사 이후에 적용되므로, 허용된 레이블 집합을 추가로 제한하는 데 사용할 수 있습니다.

tenant.web-root

이 테넌트가 화이트라벨된 zuul-web 인스턴스를 사용하는 경우, 외부에 노출되는 URL을 여기에 설정합니다(예: https://tenant.example.com/ ). 이 설정은 이 테넌트에 대한 URL을 구성할 때 web.root 설정보다 우선 적용됩니다.

tenant.admin-rules

Zuul의 REST API 및 웹 인터페이스를 통해 테넌트에 대한 관리자 권한 접근을 허용하기 위해 검사할 인증 규칙 목록입니다.

사용자가 권한이 필요한 작업을 수행하려면 목록에 있는 규칙 중 최소 하나가 일치해야 합니다. 일치하는 규칙은 사용자가 테넌트에 일반적으로 접근하는 것도 허용합니다(즉, 동일한 규칙을 `access-rules`에 중복 정의할 필요는 없습니다).

테넌트 범위 작업에 대한 자세한 내용은 인증된 액세스 (Authenticated Access) 을 참조.

tenant.access-rules

Zuul의 REST API 및 웹 인터페이스를 통해 테넌트에 대한 읽기 접근을 허용하기 위해 검사할 인증 규칙 목록입니다.

규칙이 정의되어 있지 않으면, 테넌트에 대한 익명 접근이 허용됩니다. 규칙이 하나라도 정의되어 있는 경우에는, 사용자가 테넌트에 접근하려면 목록의 규칙 중 최소 하나가 일치해야 합니다.

테넌트 범위 작업에 대한 자세한 내용은 인증된 액세스 (Authenticated Access) 을 참조.

tenant.authentication-realm

Zuul 구성에 정의된 각 인증기는 하나의 realm과 연결됩니다. 이 테넌트에서 Zuul 웹 사용자 인터페이스를 통해 인증할 경우, 웹 UI는 사용자를 해당 realm의 인증 서비스로 리디렉션합니다. 인증기는 OpenIDConnect 유형이어야 합니다.

참고

테넌트에 기본 realm을 정의하더라도, 다른 구성된 realm에서 발급된 접근 토큰은 무효화되지 않습니다. 이는 운영자가 수동으로 재정의용 접근 토큰을 발급할 수 있도록 하기 위한 것입니다. 문제가 되는 경우, 예를 들어 iss 클레임(일반적으로 발급자 ID와 동일함)을 기준으로 필터링하는 등 admin 규칙에 보다 세밀한 필터를 추가하는 것이 권장됩니다.

tenant.semaphores

이 테넌트의 잡이 접근할 수 있도록 허용할 global-semaphore 객체 이름의 목록입니다.

tenant.use-nodepool
Default: true

테넌트가 Nodepool 대신 zuul-launcher`를 사용하도록 마이그레이션된 경우, Nodepool 레이블 폴백 동작을 비활성화하려면 이 값을 ``false` 로 설정합니다. Nodepool이 실행되고 있지 않은 상태에서는, 존재하지 않는 레이블에 대한 요청을 거부해야 함을 Zuul이 인지하는 것이 중요합니다.

전역 세마포어(Global Semaphore)

세마포어는 일반적으로 저장소 내 구성에서 정의됩니다(참조: Semaphore ). 그러나 여러 Zuul 테넌트가 공유하는 제한된 전역 리소스를 표현하는 데 세마포어를 사용하는 경우를 지원하기 위해, 메인 테넌트 구성 파일에서 세마포어를 정의할 수도 있습니다.

잡이 전역 세마포어를 사용하려면, 먼저 global-semaphore 를 사용하여 테넌트 구성 파일에 해당 세마포어를 정의해야 합니다. 이후 접근이 허용된 각 테넌트에 대해 tenant.semaphores 에 추가해야 합니다. 이렇게 설정하면 Zuul 잡은 일반적인 테넌트 범위 세마포어와 동일한 방식으로 해당 세마포어를 사용할 수 있습니다.

전역 세마포어에 대한 접근 권한이 부여된 테넌트에 동일한 이름의 테넌트 범위 세마포어가 정의되어 있는 경우, 해당 정의는 구성 오류로 처리되며 전역 세마포어가 대신 사용됩니다.

예시 정의는 일반 세마포어 객체와 유사한 형태입니다:

- global-semaphore:
    name: global-semaphore-foo
    max: 5

global-semaphore

다음 속성을 사용할 수 있습니다:

global-semaphore.name (required)

잡에서 참조하는 세마포어의 이름.

global-semaphore.max
Default: 1

이 세마포어를 사용할 수 있는, 동시에 실행 중인 잡의 최대 개수.

인증 규칙(Authorization Rule)

인증 규칙은 사용자의 JWT에 포함된 클레임이 일치해야 하는 조건 집합으로, 테넌트 수준에서 작업을 수행할 수 있도록 허용하기 위한 기준입니다.

인증 규칙이 테넌트의 `admin-rules`에 포함된 경우, 보호된 작업인 autohold , enqueue , dequeue , promote 를 수행할 수 있습니다.

참고

토큰의 zuul.admin 클레임이 allow_authz_override`가 true로 설정된 인증기 구성과 일치하는 경우, 규칙은 재정의될 수 있습니다. 자세한 내용은 :ref:`authentication 을 참조.

다음은 인증 규칙을 정의하는 몇 가지 예시입니다:

- authorization-rule:
    name: affiliate_or_admin
    conditions:
      - resources_access:
          account:
            roles: "affiliate"
        iss: external_institution
      - resources_access.account.roles: "admin"
- authorization-rule:
    name: alice_or_bob
    conditions:
      - zuul_uid: alice
      - zuul_uid: bob

이전 버전의 Zuul에서는 이러한 정의에 admin-rule 을 사용했습니다. 해당 형식은 하위 호환성을 위해 여전히 허용되지만, 현재 사용 중단 상태이며 향후 Zuul 버전에서 제거될 예정입니다.

authorization-rule

지원되는 속성은 다음과 같습니다:

authorization-rule.name (required)

규칙의 이름으로, 테넌트 정의의 admin-rules 속성에서 참조됩니다. 이름은 고유해야 합니다.

authorization-rule.conditions (required)

규칙을 정의하는 조건 목록. 규칙이 적용되려면 JWT가 조건 중 최소 하나 와 일치해야 합니다. 조건은 키가 클레임인 딕셔너리입니다. 관련된 값은 모두 사용자의 토큰에 포함된 클레임과 일치해야 합니다. 즉, 조건 딕셔너리는 사용자의 JWT의 “하위 딕셔너리(sub-dictionary)”이어야 합니다.

Zuul의 인증 엔진은 토큰의 클레임 유형에 따라 매칭 방식을 조정합니다. 예:

• 클레임이 JSON 목록인 경우, 조건 값이 해당 클레임에 포함되어 있는지 확인합니다.

• 클레임이 문자열 또는 불리언(boolean)인 경우, 조건 값이 클레임 값과 동일한지 확인합니다.

명확성을 위해 클레임 이름을 XPath 형식으로 작성할 수도 있습니다. 예를 들어 다음 조건은

resources_access:
  account:
    roles: "affiliate"

다음 조건과 동일합니다.

resources_access.account.roles: "affiliate"

특수 클레임 zuul_uid 는 인증기 구성의 uid_claim 설정을 참조합니다. 기본적으로 이는 토큰의 sub 클레임을 의미합니다. 자세한 내용은 인증된 액세스 (Authenticated Access) 을 참조.

위 예시에서 다음 토큰은 affiliate_or_admin 및 alice_or_bob 규칙과 일치합니다:

{
 'iss': 'external_institution',
 'aud': 'my_zuul_deployment',
 'exp': 1234567890,
 'iat': 1234556780,
 'sub': 'alice',
 'resources_access': {
     'account': {
         'roles': ['affiliate', 'other_role']
     }
 },
}

그리고 다음 토큰은 affiliate_or_admin 규칙에만 일치합니다:

{
 'iss': 'some_other_institution',
 'aud': 'my_zuul_deployment',
 'exp': 1234567890,
 'sub': 'carol',
 'iat': 1234556780,
 'resources_access': {
     'account': {
         'roles': ['admin', 'other_role']
     }
 },
}

인증 규칙 템플릿

특수 문자열 “{tenant.name}”은 조건 값에 사용할 수 있습니다. 주어진 클레임 집합에 대해 인증을 평가할 때, 해당 테넌트 이름으로 자동 치환됩니다. 예를 들어:

- authorization-rule:
    name: tenant_in_groups
    conditions:
      - groups: "{tenant.name}"

다음 테넌트에 적용하면:

- tenant:
    name: tenant-one
    admin-rules:
      - tenant_in_groups
- tenant:
    name: tenant-two
    admin-rules:
      - tenant_in_groups

이 경우 다음 클레임 집합은 tenant-one 에서 보호된 작업을 수행할 수 있습니다:

{
 'iss': 'some_other_institution',
 'aud': 'my_zuul_deployment',
 'exp': 1234567890,
 'sub': 'carol',
 'iat': 1234556780,
 'groups': ['tenant-one', 'some-other-group'],
}

그리고 다음 클레임 집합은 tenant-one 및 tenant-two 에서 보호된 작업을 수행할 수 있습니다:

{
 'iss': 'some_other_institution',
 'aud': 'my_zuul_deployment',
 'exp': 1234567890,
 'sub': 'carol',
 'iat': 1234556780,
 'groups': ['tenant-one', 'tenant-two'],
}

API 루트

zuul-web, zuul-client 및 REST API의 대부분의 작업은 특정 테넌트의 컨텍스트 내에서 수행되는 것으로 간주되며, 따라서 해당 테넌트에 지정된 인증 규칙이 적용됩니다. zuul-web이 다중 테넌트 환경(기본값)으로 배포된 경우, 일부 작업이나 API 메서드는 개별 테넌트의 컨텍스트 밖에서 동작합니다(예: 테넌트 목록 조회 또는 Zuul 시스템 구성 요소 상태 확인). 이러한 메서드에 대한 접근을 제어하려면 api-root 객체를 사용할 수 있습니다.

테넌트 구성 파일에는 api-root 객체가 최대 하나만 존재할 수 있습니다. 둘 이상 정의되면 오류로 처리됩니다. api-root 객체가 정의되지 않은 경우, 테넌트 목록 및 기타 루트 수준 API 메서드에 대해 익명 읽기 전용 접근이 허용된 것으로 간주합니다.

/api/info 엔드포인트는 웹 UI에 필요한 인증 정보를 제공하므로 Zuul에 의해 보호되지 않습니다.

API 루트 접근은 테넌트별 URL에 접근하기 위한 전제 조건이 아니다.

api-root

지원되는 속성은 다음과 같습니다:

api-root.authentication-realm

Zuul 구성에 정의된 각 인증기(authenticator)는 하나의 realm과 연결됩니다. 다중 테넌트 루트에서 Zuul 웹 사용자 인터페이스를 통해 인증하는 경우, Web UI는 사용자를 해당 realm의 인증 서비스로 리디렉션합니다. 인증기는 OpenIDConnect 유형이어야 합니다.

참고

루트 API에 기본 realm을 정의하더라도, 다른 구성된 realm에서 발급된 접근 토큰은 무효화되지 않습니다. 이는 운영자가 수동으로 재정의용 접근 토큰을 발급할 수 있도록 하기 위한 것입니다. 문제가 되는 경우, 예를 들어 iss 클레임 (일반적으로 발급자 ID와 동일함)을 기준으로 필터링하는 등 admin 규칙에 보다 세밀한 필터를 추가하는 것이 권장됩니다.

api-root.access-rules

Zuul의 REST API 및 웹 인터페이스의 최상위(즉, 테넌트에 종속되지 않는) 영역에 대한 읽기 접근을 허용하기 위해 검사할 인증 규칙 목록입니다.

규칙이 정의되어 있지 않으면, 최상위 메서드에 대한 익명 접근이 허용됩니다. 규칙이 하나라도 정의되어 있는 경우에는, 사용자가 접근하려면 목록의 규칙 중 최소 하나가 일치해야 합니다.

테넌트 범위 작업에 대한 자세한 내용은 인증된 액세스 (Authenticated Access) 을 참조.