AWS 인프라 구성 가이드

AWS EKS 환경에서 Skuber+ Observability를 구축하기 위한 인프라 구성 가이드입니다.
설치 전에 이 문서의 모든 항목을 완료해야 합니다.

인프라 구성도

리소스 요약

EKS Cluster (Host)

Skuber+ Observability의 Host 컴포넌트를 배포할 전용 EKS Cluster를 새로 생성하는 것을 권장합니다.
기존 워크로드와의 리소스 경합을 방지하고, 독립적인 운영이 가능합니다.

EKS Cluster 생성 절차는 AWS 공식 문서를 참조하세요.
노드 사양은 요구사항 문서의 Host Cluster 요구사항을 확인하세요.

EC2 인스턴스 생성

ClickHouse VM

Data Volume 마운트 (필수, 고객사 직접 수행): Data Volume은 /var/lib/clickhouse 경로에 마운트해야 합니다.
설치 도구(skuberplus-observability-db)는 마운트된 경로를 사용하며, 마운트를 자동으로 수행하지 않습니다.
ClickHouse 설치 전에 반드시 마운트를 완료하세요.

마운트 예시:

# 1. 파일시스템 생성 (최초 1회)
sudo mkfs.ext4 /dev/nvme1n1

# 2. 마운트 포인트 생성 및 마운트
sudo mkdir -p /var/lib/clickhouse
sudo mount /dev/nvme1n1 /var/lib/clickhouse

# 3. 재부팅 시 자동 마운트 (fstab 등록)
echo '/dev/nvme1n1 /var/lib/clickhouse ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab

# 4. 마운트 확인
df -h /var/lib/clickhouse

디바이스 이름(/dev/nvme1n1)은 실제 환경에 맞게 변경하세요. lsblk 명령으로 확인할 수 있습니다.

Keeper VM

Keeper는 별도 Data Volume이 필요하지 않습니다. Root Volume에 데이터를 저장합니다.

Network Load Balancer (NLB)

Host Cluster에서 ClickHouse VM으로 접근하기 위해 Internal NLB가 필요합니다.

NLB 생성

리스너 설정

Target Group 설정

Target 등록

NLB 생성 후, ClickHouse VM의 Private IP를 Target Group에 등록합니다.

NLB의 DNS 이름 또는 IP는 Host Cluster 설치 시 externalClickhouse.host 값으로 사용됩니다.
설치 전에 NLB DNS를 확인하여 메모해두세요.

Security Group

SG-ClickHouse

ClickHouse VM에 적용하는 Security Group입니다.

Outbound ALL을 제한하는 환경에서는 Host Cluster OTel Gateway로 TCP 4317 (OTLP gRPC) 아웃바운드를 명시적으로 허용해야 합니다. CH VM의 OTel Agent가 메트릭을 전송합니다.

SG-Keeper

ClickHouse Keeper VM에 적용하는 Security Group입니다.

SG-NLB (참고용)

NLB에는 별도 Security Group이 적용되지 않지만, NLB가 위치한 서브넷의 NACL에서 아래 트래픽이 허용되어야 합니다.

VPC / Subnet

Host Cluster(EKS)와 ClickHouse VM이 서로 다른 VPC에 있는 경우, VPC Peering 또는 Transit Gateway를 통해 네트워크를 연결해야 합니다.

IAM 권한

설치 시 필요한 권한 (Installer)

설치 담당자(사용자 또는 Role)가 보유해야 하는 최소 권한입니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EKSDescribeCluster",
      "Effect": "Allow",
      "Action": ["eks:DescribeCluster"],
      "Resource": "arn:aws:eks:REGION:ACCOUNT_ID:cluster/CLUSTER_NAME"
    }
  ]
}

REGION, ACCOUNT_ID, CLUSTER_NAME을 실제 값으로 교체하세요.

런타임 권한 — AWS Load Balancer Controller (IRSA)

Host Cluster에서 NLB를 Kubernetes Service로 자동 프로비저닝하려면 AWS Load Balancer Controller와 IRSA(IAM Role for Service Account)가 필요합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ELBDescribe",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeInstances",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeTags",
        "elasticloadbalancing:Describe*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ELBManage",
      "Effect": "Allow",
      "Action": [
        "elasticloadbalancing:CreateLoadBalancer",
        "elasticloadbalancing:CreateTargetGroup",
        "elasticloadbalancing:CreateListener",
        "elasticloadbalancing:CreateRule",
        "elasticloadbalancing:DeleteLoadBalancer",
        "elasticloadbalancing:DeleteTargetGroup",
        "elasticloadbalancing:DeleteListener",
        "elasticloadbalancing:DeleteRule",
        "elasticloadbalancing:Modify*",
        "elasticloadbalancing:RegisterTargets",
        "elasticloadbalancing:DeregisterTargets",
        "elasticloadbalancing:AddTags",
        "elasticloadbalancing:RemoveTags",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:CreateTags",
        "ec2:DeleteTags"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ServiceLinkedRole",
      "Effect": "Allow",
      "Action": ["iam:CreateServiceLinkedRole"],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "iam:AWSServiceName": "elasticloadbalancing.amazonaws.com"
        }
      }
    }
  ]
}

런타임 권한 — EBS CSI Driver (IRSA)

ClickHouse 데이터용 EBS 볼륨을 Kubernetes에서 관리하려면 EBS CSI Driver와 IRSA가 필요합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EBSDescribe",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeInstances",
        "ec2:DescribeSnapshots",
        "ec2:DescribeTags",
        "ec2:DescribeVolumes",
        "ec2:DescribeVolumesModifications"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EBSManage",
      "Effect": "Allow",
      "Action": [
        "ec2:CreateSnapshot",
        "ec2:CreateTags",
        "ec2:CreateVolume",
        "ec2:DeleteSnapshot",
        "ec2:DeleteTags",
        "ec2:DeleteVolume",
        "ec2:ModifyVolume",
        "ec2:AttachVolume",
        "ec2:DetachVolume"
      ],
      "Resource": "*"
    }
  ]
}

S3 스토리지 티어링 (선택)

S3 Warm/Cold 스토리지를 사용하면 오래된 데이터를 S3로 자동 이동하여 로컬 디스크 사용량을 줄일 수 있습니다.
S3 티어링은 선택 사항이며, 설치 후 UI에서 활성화할 수 있습니다.

S3 버킷 준비

IAM 사용자 + Access Key 발급

ClickHouse VM에서 S3에 접근하기 위해 IAM 사용자의 Access Key를 사용합니다.

Step 1. IAM 사용자 생성 (프로그래매틱 접근용)

Step 2. 아래 정책을 사용자에게 연결

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3TieringAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

YOUR_BUCKET_NAME을 실제 버킷 이름으로 교체하세요.

Step 3. Access Key ID + Secret Access Key 발급 후 안전하게 보관

발급된 Access Key는 Skuber+ Observability UI의 S3 설정 화면에서 입력합니다.
자세한 설정 방법은 데이터 보존 문서를 참조하세요.

방화벽 규칙

Kubernetes Worker Nodes → 외부

ClickHouse VM → 외부

규칙 6번의 REGION은 S3 버킷이 위치한 리전으로 교체하세요 (예: ap-northeast-2).

연결 검증

방화벽 오픈 후 아래 명령어로 연결을 검증합니다.

1. Registry 연결 테스트 (K8s Worker Node에서 실행):

curl -v https://registry.skuberplus.com/v2/

2. 이미지 Pull 테스트:

docker pull registry.skuberplus.com/observability/skuber-alpine:3.18.2

3. Helm 차트 Pull 테스트:

helm pull oci://registry.skuberplus.com/charts/skuber-otel-operator --version 1.0.1

4. ClickHouse VM에서 S3 연결 테스트 (S3 사용 시):

aws s3 ls s3://YOUR_BUCKET_NAME --region REGION

사전 점검 목록

설치 전에 아래 항목을 모두 완료했는지 확인합니다.

• ClickHouse EC2 인스턴스 생성 완료
• Keeper EC2 인스턴스 생성 완료
• ClickHouse Data Volume 마운트 완료 (/var/lib/clickhouse)
• EKS Cluster (Host) 생성 완료
• NLB 생성 완료 (Internal, TCP 9000/8123)
• NLB Target Group에 ClickHouse VM Private IP 등록
• NLB DNS 이름 확인 및 메모
• Security Group 규칙 적용 완료 (SG-ClickHouse, SG-Keeper)
• IAM 정책 적용 완료 (Installer, LB Controller, EBS CSI)
• 방화벽 규칙 적용 완료 (registry.skuberplus.com 등)
• 방화벽 연결 검증 완료
• (S3 사용 시) S3 버킷 생성 완료
• (S3 사용 시) IAM 사용자 생성 + Access Key 발급 완료
• (S3 사용 시) ClickHouse VM → S3 연결 검증 완료

다음 단계

인프라 구성이 완료되면 설치를 진행합니다:

1. 설치 가이드 — 전체 설치 가이드
2. Host 클러스터 설치 — 중앙 수집 서버 설치
3. Agent 클러스터 설치 — 모니터링 대상 클러스터 설치

문의

기술 지원 문의: sales@skuberplus.com