JUST WRITE

[Azure] AKS에 Grafana 모니터링 구축하기

천재보단범재 — Sun, 12 Apr 2026 18:00:42 +0900

Hubble 기반 네트워크 관측성

AKS에 Grafana 모니터링 구축하기

저번 포스팅에서 Terraform을 이용해서 Azure에 AKS를 구축하였습니다.

[Terraform] Azure AKS 클러스터 한번에 구축하기

Terrafrom으로 AKS 클러스터 구축TL;DRAzure VM에서 Terraform을 사용해 AKS 클러스터 + ACR을 한 번에 프로비저닝 하는 방법을 정리CNI는 eBPF 기반 Cilium, 디스크는 비용/성능 모두 유리한 Ephemeral 선택Terraform i

developnote-blog.tistory.com

구축하고 운영하다 보니 쉽게 AKS를 모니터링할 수 없을까 고민되었습니다.

특히 네트워크 관련 문제는 kubectl logs로는 찾기가 힘들었습니다.

AKS 내 서비스 간 연결 문제
특정 Pod에서 타임 아웃 에러 문제가 네트워크 문제일 때
NetworkPolicy를 적용했는데 의도치 않게 트래픽이 막힐 때

이번 포스팅에서 Cilium의 Hubble과 Grafana을 통해 네트워크 트래픽을 시각화하려고 합니다.

TL;DR

AKS에 ACNS를 활성화해 Hubble 기반 네트워크 관측성 확인
Azure Managed Grafana를 Terraform으로 프로비저닝
Grafana 대시보드에서 네트워크 대시보드(DNS, Packet loss, Pod flow 등) 확인

전체 아키텍처

[AKS Cluster]
  Cilium CNI + ACNS 활성화
       │
       │ eBPF로 모든 네트워크 패킷 추적
       ▼
[Hubble Relay]
  모든 노드의 네트워크 흐름을 수집/집계
       │
       │ Prometheus 메트릭 형식으로 노출
       ▼
[ama-metrics]
  메트릭을 스크래핑해서 Azure Monitor로 전송
       │
       │ 메트릭 저장
       ▼
[Azure Monitor Workspace]
  Prometheus 메트릭 저장소
       │
       │ 데이터 조회
       ▼
[Azure Managed Grafana]
  대시보드 시각화 (DNS, Drops, Pod Flows 등)

위와 같은 아키텍처로 구성합니다.

대신 그전에 아래와 같은 사전환경이 구성되어야 합니다.

Terraform으로 AKS가 구축된 상태
network_data_plane = "cilium"으로 Cilium CNI 사용 중
Azure CLI 및 kubectl 설치 완료

ACNS 활성화

AKS에 ACNS(Advanced Container Networking Services)를 활성화해야 합니다.

ACNS는 네트워크 관측성과 보안 기능을 묶은 번들입니다.

ACNS

ACNS를 활성화하면 AKS가 자동으로 Hubble Proxy Pod를 클러스터에 배포합니다.

Hubble

그럼 Hubble이 뭘까요?

Cilium 프로젝트에서 만든 오픈소스 네트워크 관측성 도구입니다.

Hubble은 eBPF를 통해서 네트워크 데이터를 수집합니다.

eBPF는 Linux 커널 안에서 코드를 실행하는 기술입니다.

덕분에 애플리케이션을 수정하지 않고도 커널에 지나가는 모든 패킷을 수집할 수 있습니다.

eBPF

kube-proxy는 유저공간과 커널을 오가며 iptables를 거쳐야 했습니다.

eBPF는 커널 안에서 바로 처리하므로 오버헤드 없이 바로 트래픽을 관찰할 수 있습니다.

ACNS를 활성화하면 AKS 각 노드 Cilium agent에서 Hubble이 동작합니다.

Hubble Relay에서 모든 노드의 Hubble 인스턴스에서 데이터를 수집해 하나로 집계합니다.

Node 1                Node 2                Node 3
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ Cilium Agent│      │ Cilium Agent│      │ Cilium Agent│
│  + Hubble   │      │  + Hubble   │      │  + Hubble   │
└─────────────┘      └─────────────┘      └─────────────┘
  │                         │                     │
  └─────────────────────────┴─────────────────────┘
                            │
                            ▼
                     [Hubble Relay]
                    클러스터 전체 트래픽을
                      한 곳에서 집계

Terraform으로 AKS를 구성한다는 가정하에

main.tf내 network_profile 블록에 advanced_networking을 추가합니다.

resource "azurerm_kubernetes_cluster" "aks" {
  # ... 기존 설정 ...

  network_profile {
    network_plugin      = "azure"
    network_plugin_mode = "overlay"
    network_data_plane  = "cilium"

    # ACNS 활성화 - Hubble 관측성 + 보안 기능
    advanced_networking {
      observability_enabled = true
      security_enabled      = true
    }
  }
}

옵션	설명
observability_enabled	Hubble 기반 네트워크 흐름 관측성 활성화
security_enabled	FQDN 필터링 등 L7 보안 정책 활성화

Resource Provider 등록

Terraform에서 Azure Monitor와 Grafana를 생성하기 위해서 사전작업이 필요합니다.

해당 서비스의 Provider가 등록되어야 합니다.

아래 Azure CLI 명령어로 등록할 수 있습니다.

az provider register --namespace Microsoft.Monitor
az provider register --namespace Microsoft.Dashboard

# 등록 확인 (Registered 상태까지 1~2분 소요)
az provider show --namespace Microsoft.Monitor --query registrationState
az provider show --namespace Microsoft.Dashboard --query registrationState

Azure Monitor, Grafana 생성

Terraform으로 Azure Monitor와 Grafana를 생성합니다.

단, AKS와 Azure Monitor 연동은 따로 Azure CLI로 설정합니다.

azurerm provider가 이 연동을 Terraform에서 직접 지원하지 않기 때문입니다.

main.tf에서 아래 리소스를 추가합니다.

# Azure Monitor Workspace (Prometheus 메트릭 저장소)
resource "azurerm_monitor_workspace" "monitor" {
  name                = var.monitor_name
  resource_group_name = azurerm_resource_group.rg.name
  location            = azurerm_resource_group.rg.location
}

# Azure Managed Grafana
resource "azurerm_dashboard_grafana" "grafana" {
  name                  = var.grafana_name
  resource_group_name   = azurerm_resource_group.rg.name
  location              = azurerm_resource_group.rg.location
  grafana_major_version = 11

  azure_monitor_workspace_integrations {
    resource_id = azurerm_monitor_workspace.monitor.id
  }
}

variables.tf에도 아래와 같이 추가합니다.

variable "monitor_name" {
  default = "myAKSMonitor"
}

variable "grafana_name" {
  description = "Grafana 인스턴스 이름 (전 세계 유니크)"
  type        = string
}

terraform.tfvars에도 아래와 같이 추가합니다.

monitor_name = "myAKSMonitor"
grafana_name = "myUniqueGrafanaName"   # 전 세계 유니크한 이름으로 변경

이후 terraform apply 명령어도 Azure Monitor와 Grafana를 생성합니다.

Azure Monitror Metrics Addon 활성화

Terraform으로 Azure Monitor와 AKS를 연동합니다.

이 단계에서 ama-metrics Pod들이 클러스터에 배포됩니다.

aks-preview가 설치되어 있다면 --enable-azure-monitor-metrics 옵션과 충돌해,

Unsupported or missing identit type 에러가 발생합니다.

명령어 실행 전에 aks-preview를 삭제해야 합니다.

# aks-preview 확장 제거
az extension remove --name aks-preview

# Monitor, Grafana 리소스 ID를 변수에 저장
MONITOR_ID=$(az resource show \
  --resource-group myRG \
  --name ${AKSMonitor이름} \
  --resource-type "Microsoft.Monitor/accounts" \
  --query id --output tsv)

GRAFANA_ID=$(az grafana show \
  --name ${Grafana이름} \
  --resource-group ${리소스그룹이름} \
  --query id --output tsv)

# AKS에 Azure Monitor Metrics Addon 활성화
az aks update \
  --name myAKS \
  --resource-group ${리소스그룹이름} \
  --enable-azure-monitor-metrics \
  --azure-monitor-workspace-resource-id $MONITOR_ID \
  --grafana-resource-id $GRAFANA_ID

완료되면 아래 Pod들이 자동 배포됩니다.

Pod	역할
ama-metrics	- 핵심 Metric 수집기 - Prometheus 형식으로 클러스터 Metric을 스크래핑해서 Azure Monitor로 전송
ama-metrics-ksm	- Kube state 수집기 - Deployment, Pod, Node 등 K8s 오브젝트 상태 메트릭 수집
ama-metrics-node	- 각 노드에 DaemonSet으로 배포. - 노드별 CPU, 메모리, 디스크, 네트워크 메트릭 수집
ama-metrics-operator-targets	- 수집 대상(scrape target)을 관리. - PodMonitor, ServiceMonitor CRD를 감시해서 수집 대상 목록 업데이트
ama-logs	- 메트릭이 아닌 로그 수집 담당. - Pod 로그, K8s 이벤트를 Log Analytics Workspace로 전송

$ kubectl get pods -n kube-system | grep ama-
ama-logs-748pz                                   3/3     Running     0               7m56s
ama-logs-8jf5z                                   3/3     Running     0               7m56s
ama-logs-gr5wf                                   3/3     Running     0               7m56s
ama-logs-rs-5798c7dbd9-qjrz5                     2/2     Running     0               7m56s
ama-metrics-b7bff497d-dx5z5                      2/2     Running     0               5m32s
ama-metrics-b7bff497d-z8bd5                      2/2     Running     0               5m32s
ama-metrics-ksm-5d4998cdcd-n4rsn                 1/1     Running     0               5m32s
ama-metrics-node-8tfvw                           2/2     Running     0               5m32s
ama-metrics-node-h6lqh                           2/2     Running     0               5m32s
ama-metrics-node-snkpt                           2/2     Running     0               5m32s
ama-metrics-operator-targets-55cb47c96c-4rd5q    2/2     Running     3 (3m47s ago)   5m32s

Hubble 메트릭 활성화

ama-metrics Pod가 떴다고 해서 Hubble 네트워크 메트릭이 바로 수집되진 않습니다.

Hubble 메트릭은 기본적으로 비활성화 상태거든요.

Hubble은 클러스터의 모든 네트워크 흐름을 추적하기 때문에 메트릭 양이 매우 많습니다.

대규모 클러스터에서는 Azure Monitor 비용이 커져서 필요한 경우에만 켜도록 설계되어 있습니다.

Azure에서 공식으로 제공하는 ama-metrics-settings-configmap.yaml 템플릿을 적용하면 활성화 가능합니다.

curl -o ama-metrics-settings.yaml https://raw.githubusercontent.com/Azure/prometheus-collector/main/otelcollector/configmaps/ama-metrics-settings-configmap.yaml

$ sed -i 's/networkobservabilityHubble = ""/networkobservabilityHubble = "hubble.*"/' ama-metrics-settings.yaml


$ grep networkobservabilityHubble ama-metrics-settings.yaml
    networkobservabilityHubble = true
    networkobservabilityHubble = "hubble.*"
    networkobservabilityHubble = "30s"

$ kubectl apply -f ama-metrics-settings.yaml -n kube-system
configmap/ama-metrics-settings-configmap created

$ kubectl rollout restart deployment ama-metrics -n kube-system
deployment.apps/ama-metrics restarted

$ kubectl rollout restart deployment ama-metrics-ksm -n kube-system
deployment.apps/ama-metrics-ksm restarted

networkobservabilityHubble = ""을 networkobservabilityHubble = "hubble.*"로 변경하면

hubble_로 시작하는 모든 메트릭이 수집됩니다.

Grafana 접근 권한 설정

Grafana 웹 화면에 접속하려면 두 가지 권한을 별도로 설정해야 합니다.

대상	목적
본인 Azure 계정	Grafana 웹 화면에 접속하기 위한 권한
Grafana 자체	Grafana가 Azure Monitor 데이터를 읽기 위한 권한

Grafana 웹 화면에 접속에 권한이 필요

첫 번째는 Azure 본인 계정에 Grafana Admin 권한을 부여해야 합니다.

아래 Azure CLI로 쉽게 권한을 부여할 수 있습니다.

$ az role assignment create \
  --assignee $(az ad signed-in-user show --query id --output tsv) \
  --role "Grafana Admin" \
  --scope $(az grafana show \
    --name myUniqueGrafanaName \
    --resource-group myRG \
    --query id --output tsv)

두 번째는 Grafana Managed Identity에 Monitor 권한을 부여해야 합니다.

Grafana에서 Azure Monitor 데이터를 읽으려면 Grafana 자체에 Managed Identity가 필요합니다.

Grafana가 Azure Monitor 데이터를 읽기 위한 권한이 필요

Azure Portal에서 Managed Identity 활성화해야 합니다.

아래 참고 사진처럼 Azure Portal에서 [Grafana 인스턴스] → [설정] → [ID] 페이지에 들어갑니다.

시스템 할당됨 탭에서 상태를 켬으로 저장합니다.

그리고 개체(주체) ID를 확인합니다.

위에서 확인한 개체(주체) ID를 가지고 아래 Azure CLI를 통해서 Azure Monitor 권한을 부여합니다.

GRAFANA_IDENTITY="<화면에서 확인한 Object ID>"

MONITOR_ID=$(az resource show \
  --resource-group myRG \
  --name myAKSMonitor \
  --resource-type "Microsoft.Monitor/accounts" \
  --query id --output tsv)

az role assignment create \
  --assignee $GRAFANA_IDENTITY \
  --role "Monitoring Data Reader" \
  --scope $MONITOR_ID

그리고 아래 명령어로 대시보드 엔드포인트를 확인할 수 있습니다.

# Grafana 엔드포인트 확인
az grafana show \
  --name myUniqueGrafanaName \
  --resource-group myRG \
  --query "properties.endpoint" \
  --output tsv

Grafana 접속 후 [Dashboards] → [Azure Managed Prometheus] 폴더에 관련 대시보드들이 있습니다.

아래와 같은 대시보드를 확인할 수 있습니다.

대시보드	역할	필요 상황
Networking/Clusters	노드 레벨 네트워크 메트릭을 클러스터 전체 관점에서 보여줌	갑자기 클러스터 전체 응답이 느려졌는데 어느 노드가 문제인지 모를 때, 또는 특정 노드에 트래픽이 집중되는 것 같을 때
Networking/DNS(Cluster)	클러스터 전체 DNS 쿼리 수, 실패율, 응답 시간	서비스 간 연결이 간헐적으로 실패하거나 응답이 느릴 때. 애플리케이션 레벨 문제인지 DNS 레벨 문제인지 먼저 구분하고 싶을 때
Networking/DNS(Workload)	워크로드(Deployments, Daemonsets)별 DNS 메트릭	DNS 문제가 특정 서비스에서만 발생하는 것 같을 때. 어떤 워크로드가 DNS 쿼리를 과도하게 발생시키는지, 또는 특정 서비스가 DNS 응답을 못 받고 있는지 파악하고 싶을 때
Networking/Drops(Workload)	워크로드별 패킷 드롭, 인바운드/아웃바운드 드롭	서비스 간 통신이 불안정하거나 타임아웃이 자주 발생할 때. NetworkPolicy를 새로 적용했는데 의도치 않게 트래픽을 차단하고 있는 건 아닌지 확인하고 싶을 때
Networking/Pod Flows(Namespace)	Namespace별 L4, L7 트래픽 흐름	네임스페이스 간 트래픽 격리가 제대로 되고 있는지 확인하고 싶을 때. 특정 네임스페이스에서 예상치 못한 외부 통신이 발생하는지 파악하고 싶을 때
Networking/Pod Flows(Workload)	특정 Pod/Deployments 인바운드/아웃바운드 트래픽 흐름	신규 서비스를 배포한 후 트래픽이 예상대로 흐르는지 검증하고 싶을 때. 특정 Pod가 어디와 통신하고 있는지 추적하고 싶을 때

정리

AKS 클러스터의 네트워크 트래픽을 Grafana 대시보드에서 모니터링할 수 있도록 세팅하였습니다.

Hubble이 eBPF로 수집한 데이터가 Azure Monitor를 거쳐 Grafana까지의 파이프라인을 구성해 보았습니다.

특히, 패킷 드롭 대시보드는 NetworkPolicy 이슈를 디버깅할 때,

Pod Flows 대시보드는 신규 서비스 배포 후 트래픽 흐름을 검증할 때 실무에서 바로 유용하게 쓸 수 있습니다.

다음에는 AKS가 아닌 직접 구축한 k8s 클러스터에 Hubble 모니터링 체계를 구축해 보겠습니다.

[참고자료]

Advanced Container Networking Services for Azure Kubernetes Service (AKS) Overview - Azure Kubernetes Service

Learn about Advanced Container Networking Services for Azure Kubernetes Service (AKS), including features like Container Network Observability and Container Network Security.

learn.microsoft.com

GitHub - cilium/hubble: Hubble - Network, Service & Security Observability for Kubernetes using eBPF

Hubble - Network, Service & Security Observability for Kubernetes using eBPF - cilium/hubble

github.com

Customize scraping of Prometheus metrics in Azure Monitor using ConfigMap - Azure Monitor

Customize metrics scraping for a Kubernetes cluster with the metrics add-on in Azure Monitor.

learn.microsoft.com

GitHub - Azure/prometheus-collector

Contribute to Azure/prometheus-collector development by creating an account on GitHub.

github.com

[Terraform] Azure AKS 클러스터 한번에 구축하기

천재보단범재 — Sun, 22 Mar 2026 17:28:35 +0900

Terraform을 통한 IaC 구성

Terrafrom으로 AKS 클러스터 구축

TL;DR

Azure VM에서 Terraform을 사용해 AKS 클러스터 + ACR을 한 번에 프로비저닝 하는 방법을 정리
CNI는 eBPF 기반 Cilium, 디스크는 비용/성능 모두 유리한 Ephemeral 선택
Terraform init -> plan -> apply 세 단계로 한 번에 AKS 클러스터 구축

회사에서 Azure를 경험할 수 있는 업무가 생겨서 AKS를 구축하기로 하였습니다.

이전에 Terraform으로 EKS도 쉽게 구축한 경험이 있어서,

이번에도 Terraform을 이용해 AKS를 한 번에 구축하기로 하였습니다.

[Terraform] AWS EKS 한 번에 올리기(1) - VPC 구성

AWS EKS 한 번에 올리기(1)이전에 Terraform을 통해서 Kubernetes 클러스터를 한 번에 구성한 적이 있습니다.AWS EC2 인스턴스를 여러 개 생성해서 클러스터를 구성하였습니다. 명령어 한 번에 Kubernetes 설

developnote-blog.tistory.com

AKS를 Terraform으로 구축하는 이유는 크게 세 가지입니다.

재현 가능성 -> 코드로 작성하면 동일한 환경을 언제든지 만들 수 있습니다.
변경 이력 관리 -> 인프라 변경사항을 Git으로 관리할 수 있습니다.
멀티 클라우드 지원 -> Azure뿐만 아니라 AWS, GCP 등 대부분의 클라우드를 동일한 문법으로 지원합니다.

전체 아키텍처

아래와 같이 Terraform으로 Azure내 AKS와 ACR를 구축하기로 하였습니다.

├── Resource Group (myRG)
│     ├── ACR ──────────────────────────┐
│     │   (프라이빗 컨테이너 레지스트리)    │
│     │                                  │ AcrPull 권한
│     └── AKS Cluster                   │
│           ├── Control Plane ◀── Azure 관리
│           └── Worker Node × 3 ────────┘
│                 ├── Node 1 (Standard_D8s_v3)
│                 ├── Node 2 (Standard_D8s_v3)
│                 └── Node 3 (Standard_D8s_v3)
│                       └── Cilium CNI (eBPF)
│
└── Terraform State (.tfstate, 로컬 저장)

ACR(Azure Container Registry)

ACR은 Azure에서 제공하는 Private 컨테이너 이미지 레지스트리입니다.

Docker Hub와 동일한 역할을 하지만 외부에 공개되지 않는 Private 저장소입니다.

AKS Pod 생성 시 ACR에서 이미지를 pull 해서 컨테이너를 생성하려고 합니다.

사내 서비스 이미지를 외부에 공개하지 않고 Azure 내부 네트워크에서만 접근할 수 있습니다.

ACR과 AKS와 같은 리전에 있으면 Azure 내부 네트워크를 통해 이루어져 훨씬 빠릅니다.

AKS(Azure Kubernetes Service)

AKS는 Azure에서 제공하는 관리형 Kubernetes 서비스입니다.

Kubernetes의 Control Plane을 Azure가 직접 관리해 줍니다.

AKS의 구조는 크게 두 계층으로 나눠집니다.

Control Plane
- API 서버, 스케줄러, etcd(상태 저장소), Controller Manager로 구성
- Azure가 전담 관리
Worker Node
- 실제 Pod이 생성되는 VM
- 이번 구성에서는 Standard_D8s_v3 VM 3대로 구성

기본 세팅

Azure에서 Koreacentral 리전에 Terraform을 실행할 VM을 생성하였습니다.

가장 기본적인 스펙으로 Ubuntu 기반 VM을 생성하였습니다.

Terraform으로 AKS 구축하기에 앞서 필요한 도구들을 VM에 설치합니다.

Azure CLI
Terraform
kubectl

# 1. 패키지 업데이트
sudo apt update && sudo apt upgrade -y

# 2. Azure CLI 설치
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# 3. Terraform 설치
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform -y

# 4. kubectl 설치
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

$ az version
{
  "azure-cli": "2.84.0",
  "azure-cli-core": "2.84.0",
  "azure-cli-telemetry": "1.1.0",
  "extensions": {}
}

$ terraform version
Terraform v1.14.7
on linux_amd64

$ kubectl version --client
Client Version: v1.35.3
Kustomize Version: v5.7.1

위의 명령어들을 통해 필요한 도구 설치가 끝났습니다.

Azure 로그인

이제 Terraform을 통해 AKS 설치할 Azure 계정에 로그인합니다. Azure CLI를 통해 로그인합니다.

--user-device-code 옵션을 주면 URL과 인증코드를 알려줍니다.

https://login.microsoft.com/device로 들어가서 인증 코드 입력 후 Azure 로그인을 하면 됩니다.

그럼 아래와 같이 로그인되고 계정 정보를 확인할 수 있습니다.

$ az login --use-device-code
To sign in, use a web browser to open the page https://login.microsoft.com/device and enter the code ****** to authenticate.

# 웹브라우저에서 코드 입력 후 로그인 확인
Retrieving tenants and subscriptions for the selection...

[Tenant and subscription selection]

No     Subscription name    Subscription ID                       Tenant
-----  -------------------  ------------------------------------  ------------
[1] *  ******               ********-****-****-****-************  ******

The default is marked with an *; the default tenant is '******' and subscription is '******' (********-****-****-****-************).

Select a subscription and tenant (Type a number or Enter for no changes):

Tenant: ******
Subscription: ****** (********-****-****-****-************)

[Announcements]
With the new Azure CLI login experience, you can select the subscription you want to use more easily. Learn more about it and its configuration at https://go.microsoft.com/fwlink/?linkid=2271236

If you encounter any problem, please open an issue at https://aka.ms/azclibug

[Warning] The login output has been updated. Please be aware that it no longer displays the full list of available subscriptions by default.

그리고 Resource Provider을 등록합니다.

Azure에서 제공하는 서비스는 Resource Provider라는 단위로 관리됩니다.

Azure 구독에서 특정 서비스를 처음 사용하려면 해당 Resource Provider가 구독에 등록돼야 합니다.

# 필요한 Provider만 직접 등록
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.ContainerRegistry
az provider register --namespace Microsoft.Compute
az provider register --namespace Microsoft.Network

# 등록 확인 (Registered 상태인지 확인)
az provider show --namespace Microsoft.ContainerService --query registrationState
az provider show --namespace Microsoft.ContainerRegistry --query registrationState

Terraform은 기본적으로 terraform apply 실행 시 필요한 Resource Provider를 자동으로 등록합니다.

그러나 자동 등록 과정이 완료될 때까지 대기하면서 지연되는 현상이 발견되었습니다.

필요한 Provider를 직접 수동으로 등록하고 main.tf에 Provider 자동 등록을 비활성하였습니다.

resource_provider_registration = "none"

Terraform 파일 작성

총 4가지를 파일을 작성하며, 같은 path에 위치시킵니다.

파일	역할
main.tf	- 실제 Azure 리소스를 정의하는 핵심 파일 - 어떤 리소스를 만들지 선언
variables.tf	- main.tf에서 사용할 변수를 선언하는 파일 - 파일, 변수명, 타입, 기본값, 설명을 정의
terraform.tfvars	- variables.tf에서 선언한 변수의 실제 값을 지정하는 파일 - 환경마다 다르게 관리할때 유용
ouputs.tf	- terraform apply 완료 후 터미널에 출력할 값 정의 - ACR 주소 등

main.tf

main.tf는 실제로 생성할 Azure 리소스를 선언하는 핵심 파일입니다.

주요 항목은 아래와 같습니다.

terraform 블록
- Terraform 자체 설정
- 사용할 Terraform 최소 버전과 Azure Provider 버전 고정
provider "azurerm" 블록
- Azure 인증하고 연결하는 설정
- resource_provider-registration = "non"으로 Resource Provider 자동 등록 비활성화
azurerm_resource_group
- Azure 모든 리소스는 Resource Group에 속해야 하는데 AKS, ACR이 해당 Resource Group에 속함
azurerm_container_registry
- Private 이미지 저장소인 ACR 설정
- sku = "Standard"는 운영 환경에 적합한 100GB 스토리지 제공
azurerm_kubernetes_cluster
- 주요 항목인 AKS 설정

항목	설명
default_node_pool	- Worker 노드 구성 - vm_size -> 노드 스펙 - node_count -> 노드 수
os_disk_type = "Ephemeral"	- VM 로컬 SSD를 디스크로 사용 - Managed 디스크보다 빠름
network_plugin = "azure"	- Cilium 사용을 위한 CNI 기반 설정
network_plugin_mode = "overlay"	- Pod IP를 VNetIP와 분리 - IP 고갈 문제를 방지
network_data_plane = "cilium"	- eBPF 기반 고성능 네트워킹 - kube-proxy 없이 동작해 Latency 감소
identity = "SystemAssigned"	- Managed Identity tkdyd - Azure 리소스 접근 시 별도 Secret 없이 인증 가능

azurerm_role_assignment
- AKS가 ACR에서 이미지 pull할 수 있도록 권한 부여

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
  resource_provider_registrations = "none"
}

resource "azurerm_resource_group" "rg" {
  name     = var.resource_group_name
  location = var.location
}

resource "azurerm_container_registry" "acr" {
  name                = var.acr_name
  resource_group_name = azurerm_resource_group.rg.name
  location            = azurerm_resource_group.rg.location
  sku                 = "Standard"
}

resource "azurerm_kubernetes_cluster" "aks" {
  name                = var.aks_name
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  dns_prefix          = var.aks_name

  default_node_pool {
    name            = "default"
    node_count      = var.aks_node_count
    vm_size         = var.aks_node_vm_size
    os_disk_size_gb = 128
    os_disk_type    = "Ephemeral"
  }

  network_profile {
    network_plugin      = "azure"
    network_plugin_mode = "overlay"
    network_data_plane  = "cilium"
  }

  identity {
    type = "SystemAssigned"
  }

  automatic_upgrade_channel = "patch"
  node_os_upgrade_channel   = "NodeImage"
  sku_tier                  = "Standard"
}

resource "azurerm_role_assignment" "aks_acr_pull" {
  principal_id                     = azurerm_kubernetes_cluster.aks.kubelet_identity[0].object_id
  role_definition_name             = "AcrPull"
  scope                            = azurerm_container_registry.acr.id
  skip_service_principal_aad_check = true
}

AKS에서 사용할 수 있는 CNI는 kubenet, Azure CNI, Cillium 등 여러 가지가 있습니다.

이번에 Cilium을 선택한 이유는 아래와 같습니다.

eBPF(extended Berkeley Packet Filter) 기반 고성능 네트워킹
- 보통 kube-proxy를 통해 iptables 규칙을 거치지만 Cilium은 eBPF를 사용해 커널 레벨에서 직접 패킷을 처리해 Latency가 감소합니다.
강력한 Network Policy
- 기본은 L3/L4 레벨만 제어하지만 Cilium은 HTTP, gRPC 같은 L7 레벨까지 트래픽 제어가 가능합니다.
Hubble을 통한 관측성
- Cilium에 내장된 Hubble을 활성화하면 서비스 간 트래픽 흐름 실시간 시각화가 가능합니다.

AKS 노드의 디스크는 Managed와 Ephemeral 두 가지 방식이 있습니다.

이번에는 속도가 빠른 Ephemeral 디스크를 사용하였습니다.

두 디스크의 차이점은 아래와 같습니다.

항목	Managed	Ephemeral
저장 위치	Azure Storage	VM 로컬 SSD
I/O 속도	보통	빠름
추가 비용	있음	없음(VM 비용에 포함0
노드 삭제 시	디스크 유지	디스크 함께 삭제

variables.tf

variable "resource_group_name" {
  default = "****"
}

variable "location" {
  default = "koreacentral"
}

variable "acr_name" {
  description = "ACR 이름 (전 세계 유니크)"
  type        = string
}

variable "aks_name" {
  default = "****"
}

variable "aks_node_count" {
  default = 3
}

variable "aks_node_vm_size" {
  default = "Standard_D8s_v3"
}

outputs.tf

output "acr_login_server" {
  value = azurerm_container_registry.acr.login_server
}

output "kube_config_command" {
  value = "az aks get-credentials --resource-group ${var.resource_group_name} --name ${var.aks_name}"
}

terraform.tfvars

resource_group_name = "****"
location            = "koreacentral"
acr_name            = "*****"
aks_name            = "*****"
aks_node_count      = 3
aks_node_vm_size    = "Standard_D8s_v3"

Terraform 실행

이제 준비가 완료되었습니다.

Terraform은 인프라를 적용하기까지 아래 3단계 명령어를 순서대로 실행합니다.

명령어	역할
terraform init	Provider 플로그인 다운로드 및 초기화
terraform plan	현재 상태와 코드를 비교해 변경사항 미리보기, 실제 인프라 영향 없음
terraform apply	plan 결과를 실제 Azure에 적용

terraform init

$ terraform init
Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/azurerm versions matching "~> ****"...
- Installing hashicorp/azurerm v****...
- Installed hashicorp/azurerm v**** (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

terraform plan

$ terraform plan

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  + create

Terraform will perform the following actions:

  # azurerm_container_registry.acr will be created
  + resource "azurerm_container_registry" "acr" {
      + admin_enabled                 = false
      + admin_password                = (sensitive value)
      + admin_username                = (known after apply)
      + data_endpoint_host_names      = (known after apply)
      + encryption                    = (known after apply)
...
...
...
Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform
apply" now.

terraform apply

Do you want to perform these actions? 메시지가 나오면 yes를 입력하면 됩니다.

$ terraform apply

Do you want to perform these actions?


Outputs:
acr_login_server    = "xxxxxx.azurecr.io"
kube_config_command = "az aks get-credentials --resource-group myRG --name *****"

kubectl 설정 및 자동 완성

이제 AKS에 kubectl로 접근할 수 있도록 설정합니다.

# kubeconfig 설정
az aks get-credentials --resource-group myRG --name myAKS

# kubectl 자동완성 설정
kubectl completion bash | sudo tee /etc/bash_completion.d/kubectl > /dev/null
sudo apt install bash-completion -y

# alias 설정
echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc

# 적용
exec bash

설정 후 kubectl 명령어로 AKS 클러스터를 확인합니다.

$ k get no
NAME                              STATUS   ROLES    AGE     VERSION
aks-default-41983717-vmss000000   Ready    <none>   8m1s    v1.33.7
aks-default-41983717-vmss000001   Ready    <none>   7m49s   v1.33.7
aks-default-41983717-vmss000002   Ready    <none>   7m56s   v1.33.7

정리

Terraform으로 활용해서 ACR과 AKS를 구축하였습니다.

코드 한번만 잘 설정하면 손쉽게 AKS를 구축할 수 있어 인프라 관리에 꼭 필요하다는 생각이 들었습니다.

다음 포스팅에서는 구축한 AKS를 살펴보고 ACR에 있는 이미지를 pull 받는 것을 정리하겠습니다.

[참고자료]

Azure의 Terraform 설명서 - 문서, 샘플, 참조 및 리소스 - Terraform

Terraform을 사용하여 Azure에서 가상 머신 및 기타 인프라를 안정적으로 프로비전하는 방법을 알아봅니다.

learn.microsoft.com

Terraform Registry

registry.terraform.io

[Talos] 도커 하나면 쿠버네티스 설치가 가능하다고?!

천재보단범재 — Sun, 1 Feb 2026 18:05:52 +0900

Talos로 Kubernetes 설치

회사에서 솔루션을 개발하게 되었습니다.

개발하기 앞서 필요한 여러 가지 서비스를 설치해야 했습니다.

MySQL, Clickhouse, Minio와 같은 스토리지와 외부 서비스를 구축해야 하였습니다.

처음에는 docker-compose로 관리했지만 서비스가 많아지면서 관리가 너무 힘들었습니다.

Kubernetes를 도입하고 싶었지만 클라우드 k8s 도입 비용이 없었고 GPU 서버 1대만 있는 상황이었습니다.

그러던 중 Talos Linux를 발견했습니다.

What is Talos?

Talos는 Kubernetes 전용으로 설계된 Container 전용 OS입니다.

세가지 특징이 있습니다.

Container 전용 OS - SSH도 없고 shell도 없습니다. 다만 talosctl를 통해 관리할 수 있습니다.
서버에 직접 파일 수정이 힘듭니다.
Docker Container로 Talos를 실행할 수 있습니다.

GPU 서버가 1대밖에 없는 상황에서 Kubernetes 설치가 불가능해 보였지만

Talos를 통해 Container 형태로 Kubernetes 클러스터를 구축하였습니다.

talosctl를 통한 설치

Talos에서는 talosctl이라는 CLI Client를 제공합니다.

직접 Talos Container를 건드는 것보다는 talosctl를 통해 관리하는 것이 좋습니다.

설치 역시 talosctl로 설치가 가능합니다.

talosctl cluster create \
  --name dev \
  --config-patch @patch.yaml \
  --workers=3 \
  --kubernetes-version=v1.34.2 \
  --exposed-ports 30080:30080/tcp \
  --skip-k8s-node-readiness-check

위와 같은 명령어로 Talos를 통해 Kubernetes 클러스터 설치가 가능합니다.

각 플래그의 의미는 아래 표로 정리하였습니다.

Flag	설명
--name dev	Kubernetes 클러스터 명칭
--config-patch @patch.yaml	추가 설정 파일 적용
--workers=3	Worker 노드 갯수
--kubernetes-version=v1.34.2	Kubernetes 버전
--exposed-ports 30080:30080/tcp	Host에서 k8s 접근 포트 노출
--skip-k8s-node-readiness-check	CNI 설치 전까지 NotReady가 정상이므로 대기 skip

위에 보면 추가 설정 파일을 적용하고 readiness-check를 skip 하였습니다.

따로 설정을 한 이유는 해당 설정 없이 설치할 경우 CoreDNS가 Pending 상태가 되었습니다.

alidating CIDR and reserving IPs
generating PKI and tokens
creating state directory in "/home/***/.talos/clusters/llmops-dev"
creating network dev
creating controlplane nodes
creating worker nodes
waiting for API
bootstrapping cluster
waiting for etcd to be healthy: OK
waiting for etcd members to be consistent across nodes: OK
waiting for etcd members to be control plane nodes: OK
waiting for apid to be ready: OK
waiting for all nodes memory sizes: OK
waiting for all nodes disk sizes: OK
waiting for no diagnostics: OK
waiting for kubelet to be healthy: OK
waiting for all nodes to finish boot sequence: OK
waiting for all k8s nodes to report: OK
waiting for all control plane static pods to be running: OK
waiting for all control plane components to be ready: OK

merging kubeconfig into "/home/***/kube/config"
renamed cluster "dev" -> "dev-1"
renamed auth info "admin@dev" -> "admin@dev-1"
renamed context "admin@dev" -> "admin@dev-1"
PROVISIONER           docker
NAME                  dev
NETWORK NAME          dev
NETWORK CIDR          10.5.0.0/24
NETWORK GATEWAY       10.5.0.1
NETWORK MTU           1500
KUBERNETES ENDPOINT   https://127.0.0.1:35531

NODES:

NAME                  TYPE           IP         CPU    RAM      DISK
/dev-controlplane-1   controlplane   10.5.0.2   2.00   2.1 GB   -
/dev-worker-1         worker         10.5.0.3   2.00   2.1 GB   -
/dev-worker-2         worker         10.5.0.4   2.00   2.1 GB   -
/dev-worker-3         worker         10.5.0.5   2.00   2.1 GB   -


$ kubectl get nodes
NAME                 STATUS     ROLES           AGE     VERSION
dev-controlplane-1   NotReady   control-plane   7m57s   v1.34.2
dev-worker-1         NotReady   <none>          7m57s   v1.34.2
dev-worker-2         NotReady   <none>          7m56s   v1.34.2
dev-worker-3         NotReady   <none>          7m56s   v1.34.2

$ kubectl get all -n kube-system
NAME                                                    READY   STATUS    RESTARTS        AGE
pod/coredns-6bb5667469-zmqmz                            0/1     Pending   0               7m26s
pod/coredns-6bb5667469-zrqjb                            0/1     Pending   0               7m26s
pod/kube-apiserver-llmops-dev-controlplane-1            1/1     Running   0               7m8s
pod/kube-controller-manager-llmops-dev-controlplane-1   1/1     Running   3 (7m56s ago)   7m8s
pod/kube-scheduler-llmops-dev-controlplane-1            1/1     Running   4 (7m42s ago)   7m8s

NAME               TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)                  AGE
service/kube-dns   ClusterIP   10.96.0.10   <none>        53/UDP,53/TCP,9153/TCP   7m33s

NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/coredns   0/2     2            0           7m33s

NAME                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/coredns-6bb5667469   2         2         0       7m26

이유는 기본 설정에서 CNI 제대로 설치가 되지 않았기 때문입니다.

해당 이슈는 아래 Github 이슈에서도 확인할 수 있습니다.

[1.8.0] coredns does not start with talosctl cluster create · Issue #9419 · siderolabs/talos

Bug Report Description When creating a cluster with talosctl and docker, coredns does not start talosctl cluster create View logs talosctl cluster create validating CIDR and reserving IPs generatin...

github.com

별도로 CNI를 세팅하였습니다.

Cilium 설치

CNI는 Kubernetes내 Pod에 네트워크 인터페이스를 부여하는 것입니다.

Cilium을 helm으로 설치하였습니다.

helm repo add cilium https://helm.cilium.io/
helm pull cilium/cilium
tar zxvf cilium-1.18.4.tgz

values-overrides.yaml을 따로 작성해서 만들었습니다.

공식 talos 문서에도 Cilium CNI 설치에 관한 안내가 있습니다.

해당 문서를 참고해서 설치하였습니다.

Deploy Cilium CNI - Sidero Documentation

In this guide you will learn how to set up Cilium CNI on Talos.

docs.siderolabs.com

ipam:
  mode: "kubernetes"

kubeProxyReplacement: "true"

securityContext:
    capabilities:
      ciliumAgent: ["CHOWN","KILL","NET_ADMIN","NET_RAW","IPC_LOCK","SYS_ADMIN","SYS_RESOURCE","DAC_OVERRIDE","FOWNER","SETGID","SETUID"]
      cleanCiliumState: ["NET_ADMIN","SYS_ADMIN","SYS_RESOURCE"]

cgroup:
  autoMount:
    enabled: false
  hostRoot: /sys/fs/cgroup

k8sServiceHost: "localhost"
k8sServicePort: 7445

이제 helm install를 통해 Cilium을 설치합니다.

$ helm install cilium -n kube-system -f values-override.yaml .
NAME: cilium
LAST DEPLOYED: Tue Nov 25 10:40:20 2025
NAMESPACE: kube-system
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
You have successfully installed Cilium with Hubble.

Your release version is 1.18.4.

For any further help, visit https://docs.cilium.io/en/v1.18/gettinghelp


$ kubectl get nodes
NAME                 STATUS   ROLES           AGE   VERSION
dev-controlplane-1   Ready    control-plane   12m   v1.34.2
dev-worker-1         Ready    <none>          12m   v1.34.2
dev-worker-2         Ready    <none>          12m   v1.34.2
dev-worker-3         Ready    <none>          12m   v1.34.2

Cilium 설치 후 각 Kubernetes 각 Node가 정상적인 상태인 것을 확인할 수 있습니다.

그리고 CoreDNS도 Pending이 아닌 Running 상태인 것을 확인할 수 있습니다.

$ kubetctl get all -n kube-system
NAME                                                    READY   STATUS    RESTARTS      AGE
pod/cilium-25cfl                                        1/1     Running   0             82s
pod/cilium-2ktjs                                        1/1     Running   0             82s
pod/cilium-dvjlr                                        1/1     Running   0             82s
pod/cilium-envoy-6wmh5                                  1/1     Running   0             82s
pod/cilium-envoy-lg6lq                                  1/1     Running   0             82s
pod/cilium-envoy-p7gcz                                  1/1     Running   0             82s
pod/cilium-envoy-t6h9t                                  1/1     Running   0             82s
pod/cilium-operator-6b565f556c-5xdrr                    1/1     Running   0             82s
pod/cilium-operator-6b565f556c-7fkcz                    1/1     Running   0             82s
pod/cilium-xtxzw                                        1/1     Running   0             82s
pod/coredns-6bb5667469-zmqmz                            1/1     Running   0             12m
pod/coredns-6bb5667469-zrqjb                            1/1     Running   0             12m
pod/kube-apiserver-llmops-dev-controlplane-1            1/1     Running   0             11m
pod/kube-controller-manager-llmops-dev-controlplane-1   1/1     Running   3 (12m ago)   11m
pod/kube-scheduler-llmops-dev-controlplane-1            1/1     Running   4 (12m ago)   11m

NAME                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                  AGE
service/cilium-envoy   ClusterIP   None             <none>        9964/TCP                 82s
service/hubble-peer    ClusterIP   10.105.165.190   <none>        443/TCP                  82s
service/kube-dns       ClusterIP   10.96.0.10       <none>        53/UDP,53/TCP,9153/TCP   12m

NAME                          DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
daemonset.apps/cilium         4         4         4       4            4           kubernetes.io/os=linux   82s
daemonset.apps/cilium-envoy   4         4         4       4            4           kubernetes.io/os=linux   82s

NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/cilium-operator   2/2     2            2           82s
deployment.apps/coredns           2/2     2            2           12m

NAME                                         DESIRED   CURRENT   READY   AGE
replicaset.apps/cilium-operator-6b565f556c   2         2         2       82s
replicaset.apps/coredns-6bb5667469           2         2         2       12m

kubeconfig 설정

위에서 보면 kubectl로 Talos로 설치한 Kuberenetes에 접근이 가능합니다.

kubectl 사용을 위해 kubeconfig를 가져와야 합니다.

talosctl 명령어로 가져올 수 있습니다.

# kubeconfig 파일을 현재 디렉토리로 추출
$ talosctl kubeconfig --nodes 127.0.0.1 dev

# 추출된 파일 확인
$ ls -la
-rw------- 1 user user 2281 11월 25 10:31 dev

# 내용 확인 (실제로는 certificate-authority-data 등 민감정보 포함)
$ cat llmops-dev
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: ***
    server: https://127.0.0.1:35531
  name: dev
...

기본적으로 talosctl cluster create 실행 시 ~/. kubeconfig/config에 자동으로 merge 됩니다.

context 이름은 자동으로 admin@{cluster_name}으로 생성됩니다.

Storageclass 설치

이제 Talos로 Kubernetes 설치를 완료하였습니다.

Talos는 기본적으로 Storageclass를 제공하지 않으므로 직접 설치해야 합니다.

이번 포스팅에서는 rancher의 local-strorage-provisioner로 설치하였습니다.

$ wget https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.32/deploy/local-path-storage.yaml

# version -> v0.0.32 (25/11/25 기준)
apiVersion: v1
kind: Namespace
metadata:
  name: local-path-storage
  labels:
    pod-security.kubernetes.io/enforce: privileged #추가
    pod-security.kubernetes.io/audit: privileged # 추가
    pod-security.kubernetes.io/warn: privileged # 추가
...
...
...
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-path
  annotations:
    storageclass.kubernetes.io/is-default-class: "true" # 추가
provisioner: rancher.io/local-path
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete
...
...
...
kind: ConfigMap
apiVersion: v1
metadata:
  name: local-path-config
  namespace: local-path-storage
data:
  config.json: |-
    {
            "nodePathMap":[
            {
                    "node":"DEFAULT_PATH_FOR_NON_LISTED_NODES",
                    "paths":["/var/lib/local-path-provisioner"] # 수정
            }
            ]
    }
  setup: |-
    #!/bin/sh
    set -eu
    mkdir -m 0777 -p "$VOL_DIR"
  teardown: |-
    #!/bin/sh
    set -eu
    rm -rf "$VOL_DIR"
  helperPod.yaml: |-
    apiVersion: v1
    kind: Pod
    metadata:
      name: helper-pod
    spec:
      priorityClassName: system-node-critical
      tolerations:
        - key: node.kubernetes.io/disk-pressure
          operator: Exists
          effect: NoSchedule
      containers:
      - name: helper-pod
        image: busybox
        imagePullPolicy: IfNotPresent


$ kubectl apply -f local-path-storage.yaml
namespace/local-path-storage created
serviceaccount/local-path-provisioner-service-account created
role.rbac.authorization.k8s.io/local-path-provisioner-role created
clusterrole.rbac.authorization.k8s.io/local-path-provisioner-role created
rolebinding.rbac.authorization.k8s.io/local-path-provisioner-bind created
clusterrolebinding.rbac.authorization.k8s.io/local-path-provisioner-bind created
deployment.apps/local-path-provisioner created
storageclass.storage.k8s.io/local-path created
configmap/local-path-config created


$ kubectl get stroageclass
NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  48s

설치는 간단합니다.

버전을 참고해서 local-path-provisioner의 yaml 파일을 다운로드하여 설치하면 됩니다.

근데 Namespace에 Pod-security labels을 추가해줘야 합니다.

Label	역할
pod-security.kubernetes.io/enforce: privileged	이 수준을 벗어나는 Pod은 생성 자체가 거부됨.
pod-security.kubernetes.io/audit: privileged	위반 시 감사 로그에 기록됨
pod-security.kubernetes.io/warn: privileged	위반시 경고메시지를 표시함

local-path-provisioner는 내부적으로 호스트 파일 시스템에 직접 접근해서 볼륨을 생성합니다.

이를 위해 hostPath 볼륨과 특권 권한이 필요하는데, 기본 보안 정책 하에서는 이것이 막힙니다.

세 가지 label을 모두 privileged로 설정하면, 해당 Namespace에서 특권 Pod을 자유롭게 실행할 수 있습니다.

Talos 공식문서에서도 local-path-provisioner 설치 내용을 확인할 수 있습니다.

Local Storage - Sidero Documentation

Using local storage for Kubernetes workloads.

docs.siderolabs.com

정리

Talos로 docker container형태로 Kubernetes를 설치하였습니다.

docker ps 명령어를 통해 Kubernetes Node가 Container형태로 구성된 것을 확인할 수 있습니다.

$ docker ps
CONTAINER ID   IMAGE                                  COMMAND   CREATED        STATUS         NAMES
a1b2c3d4e5f6   ghcr.io/siderolabs/talos:v1.7.6       "/init"   2 min ago      Up 2 min       dev-controlplane-1
b2c3d4e5f6a7   ghcr.io/siderolabs/talos:v1.7.6       "/init"   2 min ago      Up 2 min       dev-worker-1
c3d4e5f6a7b8   ghcr.io/siderolabs/talos:v1.7.6       "/init"   2 min ago      Up 2 min       dev-worker-2
d4e5f6a7b8c9   ghcr.io/siderolabs/talos:v1.7.6       "/init"   2 min ago      Up 2 min       dev-worker-3

서비스가 너무 많고 서버가 1대라면 docker-compse 말고 Talos를 고려해 보면 좋을 거 같습니다.

Talos 덕분에 솔루션 개발을 위한 서비스 관리나 배포가 쉬울 거 같습니다.

[참고자료]

What is Talos Linux? - Sidero Documentation

Talos Linux is the best OS for Kubernetes.

docs.siderolabs.com

GitHub - siderolabs/talos: Talos Linux is a modern Linux distribution built for Kubernetes.

Talos Linux is a modern Linux distribution built for Kubernetes. - siderolabs/talos

github.com

https://docs.cilium.io/en/stable/

GitHub - rancher/local-path-provisioner: Dynamically provisioning persistent local storage with Kubernetes

Dynamically provisioning persistent local storage with Kubernetes - rancher/local-path-provisioner

github.com

[Embedding] Hybrid Search - Qdrant 구성

천재보단범재 — Sat, 12 Jul 2025 14:23:17 +0900

임베딩 Hybrid Search

Hybrid Search 구성

RAG와 LLM을 활용한 자동분류 서비스를 구성하고 있습니다.

Milvus에 Dense 임베딩 값을 넣어서 RAG를 구성하였지만 성능이 좋지 않았습니다.

성능 보완을 위해 Dense 임베딩뿐만 아니라 Sparse 임베딩도 넣어서 성능을 보완해보려고 합니다.

Sparse 임베딩과 Dense 임베딩이 무엇인지는 아래 포스팅을 참고하시길 바랍니다.

차이점 중심으로 비교해 보았습니다.

[Embedding] Sparse vs Dense 임베딩

Sparse vs Dense 임베딩프로젝트에 투입해서 RAG와 LLM을 활용한 자동 분류 서비스를 개발하였습니다.처음에는 다국어를 지원하는 paraphrase-multilingual-mpnet-base-v2 임베딩 모델로 임베딩을 생성해서Milvus

developnote-blog.tistory.com

Dense 임베딩과 Sparse 임베딩을 활용하려면 Hybrid Search 방식으로 유사 문서를 검색해야 합니다.

두 가지 임베딩 활용을 위한 Hybrid Search 구성을 진행하려고 합니다.

Hybrid Search란?

저번 포스팅에서 Dense 임베딩과 Sparse 임베딩을 비교해 보았습니다.

2가지 임베딩 방식은 각각 장단점이 있습니다.

Dense 임베딩 -> 의미적 유사성은 잘 찾지만, 정확한 키워드 매칭이 약함.
Sparse 임베딩 -> 키워드 매칭은 정확하지만, 동의어나 유의어 처리가 어려움.

Hybrid Search는 두 가지 임베딩 방식의 장점을 보완하기 위해 포괄적으로 검색하는 방식입니다.

Hybrid Search의 작동 원리

사용자 질문: "차량 구매 방법이 궁금해"

1. Dense 검색 결과:
   - "자동차 매입 절차 안내" (점수: 0.85)
   - "차량 구매 가이드" (점수: 0.82)
   - "자동차 선택 팁" (점수: 0.78)

2. Sparse 검색 결과:
   - "차량 구매 가이드" (점수: 0.92)
   - "구매 방법 총정리" (점수: 0.88)
   - "차량 관련 정보" (점수: 0.85)

3. Hybrid 최종 결과 (가중평균):
   - "차량 구매 가이드" (Dense: 0.82, Sparse: 0.92 → 최종: 0.87)
   - "자동차 매입 절차 안내" (Dense: 0.85, Sparse: 0.0 → 최종: 0.60)
   - "구매 방법 총정리" (Dense: 0.0, Sparse: 0.88 → 최종: 0.26)

위 예시처럼 Dense와 Sparse 임베딩에서 검색하는 유사 문서를 종합적으로 판단해서 유사도를 검색합니다.

아래와 같은 장점을 보입니다.

포괄적 검색 -> 키워드와 의미를 모두 고려
정확도 향상 -> 두 방식의 약점을 서로 보완
사용자 경험 개선 -> 어떤 방식으로 질문해도 적절한 결과
도메인 적응성 -> 일반적인 질문부터 전문적인 질문까지 대응

실제로 한번 Hybrid Search를 구성해 보면서 살펴보겠습니다.

벡터 DB가 필요한데 기존에 Milvus를 사용했지만 이번 포스팅에서는 Qdrant로 진행해보려고 합니다.

Qdrant란?

Qdrant는 Rust로 개발된 고성능 벡터 데이터베이스입니다.

Qdrant는 네이티브 Hybrid Search를 지원합니다.

Docker 이미지를 제공해서 쉽게 로컬에서 구성할 수 있습니다.

이러한 이유를 빠르게 Hybrid Search에 대해 알 수 있어 Qdrant로 진행해보려고 합니다.

이 밖에도 Qdrant에는 장점이 많습니다.

네이티브 Hybrid Search 지원
Rust로 개발되어 메모리 효율적
Docker로 쉬운 구성 가능
Qdrant Cloud 서비스 이용
Python Client 제공
자체 Web UI 제공

Qdrant 아키텍처

Qdrant 구성

Qdrant는 공식적으로 Docker 이미지를 제공하고 있습니다.

GPU에서 실행되는 이미지를 따로 제공하고 있으니 참고하시길 바랍니다.

이번 포스팅에서는 Docker를 통해서 Qdrant를 구성하도록 하겠습니다.

아래와 같이 docker compose 파일을 구성하였습니다.

version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant:v1.14.1
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - /***/volumes/qdrant:/qdrant/storage:z
    environment:
      - QDRANT__SERVICE__HTTP_PORT=6333
      - QDRANT__SERVICE__GRPC_PORT=6334
      - QDRANT__LOG_LEVEL=INFO
      - RUST_LOG=qdrant=info    # Rust 로깅 레벨 설정
    restart: unless-stopped

아래와 같이 docker compose로 실행하면 로그를 확인할 수 있습니다.

그리고 http://localhost:6333/dashboard로 들어가면 Qdrant Web UI를 확인할 수 있습니다.

$ docker compose up -d
$ docker ps
CONTAINER ID   IMAGE                   COMMAND             CREATED         STATUS         PORTS                              NAMES
fede6b49a583   qdrant/qdrant:v1.14.1   "./entrypoint.sh"   6 seconds ago   Up 5 seconds   0.0.0.0:6333-6334->6333-6334/tcp   ai_test-qdrant-1

$ docker logs fede6b49a583
           _                 _
  __ _  __| |_ __ __ _ _ __ | |_
 / _` |/ _` | '__/ _` | '_ \| __|
| (_| | (_| | | | (_| | | | | |_
 \__, |\__,_|_|  \__,_|_| |_|\__|
    |_|

Version: 1.14.1, build: 530430fa
Access web UI at http://localhost:6333/dashboard

2025-07-12T06:44:15.928608Z  INFO storage::content_manager::consensus::persistent: Initializing new raft state at ./storage/raft_state.json
2025-07-12T06:44:15.971620Z  INFO qdrant: Distributed mode disabled
2025-07-12T06:44:15.971711Z  INFO qdrant: Telemetry reporting enabled, id: 3f6e77f1-b845-40bd-b911-54981f4ab3bf
2025-07-12T06:44:15.971822Z  INFO qdrant: Inference service is not configured.
2025-07-12T06:44:15.972711Z  INFO qdrant::actix: TLS disabled for REST API
2025-07-12T06:44:15.972812Z  INFO qdrant::actix: Qdrant HTTP listening on 6333
2025-07-12T06:44:15.972837Z  INFO actix_server::builder: starting 3 workers
2025-07-12T06:44:15.972841Z  INFO actix_server::server: Actix runtime found; starting in Actix runtime
2025-07-12T06:44:15.972864Z  INFO actix_server::server: starting service: "actix-web-service-0.0.0.0:6333", workers: 3, listening on: 0.0.0.0:6333
2025-07-12T06:44:15.975946Z  INFO qdrant::tonic: Qdrant gRPC listening on 6334
2025-07-12T06:44:15.975997Z  INFO qdrant::tonic: TLS disabled for gRPC API

Qdrant WEB UI

fastembed

FastEmbed는 Qdrant에서 개발한 경량화된 임베딩 생성 라이브러리입니다.

FastEmbed는 세 가지 장점이 있습니다.

첫 번째 장점은 경량화입니다.

ONNX Runtime을 활용하여 임베딩 모델을 경량화해서 사용할 수 있게 하였습니다.

# 기존 방식 (Sentence Transformers)
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('BAAI/bge-small-en-v1.5')
# → PyTorch 의존성으로 인한 수GB 다운로드
# → GPU 메모리 많이 사용

# FastEmbed 방식
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-small-en-v1.5")
# → ONNX Runtime 사용으로 경량화
# → CPU만으로도 실용적 성능

두 번째 장점은 속도입니다.

ONNX Runtime을 사용해서 PyTorch보다는 빠르게 추론하여 임베딩을 생성할 수 있습니다.

그리고 메모리를 효율적으로 사용합니다.

세 번째 장점은 다양한 모델 지원입니다.

Dense 임베딩, Sparse 임베딩뿐만 아니라 이미지 임베딩 모델도 지원합니다.

아래 코드를 통해서 fastembed에서 지원하는 Dense 임베딩 모델을 확인할 수 있습니다.

25년 7월 12일 기준 30개를 지원하고 있습니다.

from fastembed import TextEmbedding

supported_text_models = (
    pd.DataFrame(TextEmbedding.list_supported_models())
    .sort_values("size_in_GB")
    .drop(columns=["sources", "model_file", "additional_files"])
    .reset_index(drop=True)
)
supported_text_models

fastembed에서 지원하는 TextEmbedding 모델

그리고 fastembed에서 지원하는 Spare 임베딩 모델도 지원을 합니다.

25년 7월 12일 기준 5개를 지원하고 있습니다.

from fastembed import SparseTextEmbedding

supported_sparse_models = (
    pd.DataFrame(SparseTextEmbedding.list_supported_models())
    .sort_values("size_in_GB")
    .drop(columns=["sources", "model_file", "additional_files"])
    .reset_index(drop=True)
)
supported_sparse_models

fastembed에서 지원하는 SparseEmbedding 모델

이번 포스팅에서 Qdrant와 fastembed를 통해서 Hybrid Search를 구성해 보겠습니다.

임베딩 생성 및 컬렉션 저장

이제 Dense 임베딩과 Sparse 임베딩을 생성해서 Qdrant에 저장해 보겠습니다.

데이터는 파이썬 dataset 라이브러리에 있는 ms_macro 데이터셋으로 활용하겠습니다.

from datasets import load_dataset

dataset = load_dataset("ms_marco", "v1.1", split="train[:1000]")
df = pd.DataFrame(dataset)

dataset의 queries 데이터

해당 데이터에서 Dense 임베딩과 Sparse 임베딩을 만들어보겠습니다.

fastembed 라이브러리로 각각 아래 모델들로 생성하였습니다.

from fastembed import TextEmbedding, SparseTextEmbedding

dense_model = TextEmbedding('sentence-transformers/paraphrase-multilingual-mpnet-base-v2')
dense_embeddings = list(dense_model.embed(texts))

sparse_model = SparseTextEmbedding('Qdrant/bm25')
sparse_embeddings = list(sparse_model.embed(texts))

이렇게 생성한 임베딩들을 바탕으로 Qdrant에 컬렉션을 생성하고 저장합니다.

Qdrant는 파이썬 클라이언트를 제공해서 파이썬을 통해 쉽게 컬렉션을 생성하고 저장할 수 있습니다.

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, SparseVectorParams, PointStruct, SparseVector

def setup_qdrant_hybrid(passages, dense_embeddings, sparse_embeddings):
    client = QdrantClient('localhost', port=6333)
    collection_name = 'hybrid_test'
    dense_dim = len(dense_embeddings[0])

    if client.collection_exists(collection_name):
        client.delete_collection(collection_name)
    
    # Create collection with both dense and sparse vector configurations
    client.create_collection(
        collection_name = collection_name,
        vectors_config = {
            "dense" : VectorParams(
                size=dense_dim,
                distance=Distance.COSINE
            )
        },
        sparse_vectors_config = {
            "sparse" : SparseVectorParams()
        }
    )
    
    # 데이터 삽입
    points = []
    for i, (passage, dense_emb, sparse_emb) in enumerate(zip(passages, dense_embeddings, sparse_embeddings)):
...
...
...
        point = PointStruct(
            id=i,
            vector={
                "dense": dense_vector,
                "sparse": sparse_vector
            },
            payload={"text": passage}
        )
        points.append(point)
    
    client.upsert(collection_name, points)
    return client

저장 후 Qdrant WEB UI에서 저장된 것을 확인할 수 있습니다.

Hybrid Search

Qdrant에 Dense 임베딩과 Sparse 임베딩을 넣었으면 이제 Hybrid Search를 해보겠습니다.

Qdrant에는 자체 내장 RRF를 가지고 있어서 query 변수에 RRF를 추가해 주면 됩니다.

results = client.query_points(
    collection_name = collection_name,
    query=models.FusionQuery(
        fusion=models.Fusion.RRF  # Reciprocal Rank Fusion
    ),
    prefetch=[
        models.Prefetch(
            query=models.Document(text=query_text, model="sentence-transformers/paraphrase-multilingual-mpnet-base-v2"),
            using="dense",
        ),
        models.Prefetch(
            query=models.Document(text=query_text, model="Qdrant/bm25"),
            using="sparse",
        ),
    ],
    query_filter=None,
    limit=top_k,
)

1가지 텍스트를 비교해 보았습니다.

Dense 임베딩으로만, Sparse 임베딩으로만, Hybrid Search를 했을 경우를 비교해 보았습니다.

단순 비교라 정확하지 않지만 각각 score를 어떻게 내는지 비교해 볼 수 있었습니다.

Comparing search methods for query: 'what is a diabetic'
================================================================================

  DENSE-ONLY SEARCH
------------------------------
Search time: 0.0322s
1. Score: 0.8025
   Text: what is a diabetic kidney...

2. Score: 0.4516
   Text: what does a metabolic acidosis need to reverse the condition...

3. Score: 0.3117
   Text: what is the discriminant of an equation...

4. Score: 0.2867
   Text: why conversion observed in body...

5. Score: 0.2716
   Text: diseases caused by clostridium...


  SPARSE-ONLY SEARCH
------------------------------
Search time: 0.0119s
1. Score: 2.8408
   Text: what is a diabetic kidney...


  HYBRID SEARCH
------------------------------
Search time: 0.0237s
1. Score: 1.0000
   Text: what is a diabetic kidney...

2. Score: 0.3333
   Text: what does a metabolic acidosis need to reverse the condition...

3. Score: 0.2500
   Text: what is the discriminant of an equation...

4. Score: 0.2000
   Text: why conversion observed in body...

5. Score: 0.1667
   Text: diseases caused by clostridium...


  PERFORMANCE SUMMARY
------------------------------
Dense search:  0.0322s
Sparse search: 0.0119s
Hybrid search: 0.0237s

정리

이번 포스팅에서는 Vector DB인 Qdrant를 설치하고 거기에 Hybrid Search를 구현해 보았습니다.

Qdrant에서 개발한 fastembed 라이브러리를 활용해서 Dense와 Sparse 임베딩을 생성해 보았습니다.

Qdrant에서 제공하는 네이티브 RRF를 이용하여 Hybrid Search를 해보았습니다.

다음에는 RRF에 대해서 정리해 보면서 Hybrid Search에 대해서 좀 더 정리하겠습니다.

[참고사이트]

Qdrant - Vector Database

Qdrant is an Open-Source Vector Database and Vector Search Engine written in Rust. It provides fast and scalable vector similarity search service with convenient API.

qdrant.tech

GitHub - qdrant/fastembed: Fast, Accurate, Lightweight Python library to make State of the Art Embedding

Fast, Accurate, Lightweight Python library to make State of the Art Embedding - qdrant/fastembed

github.com

[Embedding] Sparse vs Dense 임베딩

천재보단범재 — Wed, 2 Jul 2025 13:23:13 +0900

RAG 구성 시 임베딩 선택

Sparse vs Dense 임베딩

프로젝트에 투입해서 RAG와 LLM을 활용한 자동 분류 서비스를 개발하였습니다.

처음에는 다국어를 지원하는 paraphrase-multilingual-mpnet-base-v2 임베딩 모델로 임베딩을 생성해서

Milvus에 해당 임베딩을 저장하여 RAG를 구성하였습니다.

[LLM] RAG와 LLM을 활용한 자동 분류(1) - VectorDB 구성하기

VectorDB 구성하기좋은 기회로 사내에서 데이터를 카테고리별로 자동 분류하는 과제를 맡게 되었습니다.엔지니어이기 때문에 분류 서비스를 만들어 본 적은 없지만,이번 기회에 다양한 것들을 도

developnote-blog.tistory.com

RAG만 구성하면 다 될 줄 알았지만 생각보다 검색 성능이 좋지 않았습니다.

유사 문서의 검색 성능을 높이려면 어떻게 해야 할지 고민하였습니다.

그러던 중 Sparse와 Dense를 알게 되고 Hybrid Search를 알게되었습니다.

Sparse와 Dense 임베딩을 서비스에 도입하여 유사 문서 검색 성능을 높이려고 합니다.

이번 포스팅에서는 Sparse와 Dense 임베딩을 비교해 보겠습니다.

Embedding

임베딩은 텍스트를 숫자 벡터, 숫자 배열로 변환하는 기술입니다.

텍스트끼리는 단순 비교가 힘들지만 벡터로 변환하면 의미적 유사도를 계산해서 비교할 수 있습니다.

벡터로 바꾸면 코사인 유사도, 유클리드 거리 같은 수학 공식으로 계산할 수 있습니다.

코사인 유사도

유클리드 거리

임베딩하는 방식은 여러 가지가 있는데

이번 포스팅에서는 Sparse와 Dense 2가지를 비교해보려고 합니다.

Sparse 임베딩

Sparse는 영어 뜻대로 하면 '드문드문 난'이란 뜻입니다.

Sparse 임베딩 모델로 나온 벡터는 대부분 0 값이 들어 있습니다.

단어의 인덱스 값만 1이고 나머지는 0으로 들어가 있기 때문입니다.

대신 Sparse 임베딩으로 나온 벡터는 수천에서 수백만 개의 차원을 가지게 됩니다.

1000개 단어로 구성된 것이면 1000개 차원을 가지는 벡터를 만듭니다.

대표적으로 원핫인코딩 방법이 있습니다.

아래는 pandas Dataframe에서 get_dummies를 통해 원핫인코딩을 한 것입니다.

import pandas as pd
import numpy as np

# 문서 데이터 예시
documents = [
    "자동차 구매 가이드",
    "구매 방법 추천", 
    "자동차 최고 추천",
    "가이드 방법"
]
all_words = []
for doc in documents:
    all_words.extend(doc.split())

# DataFrame 생성
df = pd.DataFrame({'words': all_words})

# One-Hot Encoding 적용
onehot_df = pd.get_dummies(df['words'])

고차원성 (High Dimensionality)
- 수천에서 수백만 차원의 벡터 사용
- 예: 1,000개 어휘 → 1,000차원 벡터
지역성 (Locality)
- 각 단어를 독립적으로 표현
- 단어 간 공유 정보나 겹치는 부분이 거의 없음
- "자동차"와 "차량"을 완전히 다른 차원으로 처리
해석 가능성 (Interpretability)
- 각 차원이 명확한 의미를 가짐 (특정 단어의 존재/부재)
- 어떤 단어가 문서 검색에 기여했는지 쉽게 파악 가능
주요 기법
- One-Hot Encoding (원핫인코딩)
- Bag-of-Words (BoW)
- TF-IDF (Term Frequency-Inverse Document Frequency)

이러한 특징들이 있지만 단점이 있습니다.

단어에 대해서는 파악하기 좋지만 의미적인 정보는 알기가 쉽지 않습니다.

문맥에 대한 정보를 파악하기 힘듭니다.

이런 단점을 보완할 Dense 임베딩이 있습니다.

Dense 임베딩

Dense는 영어 뜻대로 하면 '밀집된'이란 뜻입니다.

뜻만 봐도 Sparse와 상반된 의미라는 것을 알 수 있습니다.

Sparse와는 다르게 벡터가 0이 아닌 실수로 이루어져 있습니다.

데이터 포인트 간의 의미적인 관계를 알 수 있도록 벡터를 만듭니다.

저차원성 (Low Dimensionality)
- 보통 256 ~ 1024개 차원
분산 표현 (Distributed Representations)
- 각 차원이 특정 의미가 아닌 전체적으로 의미를 분산 저장
의미적 관계 (Semantic Relationships)
- 데이터 포인트 간의 의미적 관계를 포착
주요 기법
- Word2Vec
- GloVe (Global Vectors for Word Representation)
- BERT (Bidirectional Encoder Representations from Transformers)

paraphrase-multilingual-mpnet-base-v2도 BERT 기반 Dense 임베딩 모델입니다.

2가지를 비교해보자면 아래와 같이 정리해볼 수 있습니다.

특징	Sparse 임베딩	Dense 임베딩
차원 수	높음 (수만~수십만 차원)	낮음 (50~1,000 차원)
벡터 표현	대부분 값이 0	대부분 실수, non-zero
의미 정보	제한적, 관계 포착 어려움	풍부, 의미적·문법적 관계 인코딩
해석 가능성	높음 (각 차원이 특정 단어)	낮음 (추상적 표현)
계산 효율성	고차원으로 인해 비효율적	효율적, 컴팩트한 표현

주요 모델

Sparse 모델

#	방식	임베딩 모델
1	BM25	rank-bm25
2	TF-IDF	scikit-learn
3	SPLADE	naver/splade-cocondenser-ensembledistil

Dense 모델

#	임베딩 모델	특징
1	sentence-transformers/all-MiniLM-L6-v2	가장 많이 사용, 384차원
2	sentence-transformers/paraphrase-multilingual-mpnet-base-v2	다국어 지원
3	BAAI/bge-large-en-v1.5	최고 성능

정리

Sparse와 Dense 임베딩 방식을 정리해보았습니다.

2가지 임베딩 방식 모두 특징을 가지고 있어 용도에 맞게 사용할 수 있습니다.

챗봇이나 Q&A에서는 의미 파악을 위해 Dense가 좋을 수가 있고

전문적인 용어를 많이 사용한는 곳이라면 단어 기반의 Sparse가 나을 수도 있습니다.

다음 포스팅에서는 Dense로만 구성했던 것을 Sparse와 Dense 2가지 임베딩을 hybrid할지 정리해보겠습니다.

[참고사이트]

sentence-transformers/paraphrase-multilingual-mpnet-base-v2 · Hugging Face

sentence-transformers/paraphrase-multilingual-mpnet-base-v2 This is a sentence-transformers model: It maps sentences & paragraphs to a 768 dimensional dense vector space and can be used for tasks like clustering or semantic search. Usage (Sentence-Transfor

huggingface.co

Dense and Sparse Embeddings: A Comprehensive Overview

Embeddings are a foundational concept in machine learning and natural language processing (NLP). They provide a way to represent data…

mlokhandwalas.medium.com

[카이제곱검정(1)] 부서별 업무 환경이 질환에 영향을 미칠까?

천재보단범재 — Sun, 22 Jun 2025 18:46:04 +0900

카이제곱 검정

부서별 업무 환경이 질환에 영향을 미칠까?

프로젝트에서 데이터 분석 업무를 맡게 되었습니다.

그중 하나가 직원 건강검진 데이터를 분석하는 것이었습니다.

개인 정보 보안 때문에 제한된 정보만으로 분석하게 되었습니다.

건강검진 데이터는 아래와 같은 형태로 되어 있었습니다.

연령대	부서	고혈압	당뇨	빈혈
20대	A 부서	A	A	A
50대	B 부서	D1	C2	A

2022년부터 데이터를 관리하기 시작해서 3년 치 정도의 데이터만 엑셀로 관리되고 있었습니다.

데이터는 총 700건 정도밖에 되지 않았습니다.

작은 데이터 셋으로도 의미 있는 인사이트를 얻을 수 있을지 고민하였습니다.

데이터를 보고 아래와 같은 궁금증이 생겼습니다.

연령대가 높을수록 질병 발생률이 높을까?
부서별 업무 환경이 영향을 미칠까?
이게 단순한 우연일까? 데이터로 증명할 수 없을까?

이러한 궁금증을 해결하기 위해서 생각한 것이 카이제곱 검정(chi-squared test)이었습니다.

카이제곱 검정

카이제곱 검정은 두 범주형 변수 관계에 대해 분석하는 방법입니다.

1900년에 칼 피어슨이 처음으로 고안했다고 알려져 있습니다.

관찰 데이터(observed value)와 기대한 데이터가(expected value)의 차이가 우연인가에서 시작되었습니다.

카이제곱에서 카이(Chi)는 그리스 문자로 C에 해당하며 Contingency(우연성)에서 유래된 것입니다.

아래 검정 통계량에서도 편차가 핵심입니다.

카이제곱 검정 통계량 공식

카이제곱 검정은 크게 3가지 목적으로 사용할 수 있습니다.

목적	예시	가설
적합도 검정	고혈압 정상이 전체 중이 70% 정도 나올 것인가?	귀무가설(H0) : 관찰 분포 = 기대분포 대립가설(H1) : 관찰 분포 ≠ 기대분포
동질성 검정	A부서와 B부서의 고혈압 정상 비율 분포가 같은가?	귀무가설(H0) : 집단1 분포 = 집단2 분포 대립가설(H1) : 집단1 분포 ≠ 집단2 분포
독립성 검정	부서와 고혈압 상태가 서로 관련이 있는가?	귀무가설(H0) : 두 변수는 독립적 대립가설(H1) : 두 변수는 의존적

이번에는 카이제곱 검정에서 독립성 검정을 목적으로 진행하였습니다.

왜 카이제곱 검정인가?

카이제곱 검정으로 검진 데이터를 분석하는 이유는 3가지입니다.

첫 번째는 건강검진 데이터는 범주형 데이터로 구성되어 있습니다.

연령대 : 20대, 30대, 40대, 50대 (순서형 범주)
부서 : A 부서, B 부서, C부서 ... (명목형 범주)
검진 결과 : 아래 코드표 참고

출처 https://www.hanaromf.com/program/prog07/prog07_03.jsp

카이제곱 검정은 이러한 범주형 데이터의 관계를 분석할 때 사용됩니다.

두 번째는 카이제곱 검정의 독립성 검정을 통해 위에서 제기한 궁금증에 대해서 분석할 수 있습니다.

아래와 같이 귀무가설과 대립가설을 세울 수 있습니다.

귀무가설(H0) : 두 변수는 독립적 -> '부서와 고혈압은 관계없다'
대립가설(H1) : 두 변수는 서로 의존 -> '부서 업무 환경에 따라 고혈압 발생률이 다르다'

마지막으로 제한된 데이터의 규모입니다.

약 700건의 적은 데이터이기 때문에 예측 모델 설계는 힘들다고 판단하였습니다.

적은 데이터로도 해당 검정을 통해 해석하기 쉬운 결과가 나올 수 있다고 판단하였습니다.

분석 실시

분석 가설은 아래와 같이 설정하였습니다.

부서별 건강상태 차이 : 업무 환경에 따라 특정 질병 발생률이 다를 것이다

데이터 구조

데이터는 크게 3가지로 구분할 수 있습니다.

부서명은 보안 상 알파벳으로 표시하였습니다.

연령대 -> 20대, 30대, 40대, 50대
부서 -> A 부서, B 부서, C 부서, D 부서, E 부서
검진 항목 별 코드
- 검진 항목 -> 간장질환, 고혈압, 당뇨, 비만, 신장질환 등
- 정상 -> A
- 질환 의심 -> C, C1, C2
- 질환 -> D1, D2

데이터 전처리

데이터 전처리는 크게 2가지로 나눠서 진행하였습니다.

먼저 결측치를 제거하였습니다.

부서나 검진항목에 대한 결과 데이터가 없을 경우 제거하였습니다.

그리고 검진 항목을 크게 3가지 항목(정상, 질환의심, 질환)으로 범주화하였습니다.

import pandas as pd

df = pd.read_csv('./검진데이터.csv')

def categorize_level(code):
    if pd.isna(code) or code == 'U':
        return None  # 결측치/미분류는 제외
    elif code in ['A', 'A(B)']:
        return '정상'
    elif code in ['C', 'C1', 'C2', 'CN']:
        return '질환의심'
    elif code in ['D1', 'D2', 'DN']:
        return '질환'
    else:
        return None
        
df[disease_category] = df[disease].apply(categorize_level)

카이제곱 검정 시행

카이제곱 검정 분석에는 교차표를 가지고 분석합니다.

교차표는 항목을 각각 행과 열로 배열하여 교차되는 항목에 대해 빈도를 나타낸 표입니다.

다음은 부서와 고혈압에 대한 교차표 예시입니다.

import pandas as pd

pd.crosstab(df['부서'], df['고혈압_category'])

          정상    질환의심   질환
A부서      180      20     50    
B부서       80     140     30
..
..
..

데이터가 데이터프레임 형태면 pandas에서 제공하는 함수로 쉽게 교차표를 생성할 수 있습니다.

scipy 라이브러리를 통해서 카이제곱 검정을 할 수 있습니다.

import pandas as pd
from scipy.stats import chi2_contingency

contingency_table = pd.crosstab(df['부서'], df['고혈압_category'])

chi2_stat, p_value, dof, expected = chi2_contingency(contingency_table)

print(f"카이제곱 통계량: {chi2_stat:.4f}")
print(f"p-value: {p_value:.4f}")
print(f"자유도: {dof}")

if p_value < 0.05:
    print("결과: 부서와 고혈압 간에 통계적으로 유의한 관계가 있습니다!")
else:
    print("결과: 부서와 고혈압 간에 유의한 관계를 찾을 수 없습니다.")

scipy 라이브러리에서 chi2_contingency 함수를 통해서 카이제곱 검정을 할 수 있습니다.

4개의 반환값을 확인할 수 있습니다.

chi2_stat -> 검정통계량, 실제 데이터와 독립성 가정 간의 차이 크기
p_value -> 우연히 발생할 확률, 보통 0.05보다 작으면 귀무가설을 기각하고 증명하려던 가설이 맞다고 볼 수 있음
dof -> 자유도, 교차표에서 자유롭게 변할 수 있는 셀의 개수
expected -> 기대빈도 행렬, 립성 가정하에서의 이론적 빈도

p_value가 0.05보다 낮으면 귀무가설을 기각하고 두 변수가 상관있다고 판단합니다.

여기에서는 부서에 따라 고혈압 질환 비율이 다르다고 판단합니다.

이렇게 검진항목별로 부서와 교차표를 생성해서 카이제곱 검정을 실시해 보았습니다.

보안 상 결과를 올리지 않겠습니다.

결과

'부서별 업무 환경이 질환에 영향을 미칠까'라는 질문에 대한 답을 찾기 위해 카이제곱 검정을 하였습니다.

범주형 변수들 간의 관계를 독립성 검정을 진행하였습니다.

카이제곱 검정으로 부서와 검진항목별로 독립적인지 연관이 있는지 분석해 보았습니다.

다음 포스팅에서 사후 분석을 통해서 더 깊이 분석해 보겠습니다.

카이제곱 검정으로 관계가 유의한 지를 보았다면 이제는 구체적으로 어떤 관계인지 분석해 보겠습니다.

[참고사이트]

chi2_contingency — SciPy v1.15.3 Manual

A two-way example (2 x 3): >>> import numpy as np >>> from scipy.stats import chi2_contingency >>> obs = np.array([[10, 10, 20], [20, 20, 20]]) >>> res = chi2_contingency(obs) >>> res.statistic 2.7777777777777777 >>> res.pvalue 0.24935220877729619 >>> res.

docs.scipy.org

[LLM] RAG와 LLM을 활용한 자동 분류(2) - Ollama 세팅하기

천재보단범재 — Sat, 14 Dec 2024 11:52:47 +0900

RAG와 LLM을 활용한 자동 분류(2)

Ollama 세팅하기

데이터를 카테고리별로 자동 분류하는 과제를 진행하고 있습니다.

LLM과 RAG를 활용해서 자동 분류를 진행하려고 합니다.

방식을 간단하게 나열해 보면 아래와 같습니다.

학습에 쓰일 과거 데이터를 VectorDB에 저장한다.
서버에 OpenSource 기반의 LLM을 설치한다.
분류를 진행하려는 데이터를 VectorDB에서 유사한 데이터를 찾는다.
찾은 데이터를 기반으로 프롬프트를 구성해서 LLM에 어떤 카테고리에 해당하는지 물어본다.

이전 포스팅에서 VectorDB 설치에 관해 정리하였습니다.

[LLM] RAG와 LLM을 활용한 자동 분류(1) - VectorDB 구성하기

developnote-blog.tistory.com

이번 포스팅은 2번째 포스팅으로 오픈소스 기반의 LLM 설치를 정리하겠습니다.

LLM 모델 선택

LLM(Large Language Model) 개발에 대규모 자본과 투자가 필요합니다.

이를 감당할 수 있는 것은 빅테크 기업뿐입니다.

LLM이 빠르게 독점화, 권력화 되어가고 있었습니다.

마이크로소프트가 GPT-3 독점 라이선스를 획득한 경우도 있었습니다.

MS, 인공지능 GPT-3 독점 라이선스 획득 - 디지털투데이 (DigitalToday)

[디지털투데이 추현우 기자] 마이크로소프트(MS)가 인공지능 개발사인 오픈AI(OpenAI)와 협력을 통해 첨단 AI 모델 'GPT-3' 독점 라이선스를 획득했다고 23일(현지시간) 발표했다. GPT-3는 오픈A...

www.digitaltoday.co.kr

하지만 이에 맞서 허깅페이스 중심으로 많은 오픈소스 LLM이 나오고 있습니다.

LLM	설명
Falcon	UAE의 TII가 개발했으며 적은 파라미터로도 뛰어난 성능을 보여주는 리소스 효율적인 모델
BLOOM	프랑스 주도로 개발된 다국어 지원에 특화된 모델로, 46개 자연어와 13개 프로그래밍 언어 지원
MPT	MosaicML이 개발한 모델로 긴 컨텍스트 처리에 강점이 있으며 32k 토큰 길이 지원
Mistral	프랑스 Mistral AI가 개발한 7B 크기의 컴팩트한 모델로 효율성과 성능의 균형이 뛰어남

BLOOM

빅테크 기업 중 하나인 Meta에서도 llama라는 LLM을 오픈소스로 공개하였습니다.

현재 llama 3.3까지(24/12/14 기준) 공개하였습니다.

다른 모델들에 비해 더 적은 파라미터로 높은 성능을 달성하여 효율적인 LLM으로도 유명합니다.

업데이트도 빠르고 라이선스 조건도 관대해서 다양한 파생모델이 존재합니다.

llama 3

이번 과제에서는 우선적으로 llama 파생 모델을 사용하려고 합니다.

서울과기대 MLP연구실에서 한국어-영어 시각-언어모델 Bllossom-Vision을 공개하였습니다.

해당 모델은 llama 3.1 모델을 기반으로 만들어졌다고 합니다.

한국어 기반의 내용을 토대로 카테고리를 분류를 할 예정이라 해당 모델을 최우선적으로 선택하였습니다.

Ollama 설치

LLM을 쉽게 사용할 수 있도록 Ollama를 설치합니다.

Ollama는 로컬 환경에서 AI 모델을 쉽게 실행할 수 있게 해주는 오픈소스 플랫폼입니다.

간단하게 로컬 환경에서 LLM을 실행할 수 있고 CLI도 비교적 쉽습니다.

다양한 오픈소스 LLM을 지원하며 REST API 형태로 LLM를 사용할 수 있게 해 줍니다.

이번 포스팅에서는 docker compose를 활용하여 Ollama를 설치합니다.

그리고 open-webui를 연결해서 WEB UI 형태로도 접근할 수 있게 세팅합니다.

services:
  ollama:
    volumes:
      - ./volumes/ollama:/root/.ollama
      - /usr/bin/nvidia-smi:/usr/bin/nvidia-smi
      - /usr/lib/x86_64-linux-gnu/libnvidia-ml.so:/usr/lib/x86_64-linux-gnu/libnvidia-ml.so
      - /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1:/usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1
    container_name: ollama
    pull_policy: always
    tty: true
    restart: unless-stopped
    image: ollama/ollama:0.4.7
    ports:
      - 7869:11434
    environment:
      - OLLAMA_KEEP_ALIVE=24h
    networks:
      - ollama-docker
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  ollama-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: ollama-webui
    volumes:
      - ./volumes/ollama-webui:/app/backend/data
    depends_on:
      - ollama
    ports:
      - 8080:8080
    environment: # https://docs.openwebui.com/getting-started/env-configuration#default_models
      - OLLAMA_BASE_URLS=http://host.docker.internal:7869 #comma separated ollama hosts
      - ENV=dev
      - WEBUI_AUTH=False
      - WEBUI_NAME=valiantlynx AI
      - WEBUI_URL=http://localhost:8080
      - WEBUI_SECRET_KEY=t0p-s3cr3t
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped
    networks:
      - ollama-docker

networks:
  ollama-docker:
    external: false

docker compose up 명령어로 실행하면 2개의 컨테이너가 실행된 것을 확인할 수 있습니다.

그리고 open-webui 포트로 WEB-UI를 확인할 수 있습니다.

$ docker ps
fd4bffde5661   ghcr.io/open-webui/open-webui:main         "bash start.sh"          9 days ago   Up 9 days (healthy)   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp                                                  ollama-webui
310eb3c663a5   ollama/ollama:0.4.7                        "/bin/ollama serve"      9 days ago   Up 9 days             0.0.0.0:7869->11434/tcp, [::]:7869->11434/tcp

openweb-ui

ChatGPT와 비슷한 화면을 제공하기 때문에 사용하기 편리합니다.

로컬에 다양한 모델을 다운받고 원하는 대로 모델을 선택해서 사용할 수 있습니다.

open-webui에서 모델 선택

허깅페이스 모델 Ollama에서 사용하기

Ollama에서 제공하는 모델을 사용하기 위해서는 CLI로 간단하게 다운로드 할 수 있습니다.

$ ollama pull llama3.1:8b

# 다운로드한 모델 리스트 확인
$ ollama list
NAME                       ID              SIZE      MODIFIED
nomic-embed-text:latest    0a109f422b47    274 MB    9 days ago
mistral:7b                 f974a74358d6    4.1 GB    9 days ago
llama3.1:8b                46e0c10c039e    4.9 GB    9 days ago

# 실행중인 모델 확인
$ ollama ps
NAME           ID              SIZE      PROCESSOR    UNTIL
llama3.1:8b    46e0c10c039e    6.9 GB    100% GPU     24 hours from now

Ollama CLI를 통해서 쉽게 사용할 수 있지만 Ollama에서 모든 모델을 제공하지 않습니다.

이번에 사용하려고 하는 Bllossom-Vision 모델도 허깅페이스에 업로드되어 있습니다.

다른 프레임워크인 vLLM에서도 사용가능하지만 이번 포스팅에서 Ollama에서 사용할 수 있도록 세팅하겠습니다.

llama.app을 통해 모델 변환

Ollama의 Modelfile을 사용해서 바꾸는 방법도 있지만

llama.app을 통해서 Ollama에서 사용할 수 있도록 변환해 보겠습니다.

GitHub - ggerganov/llama.cpp: LLM inference in C/C++

LLM inference in C/C++. Contribute to ggerganov/llama.cpp development by creating an account on GitHub.

github.com

먼저 위 Github에서 소스를 다운로드합니다.

소스에 있는 requirements.txt 파일 기준으로 필요한 파이썬 패키지를 설치합니다.

추가적으로 허깅페이스에서 모델을 다운로드하기 위해 huggingface_hub 패키도 설치합니다.

$ git clone https://github.com/ggerganov/llama.cpp.git
Cloning into 'llama.cpp'...
remote: Enumerating objects: 39659, done.
remote: Counting objects: 100% (9656/9656), done.
remote: Compressing objects: 100% (559/559), done.
remote: Total 39659 (delta 9404), reused 9109 (delta 9097), pack-reused 30003 (from 1)
Receiving objects: 100% (39659/39659), 62.67 MiB | 18.65 MiB/s, done.
Resolving deltas: 100% (28930/28930), done.

$ cd llama.cpp
$ pip install -r requirements.txt
$ pip install huggingface_hub

아래 파이썬 코드를 통해서 원하는 Bllossom-Vision 모델을 다운로드하겠습니다.

$ mkdir bllossom

$ vi download.py

from huggingface_hub import snapshot_download

model_id="Bllossom/llama-3.1-Korean-Bllossom-Vision-8B"
snapshot_download(repo_id=model_id, local_dir="bllossom", local_dir_use_symlinks=False, revision="main")

$ python download.py
.gitattributes: 100%|████████████████████████████████████████████████████████████████████| 1.52k/1.52k [00:00<00:00, 4.78MB/s]
generation_config.json: 100%|████████████████████████████████████████████████████████████████| 143/143 [00:00<00:00, 2.21MB/s]
README.md: 100%|██████████████████████████████████████████████████████████████████████████| 9.53k/9.53k [00:00<00:00, 124MB/s]
config.json: 100%|███████████████████████████████████████████████████████████████████████| 1.35k/1.35k [00:00<00:00, 23.0MB/s]
model.safetensors.index.json: 100%|██████████████████████████████████████████████████████| 70.2k/70.2k [00:00<00:00, 3.18MB/s]
preprocessor_config.json: 100%|██████████████████████████████████████████████████████████████| 702/702 [00:00<00:00, 12.7MB/s]
special_tokens_map.json: 100%|███████████████████████████████████████████████████████████████| 444/444 [00:00<00:00, 8.62MB/s]
tokenizer_config.json: 100%|█████████████████████████████████████████████████████████████| 51.7k/51.7k [00:00<00:00, 17.5MB/s]
tokenizer.json: 100%|████████████████████████████████████████████████████████████████████| 9.09M/9.09M [00:01<00:00, 7.17MB/s]
model-00004-of-00004.safetensors: 100%|██████████████████████████████████████████████████| 1.84G/1.84G [00:45<00:00, 40.4MB/s]
model-00001-of-00004.safetensors:   4%|██                                                 | 199M/4.95G [00:44<26:27, 2.99MB/s]
model-00001-of-00004.safetensors:  11%|█████▊                                             | 566M/4.95G [01:03<05:03, 14.4MB/s]
model-00002-of-00004.safetensors:  47%|███████████████████████▌                          | 2.32G/4.92G [01:04<01:03, 41.1MB/s]
model-00003-of-00004.safetensors:  18%|████████▉                                          | 881M/5.00G [00:44<07:26, 9.22MB/s]
model-00003-of-00004.safetensors:  31%|███████████████▌                                  | 1.55G/5.00G [01:04<01:16, 44.8MB/s]

다운로드가 완료되고 해당 폴더를 확인해 보면 16GB가 정도 되는 파일들이 존재합니다.

그중에서도 safetensors 파일 용량을 확인해 보면 눈에 띄게 큰 것을 알 수 있습니다.

모델이 safetensors 파일 형태로 저장되어 있습니다.

$ bllossom & ls -alh
drwxrwxr-x  3 manager manager 4.0K Dec 14 04:15 .cache
-rw-rw-r--  1 manager manager 1.4K Dec 14 04:15 config.json
-rw-rw-r--  1 manager manager  143 Dec 14 04:15 generation_config.json
-rw-rw-r--  1 manager manager 1.5K Dec 14 04:15 .gitattributes
-rw-rw-r--  1 manager manager 4.7G Dec 14 04:18 model-00001-of-00004.safetensors
-rw-rw-r--  1 manager manager 4.6G Dec 14 04:17 model-00002-of-00004.safetensors
-rw-rw-r--  1 manager manager 4.7G Dec 14 04:18 model-00003-of-00004.safetensors
-rw-rw-r--  1 manager manager 1.8G Dec 14 04:16 model-00004-of-00004.safetensors
-rw-rw-r--  1 manager manager  69K Dec 14 04:15 model.safetensors.index.json
-rw-rw-r--  1 manager manager  702 Dec 14 04:15 preprocessor_config.json
-rw-rw-r--  1 manager manager 9.4K Dec 14 04:15 README.md
-rw-rw-r--  1 manager manager  444 Dec 14 04:15 special_tokens_map.json
-rw-rw-r--  1 manager manager  51K Dec 14 04:15 tokenizer_config.json
-rw-rw-r--  1 manager manager 8.7M Dec 14 04:15 tokenizer.json

$ du -h -d 1 .
68K     ./.cache
16G     .

safetensors 파일을 gguf 파일 형태로 변환해줘야 합니다.

llama.app에서 제공하는 파일 convert_hf_to_gguf.py을 통해 변환해 줍니다.

아래와 같은 에러가 발생하였습니다.

llconvert_hf_to_gguf.py는 현재 멀티모달 모델(이미지와 텍스트를 함께 처리하는 모델)을 지원하지 않는 것을 알았습니다.

$ python convert_hf_to_gguf.py ./bllossom \
--outfile llama-3.1-Korean-Bllossom-Vision-8B.gguf

INFO:hf-to-gguf:Loading model: bllossom
ERROR:hf-to-gguf:Model LlavaNextForConditionalGeneration is not supported

대신 한국 기업 올거나이즈에서 llama3 기반으로 만든 모델을 변환해보겠습니다.

한국어 실무 특화 '알파-인스트럭트' LLM 오픈소스 출시

올거나이즈는 한국어 실무에 강한 알파-인스트럭트 LLM을 오픈소스로 출시했습니다. 라마3(Llama3) 기반의 8B 모델로 한국어 이해도가 높아 문서 생성 및 요약 등의 실무에 특화돼 있습니다. Logickor

blog-ko.allganize.ai

$ python download.py
/home/manager/.pyenv/versions/transfer-llm/lib/python3.10/site-packages/huggingface_hub/file_download.py:834: UserWarning: `local_dir_use_symlinks` parameter is deprecated and will be ignored. The process to download files to a local folder has been updated and do not rely on symlinks anymore. You only need to pass a destination folder as`local_dir`.
For more details, check out https://huggingface.co/docs/huggingface_hub/main/en/guides/download#download-files-to-local-folder.
  warnings.warn(
README.md: 100%|█████████████████████████████████████████████████████████████████████████| 5.82k/5.82k [00:00<00:00, 15.3MB/s]
.gitattributes: 100%|████████████████████████████████████████████████████████████████████| 1.52k/1.52k [00:00<00:00, 5.11MB/s]
config.json: 100%|███████████████████████████████████████████████████████████████████████████| 772/772 [00:00<00:00, 1.97MB/s]
generation_config.json: 100%|█████████████████████████████████████████████████████████████████| 121/121 [00:00<00:00, 398kB/s]
alpha-instruct.png: 100%|███████████████████████████████████████████████████████████████████| 116k/116k [00:00<00:00, 667kB/s]
model.safetensors.index.json: 100%|██████████████████████████████████████████████████████| 23.9k/23.9k [00:00<00:00, 15.3MB/s]
special_tokens_map.json: 100%|███████████████████████████████████████████████████████████████| 350/350 [00:00<00:00, 5.56MB/s]
tokenizer_config.json: 100%|█████████████████████████████████████████████████████████████| 51.0k/51.0k [00:00<00:00, 12.0MB/s]
tokenizer.json: 100%|████████████████████████████████████████████████████████████████████| 9.09M/9.09M [00:01<00:00, 7.56MB/s]
model-00004-of-00004.safetensors: 100%|██████████████████████████████████████████████████| 1.17G/1.17G [01:03<00:00, 18.4MB/s]
model-00003-of-00004.safetensors: 100%|██████████████████████████████████████████████████| 4.92G/4.92G [01:58<00:00, 41.6MB/s]
model-00002-of-00004.safetensors: 100%|██████████████████████████████████████████████████| 5.00G/5.00G [02:14<00:00, 37.1MB/s]
model-00001-of-00004.safetensors: 100%|██████████████████████████████████████████████████| 4.98G/4.98G [04:22<00:00, 18.9MB/s]
Fetching 13 files: 100%|██████████████████████████████████████████████████████████████████████| 13/13 [04:23<00:00, 20.27s/it]

$ cd allganize/

$ ll
total 15G
drwxrwxr-x  3 manager manager 4.0K Dec 14 04:39 .
drwxrwxr-x 26 manager manager 4.0K Dec 14 04:39 ..
-rw-rw-r--  1 manager manager 114K Dec 14 04:34 alpha-instruct.png
drwxrwxr-x  3 manager manager 4.0K Dec 14 04:34 .cache
-rw-rw-r--  1 manager manager  772 Dec 14 04:34 config.json
-rw-rw-r--  1 manager manager  121 Dec 14 04:34 generation_config.json
-rw-rw-r--  1 manager manager 1.5K Dec 14 04:34 .gitattributes
-rw-rw-r--  1 manager manager 4.7G Dec 14 04:39 model-00001-of-00004.safetensors
-rw-rw-r--  1 manager manager 4.7G Dec 14 04:36 model-00002-of-00004.safetensors
-rw-rw-r--  1 manager manager 4.6G Dec 14 04:36 model-00003-of-00004.safetensors
-rw-rw-r--  1 manager manager 1.1G Dec 14 04:35 model-00004-of-00004.safetensors
-rw-rw-r--  1 manager manager  24K Dec 14 04:34 model.safetensors.index.json
-rw-rw-r--  1 manager manager 5.7K Dec 14 04:34 README.md
-rw-rw-r--  1 manager manager  350 Dec 14 04:34 special_tokens_map.json
-rw-rw-r--  1 manager manager  50K Dec 14 04:34 tokenizer_config.json
-rw-rw-r--  1 manager manager 8.7M Dec 14 04:34 tokenizer.json

$ du -h -d 1 .
68K     ./.cache
15G     .

다운로드 받은 모델을 llama.app에서 제공하는 파일 convert_hf_to_gguf.py을 통해 변환해 줍니다.

15GB 용량의 gguf 파일을 확인할 수 있습니다.

$ python convert_hf_to_gguf.py ./allganize \
--outfile allganize-llama-3-Alpha-Ko-8B-Instruct.gguf
INFO:hf-to-gguf:Loading model: allganize
INFO:gguf.gguf_writer:gguf: This GGUF file is for Little Endian only
INFO:hf-to-gguf:Exporting model...
INFO:hf-to-gguf:gguf: loading model weight map from 'model.safetensors.index.json'
INFO:hf-to-gguf:gguf: loading model part 'model-00001-of-00004.safetensors'
INFO:hf-to-gguf:token_embd.weight,           torch.bfloat16 --> F16, shape = {4096, 128256}
...
...
...
INFO:hf-to-gguf:Set model quantization version
INFO:gguf.gguf_writer:Writing the following files:
INFO:gguf.gguf_writer:allganize-llama-3-Alpha-Ko-8B-Instruct.gguf: n_tensors = 291, total_size = 16.1G
Writing: 100%|█████████████████████████████████████████████████████████████████████████| 16.1G/16.1G [00:44<00:00, 364Mbyte/s]
INFO:hf-to-gguf:Model successfully exported to allganize-llama-3-Alpha-Ko-8B-Instruct.gguf

$ ls -alh allganize-llama-3-Alpha-Ko-8B-Instruct.gguf
-rw-rw-r-- 1 manager manager 15G Dec 14 04:46 allganize-llama-3-Alpha-Ko-8B-Instruct.gguf

gguf 파일 기준으로 Modelfile을 생성합니다.

생성한 Modelfile을 기준으로 ollama create 명령어를 통해 Ollama에 모델을 로드합니다.

확인해보면 Ollama에서 모델을 사용할 수 있는것으로 보입니다.

# Modelfile 생성
$ echo "from ./allganize-llama-3-Alpha-Ko-8B-Instruct.gguf" > ./Modelfile
$ cat Modelfile
from ./allganize-llama-3-Alpha-Ko-8B-Instruct.gguf

$ ollama create allganize-llama-3-Alpha-Ko-8B-Instruct -f ./Modelfile
transferring model data 100%
using existing layer sha256:eccccd32404b0a2a9021c8060a5cc6917446b7dae2a9c86694b51ac338a0e4cd
using autodetected template llama3-instruct
using existing layer sha256:56bb8bd477a519ffa694fc449c2413c6f0e1d3b1c88fa7e3c9d88d3ae49d4dcb
creating new layer sha256:4ff5f8289df199e76dfc9c3d0d9bc44624a351b1122a69beab262513d20e18e7
writing manifest
success

$ ollama list
NAME                                             ID              SIZE      MODIFIED
allganize-llama-3-Alpha-Ko-8B-Instruct:latest    ee863455b97f    16 GB     12 seconds ago
nomic-embed-text:latest                          0a109f422b47    274 MB    9 days ago
mistral:7b                                       f974a74358d6    4.1 GB    9 days ago
llama3.1:8b                                      46e0c10c039e    4.9 GB    9 days ago

Bllossom-Vision 모델 세팅

이후 찾아보니 4bit 양자화 모델은 Ollama에서 바로 활용할 수 있어서 다운로드해보았습니다.

Ollama에서 서울과기대에서 만든 Bllossom 모델을 사용하려면 해당 모델을 사용하시면 될거 같습니다.

MLP-KTLim/llama-3-Korean-Bllossom-8B-gguf-Q4_K_M · Hugging Face

Update! [2024.06.18] 사전학습량을 250GB까지 늘린 Bllossom ELO모델로 업데이트 되었습니다. 다만 단어확장은 하지 않았습니다. 기존 단어확장된 long-context 모델을 활용하고 싶으신분은 개인연락주세요!

huggingface.co

$ ollama pull hf.co/MLP-KTLim/llama-3-Korean-Bllossom-8B-gguf-Q4_K_M
pulling manifest
pulling 36edb3ca5dfd... 100% ▕██████████████████████████████████████████████████████████████▏ 4.9 GB
pulling 62fbfd9ed093... 100% ▕██████████████████████████████████████████████████████████████▏  182 B
pulling b78301c0df4d... 100% ▕██████████████████████████████████████████████████████████████▏   38 B
pulling eef4a93c7add... 100% ▕██████████████████████████████████████████████████████████████▏  193 B
verifying sha256 digest
writing manifest
success

$ ollama list
NAME                                                             ID              SIZE      MODIFIED
hf.co/MLP-KTLim/llama-3-Korean-Bllossom-8B-gguf-Q4_K_M:latest    6d4bd7f95f75    4.9 GB    6 seconds ago
allganize-llama-3-Alpha-Ko-8B-Instruct:latest                    ee863455b97f    16 GB     2 minutes ago
nomic-embed-text:latest                                          0a109f422b47    274 MB    9 days ago
mistral:7b                                                       f974a74358d6    4.1 GB    9 days ago
llama3.1:8b                                                      46e0c10c039e    4.9 GB    9 days ago

정리

이번 포스팅에서는 오픈 소스 LLM을 사용할 수 있도록 Ollama를 설치해보았습니다.

open-webui까지 설치하여 ChatGPT와 유사한 WEB UI도 구성해보았습니다.

허깅페이스에 있는 모델을 gguf 파일로 변환하여 Ollama에서 사용할 수 있도록 해보았습니다.

다양한 모델이 존재하기에 테스트해보며 적합한 모델을 선택해야 될거 같습니다.

[참고사이트]

Bllossom/llama-3.1-Korean-Bllossom-Vision-8B · Hugging Face

Update! [2024.09.04] Bllossom의 시각-언어 preview 모델이 최초 업데이트 되었습니다. 저희 Bllossom 팀에서 llama3.1 기반의 한국어-영어 시각-언어모델 Bllossom-Vision을 공개합니다. 이번 Bllossom-Vision은 preview

huggingface.co

Ollama

Get up and running with large language models.

ollama.com

GitHub - open-webui/open-webui: User-friendly AI Interface (Supports Ollama, OpenAI API, ...)

User-friendly AI Interface (Supports Ollama, OpenAI API, ...) - open-webui/open-webui

github.com

GitHub - ggerganov/llama.cpp: LLM inference in C/C++

LLM inference in C/C++. Contribute to ggerganov/llama.cpp development by creating an account on GitHub.

github.com

한국어 실무 특화 '알파-인스트럭트' LLM 오픈소스 출시

blog-ko.allganize.ai

[LLM] RAG와 LLM을 활용한 자동 분류(1) - VectorDB 구성하기

천재보단범재 — Sat, 23 Nov 2024 15:48:51 +0900

RAG와 LLM을 활용한 자동 분류

VectorDB 구성하기

좋은 기회로 사내에서 데이터를 카테고리별로 자동 분류하는 과제를 맡게 되었습니다.

엔지니어이기 때문에 분류 서비스를 만들어 본 적은 없지만,

이번 기회에 다양한 것들을 도전하려고 합니다.

그래서 자동 분류를 RAG와 LLM을 활용해서 해보려고 합니다.

방식을 간단하게 나열해 보면 아래와 같습니다.

학습에 쓰일 과거 데이터를 VectorDB에 저장한다.
서버에 OpenSource 기반의 LLM을 설치한다.
분류를 진행하려는 데이터를 VectorDB에서 유사한 데이터를 찾는다.
찾은 데이터를 기반으로 프롬프트를 구성해서 LLM에 어떤 카테고리에 해당하는지 물어본다.

시리즈로 구성해서 위 내용들을 블로그에 정리해보려고 합니다.

이번 포스팅에서는 VectorDB를 구성하고 분류에 참고할 과거 데이터를 저장하려고 합니다.

Milvus 설치

VectorDB 중 하나인 Milvus를 설치하려고 합니다.

현재 사용하고 있는 주요 VectorDB는 아래와 같습니다.

Pinecone
Milvus
Weaviate
Qdrant
Chroma
FAISS (Facebook AI Similarity Search)
pgvector

그중에서 이번 포스팅에서는 Milvus를 사용하려고 합니다.

Milvus는 오픈 소스 기반이며 커뮤니티가 활발하게 이뤄지고 있습니다.

분산 아키텍처로 지원으로 안정성도 확보하고 있습니다.

MinIO나 S3 같은 Object Storage에 데이터를 저장하는 구조라 스토리지 구성이 부담이 적습니다.

인덱싱 방식을 지원해서 성능을 최적화해 볼 수 있습니다.

쿠버네티스 환경에서도 구성할 수 있고 Milvus lite 버전이 있어 로컬 테스트용으로도 설치 가능합니다.

(Milvus lite를 지원하는 OS는 Linux, MacOS입니다.)

Milvus architecture

docker-compose로 구성

이번 포스팅에서는 Milvus Standalone 버전을 docker compose로 구성해 보겠습니다.

총 4가지 컨테이너가 실행됩니다.

etcd -> Meta Storage
minio -> Blob Storage
milvus -> VectorDB engine
attu -> Mivus WEB UI

Minio는 많이 사용되는 Object Storage로 실질적인 데이터 저장소로 쓰이게 됩니다.

etcd는 메타정보를 저장하는 곳으로 쓰입니다.

attu는 오픈 소스로 Milvus 관리용 툴입니다. WEB UI를 제공하고 있습니다.

적절한 path에 볼륨 설정을 한 뒤 아래 compose 파일로 실행합니다.

version: '3.5'

services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.5
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ./volumes/milvus/etcd:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd

  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - ./volumes/milvus/minio:/minio_data
    command: minio server /minio_data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.3.3
    command: ["milvus", "run", "standalone"]
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ./volumes/milvus/milvus:/var/lib/milvus
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"
  attu:
    container_name: milvus-attu
    image: zilliz/attu:v2.4.12
    environment:
      MILVUS_URL: standalone:19530
    ports:
      - "8000:3000"
    depends_on:
      - "standalone"

networks:
  default:
    name: milvus

# docker compose을 통해서 milvus 생성

$ docker-compose up -d
Creating network "milvus" with the default driver
Pulling etcd (quay.io/coreos/etcd:v3.5.5)...
v3.5.5: Pulling from coreos/etcd
dbba69284b27: Pull complete
270b322b3c62: Pull complete
7c21e2da1038: Pull complete
cb4f77bfee6c: Pull complete
e5485096ca5d: Pull complete
3ea3736f61e1: Pull complete
1e815a2c4f55: Pull complete
Digest: sha256:89b6debd43502d1088f3e02f39442fd3e951aa52bee846ed601cf4477114b89e
Status: Downloaded newer image for quay.io/coreos/etcd:v3.5.5
Pulling minio (minio/minio:RELEASE.2023-03-20T20-16-18Z)...
RELEASE.2023-03-20T20-16-18Z: Pulling from minio/minio
c7e856e03741: Pull complete
c1ff217ec952: Pull complete
b12cc8972a67: Pull complete
4324e307ea00: Pull complete
152089595ebc: Pull complete
05f217fb8612: Pull complete
Digest: sha256:6d770d7f255cda1f18d841ffc4365cb7e0d237f6af6a15fcdb587480cd7c3b93
Status: Downloaded newer image for minio/minio:RELEASE.2023-03-20T20-16-18Z
Pulling standalone (milvusdb/milvus:v2.3.3)...
v2.3.3: Pulling from milvusdb/milvus
d5fd17ec1767: Pull complete
0f5a22c44678: Pull complete
72ad4f350efb: Pull complete
2f5ee08a99b8: Pull complete
3fe28e251347: Pull complete
1f27396f6efc: Pull complete
fe556ec02776: Pull complete
Digest: sha256:6145db1368742b717b5a27d53cc568068308dc204d2014c70e8e8faf0869456b
Status: Downloaded newer image for milvusdb/milvus:v2.3.3
v2.4.12: Pulling from zilliz/attu
2d429b9e73a6: Pull complete
590bc9eabc7e: Pull complete
11b54226a0fa: Pull complete
465f246c24c6: Pull complete
64464083a822: Pull complete
cc991b86a68f: Pull complete
964728ba53f9: Pull complete
dc965c2a769e: Pull complete
d3769fbc79b3: Pull complete
677a81c8214c: Pull complete
0d5e29692220: Pull complete
85441f2440c0: Pull complete
9eeca687e63a: Pull complete
Digest: sha256:36a242d51dbd48e75d8378cd735807502403e4040928d77e92aefc644679855f
Status: Downloaded newer image for zilliz/attu:v2.4.12
Creating milvus-minio ... done
Creating milvus-etcd  ... done
Creating milvus-standalone ... done
Creating milvus-attu       ... done

attu 컨테이너에서 포워딩한 포트로 브라우저에서 확인하면 아래와 같은 화면을 볼 수 있습니다.

VectorDB에 데이터 저장

Milvus 설치가 완료되었습니다.

이제 LLM이 참고할 수 있도록 외부 지식을 Milvus에 저장하도록 하겠습니다.

LLM에게는 외부에 있는 지식으로 표현되지만 사용자 입장에서는 내부 데이터입니다.

Milvus 파이썬 SDK와 임베딩값을 추출하기 위해 SBERT 라이브러리를 설치합니다.

$ pip install pymilvus sentence-transformers

Milvus 컬렉션 구성

Milvus에서는 컬렉션이라는 단위가 있습니다.

데이터를 저장하는 기본 단위로 RDB에서 테이블과 비슷한 개념입니다.

필드, primary key, 인덱스를 가지고 있습니다.

VectorDB이기 때문에 vector 필드를 구성할 수 있으며 dimension값을 지정할 수 있습니다.

# 필드 정의
id_field = FieldSchema(name="id", dtype=DataType.INT64, is_primary=True)
vector_field = FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=128)
age_field = FieldSchema(name="age", dtype=DataType.INT64)
name_field = FieldSchema(name="name", dtype=DataType.VARCHAR, max_length=200)

# 스키마 생성
schema = CollectionSchema(
    fields=[id_field, vector_field, age_field, name_field],
    description="User profiles collection"
)

# 컬렉션 생성
collection = Collection(
    name="user_profiles", 
    schema=schema,
    using='default'
)

Milvus 인덱스

테스트 데이터로 VOC 데이터를 LLM을 생성해 보았습니다.

내용을 보고 카테고리를 자동으로 분류하는 서비스를 만들어볼 예정입니다.

제목과 내용을 기반으로 임베딩을 생성하며 임베딩값을 vector 필드에 넣을 예정입니다.

컬렉션을 생성하면 attu WEB UI에서도 확인할 수 있습니다.

Milvus WEB UI

SBERT로 임베딩 생성

분류를 하려고 하는 데이터와 유사한 데이터를 기반으로 프롬프트를 구성하려고 합니다.

유사 데이터 기반 외부 지식이 더해진 프롬포트가 LLM에 더 좋은 결과를 얻을 수 있습니다.

유사한 데이터를 검색하기 위해 해당 내용을 임베딩해서 VectorDB에 저장해야 합니다.

이번 포스팅에서는 SBERT를 이용해서 임베딩을 생성합니다.

SBERT는 Sentence-BERT는 BERT를 기반으로 합니다.

문장 임베딩을 생성하는데 특화되어 있는 모델입니다.

문장 간의 유사도를 계산하기 위한 의미 있는 문장 임베딩을 생성할 때 주로 쓰입니다.

pip install sentence-transformers

from sentence_transformers import SentenceTransformer
model = SentenceTransformer('sentence-transformers/paraphrase-multilingual-mpnet-base-v2')

다국어지원이 가능하며 가장 범용적인 paraphrase-multilingual-mpnet-base-v2를 사용합니다.

encode 함수를 사용하면 쉽게 임베딩값을 생성할 수 있습니다.

# 전체 텍스트 임베딩 생성
# 제목과 내용 합치기
combined_texts = [f"{title} {content}"
                    for title, content in zip(df['title'], df['content'])]
# 임베딩 생성
text_vectors = model.encode(combined_texts)

컬렉션 스키마 구성은 id, title, content, category, vector 필드입니다.

id값은 primary key로 자동 생성하도록 설정하였습니다.

제목(title)과 내용(content)을 기반으로 주제(category)를 자동으로 분류하려고 합니다.

# 데이터 준비
titles = df['title'].tolist()
contents = df['content'].tolist()
categories = df['category'].tolist()

# 데이터 삽입
entities = [
    text_vectors.tolist(),
    titles,
    contents,
    categories
]
    
collection.insert(entities)

성공적으로 Milvus에 데이터를 넣으면 WEB UI에서도 확인할 수 있습니다.

정리

이번 포스팅에서는 RAG와 LLM을 활용해 자동분류하기 첫 번째 포스팅이었습니다.

VectorDB인 Milvus를 구성하였습니다.

SBERT를 이용해서 데이터에서 임베딩값을 생성해서 VectorDB에 저장하였습니다.

다음 포스팅에서는 오픈 소스 기반의 LLM을 서버에 구축해보도록 하겠습니다.

[참고사이트]

Run Milvus with Docker Compose | Milvus Documentation

Learn how to install Milvus standalone with Docker Compose. | v2.4.x

milvus.io

GitHub - zilliztech/attu: The GUI for Milvus

The GUI for Milvus. Contribute to zilliztech/attu development by creating an account on GitHub.

github.com

SentenceTransformers Documentation — Sentence Transformers documentation

www.sbert.net

[Trino] 너의 흔적을 기록하고 싶어 - 히스토리 데이터 영구 저장

천재보단범재 — Sun, 17 Nov 2024 15:10:51 +0900

Trino 히스토리 데이터 영구 저장

사내에서 빅데이터 쿼리에 뛰어난 성능을 보여주는 Trino를 활용하고 있습니다.

빅데이터 쿼리뿐만 아니라 다른 데이터베이스의 데이터끼리 조인이 가능합니다.

현재 쿠버네티스 환경에 Trino를 구성해서 사용하고 있습니다.

다만 한 가지 문제가 있었습니다.

presto 기반의 쿼리 엔진이라 메모리를 사용해서 로그성 데이터가 남지 않았습니다.

따로 벡엔드 데이터베이스를 가지지 않습니다.

Trino에서 쿼리 한 이력을 확인하는데 큰 제약이 있습니다.

하지만 방법은 없는 것이 아닙니다.

Trino에서 쿼리 이력을 저장할 수 있도록 제공해 주는데 따로 설정이 필요합니다.

이번 포스팅에서는 Trino에서 쿼리 이력을 따로 저장하는 방법을 정리하도록 하겠습니다.

Trino WEB UI

이번 포스팅에서는 쿠버네티스에서 Trino를 구성하는 것을 정리하지 않겠습니다.

구성하는 방법은 아래 포스팅을 참고해 주시길 바랍니다.

Trino 한번 써보겠습니다(1) - Kubernetes에 Trino 설치

Trino 한번 써보겠습니다(1) RDB에서 데이터를 조회할 때 SQL를 통해 조회하였습니다. 데이터는 방대해져서 빅데이터가 생겼고, RDB뿐만 아니라 Storage의 종류도 다양해졌습니다. 데이터 조회는 다양

developnote-blog.tistory.com

helm를 통해 쿠버네티스에서 쉽게 구성이 가능합니다.

물론 운영시에는 리소스 관리, 쿼리 옵션 등 디테일한 설정들이 필요합니다.

# helm을 통해서 trino를 쿠버네티스에 구성
$ helm install trino -n trino --create-namespace -f values-overrides.yaml ./
NAME: trino
LAST DEPLOYED: Sun Nov 17 05:52:25 2024
NAMESPACE: trino
STATUS: deployed
REVISION: 1
NOTES:
Get the application URL by running these commands:
  export NODE_PORT=$(kubectl get --namespace trino -o jsonpath="{.spec.ports[0].nodePort}" services trino)
  export NODE_IP=$(kubectl get nodes --namespace trino -o jsonpath="{.items[0].status.addresses[0].address}")
  echo http://$NODE_IP:$NODE_PORT
  
  
# 구성한 trino 확인  
$ kubectl get all -n trino
NAME                                     READY   STATUS    RESTARTS   AGE
pod/trino-coordinator-55c78798c9-bskql   1/1     Running   0          3m46s
pod/trino-worker-f7d84cbf9-7wb7j         1/1     Running   0          3m46s

NAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
service/trino          NodePort    10.101.139.23   <none>        8080:30450/TCP   3m46s
service/trino-worker   ClusterIP   None            <none>        8080/TCP         3m46s

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/trino-coordinator   1/1     1            1           3m46s
deployment.apps/trino-worker        1/1     1            1           3m46s

NAME                                           DESIRED   CURRENT   READY   AGE
replicaset.apps/trino-coordinator-55c78798c9   1         1         1       3m46s
replicaset.apps/trino-worker-f7d84cbf9         1         1         1       3m46s

NAME                                               REFERENCE                 TARGETS                                     MINPODS   MAXPODS   REPLICAS   AGE
horizontalpodautoscaler.autoscaling/trino-worker   Deployment/trino-worker   memory: <unknown>/80%, cpu: <unknown>/20%   1         3         1          3m46s

Trino를 구성하면 바로 WEB UI를 사용할 수 있습니다.

아래 이미지가 NodePort로 통해 외부에서 접속한 Trino WEB UI입니다.

보안 설정을 따로 하지 않았기 때문에 패스워드 없이 유저명을 무작위로 넣어서 접속 가능합니다.

trino web login

쿼리 툴인 Dbeaver로 Trino에 접속해서 쿼리 해보겠습니다.

dbeaver로 trino에 query

쿼리 결과를 Trino WEB UI에서 확인이 가능합니다.

백엔드 데이터베이스는 없지만 쿼리 이력을 메모리에 일부 저장하여 확인할 수 있게 해 줍니다.

Trino WEB UI에서 쿼리 확인

쿼리 아이디를 클릭하면 해당 쿼리의 상세한 정보를 확인할 수 있습니다.

관리자 입장에서 정말 유용한 기능입니다.

다만 쿼리 이력은 메모리에서 관리되기 때문에 최신 데이터만 볼 수 있습니다.

기본 설정에서는 영구적으로 저장하지 않습니다.

쿼리 이력이 얼마나 저장되는지는 아래 2가지 옵션값에 따라 달라집니다.

query.max-history
query.min-expire-age

query.max-history는 이력 데이터를 몇 개까지 저장할 것인가이며 디폴트값은 100입니다.

query.min-expire-age는 이력 데이터 저장 만료 시간을 나타내며 디폴트값은 15분입니다.

메모리에 활용하기 때문에 많은 데이터를 저장하고 있을 수 없습니다.

Trino Event Listener

쿼리 이력을 15분 기준으로만 본다면 이슈가 터지면 15분 만에 해결해야 합니다.

그렇다고 시간을 늘려서 메모리 사용률을 높이는 것은 부담이 됩니다.

Trino에서 Event Listener가 있어 해당 문제를 해결할 수 있습니다.

Trino에서 발생하는 이벤트에 대해서 리슨하고 있다가 필요한 후속 작업을 진행할 수 있습니다.

Trino 464 버전 기준으로 아래와 같은 Event Listener를 제공합니다.

HTTP Event Listener
Kafka Event Listener
MySQL Event Listener
OpenLineage Event Listener

MySQL Event Listener를 활용해서 쿼리 이력 데이터를 MySQL에 저장하려고 합니다.

MySQL Event Listener

MySQL에 Trino 이력 데이터를 넣을 데이터베이스와 접속할 유저를 생성해 줍니다.

MySQL 접속 정보를 Trino Event Listener 설정에 세팅해 주면 됩니다.

이번 포스팅에서는 Trino를 쿠버네티스에 Helm으로 구성하였기 때문에,

Helm values.yaml에 Event Listener 설정 값을 넣어줍니다.

eventListenerProperties:
- event-listener.name=mysql
- mysql-event-listener.db.url=jdbc:mysql://mysql-service.trino.svc.cluster.local:3306/trino?user=trino&password=trino

values.yaml을 수정하고 helm upgrade 하게 되면 configmap값에

event-listener.properties 부분이 추가되어 있습니다.

$ kubectl get cm -n trino trino-coordinator -o yaml
apiVersion: v1
data:
  config.properties: |
    coordinator=true
    node-scheduler.include-coordinator=false
    http-server.http.port=8080
    query.max-memory=4GB
    query.max-memory-per-node=1GB
    discovery.uri=http://localhost:8080
  event-listener.properties: |
    event-listener.name=mysql
    mysql-event-listener.db.url=jdbc:mysql://mysql-service.trino.svc.cluster.local:3306/trino?user=trino&password=trino

MySQL에 해당 데이터베이스에 접속하면 trino_queries 테이블이 생성되어 있습니다.

MySQL Trino history 테이블

MySQL Event Listener 세팅이 끝났으니 Trino에 쿼리를 날려보겠습니다.

쿼리 후 MySQL trino_queries 테이블을 확인해 보면 쿼리 이력 데이터가 저장된 것을 확인할 수 있습니다.

trino_queries 테이블의 데이터는 WEB UI에서 확인한 쿼리 데이터와 동일합니다.

정리

이번 포스팅에서는 Trino 쿼리 이력 데이터를 영구 저장하는 방법을 정리해 보았습니다.

기본 설정에서는 메모리에 일부만 가지고 있어 제한 사항이 있었습니다.

MySQL Event Listener 설정을 통해서 MySQL에 Trino 쿼리 이력을 별도로 저장할 수 있습니다.

Kafka Event Listener도 있기 때문에 Kafka에 저장 후 다양하게 활용하는 것도 좋을 거 같습니다.

[참고사이트]

Web UI — Trino 464 Documentation

Web UI Trino provides a web-based user interface (UI) for monitoring a Trino cluster and managing queries. The Web UI is accessible on the coordinator via HTTP or HTTPS, using the corresponding port number specified in the coordinator Config properties. It

trino.io

Query management properties — Trino 464 Documentation

query.max-history The maximum number of queries to keep in the query history to provide statistics and other information. If this amount is reached, queries are removed based on age.

trino.io

[Terraform] AWS EKS 한 번에 올리기(1) - VPC 구성

천재보단범재 — Sun, 3 Nov 2024 20:48:05 +0900

Terraform - VPC 구성

AWS EKS 한 번에 올리기(1)

이전에 Terraform을 통해서 Kubernetes 클러스터를 한 번에 구성한 적이 있습니다.

AWS EC2 인스턴스를 여러 개 생성해서 클러스터를 구성하였습니다.

명령어 한 번에 Kubernetes 설치하기 - Terraform으로 Kubernetes 설치

명령어 한 번에 Kubernetes 설치하기 개발 환경을 자주 구성하다 보니 Kubernetes Cluster를 구성하는 일이 많았습니다. Kubernetes Cluster 구성은 단계도 많고 쉽지 않아 할 때마다 새로웠습니다. 구성을 간

developnote-blog.tistory.com

EC2 인스턴스에 kubeadm를 이용해서 클러스터를 구성하였는데, AWS EKS라는 서비스가 존재합니다.

이번 포스팅에서는 Terraform을 통해서 AWS EKS를 손쉽게 구성해 보도록 하겠습니다.

이번 포스팅은 테라폼을 사용할 줄 아시는 분이 독자라 생각하고 작성하였습니다.

What is EKS?

EKS는 Elastic Kubernetes Service입니다.

명칭대로 AWS에서 제공하는 쿠버네티스 서비스입니다.

AWS 콘솔에서 손쉽게 구성할 수 있으며 다른 AWS 서비스와 쉽게 통합이 가능합니다.

쿠버네티스 클러스터에서 컨트롤 플레인 컴포넌트들은 Worker 노트와 Pod를 관리하는 중요한 역할을 합니다.

Kubernetse Control Plane

kube-apiserver
etcd
kube-scheduler
kube-controller-manager
cloud-controller-manager

EKS는 위 컨트롤 플레인 컴포넌트들을 직접 구성하지 않고 쿠버네티스 환경을 경험할 수 있게 해 줍니다.

사용자는 쿠버네티스 클러스터 관리 리소스를 최소화할 수 있습니다.

클러스터 규모도 자동으로 조정해 주기 때문에 리소스 관리 비용도 최소화할 수 있습니다.

AWS EKS

Terraform으로 VPC 구성

이제 테라폼을 활용하여 VPC를 구성해 보겠습니다.

VPC는 Virtual Private Cloud로 논리적으로 격리된 가상 네트워크입니다.

EKS용 VPC를 구성하여 EKS에 실행되는 서비스를 보안적으로 안전하게 구성할 수 있습니다.

퍼블릭 서브넷, 프라이빗 서브넷을 VPC에 구성해서 안전하게 구성합니다.

내부 통신만 필요한 것은 프라이빗 서브넷에 두어 외부에서 접근하지 못하도록 합니다.

AWS 권한 설정

테라폼으로 구성하기 전에 AWS 권한 설정이 필요합니다.

VPC를 구성할 수 있는 권한이 필요합니다.

AWS 콘솔 IAM 메뉴에서 AmazonEC2FullAcess 권한을 가진 유저를 생성합니다.

유저 생성 시 만들어지는 accesskey, secretkey를 따로 저장합니다.

AWS IAM - 유저 생성

테라폼을 실행할 서버에 AWS credentials 파일을 생성합니다.

credentials 파일에 명시된 유저의 권한으로 테라폼이 실행됩니다.

[eks]
aws_access_key_id = ************
aws_secret_access_key = ************************************

Terraform code

VPC 구성을 위한 테라폼 코드(tf 파일)는 아래와 같습니다.

VPC만 생성하는 것이 아니라 VPC 내에 필요한 구성요소들이 명시되어 있습니다.

아래 요소들이 아래 테라폼으로 구성됩니다.

VPC
public subnet, private subnet
elastic IP
internet gateway
nat gateway
route table

provider "aws" {
  region = "ap-northeast-2"
  shared_credentials_files = [".aws/credentials"]
  profile = "eks"
}

locals {
  azs             = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
}

resource "aws_vpc" "eks_vpc" {
  cidr_block = "10.0.0.0/16"
  enable_dns_hostnames = true

  tags = {
    Name = "eks-vpc"
  }
}

resource "aws_subnet" "eks_private_subnets" {
  count      = length(local.private_subnets)
  vpc_id     = aws_vpc.eks_vpc.id
  cidr_block = local.private_subnets[count.index]
  availability_zone = local.azs[count.index]

  tags = {
    Name = "eks-vpc-private-subnet-${count.index}"
  }
}

resource "aws_subnet" "eks_public_subnets" {
  count      = length(local.public_subnets)
  vpc_id     = aws_vpc.eks_vpc.id
  cidr_block = local.public_subnets[count.index]
  availability_zone = local.azs[count.index]
  map_public_ip_on_launch = true

  tags = {
    Name = "eks-vpc-public-subnet-${count.index}"
  }
}

resource "aws_eip" "lb" {
  domain = "vpc"

  tags = {
    Name = "eks-eip-lb"
  }
}

resource "aws_internet_gateway" "gw" {
  vpc_id = aws_vpc.eks_vpc.id

  tags = {
    Name = "eks-igw"
  }
}

resource "aws_nat_gateway" "ng" {
  allocation_id = aws_eip.lb.id
  subnet_id = aws_subnet.eks_public_subnets[0].id

  tags = {
    Name = "eks-nat-gateway"
  }
}

resource "aws_route_table" "public_route_table" {
  vpc_id = aws_vpc.eks_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }

  tags = {
    Name = "eks-public-route-table"
  }
}

resource "aws_route_table" "private_route_table" {
  vpc_id = aws_vpc.eks_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    nat_gateway_id = aws_nat_gateway.ng.id
  }

  tags = {
    Name = "eks-private-route-table"
  }
}

resource "aws_route_table_association" "a" {
  count = length(aws_subnet.eks_public_subnets)

  subnet_id      = aws_subnet.eks_public_subnets[count.index].id
  route_table_id = aws_route_table.public_route_table.id
}

resource "aws_route_table_association" "b" {
  count = length(aws_subnet.eks_private_subnets)

  subnet_id      = aws_subnet.eks_private_subnets[count.index].id
  route_table_id = aws_route_table.private_route_table.id
}

테라폼 코드 부분별로 간단하게 살펴보겠습니다.

AWS Provider를 통해 테라폼에서 AWS 리소스들을 생성할 수 있습니다.

terraform aws provider

리소스를 생성할 리전과 credentials 파일 위치를 설정하였습니다.

변수 설정에서는 생성할 VPC내 가용영역과 IP대역대를 지정하였습니다.

해당 VPC에는 3개의 가용영역에 각각 퍼블릭 서브넷과 프라이빗 서브넷을 구성할 예정입니다.

provider "aws" {
  region = "ap-northeast-2"
  shared_credentials_files = [".aws/credentials"]
  profile = "eks"
}

locals {
  azs             = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
}

다음은 VPC와 서브넷 구성입니다.

VPC 대역대를 10.0.0.0/16으로 지정하여 IP를 여유롭게 사용할 수 있도록 합니다.

DNS 호스트 네임을 활성해서 퍼블릭 IP주소가 할당될 때 DNS 주소를 제공하도록 설정합니다.

서브넷 대역대는 VPC 대역대 내에서 잘 분할하여 설정합니다.

3개의 가용영역에 적절하게 분배해서 설정합니다.

resource "aws_vpc" "eks_vpc" {
  cidr_block = "10.0.0.0/16"
  enable_dns_hostnames = true

  tags = {
    Name = "eks-vpc"
  }
}

resource "aws_subnet" "eks_private_subnets" {
  count      = length(local.private_subnets)
  vpc_id     = aws_vpc.eks_vpc.id
  cidr_block = local.private_subnets[count.index]
  availability_zone = local.azs[count.index]

  tags = {
    Name = "eks-vpc-private-subnet-${count.index}"
  }
}

resource "aws_subnet" "eks_public_subnets" {
  count      = length(local.public_subnets)
  vpc_id     = aws_vpc.eks_vpc.id
  cidr_block = local.public_subnets[count.index]
  availability_zone = local.azs[count.index]
  map_public_ip_on_launch = true

  tags = {
    Name = "eks-vpc-public-subnet-${count.index}"
  }
}

외부에서 접근할 수 있도록 EIP(Elastic IP)를 생성하여 고정 퍼블릭 IP를 만듭니다.

인터넷 게이트웨이를 생성하여 VPC과 인터넷 간의 통신이 가능하도록 합니다.

NAT 게이트웨이를 통해 프라이빗 서브넷에서도 인터넷을 접근(아웃바운드)할 수 있도록 생성합니다.

resource "aws_eip" "lb" {
  domain = "vpc"

  tags = {
    Name = "eks-eip-lb"
  }
}

resource "aws_internet_gateway" "gw" {
  vpc_id = aws_vpc.eks_vpc.id

  tags = {
    Name = "eks-igw"
  }
}

resource "aws_nat_gateway" "ng" {
  allocation_id = aws_eip.lb.id
  subnet_id = aws_subnet.eks_public_subnets[0].id

  tags = {
    Name = "eks-nat-gateway"
  }
}

라우트 테이블 생성하여 퍼블릭 서브넷과 프라이빗 서브넷에 맞춰서 연결합니다.

resource "aws_route_table" "public_route_table" {
  vpc_id = aws_vpc.eks_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }

  tags = {
    Name = "eks-public-route-table"
  }
}

resource "aws_route_table" "private_route_table" {
  vpc_id = aws_vpc.eks_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    nat_gateway_id = aws_nat_gateway.ng.id
  }

  tags = {
    Name = "eks-private-route-table"
  }
}

resource "aws_route_table_association" "a" {
  count = length(aws_subnet.eks_public_subnets)

  subnet_id      = aws_subnet.eks_public_subnets[count.index].id
  route_table_id = aws_route_table.public_route_table.id
}

resource "aws_route_table_association" "b" {
  count = length(aws_subnet.eks_private_subnets)

  subnet_id      = aws_subnet.eks_private_subnets[count.index].id
  route_table_id = aws_route_table.private_route_table.id
}

테라폼 실행

테라폼 코드 작성이 완료되었으면 테라폼을 실행합니다.

테라폼으로 AWS 리소스를 생성하기 전 init 명령어를 통해 로컬에 aws provider를 설치합니다.

$ terraform init

.terraform/providers/registry.terraform.io/hashicorp/aws

apply 명령어를 통해 테라폼 코드를 작성한대로 AWS 리소스를 생성합니다.

$ terraform apply

Plan: 18 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

aws_vpc.eks_vpc: Creating...
aws_eip.lb: Creating...
aws_eip.lb: Creation complete after 1s [id=eipalloc-0c438a05dbfb516c9]
aws_vpc.eks_vpc: Still creating... [10s elapsed]
aws_vpc.eks_vpc: Creation complete after 12s [id=vpc-08546d14e33143fc2]
aws_internet_gateway.gw: Creating...
aws_subnet.eks_public_subnets[2]: Creating...
aws_subnet.eks_public_subnets[0]: Creating...
aws_subnet.eks_private_subnets[2]: Creating...
aws_subnet.eks_private_subnets[0]: Creating...
aws_subnet.eks_private_subnets[1]: Creating...
aws_subnet.eks_public_subnets[1]: Creating...
aws_internet_gateway.gw: Creation complete after 1s [id=igw-0925ec8acc4cf4eb9]
aws_route_table.public_route_table: Creating...
aws_subnet.eks_private_subnets[0]: Creation complete after 1s [id=subnet-0dc7696400c64ee6a]
aws_subnet.eks_private_subnets[1]: Creation complete after 1s [id=subnet-0ad16d11e629ea4fc]
aws_subnet.eks_private_subnets[2]: Creation complete after 1s [id=subnet-002dc8a5f514902ab]
aws_route_table.public_route_table: Creation complete after 0s [id=rtb-0edf0e378dcac2344]
aws_subnet.eks_public_subnets[0]: Still creating... [10s elapsed]
aws_subnet.eks_public_subnets[2]: Still creating... [10s elapsed]
aws_subnet.eks_public_subnets[1]: Still creating... [10s elapsed]
aws_subnet.eks_public_subnets[0]: Creation complete after 11s [id=subnet-0716da3c33da7d83b]
aws_nat_gateway.ng: Creating...
aws_subnet.eks_public_subnets[1]: Creation complete after 11s [id=subnet-0a22fde8e2c65d603]
aws_subnet.eks_public_subnets[2]: Creation complete after 11s [id=subnet-05d18452d0c126bb8]
aws_route_table_association.a[0]: Creating...
aws_route_table_association.a[2]: Creating...
aws_route_table_association.a[1]: Creating...
aws_route_table_association.a[0]: Creation complete after 1s [id=rtbassoc-084e25393b0fede4a]
aws_route_table_association.a[1]: Creation complete after 1s [id=rtbassoc-071910372228a5d37]
aws_route_table_association.a[2]: Creation complete after 1s [id=rtbassoc-0883eabf4615e371b]
aws_nat_gateway.ng: Still creating... [10s elapsed]
aws_nat_gateway.ng: Still creating... [20s elapsed]
aws_nat_gateway.ng: Still creating... [30s elapsed]
aws_nat_gateway.ng: Still creating... [40s elapsed]
aws_nat_gateway.ng: Still creating... [50s elapsed]
aws_nat_gateway.ng: Still creating... [1m0s elapsed]
aws_nat_gateway.ng: Still creating... [1m10s elapsed]
aws_nat_gateway.ng: Still creating... [1m20s elapsed]
aws_nat_gateway.ng: Still creating... [1m30s elapsed]
aws_nat_gateway.ng: Still creating... [1m40s elapsed]
aws_nat_gateway.ng: Still creating... [1m50s elapsed]
aws_nat_gateway.ng: Still creating... [2m0s elapsed]
aws_nat_gateway.ng: Still creating... [2m10s elapsed]
aws_nat_gateway.ng: Creation complete after 2m14s [id=nat-0f1e77a57fae54110]
aws_route_table.private_route_table: Creating...
aws_route_table.private_route_table: Creation complete after 1s [id=rtb-0688a4d80ce4e125f]
aws_route_table_association.b[0]: Creating...
aws_route_table_association.b[1]: Creating...
aws_route_table_association.b[2]: Creating...
aws_route_table_association.b[0]: Creation complete after 1s [id=rtbassoc-0b1cef740bd15a0b0]
aws_route_table_association.b[2]: Creation complete after 1s [id=rtbassoc-0705d817199bc9013]
aws_route_table_association.b[1]: Still creating... [10s elapsed]
aws_route_table_association.b[1]: Creation complete after 14s [id=rtbassoc-024f88f74a71b09ef]

Apply complete! Resources: 18 added, 0 changed, 0 destroyed.

정상적으로 생성이 되었으면 AWS 콘솔에서 VPC 생성이 확인 가능합니다.

EKS용 VPC가 생성되었고 3개의 가용영역에 각각 2개의 서브넷이 생성된 것을 확인할 수 있습니다.

퍼블릭 서브넷 3개, 프라이빗 서브넷 3개 총 6개의 서브넷이 생성된 것을 확인할 수 있습니다.

각 서브넷 대역대가 겹치지 않는 것을 확인할 수 있습니다.

라우트 테이브에 보면 각 인터넷 게이트웨이와 NAT 게이트웨이 설정된 것을 확인할 수 있습니다.

프라이빗 서브넷에 EC2를 생성해보았습니다.

EC2가 생성되고 퍼블릭 IP가 설정되어 있지 않은 것을 확인할 수 있습니다.

정리

이번 포스팅에서는 테라폼을 통해 AWS VPC를 구성해 보았습니다.

VPC를 위한 테라폼 코드를 작성해 보면서 VPC의 구성요소에 대해 정리해 볼 수 있었습니다.

다음 포스팅에서는 테라폼을 통해 AWS EKS를 구성해 보겠습니다.

[참고사이트]

Install Terraform | Terraform | HashiCorp Developer

Install Terraform on Mac, Linux, or Windows by downloading the binary or using a package manager (Homebrew or Chocolatey). Then create a Docker container locally by following a quick-start tutorial to check that Terraform installed correctly.

developer.hashicorp.com

Terraform Registry

registry.terraform.io

Amazon EKS란 무엇입니까? - Amazon EKS

이 페이지에 작업이 필요하다는 점을 알려 주셔서 감사합니다. 실망시켜 드려 죄송합니다. 잠깐 시간을 내어 설명서를 향상시킬 수 있는 방법에 대해 말씀해 주십시오.

docs.aws.amazon.com

[AWS] VPC를 생성할 때 고려할 점.

클라우드 사용하는 목적이 무엇이 됐건 VPC(Virtual Private Cloud)를 생성하는 것이 가장 기본이 아닌가 싶다. VPC를 만들고자 한다면 크게 다음 4가지를 거쳐야 한다. VPC라는 가상의 데이터센터를 생성

bosungtea9416.tistory.com