Make Interface v2¶
tirosh-infra의 공개 운영 API는 Make target입니다. 사람과 agent는 기본적으로 ansible-playbook, tofu, kubectl, gh를 직접 호출하지 않고 make <area>/<lifecycle> SITE=<site> 형태로 시작합니다.
직접 도구를 호출하는 경우는 Make target 실패를 디버깅하거나, 문서가 명시한 읽기 전용 확인을 수행할 때로 제한합니다.
1. 계층 계약¶
1-1. 계층별 역할¶
Make target
사용자와 agent가 호출하는 운영 명령
make/interface/*.mk
공개 target wrapper와 alias
make/areas/*.mk
영역별 구현 target
profile.toml
site 단위 실행 경로와 metadata
inventory.toml
machine, group, workload 선언
inventory.yml
렌더링된 Ansible inventory
*.vars.yml and *.tfvars
하위 시스템 desired state
infra-tools
parsing, validation, rendering, doctor check
예를 들어 아래 명령은 사용자가 vars 파일 경로나 playbook 경로를 직접 알 필요 없게 합니다.
1-2. 호출 예시¶
make nexus/apply SITE=tirosh-home
Make는 sites/tirosh-home/profile.toml에서 nexus.vars를 읽고, sites/tirosh-home/nexus/vars.yml을 Nexus provisioning playbook에 전달합니다.
2. 안전 등급¶
Help 출력은 target의 안전 등급을 표시합니다.
2-1. 등급표¶
| 등급 | 의미 |
|---|---|
[SAFE] |
local 또는 remote state를 조회하거나 검증합니다. remote state를 변경하지 않습니다. |
[CHANGES] |
desired state를 적용하거나 local/remote/GitHub/Nexus state를 변경합니다. |
[DANGER] |
제거, 파괴, 운영 restore처럼 되돌리기 어려운 변경을 수행합니다. |
기본 순서는 다음입니다.
2-2. 기본 실행 순서¶
make help
make repo/doctor SITE=tirosh-home
make <area>/help
make <area>/doctor SITE=tirosh-home
make <area>/status SITE=tirosh-home
make <area>/plan SITE=tirosh-home
make <area>/apply SITE=tirosh-home
모든 area가 아직 모든 lifecycle을 구현하지는 않습니다. 해당 area help에 표시된 target만 사용합니다.
2-3. apply와 install의 차이¶
apply가 모든 area에 존재해야 하는 것은 아닙니다. VM, repository, host network처럼 desired state를 반복 적용하는 area는 apply를 표준 lifecycle로 둡니다. k3s, RKE2, Argo CD처럼 runtime이나 component 설치 의미가 더 강한 area는 install을 표준 lifecycle로 둡니다.
3. 표준 lifecycle 이름¶
3-1. Lifecycle 표¶
| Lifecycle | 안전 등급 | 의미 |
|---|---|---|
help |
[SAFE] |
area command와 필수 변수를 확인합니다. |
doctor |
[SAFE] |
로컬 도구, profile, inventory, vars, secret 존재 여부를 확인합니다. |
status |
[SAFE] |
대상 시스템의 현재 상태를 조회합니다. |
plan |
[SAFE] |
적용 전 변경 계획을 출력합니다. |
apply |
[CHANGES] |
desired state를 반영합니다. |
install |
[CHANGES] |
component 또는 runtime을 설치합니다. |
register |
[CHANGES] |
외부 시스템에 runner, cluster, secret 등을 등록합니다. |
uninstall |
[DANGER] |
component 또는 runtime을 제거합니다. |
restore/apply |
[DANGER] |
운영 데이터 restore처럼 큰 영향을 주는 작업을 실행합니다. |
4. 현재 v2 진입점¶
4-1. Repo와 interface 확인¶
make repo/doctor SITE=tirosh-home
make interface/check SITE=tirosh-home
uv run infra-tools doctor repo --site tirosh-home --format json
uv run infra-tools interface list --format json
4-2. Area별 운영 진입점¶
make proxmox/help
make proxmox/doctor SITE=tirosh-home
make proxmox/plan SITE=tirosh-home
make proxmox/apply SITE=tirosh-home
make nexus/help
make nexus/doctor SITE=tirosh-home
make nexus/apply SITE=tirosh-home
make nexus/github/apply
make github-runner/help
make github-runner/doctor SITE=tirosh-home
make github-runner/apply SITE=tirosh-home
make github-runner/register SITE=tirosh-home
make github-runner/status SITE=tirosh-home
make github-runner/pool/doctor SITE=aws-ci
make github-runner/pool/plan SITE=aws-ci
make github-runner/pool/apply SITE=aws-ci
make github-runner/pool/status SITE=aws-ci
make host/help
make host/doctor SITE=tirosh-home
make host/apply SITE=tirosh-home
make k3s/help
make k3s/doctor SITE=tirosh-home
make k3s/install SITE=tirosh-home
make rke2/help
make rke2/doctor SITE=tirosh-home
make rke2/server/install SITE=tirosh-home
make rke2/agent/install SITE=tirosh-home
make argocd/help
make argocd/doctor SITE=tirosh-home
make argocd/install SITE=tirosh-home
make kubernetes/help
make kubernetes/doctor SITE=tirosh-home
make kubernetes/image-pull-secret/plan SITE=tirosh-home
make kubernetes/secret/plan SITE=tirosh-home KUBERNETES_SECRET=<secret-id>
make kubernetes/secret/apply SITE=tirosh-home KUBERNETES_SECRET=<secret-id>
4-3. Alias 기준¶
기존 상세 target은 호환성을 위해 유지합니다. 예를 들어 nexus/apply는 nexus/repositories/apply의 v2 alias이고, github-runner/apply는 github-runner/prepare의 v2 alias입니다.
의도적으로 만들지 않는 alias도 있습니다. k3s/apply, rke2/apply, argocd/apply는 현재 의미가 모호하므로 사용하지 않습니다. 이 영역에서는 install, status, cluster/add처럼 area help가 표시하는 표준 target을 사용합니다.
5. 필수 값¶
공통적으로 SITE는 site directory 이름입니다.
5-1. SITE 값¶
make repo/doctor SITE=tirosh-home
SITE=tirosh-home이면 Make는 sites/tirosh-home/profile.toml을 읽어 area별 기본값을 채웁니다.
5-2. Profile key와 desired state¶
| 영역 | profile key | desired state |
|---|---|---|
nexus |
nexus.vars |
sites/<site>/nexus/vars.yml |
github-runner |
github_runner.prepare_vars, github_runner.register_vars |
sites/<site>/inventory.toml, sites/<site>/github-runner/*.vars.yml |
github-runner/pool |
cloud.provider, cloud.vars, github_runner.pool_vars, github_runner.worker_platforms.*, github_runner.prepare_vars, github_runner.register_vars |
sites/<site>/inventory.toml, sites/<site>/cloud/*.tfvars, sites/<site>/github-runner/*.vars.yml |
proxmox |
proxmox.vm_vars, proxmox.vm_catalog, proxmox.vm_secrets |
sites/<site>/proxmox/*.tfvars, sites/<site>/vms.tfvars |
host |
host.network_vars |
sites/<site>/host/network.vars.yml |
k3s |
k3s.vars |
sites/<site>/k3s/vars.yml |
rke2 |
rke2.<cluster>.vars |
sites/<site>/rke2/vars.yml |
argocd |
argocd.vars |
sites/<site>/argocd/vars.yml |
5-3. Secret과 credential¶
Secret은 .env, exported environment variable, local CLI profile, 또는 전용 local secret file로 공급합니다.
TOML/YAML 파일에 secret을 commit하지 않고, doctor/help target은 secret 값을 출력하지 않아야 합니다.
Cloud IaC credential은 provider별 관례를 따릅니다.
| Provider | 권장 local credential source | .env 값 |
|---|---|---|
| AWS | ~/.aws/credentials의 AWS CLI profile |
AWS_PROFILE=tirosh-infra, AWS_DEFAULT_REGION=ap-northeast-2 |
| NCloud | OpenTofu provider environment variable | NCLOUD_ACCESS_KEY, NCLOUD_SECRET_KEY, NCLOUD_REGION |
profile.toml에는 cloud credential을 저장하지 않습니다. profile.toml은 site 기본값과 파일 경로만 저장합니다.
5-4. Cloud CI runner site¶
aws-ci, ncloud-ci 같은 Cloud CI runner site는 site.areas = ["github_runner_pool"]를 선언합니다.
이 site들은 proxmox, k3s, argocd, nexus 기본값을 갖지 않아도 됩니다. 기본값의 출처 순서는
다른 site와 같습니다.
sites/<site>/profile.toml
sites/<site>/inventory.toml
rendered sites/<site>/inventory.yml
sites/<site>/cloud/*.tfvars
sites/<site>/github-runner/*.vars.yml
github-runner/pool/apply는 cloud runner pool infrastructure와 controller 설정을 적용합니다.
GitHub queue를 보고 runtime CI 용량을 판단하지는 않습니다. Runtime scale-out과 cleanup 판단은 이
target이 배포하는 controller service의 책임입니다.
6. Agent workflow¶
Agent는 다음 규칙으로 움직입니다.
6-1. 기본 규칙¶
make help로 공개 interface를 확인합니다.make interface/check SITE=<site>로 공개 Make target 계약을 확인합니다.make repo/doctor SITE=<site>로 repo/profile/inventory 준비 상태를 확인합니다.- machine-readable target catalog가 필요하면
infra-tools interface list --format json을 사용합니다. - machine-readable 준비 상태 결과가 필요하면
infra-tools doctor <area> --site <site> --format json을 사용합니다. - area 작업 전
make <area>/help와make <area>/doctor SITE=<site>를 실행합니다. - 변경 전
status또는plan이 있으면 먼저 실행합니다. [CHANGES]또는[DANGER]target은 필요한 secret과 confirmation을 확인한 뒤 실행합니다.- 실패 시에는 Make output과 docs를 먼저 보고, 필요한 경우에만 직접 도구로 원인을 확인합니다.