프로젝트 구성 (Project Configuration)
다음 섹션에서는 Zuul 구성의 주요 부분을 설명합니다. 아래의 모든 내용은 Zuul이 관리하는 저장소 내부의 파일에서 찾을 수 있습니다.
보안 컨텍스트 (Security Contexts)
시스템 관리자가 프로젝트에서 작동하도록 Zuul을 구성할 때, 해당 프로젝트에 대한 두 가지 보안 컨텍스트 중 하나를 지정합니다. ‘config-project’는 주로 Zuul에 대한 구성 정보와 잡(job) 콘텐츠를 보관하는 임무를 맡은 프로젝트입니다. config-project에 정의된 잡은 상승된 권한(elevated privileges)으로 실행되며 모든 Zuul 구성 항목을 사용할 수 있습니다. 베이스 잡(즉, 부모가 없는 잡)은 config-project에서만 정의될 수 있습니다. config-project에 대한 변경 사항은 병합되기 전에 세심한 검토를 거칠 것으로 예상됩니다.
*untrusted-project*는 주된 초점이 Zuul을 운영하는 것이 아니라 테스트되거나 배포되는 프로젝트 중 하나인 프로젝트입니다. 이러한 프로젝트에서 사용할 수 있는 Zuul 구성 언어는 (아래 개별 섹션에 자세히 설명된 대로) 다소 제한되어 있으며, 이러한 프로젝트에 정의된 잡은 아직 리뷰를 거치지 않은 변경 사항에 대해 작동할 수 있으므로 제한된 실행 환경에서 실행됩니다.
구성 로딩 (Configuration Loading)
Zuul이 시작되면 시스템 관리자가 테넌트 구성 에 지정한 모든 git 저장소를 검사하고 각 저장소의 루트에서 파일을 검색합니다. Zuul은 먼저 zuul.yaml 이라는 파일이나 zuul.d 라는 디렉터리를 찾고, 발견되지 않으면 (앞에 점이 있는 형태인) .zuul.yaml 또는 .zuul.d 를 찾습니다. untrusted-project 의 경우 모든 브랜치의 구성이 포함되지만, config-project 의 경우 단일 브랜치만 검사됩니다. config 프로젝트 브랜치는 테넌트 구성의 tenant.config-projects.<project>.load-branch 속성으로 구성할 수 있습니다.
untrusted-project의 이러한 파일 중 하나에 대한 변경이 제안되면, 제안된 구성이 실행 중인 구성에 병합되어 Zuul 구성에 대한 모든 변경 사항이 해당 변경의 일부로서 자체 테스트(self-testing)되도록 합니다. 구성 오류가 있는 경우 어떤 잡도 실행되지 않으며 해당되는 모든 파이프라인에서 오류를 보고합니다. config-project에 대한 변경의 경우, 새로운 구성을 파싱하여 오류를 검사하지만 새로운 구성이 변경 사항 테스트에 사용되지는 않습니다. 이는 config-project의 구성이 상승된 권한에 액세스할 수 있으며 병합되기 전에 항상 리뷰를 거쳐야 하기 때문입니다.
Zuul 구성 변경을 포함하는 변경 사항이 Zuul 관리 저장소에 병합되는 즉시 새로운 구성이 적용됩니다.
정규 표현식 (Regular Expressions)
많은 옵션이 리터럴 문자열이나 정규 표현식을 허용합니다. 이 경우, 정규 표현식 일치는 마치 정규 표현식의 시작 부분에 암묵적인 ``^``가 있는 것처럼 문자열의 시작 부분부터 일치를 시작합니다. 임의의 위치에서 일치시키려면 정규 표현식 앞에 ``.*``를 추가하세요.
Zuul은 PCRE에 비해 제한된 정규 표현식 문법을 가진 RE2 라이브러리 를 사용합니다.
정규 표현식에 대해 일부 옵션을 지정할 수 있습니다. 이를 위해 딕셔너리를 사용하여 YAML 구성에 정규 표현식을 지정하세요.
예를 들어, 다음은 모두 job.branches 속성에 대한 유효한 값들이며, 모두 “devel” 브랜치와 일치합니다:
- job:
branches: devel
- job:
branches:
- devel
- job:
branches:
regex: devel
negate: false
- job:
branches:
- regex: devel
negate: false
암호화 (Encryption)
Zuul은 작동 중인 프로젝트의 git 저장소에 직접 암호화된 데이터를 저장하는 것을 지원합니다. 실행하기 위해 비공개 정보(예: 타사 서비스와 상호 작용하기 위한 자격 증명)가 필요한 잡이 있는 경우, 이러한 자격 증명을 잡 정의와 함께 저장할 수 있습니다.
Zuul의 각 프로젝트에는 자동으로 생성된 고유한 RSA 키 페어가 있으며, 이 키를 사용해 누구나 시크릿을 암호화할 수 있고 Zuul만이 이를 복호화할 수 있습니다. Zuul은 내장 웹 서버를 사용하여 각 프로젝트의 공개 키를 제공합니다. 이 키들은 /api/tenant/<tenant>/key/<project>.pub 경로에서 가져올 수 있으며, 여기서 <project> 는 프로젝트의 정규 이름(canonical name)이고 <tenant> 는 해당 프로젝트가 속한 테넌트의 이름입니다.
Zuul은 현재 단일 암호화 체계인 PKCS#1 with OAEP를 지원하며, 이는 3760비트(4096비트의 키 길이에서 오버헤드 336비트를 뺀 값)보다 긴 시크릿을 저장할 수 없습니다. 이 체계에서 사용하는 패딩은 암호화된 데이터를 검사하는 사람이 해당 데이터의 길이가 3760비트(또는 그 배수)를 넘지 않는다는 것 외에는 평문 버전의 데이터 길이를 알아낼 수 없도록 보장합니다.
구성 파일 자체에서 Zuul은 시크릿에 사용되는 암호화 체계를 지정하는 확장 가능한 방법을 사용하여 향후 다른 체계를 추가할 수 있도록 합니다. 시크릿을 지정하려면 base64로 인코딩된 값과 함께 !encrypted/pkcs1-oaep YAML 태그를 사용하세요. 예를 들면 다음과 같습니다:
- secret:
name: test_secret
data:
password: !encrypted/pkcs1-oaep |
BFhtdnm8uXx7kn79RFL/zJywmzLkT1GY78P3bOtp4WghUFWobkifSu7ZpaV4NeO0s71YUsi
...
3760비트보다 긴 시크릿을 지원하기 위해, 암호화 태그 뒤의 값은 스칼라(scalar) 대신 리스트(list) 형태일 수 있습니다. 예를 들면 다음과 같습니다:
- secret:
name: long_secret
data:
password: !encrypted/pkcs1-oaep
- er1UXNOD3OqtsRJaP0Wvaqiqx0ZY2zzRt6V9vqIsRaz1R5C4/AEtIad/DERZHwk3Nk+KV
...
- HdWDS9lCBaBJnhMsm/O9tpzCq+GKRELpRzUwVgU5k822uBwhZemeSrUOLQ8hQ7q/vVHln
...
zuul-client 유틸리티 는 Zuul 프로젝트의 시크릿을 암호화하는 간단한 방법을 제공합니다:
usage: zuul-client encrypt [-h] [--public-key /path/to/pubkey]
[--tenant TENANT] [--project PROJECT] [--no-strip]
[--secret-name SECRET_NAME]
[--field-name FIELD_NAME] [--infile INFILE]
[--outfile OUTFILE]
options:
-h, --help show this help message and exit
--public-key /path/to/pubkey
path to project public key (bypass API call)
--tenant TENANT tenant name
--project PROJECT project name
--no-strip Do not strip whitespace from beginning or end of
input. Ignored when --infile is used.
--secret-name SECRET_NAME
How the secret should be named. If not supplied, a
placeholder will be used.
--field-name FIELD_NAME
How the name of the secret variable. If not supplied,
a placeholder will be used.
--infile INFILE A filename whose contents will be encrypted. If not
supplied, the value will be read from standard input.
If entering the secret manually, press Ctrl+d when
finished to process the secret.
--outfile OUTFILE A filename to which the encrypted value will be
written. If not supplied, the value will be written to
standard output.
구성 항목 (Configuration Items)
zuul.yaml 및 .zuul.yaml 구성 파일은 YAML 형식이며 일련의 항목들로 구성되어 있고, 각각은 아래에서 참조됩니다.
zuul.d (또는 .zuul.d ) 디렉터리의 경우, Zuul은 디렉터리를 재귀적으로 순회하고 정렬된 경로 순서에 따라 모든 .yaml 파일을 사용하여 구성을 확장합니다. 예를 들어, 잡의 변형(variants)을 별도의 파일에 보관하려면 메인 항목 뒤에 로드되어야 하므로 파일 이름에 숫자 접두사를 사용하는 식으로 할 수 있습니다:
* zuul.d/pipelines.yaml
* zuul.d/projects.yaml
* zuul.d/01_jobs.yaml
* zuul.d/02_jobs-variants.yaml
하위 디렉터리도 순회된다는 점에 유의하세요. .zuul.ignore 파일이 있는 하위 디렉터리는 잘려나가 무시됩니다(이는 필요한 경우 구성 디렉터리에 플레이북이나 역할(roles)을 유지하기 쉽게 해줍니다).
아래는 YAML 파일 내에서 사용할 수 있는 다양한 구성 항목에 대한 참조입니다:
프로젝트에 공급자 구성(provider config)과 관련된 항목을 로드할 권한이 있는 경우 몇 가지 추가 항목을 사용할 수 있습니다. 이에 대한 자세한 내용은 빌드 노드(Build Nodes) 를 참조하세요: