시작하기¶

이 문서는 tirosh-infra를 처음 열었을 때 확인해야 하는 실행 방식, site 설정 구조, 전체 운영 순서, 자주 쓰는 변수를 한 번에 설명합니다.

1. 기본 실행 방식¶

대부분의 작업은 SITE를 지정해서 실행합니다.

make help
make repo/doctor SITE=tirosh-home

처음 보는 명령어는 세부 help를 먼저 확인합니다.

make proxmox/help
make host/help
make k3s/help
make rke2/help
make argocd/help
make nexus/help
make github-runner/help

Password SSH를 사용하는 환경에서는 ASK_PASS=true를 붙입니다. sudo password도 필요하면 ASK_BECOME_PASS=true를 함께 붙입니다.

make rke2/status SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true

ASK_PASS류 값은 정확히 true 또는 false만 사용합니다. yes, 1, y는 password prompt를 켜지 않습니다.

1-1. 자주 쓰는 시작 명령¶

make site-show SITE=tirosh-home
make site/inventory/render SITE=tirosh-home
make repo/doctor SITE=tirosh-home
make rke2/status SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true

1-2. 문서 확인¶

make docs/serve

기본 주소는 MkDocs 기본값인 http://127.0.0.1:8000입니다.

2. Site 설정 구조¶

site 디렉터리는 site의 상태를 읽는 출발점입니다. 처음에는 아래 네 파일의 차이만 이해하면 됩니다.

profile.toml   = 기본 실행 context와 파일 경로 선택
inventory.toml = 실제 접속 대상과 host 속성
inventory.yml  = Ansible이 읽는 렌더링 결과
manifest.yaml  = site 식별 정보와 문서화용 metadata

사람이 아래처럼 짧게 명령하면,

make rke2/server/install SITE=tirosh-home

Make는 profile.toml에서 기본 inventory, target group, vars 파일, kube context를 읽어 실행 인자로 바꿉니다. 실제 host IP, SSH 계정, node role은 inventory.toml에 둡니다.

전체 책임 경계와 아키텍처 원칙은 운영 모델을 기준으로 봅니다. Make target, profile, inventory, vars의 public interface 계약은 Make Interface v2를 기준으로 봅니다. 시작하기 문서는 실행에 필요한 최소 구조만 다룹니다.

2-1. 주요 파일¶

sites/tirosh-home/
  profile.toml                site의 기본 실행 컨텍스트
  inventory.toml              사람이 관리하는 실제 대상 목록
  inventory.yml               inventory.toml에서 생성한 Ansible inventory
  manifest.yaml               site 식별 정보와 문서화용 metadata
  vms.tfvars                  OpenTofu가 생성/관리할 VM catalog
  proxmox/                    Proxmox bootstrap, template, VM 공통 설정
  host/                       host network 설정
  k3s/                        Argo CD management cluster 설정
  rke2/                       RKE2 workload cluster 설정
  argocd/                     Argo CD 설치와 노출 설정
  nexus/                      Nexus 내부 운영 상태 설정
  github-runner/              GitHub Actions runner 설정

2-2. inventory 렌더링¶

inventory.toml은 사람이 유지보수하는 inventory source입니다. 수정 후에는 반드시 inventory.yml을 다시 렌더링합니다.

[baremetals.gpu-01]
ansible_host = "172.31.0.20"
ansible_user = "tirosh"
ansible_become_user = "root"
rke2_node_labels = [
  "node.tirosh.dev/role=gpu",
  "node.tirosh.dev/site=tirosh-home",
  "node.tirosh.dev/model=dgx-spark",
]
workloads = ["gpu"]
rke2 = { cluster = "gpu", role = "server" }

make site/inventory/render SITE=tirosh-home

workloads는 host가 어떤 기능에 참여하는지 표시하고, 렌더링 후 Ansible group으로 변환됩니다. RKE2의 server/agent 역할처럼 도메인별 세부 host 속성도 inventory.toml에 둡니다.

make repo/doctor SITE=<site_id>는 profile.toml, 필수 site 파일, inventory 참조 경로를 확인합니다.

make repo/doctor SITE=tirosh-home

2-3. vars와 tfvars¶

*.vars.yml은 Ansible playbook에 넘기는 site별 desired state입니다. 예를 들어 rke2/vars.yml은 RKE2 설치와 설정을 위한 입력이고, github-runner/prepare.vars.yml은 runner VM 내부 준비 작업의 입력입니다.

*.tfvars는 OpenTofu module에 넘기는 입력입니다. proxmox/vars.tfvars는 Proxmox provider와 VM 생성 공통값을 담고, vms.tfvars는 site에서 관리할 VM catalog를 담습니다.

profile.toml은 이 값들을 다시 선언하지 않고 어떤 파일을 사용할지만 선택합니다.

3. 운영 순서¶

운영 순서는 아래 phase로 나눠서 봅니다. 이미 준비된 phase는 건너뛰면 됩니다.

Site 확인
  -> Proxmox / VM
  -> Host network
  -> Management cluster
  -> Workload cluster
  -> Platform services
  -> CI runner

Phase	목적	주요 명령	상세 문서
0. Site 확인	profile, inventory, 참조 파일 확인	`make repo/doctor`, `make site-show`	Make Interface v2
1. Proxmox / VM	Proxmox node, template, VM catalog 반영	`make proxmox/plan`, `make proxmox/apply`	Proxmox
2. Host network	bare-metal host static IP 적용	`make host/apply`	Host Network
3. Management cluster	k3s와 Argo CD 설치	`make k3s/install`, `make argocd/install`	Argo CD
4. Workload cluster	RKE2 GPU cluster 설치와 Argo CD 등록	`make rke2/server/install`, `make argocd/cluster/add`	RKE2 GPU cluster
5. Platform services	Nexus package registry 운영 상태 적용	`make nexus/doctor`, `make nexus/apply`	Nexus
6. CI runner	GitHub Actions self-hosted runner 준비와 등록	`make github-runner/doctor`, `make github-runner/apply`, `make github-runner/register`	GitHub CI

예를 들어 GPU node가 이미 준비되어 있다면 Phase 2와 Phase 4부터 진행하면 됩니다. github-ci VM이 이미 생성되어 있다면 Phase 6의 runner prepare/register 단계부터 진행하면 됩니다.

3-1. Phase 0: Site 확인¶

make site-show SITE=tirosh-home
make site/inventory/render SITE=tirosh-home
make repo/doctor SITE=tirosh-home

site-show는 manifest.yaml metadata와 profile.toml에서 선택된 실행 기본값을 함께 보여줍니다. inventory.toml을 수정했다면 site/inventory/render를 먼저 실행한 뒤 repo/doctor로 참조 파일과 필수 key를 확인합니다.

3-2. Phase 1: Proxmox / VM¶

make proxmox/bootstrap SITE=tirosh-home
make proxmox/template/apply SITE=tirosh-home
make proxmox/vms/init SITE=tirosh-home
make proxmox/plan SITE=tirosh-home
make proxmox/apply SITE=tirosh-home

상세 가이드: Proxmox

3-3. Phase 2: Host network¶

make host/apply SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true

상세 가이드: Host Network

3-4. Phase 3: Management cluster¶

make k3s/install SITE=tirosh-home ASK_PASS=true
make k3s/kubeconfig/merge SITE=tirosh-home ASK_PASS=true
make argocd/install SITE=tirosh-home ASK_PASS=true

상세 가이드: Argo CD

3-5. Phase 4: Workload cluster¶

make rke2/server/install SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true
make rke2/agent/install SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true
make rke2/kubeconfig/merge SITE=tirosh-home ASK_PASS=true ASK_BECOME_PASS=true
make argocd/cluster/add SITE=tirosh-home

상세 가이드: RKE2 GPU cluster

Argo CD 등록은 Argo CD의 workload cluster 등록 절도 함께 참고합니다.

3-6. Phase 5: Platform services¶

Nexus Kubernetes resource는 tirosh-gitops가 관리하고, Nexus 내부 repository, role, user 같은 애플리케이션 운영 상태는 tirosh-infra에서 관리합니다.

make nexus/doctor SITE=tirosh-home
make nexus/apply SITE=tirosh-home
make nexus/github/apply

상세 가이드: Nexus

3-7. Phase 6: CI runner¶

GitHub CI runner는 VM lifecycle과 runner 등록을 분리해서 봅니다. github-ci VM은 Proxmox/OpenTofu 단계에서 생성하고, VM 내부 준비와 GitHub organization 등록은 아래 target으로 수행합니다.

make github-runner/doctor SITE=tirosh-home

make github-runner/apply SITE=tirosh-home \
  ASK_PASS=true \
  ASK_BECOME_PASS=true

make github-runner/register SITE=tirosh-home \
  ASK_PASS=true \
  ASK_BECOME_PASS=true

make github-runner/status SITE=tirosh-home \
  ASK_PASS=true \
  ASK_BECOME_PASS=true

상세 가이드: GitHub CI

4. 자주 쓰는 변수¶

루트 Makefile은 대부분의 기본값을 sites/<site_id>/profile.toml에서 읽습니다. 필요한 경우 command line에서 override합니다.

변수	기본값	설명
`SITE`	없음	site 디렉터리 이름
`ASK_PASS`	`true`	Ansible SSH password prompt
`ASK_BECOME_PASS`	`false`	Ansible sudo password prompt
`HOST_TARGET_NAME`	`profile.toml: host.target_name`	host network target
`K3S_TARGET_NAME`	`profile.toml: k3s.target_name`	k3s target
`RKE2_CLUSTER`	`profile.toml: rke2.default_cluster`	RKE2 cluster profile name
`RKE2_TARGETS`	`profile.toml: rke2.<name>.targets`	RKE2 generic targets
`RKE2_SERVER_TARGETS`	`profile.toml: rke2.<name>.server_targets`	RKE2 server install targets
`RKE2_AGENT_TARGETS`	`profile.toml: rke2.<name>.agent_targets`	RKE2 agent install targets
`K3S_CONTEXT_NAME`	`profile.toml: k3s.context_name`	k3s kube context
`RKE2_CONTEXT_NAME`	`profile.toml: rke2.<name>.context_name`	RKE2 kube context
`K3S_KUBECONFIG_PATH`	`profile.toml: k3s.kubeconfig_path`	k3s에서 가져온 kubeconfig 저장 경로
`RKE2_KUBECONFIG_PATH`	`profile.toml: rke2.<name>.kubeconfig_path`	RKE2에서 가져온 kubeconfig 저장 경로
`KUBECONFIG`	`profile.toml: kube.kubeconfig`	kubectl이 사용할 kubeconfig override
`KUBECTX`	`profile.toml: kube.contexts.argocd`	Argo CD management cluster context
`KUBECONFIG_MAIN`	`profile.toml: kube.kubeconfig`	merge 대상 kubeconfig
`CLUSTER_KUBECTX`	`profile.toml: argocd.cluster_context`	Argo CD에 등록할 target cluster context
`ARGOCD_CLUSTER_NAME`	`profile.toml: argocd.cluster_name`	Argo CD cluster 표시 이름
`NEXUS_VARS`	`profile.toml: nexus.vars`	Nexus 내부 상태 provisioning vars
`GITHUB_RUNNER_TARGET_NAME`	`profile.toml: github_runner.target_name`	GitHub runner target
`GITHUB_RUNNER_PREPARE_VARS`	`profile.toml: github_runner.prepare_vars`	runner host 준비 vars
`GITHUB_RUNNER_REGISTER_VARS`	`profile.toml: github_runner.register_vars`	runner GitHub 등록 vars

특정 영역만 password prompt 설정을 바꿔야 할 때는 K3S_ASK_PASS, RKE2_ASK_PASS, ARGOCD_ASK_PASS, HOST_ASK_PASS 같은 override 변수를 사용할 수 있습니다. GitHub runner target은 공통 ASK_PASS와 ASK_BECOME_PASS를 그대로 사용합니다.