# vmagent 배포 (Kubernetes 메트릭 수집)

kubelet·cadvisor·kube-state-metrics·node-exporter·파드 annotation을 스크레이핑하여 VictoriaMetrics Cluster로 전송한다.

## 1. 배포 방법

### 사전 준비 — relabel ConfigMap

`remoteWrite`의 `urlRelabelConfig`가 참조하는 ConfigMap을 먼저 생성한다. 네임스페이스 → accountID 분기 규칙을 담는다.

```sh
kubectl create configmap vmagent-relabel-configs -n monitoring \
  --from-file=demo01.yaml --from-file=demo02.yaml --from-file=platform.yaml
```

각 파일은 `write_relabel_configs` 규칙을 담는다. 해당 accountID에 **남길 시계열만 keep**(또는 특정 테넌트를 drop)하는 규칙이다. 예:

```yaml
# demo01.yaml — accountID 1: demo01-* namespace 메트릭만 남김
- action: keep
  source_labels: [namespace]
  regex: "demo01-.*"
# platform.yaml — accountID 9000: demo 테넌트 제외한 나머지
- action: drop
  source_labels: [namespace]
  regex: "(demo01|demo02)-.*"
```

> ⚠️ **빈 규칙(`[]`)은 격리가 아니다.** keep 규칙이 없으면 스크레이프한 모든 메트릭이 그 accountID에 기록된다 → 여러 URL에 `[]`를 두면 모든 테넌트가 서로의 메트릭을 보게 된다. 격리하려면 위처럼 namespace 기준 keep/drop 규칙을 반드시 채운다. 테넌트별 격리가 필요 없으면 fallback(accountID 0) remoteWrite 하나만 남겨도 된다.

```sh
helm upgrade vmagent ./ -f custom-values.yaml --install -n monitoring
```

## 2. custom-values.yaml 설정 설명

### 2.1 remoteWrite (accountID 매핑)

| accountID | 대상 | urlRelabelConfig |
|-----------|------|------------------|
| 1 | demo01 (namespace: demo01-*) | `/relabel/demo01.yaml` |
| 2 | demo02 (namespace: demo02-*) | `/relabel/demo02.yaml` |
| 9000 | platform (kafka-system, kubeflow 등) | `/relabel/platform.yaml` |
| 0 | fallback (미매칭) | 없음 |

> 쓰기 경로는 vmauth를 경유하지 않고 vminsert(`:8480`)에 직접 쓴다.
>
> **테넌트 라우팅 방식 결정 (per-URL)**: 차트는 `urlRelabelConfig`에 relabel 규칙을 **인라인**으로 줘도 자동으로 ConfigMap을 생성·마운트한다(기술적으로 인라인 가능). 그럼에도 **테넌트마다 별도 remoteWrite URL(`/insert/{accountID}/`) + 별도 relabel 파일**을 쓰는 이유는 **보안·격리** 때문이다: ① 테넌시를 URL이 강제하므로 데이터 라벨 스푸핑이 불가, ② 새 테넌트 추가가 Git/PR 변경(감사·승인)을 거침, ③ remoteWrite 큐가 테넌트별로 분리돼 장애·오설정의 cross-tenant 파급이 제한됨. (대안인 `/insert/multitenant/` + `vm_account_id` 라벨 매핑은 온보딩이 ConfigMap만으로 가능하나 테넌시가 relabel 규칙에 의존 → 격리가 약함. 트레이드오프는 아키텍처 문서 참조.)

### 2.2 scrape_configs

kubelet / cadvisor / kube-state-metrics / node-exporter / `kubernetes-pods`(annotation 기반) 5개 job을 포함한다. kube-state-metrics·node-exporter는 `monitoring` 네임스페이스의 엔드포인트를 keep 한다.

### 2.3 RBAC

`rbac.extraRules`로 nodes/proxy, nodes/metrics, `/metrics/cadvisor` 등 kubelet 스크레이프 권한을 부여한다.

## 3. 의존 관계

- **전송 대상**: vmcluster vminsert:8480
- **스크레이프 대상**: kube-state-metrics, prometheus-node-exporter (먼저 배포)

## 4. 검증

```sh
kubectl port-forward -n monitoring deploy/vmagent-victoria-metrics-agent 8429:8429
curl -s http://localhost:8429/targets | grep -c 'up'   # active target 확인
```