LOGPOSE

[함수형 리팩터링] 비동기 전환을 고려한 공유 Mutable 제거

LOGPOSE 로그포스 — Thu, 5 Feb 2026 18:08:39 +0900

배경

이번 리팩터링 목적은 코드 내 작업을 비동기적으로 바꾸기 전에 문제(race, 흐름 의존성)를 제거하는 것이다.
그 방법은 기존 코드에 함수형 패러다임을 적용하는 것이다. 상태 변경을 줄이고, 행동을 조합 가능하게 만들 것이다.

0. 기존 코드

아래 코드는 이미지 첨부파일 리스트를 가져와서 NCloud Green Eye를 통해 각 첨부파일에 대해 유해성 판별을 한다.
현재는 이 작업이 .block() 기반 순차 처리라 race가 표면화되진 않지만, 비동기 전환 시 공유 리스트에 대한 동시 접근이 생길 수 있어 구조적으로 위험해진다. 또한, for문 내에서 흐름 제어와 계산 로직이 묶여 테스트가 어려웠다.

참고) 비동기 전환을 고려하는 이유는 외부 API요청에 대해 굳이 쓰레드를 점유하게 하고 싶지 않은 점이다.
본질적으로 WebClient가 non-blocking 사용을 전제로 설계되어 이러한 전환이 바람직해 보인다.

@Override
public List<FeedAttachment> findBadImageListByAI(List<FeedAttachment> feedAttachmentList) {
    log.info("feedAttachmentList={}", feedAttachmentList);

    WebClient client = WebClient.create(apigwUrl);
    List<FeedAttachment> badImageList = new ArrayList<>();

    // Green Eye 유해성 판별은 요청 1회당 1개의 이미지만 가능
    for (FeedAttachment feedAttachment : feedAttachmentList) {

        if (!feedAttachment.isActivated()) continue;

        String requestBody = """
            {
              "version": "V1",
              "requestId": "%s",
              "timestamp": 0,
              "images": [
                {
                  "name": "%s",
                  "url": "%s"
                }
              ]
            }
            """.formatted(
                feedAttachment.getAttachmentId(),
                feedAttachment.getAttachmentId(),
                feedAttachment.getFileUrl()
            );

        try {
            JSONObject response = new JSONObject(
                client.post()
                    .header(GREENEYE_SECRET_KEY_HEADER, this.secretKey)
                    .header("Content-Type", "application/json")
                    .bodyValue(requestBody)
                    .retrieve()
                    .onStatus(status -> status.is4xxClientError(), ClientResponse::createException)
                    .bodyToMono(String.class)
                    .block()
            );

            if (checkHarmful(response)) {
                badImageList.add(feedAttachment);
            }

        } catch (Exception e) {
            System.err.println("GreenEye 요청이 잘못됨: " + e.getMessage());
        }
    }

    return badImageList;
}

1. 리팩터링 포인트 (문제점)

그러나 요청을 비동기적으로 바꿀 때 미리 검토할 사항이 있었다.

1) badImageList의 공유 mutable 상태

List<FeedAttachment> badImageList = new ArrayList<>();
...
badImageList.add(feedAttachment);

badImageList는 외부에서 관찰 가능한 mutable state이며, continue/try-catch/checkHarmful 분기마다 add 수행 여부가 달라져 변경 지점이 분산되고 테스트가 어려워진다.(로직이 바뀌면 add 시점이 바뀌므로, 디버깅 어려움)

다르게 말하면, 이 리스트가 언제 어떤 값으로 바뀌는지 직접 추론해야한다.

특히 비동기 처리(예: subscribe, flatMap, CompletableFuture 등)로 전환하면, 여러 실행 흐름이 동일 리스트에 접근해 add()를 수행할 수 있어 race condition이 발생할 여지가 커진다.

2) 로직이 하나의 블록으로 뭉쳐 있음

외부 API 호출
requestBody 생성
응답 파싱
harmful 판단
결과 수집(상태 변경)
활성화 여부 체크

이게 모두 for 문 안에 섞여 있어, 각 단계가 다음 단계에 강하게 의존(조립 불가)한다.
테스트가 어려운 거대한 블록 형태인데, 개별 단계를 테스트 가능한 작은 함수로 나눌 수 있어 보인다.

2. 리팩터링 목표 (방향성)

공유 mutable 상태 제거, 상태 변경 최소화
테스트 가능한 작은 함수로 각 단계를 분리

참고) Java 코드인 만큼, 모든 코드가 클래스 안에 있어 '함수'개념은 없긴 하다. 사실상 구현 형태는 전부 메서드이기 때문이다.
다만, 여기서 함수로 분리한다는 말은 메서드를 객체 상태에 의존하지 않도록 설계해 함수처럼 사용하는 것을 의미한다.

3. 리팩터링 된 코드 (결과)

함수형 스타일 본문

@Override
public List<FeedAttachment> findBadImageListByAI(List<FeedAttachment> feedAttachmentList) {

    WebClient client = WebClient.create(apigwUrl);

    return feedAttachmentList.stream()
        // 1) 활성화된 이미지만
        .filter(FeedAttachment::isActivated)

        // 2) 유해 판별 규칙(조합 가능한 Boolean Predicate)
        .filter(attachment -> isHarmfulAttachment(client, attachment))

        // 3) 한 번에 결과 수집 (중간 상태 변경 없음)
        .toList();
}

for문 내에서 흐름 제어와 계산 로직이 묶여 가변(badImageList)되던 중간 상태를 없앴다.
외부 API요청 및 유해성 판단 로직을 캡슐화하여 toList() 전까지의 파이프라인에서는 조합 가능한(filter) Boolean 반환 로직만 드러나게 했다.
결과 리스트를 직접 add()하지 않고 toList()에 수집을 위임해서 마지막에만 최종 리스트를 리턴하게 했다.

API 호출 및 유해 여부 판별 분리

private boolean isHarmfulAttachment(WebClient client, FeedAttachment attachment) {
    return callGreenEye(client, attachment)
        .map(this::checkHarmful)
        .orElse(false);
}

private Optional<JSONObject> callGreenEye(WebClient client, FeedAttachment feedAttachment) {
    try {
        String requestBody = createRequestBody(feedAttachment);

        String result = client.post()
            .header(GREENEYE_SECRET_KEY_HEADER, this.secretKey)
            .header("Content-Type", "application/json")
            .bodyValue(requestBody)
            .retrieve()
            .bodyToMono(String.class)
            .block();

        return Optional.of(new JSONObject(result));

    } catch (Exception e) {
        log.error("GreenEye error attachmentId={} msg={}",
            feedAttachment.getAttachmentId(),
            e.getMessage()
        );
        return Optional.empty();
    }
}

실패가 발생하면 예외나 null 대신 Optional.empty()로 "값이 없다"를 표현한다.
즉, callGreenEye는 성공/실패에 대한 사실만 전달한다.
외부 네트워크·서버 상태 등 외부 변수에 의존하므로 pure function으로 만들지는 못했지만, effect 경계를 분리했으므로 조금 더 예측 가능한 형태가 되었다고 생각한다.

RequestBody 생성 분리

private String createRequestBody(FeedAttachment feedAttachment) {
    return """
       {
         "version": "V1",
         "requestId": "%s",
         "timestamp": 0,
         "images": [
           {
             "name": "%s",
             "url": "%s"
           }
         ]
       }
       """.formatted(
            feedAttachment.getAttachmentId(),
            feedAttachment.getAttachmentId(),
            feedAttachment.getFileUrl()
    );
}

이 부분의 의의는 Pure function으로 분리했다는 점이다.
생각 비용(?)이 0이다! (같은 입력에 대해 같은 출력)

마무리

공유 mutable List를 직접 변경하지 않는다 (add 제거)
각 FeedAttachment 요소는 결과 리스트를 변경하는 주체가 아니라, filter 조건을 통과할지 여부만 평가되는 값으로 취급된다.
side effect가 발생하는 로직을 함수형으로 분리하고, pure function만 스트림 단계에 남겨 조합했다. 결과는 마지막에 한 번만 List로 수집해 리턴한다.

이제 아래와 같이 비동기로 작업을 수행할 수 있다.

public Mono<List<FeedAttachment>> findBadImageListByAIAsync(List<FeedAttachment> list) {
    WebClient client = WebClient.create(apigwUrl);

    return Flux.fromIterable(list)
        .filter(FeedAttachment::isActivated)
        .filterWhen(att -> callGreenEyeAsync(client, att)
            .map(this::checkHarmful)
            .onErrorReturn(false)
        )
        .collectList();
}

비동기 전환 시 race condition이 우려되는 공유 mutable 상태를 구조적으로 제거했다.
상태를 누적하는 방식 대신 조건을 조합하는 방식으로 로직을 재구성함으로써, 기존보다 예측 가능한 코드를 만들었다.

[(Kubeadm) K8s 클러스터 구축 3/3] Kubeadm init 및 Node join

LOGPOSE 로그포스 — Thu, 16 Oct 2025 20:00:08 +0900

[(Kubeadm) K8s 클러스터 구축 2/3] Kubeadm, Kubelet, Kubectl 설치

[(Kubeadm) K8s 클러스터 구축 1/3] Container Runtime 설치개요kubeadm 기반으로 K8s클러스터를 구축하는 과정을 3편의 글로 요약해 본다.가용 Virtual Machine이 2대 이상(각 Machine의 메모리 2GB, 2 CPU 이상) 준비됐

crayeji.tistory.com

앞선 글 [01. Container Runtime(Containerd) 구성]와 [02. Kubeadm, Kubelet, Kubectl 설치]에서
Container Runtime 및 kubeadm, kubelet, kubectl 설치가 마쳐져 있어야 한다.

Kubeadm Init 하기 전 설정

1. Memory Swap 비활성화 (Master, Worker Node 모두)

Kubernetes v1.33에서 kubelet은 swap(스왑 메모리)이 켜져 있으면 기본적으로 실행을 거부한다고 언급되었다.
kubelet이 적절하게 동작하도록 swap을 비활성화했다.

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

2. 방화벽 K8s관련 포트 열기 (Master, Worker Node 각각)

# Master
sudo ufw allow 6443/tcp
sudo ufw allow 2379:2380/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 10257/tcp
sudo ufw allow 10259/tcp

# Worker
sudo ufw allow 10250/tcp
sudo ufw allow 30000:32767/tcp

* CNI/Pod 네트워크로 열어야 하는 포트는 CNI 플러그인(Flannel, Calico, Cilium 등)에 따라 다르므로 별도 설정이 필요할 수 있다.

3. IPv4 패킷 포워딩 켜기 (Master, Worker Node 모두)

K8s는 Pod 간 네트워크를 만들기 위해 노드에서 패킷을 다른 인터페이스로 전달해야 한다.
이때, 리눅스 커널의 IP포워딩(net.ipv4.ip_forward)이 기본적으로 비활성화되어 있으니, Pod 간 통신&라우팅이 가능하도록 활성화한다.

# 설정 파일을 열어 net.ipv4.ip_forward=1 주석 해제 또는 추가
sudo vim /etc/sysctl.conf

# 설정 파일 변경 내용을 커널에 즉시 반영
sudo sysctl -p

Kubeadm Init

Init (Master Node)

sudo kubeadm init --pod-network-cidr=192.168.0.0/16

출력된 join 명령어를 복사해 두자. (추후 Worker Node join 단계에서 복붙 할 것이다.)

Pod Network CIDR은 CNI에 따라 달라지는데, 이 글에서는 Calico를 사용하므로

Calico 공식 문서에서 제공하는 IP Pool 범위 192.168.0.0/16를 써줬다. (256x256=약 65000)

# 참고
실행 후 kubeadm이 하는 일:
- etcd 초기화 (클러스터 저장소)
- API Server / Controller Manager / Scheduler kube-system 네임스페이스에 Pod로 배포
- kubeconfig 생성 (/etc/kubernetes/admin.conf)
- Worker Node가 붙을 수 있는 kubeadm join 명령어 출력

Kubeconfig Setting (Master Node) (선택)

kubectl은 기본적으로 $HOME/.kube/config 파일을 찾아
클러스터의 접근 정보(클러스터 주소, 인증서, 사용자 계정 등)를 로드한다.
따라서 해당 경로에 기본으로 사용할 kubeconfig 파일을 복사해 두면,
kubectl이 별도 옵션(--kubeconfig) 없이 바로 클러스터와 통신할 수 있다.

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Worker node Join

Worker Node를 클러스터에 Join 하자.
앞서 init시 복사해 뒀던 명령어를 복붙 한다.

#복붙해뒀던 join 명령
kubeadm join <MASTER_IP>:6443 --token <TOKEN> \
--discovery-token-ca-cert-hash sha256:<CA SHA256 HASH>

참고) 복사해 둔 게 없을 경우, 아래 명령을 통해 토큰 재발급과 동시에 join명령어를 그대로 다시 받을 수 있다.
(물론 kubeadm token list로 기존 토큰을 조회할 수도 있다.)

sudo kubeadm token create --print-join-command

Master에서 클러스터 상태 확인

kubectl get nodes

이제 kubectl명령으로 클러스터의 노드들을 확인할 수 있다.
다만, Status는 NotReady로 뜰 텐데, CNI가 아직 설치되지 않았기 때문이다.

CNI(네트워크 플러그인) 설치

NetworkPolicy를 지원하는 Calico를 선택했다.

### crd 설치
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.30.3/manifests/tigera-operator.yaml

### cr 리소스 create
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.30.3/manifests/custom-resources.yaml

이제 kubectl get nodes를 해보면 노드들이 Ready로 뜨며, 작업 가능한 K8s 클러스터 구성이 완료됐다.

[(Kubeadm) K8s 클러스터 구축 2/3] Kubeadm, Kubelet, Kubectl 설치

LOGPOSE 로그포스 — Wed, 15 Oct 2025 20:00:13 +0900

[(Kubeadm) K8s 클러스터 구축 1/3] Container Runtime 설치

개요kubeadm 기반으로 K8s클러스터를 구축하는 과정을 3편의 글로 요약해 본다.가용 Virtual Machine이 2대 이상(각 Machine의 메모리 2GB, 2 CPU 이상) 준비됐다고 가정한다.첫 단계로 Container Runtime을 설치한

crayeji.tistory.com

앞선 글에서 노드들에 Pod가 실행될 수 있게 Container Runtime을 설치했다.

이번 글에서는 클러스터를 구성하고 초기화하기 위한 kubeadm, 각 노드에서 K8s API 서버 명령을 받아 Pod을 관리하고 Container Runtime이 컨테이너를 실행하게 하는 에이전트 kubelet, 사용자가 API 서버를 통해 명령할 수 있는 CLI인 kubectl을 설치해 본다.

Master Node에 kubeadm, kubelet, kubectl을 설치할 것이며
Worker Node에는 kubeadm, kubelet을 설치할 것이다. kubectl은 설치하지 않을 것이다.

Kubernetes v1.33을 기준으로 한다.
kubeadm은 kubelet과 kubectl의 설치나 관리를 책임지지 않으므로, 버전 호환성 등에 대해서는 확인해야 한다.

작업 위치: Master Node & Worker Node

GPG 키를 등록하고 K8s 공식 apt 저장소를 추가하여 패키지 설치를 준비한다.
(Master Node, Worker Node모두 패키지들을 설치해야 하므로, 동일 작업을 각각에 진행한다.)

# 패키지 설치 준비
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

# Kubernetes 패키지(kubeadm, kubelet, kubectl)검증을 위한 공개키(GPG key)등록
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# K8s APT repository를 시스템에 등록
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

작업 위치: Master Node

kubeadm, kubelet, kubectl 설치

sudo apt-get update
sudo apt-mark unhold kubelet kubeadm kubectl
sudo apt-get install -y kubelet kubeadm kubectl# worker node는 kubectl제외
sudo apt-mark hold kubelet kubeadm kubectl# worker node는 kubectl제외

sudo systemctl enable --now kubelet

작업 위치: Worker Node

kubeadm, kubelet 설치

sudo apt-get update
sudo apt-mark unhold kubelet kubeadm
sudo apt-get install -y kubelet kubeadm 
sudo apt-mark hold kubelet kubeadm

sudo systemctl enable --now kubelet

[(Kubeadm) K8s 클러스터 구축 1/3] Container Runtime 설치

LOGPOSE 로그포스 — Tue, 14 Oct 2025 20:00:55 +0900

개요

kubeadm 기반으로 K8s클러스터를 구축하는 과정을 3편의 글로 요약해 본다.

가용 Virtual Machine이 2대 이상(각 Machine의 메모리 2GB, 2 CPU 이상) 준비됐다고 가정한다.

첫 단계로 Container Runtime을 설치한다. Containerd를 사용한다.

1. Container Runtime 설치

Step 1. Containerd 설치

설명

Pod가 Node에서 실행될 수 있게, 클러스터의 노드들에 Container Runtime을 설치한다.
CRI를 통해 Container Runtime에 K8s가 인터페이스 한다. 이 글에서는 Containerd라는 Container Runtime을 설치해 본다.

Getting-started 문서의 Containerd 설치 방법 중 Option1(=Official binaries를 이용해 설치하기)을 따라 진행한다.

공식 바이너리 릴리스(빌드 완료된 실행 파일)로 설치 ✅
apt/dnf 패키지를 이용한 설치
소스 코드로부터 빌드하여 설치

아카이브에서 아래 버전, OS, 컴퓨터 아키텍처(ARM64, AMD64 등)를 선택해 다운로드하면 된다.

공식 바이너리 패키지, 무결성 검증 파일 2개를 다운로드하여 무결성 검사 진행 후 압축 해제를 하자.

설치 참고

#파일명
containerd-<VERSION>-<OS>-<ARCH>.tar.gz #공식 바이너리
containerd-<VERSION>-<OS>-<ARCH>.tar.gz.sha256sum #무결성 검사

#예시) VM에서 Linux 운영체제로 aarch64(=ARM64)를 사용중이므로 아래와 같이 선택
containerd-2.1.4-linux-arm64.tar.gz
containerd-2.1.4-linux-arm64.tar.gz.sha256sum

설치 명령어

### 다운로드
wget https://github.com/containerd/containerd/releases/download/v2.1.4/containerd-2.1.4-linux-arm64.tar.gz
wget https://github.com/containerd/containerd/releases/download/v2.1.4/containerd-2.1.4-linux-arm64.tar.gz.sha256sum

### sha256 무결성 검증
sha256sum -c containerd-2.1.4-linux-arm64.tar.gz.sha256sum

### 압축 해제
sudo tar Cxzvf /usr/local containerd-2.1.4-linux-arm64.tar.gz

Start containerd via systemd

containerd를 systemd 서비스로 등록했다.
즉, Containerd 프로세스도 systemd가 생성한 cgroup에서 실행되게 한다.

# 아래 경로에 설정
sudo mkdir -p /usr/local/lib/systemd/system
cd /usr/local/lib/systemd/system

# containerd.service 파일을 링크로 설치하기
sudo wget https://raw.githubusercontent.com/containerd/containerd/main/containerd.service

# 적용 및 확인
sudo systemctl daemon-reload # 새 유닛 파일 읽기
sudo systemctl enable --now containerd # 부팅 시 자동 실행
systemctl status containerd # 확인

Customizing containerd

containerd는 daemon level의 옵션을 지정하기 위해 /etc/containerd/config.toml 파일을 사용한다.

Cgroup 설정(SystemdCgroup = true)이 필요할 수 있다. 컨테이너 런타임과 kubelet의 cgroup 드라이버를 일치시켜야 한다.

아래 명령을 통해 Default config를 만들 수 있다.

sudo mkdir -p /etc/containerd 
sudo containerd config default | sudo tee /etc/containerd/config.toml

자세한 사항은 아래를 참고한다.

Step 2. runc 설치

official binaries를 통해 설치했기 때문에, runc와 CNI를 별도로 설치해주어야 한다.
runc는 OCI사양에 따라 Linux에서 컨테이너를 실행하기 위한 CLI 도구이다.
runc.ARCH 바이너리를 아카이브에서 다운한다. 마찬가지로 검증 후 /usr/local/sbin/runc에 설치한다.

# 다운로드
sudo wget https://github.com/opencontainers/runc/releases/download/v1.3.1/runc.arm64
sudo wget https://github.com/opencontainers/runc/releases/download/v1.3.1/runc.arm64.asc

# fingerprint 확인(공개키를 받아오기 위함)
gpg --verify runc.arm64.asc runc.arm64

모든 릴리스는 공식 레포지토리에 있는 키 중 하나로 서명된다고 하니 참고한다.

확인한 fingerprint를 통해 공개 키를 받아 검증 및 설치를 진행한다.

# 공개키를 keyserver에서 받아옴
gpg --keyserver keyserver.ubuntu.com --recv-keys <fingerprint>

# 검증
gpg --verify runc.arm64.asc runc.arm64

# install
sudo install -m 755 runc.arm64 /usr/local/sbin/runc

# 확인
/usr/local/sbin/runc --version

Step3. CNI plugins 다운로드

CNI 플러그인을 설치한다.

역시나 cni-plugins-<OS>-<ARCH>-<VERSION>.tgz를 다운로드&검증&설치한다.

참고) 나는 해당 플러그인 대신 Calico를 쓸 것이며, 클러스터 생성 이후에 Calico를 설치하므로
여기서 CNI plugins 다운로드는 생략한다. (추후 3편 글에서 Calico 설치 언급)

# 다운
sudo wget https://github.com/containernetworking/plugins/releases/download/v1.8.0/cni-plugins-linux-arm-v1.8.0.tgz
sudo wget https://github.com/containernetworking/plugins/releases/download/v1.8.0/cni-plugins-linux-arm-v1.8.0.tgz.sha256

# 검증 (OK가 뜨면 됨)
sha256sum -c cni-plugins-linux-arm-v1.8.0.tgz.sha256

# 설치
sudo mkdir -p /opt/cni/bin
sudo tar Cxzvf /opt/cni/bin cni-plugins-linux-arm-v1.8.0.tgz

Pod이 실행될 노드들에 동일 작업(Step1-3의 Container Runtime구성)을 진행한다.

다음 단계

[(Kubeadm) K8s 클러스터 구축 2/3] Kubeadm, Kubelet, Kubectl 설치

crayeji.tistory.com

[SigV4] 개념, 서명된 요청 생성하기(JS)

LOGPOSE 로그포스 — Tue, 30 Sep 2025 20:00:11 +0900

개요

AWS API 요청에 인증 정보를 추가하는 서명 메커니즘.

요청 주체를 확인하고, 내용 또한 중간에 변조되지 않았다는 것을 증명하기 위한 서명 방식 중 하나이다.

SigV4 서명 프로세스를 이용해서 요청에 Authorization header를 추가하면,

요청을 받는 쪽(AWS 리소스. API Gateway 등)에서도 요청 쪽에서 서명을 만든 것과 같은 원리로 서명을 만들어 서로 비교해 본다. 같으면 요청을 처리한다.

이를 통해 요청이 정확히 그 시각&그 클라이언트가 보낸 것임을 보장하고,
요청 Body까지 포함해서 무결성 확인하며, 요청 Expiration을 제한해 재사용 공격 방지도 가능해진다.

요청에 포함시킬 요소

SigV4로 HTTP/HTTPS요청을 보낼 때는 아래 요소들을 포함해야 한다.

Endpoint Speciifcation
요청 보낼 DNS name을 명시해야 한다. 주로 서비스 코드, 리전을 포함하는 name이다.
예를 들어 us-east-1리전의 Amazon DynamoDB서비스는 엔드포인트가 dynamodb.us-east-1.com과 같은 형태가 된다.
HTTP/1.1 요청의 경우 꼭 Host 헤더를 포함시켜야 한다.
HTTP/2 요청은 :authority 헤더 또는 Host헤더를 포함시키면 된다. (:authority헤더 권장)
Action
서비스 API action을 명세한다.
예를 들어 DynamoDB에서 CreateTable 하는 Action이라거나
EC2를 DescribeInstance 한다는 등이 있다.
Action parameters
각 API Action에 필요한 파라미터 명시한다. 주로 API Version 등이 쓰인다.
Date
요청 시 date, time을 작성한다.
이는 써드파티가 요청을 인터셉팅해서 나중에 대시 submitting 하는 것을 막아준다.
credentail scope의 date는 request의 date와 무조건 매치되어야 한다.
timestamp는 반드시 UTC, ISO8601 format: YYYYMMDD_T_HHMMSS_Z을 따라야 한다. milliseconds는 포함시키지 않는다.
Authentication information

- Algorithm
서명 프로세스에 사용하는 알고리즘. 
SigV4의 경우 AWS4-HMAC-SHA256을 사용해서 HMAC-SHA256해시 알고리즘으로 SigV4를 지정한다.

- Credentials
Access_key 및 자격 증명 범위 등을 연결하여 구성된 문자열.
SigV4에서는 액세스 키 ID, YYYYMMDD 형식의 날짜, 리전 코드, 서비스 코드, aws4_request 종료 문자열(슬래시(/)로 구분됨)이 포함된다. 
(리전 코드, 서비스 코드 및 종료 문자열에는 소문자를 사용해아함)
AKIAIOSFODNN7EXAMPLE/YYYYMMDD/region/service/aws4_request

- Signed Headers
서명에 포함할 HTTP 헤더. (;)으로 구분된다. ( host;x-amz-date ) 이런식

- Signature
계산된 서명을 나타내는 16진수 인코딩 문자열. Algorithm파라미터에서 지정했던 알고리즘으로 계산해야함.

인증 방법

HTTP Authorization 헤더를 사용하는 방법
첫 번째 방법으로 HTTP 기본 인증 방식인 Authorization 헤더를 쓸 수 있다.

아래와 같은 형태로 SigV4 헤더를 구성한다.
```
Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, 
SignedHeaders=host;range;x-amz-date, 
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
```
Authorization과 Credential사이에만 빼고 각 요소를 쉼표(,)로 구분해야 한다.

참고) Authorization 헤더 값 예시

출처: https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/reference_sigv.html

Query String Parameter를 사용하는 방법
두 번째 방법은 전체 요청을 URL로 표현해 버리는 것이다.
이 경우 인증 정보 및 요청 정보를 쿼리 파라미터에 다 포함시키는 것이다. (따라서, 서명된 URL이라고 부르기도 한다)
X-Amz-Expires을 통해 최대 7일까지 유효한 링크를 HTML에 포함시키는 등 할 수 있다.

참고) SigV4 서명된 URL 예시

https://s3.amazonaws.com/amzn-s3-demo-bucket/test.txt ?
X-Amz-Algorithm=AWS4-HMAC-SHA256 &
X-Amz-Credential=<your-access-key-id>/20130721/<region>/s3/aws4_request &
X-Amz-Date=20130721T201207Z &
X-Amz-Expires=86400 &
X-Amz-SignedHeaders=host &X-Amz-Signature=<signature-value>

요청 만들기

앞서 설명한 요소 및 인증방법들을 통해 SigV4 서명된 요청을 생성해서 보내보자.
SDK를 사용하면 훨씬 간단하게 구현 가능하며 권장되는 방식이지만, 학습 차원에서 단계별로 코드를 작성해 본다.
할 일을 3단계로 요약하면 아래와 같다.

1. Canonical request 만들기 (앞선 요청 정보들을 기반으로 표준 요청을 만든다.)
2. AWS Credentials를 통해 Signature를 계산한다.
3. Signature를 request의 Authorization header에 넣는다.

이 과정을 통해 서명된 요청을 보내면, AWS에서도 동일하게 서명을 계산해서 같은 값이면 액세스를 허용한다.

0. Date, PayloadHash 설정

앞서 SigV4는 요청 Body까지 포함해서 무결성 확인하며, 요청 Expiration을 제한해 재사용 공격 방지도 가능해진다고 했다.

그를 위한 Payload Hash와 요청 시간을 설정하는 코드이다.

  // 1. 요청 시간 설정 (UTC) 
  const now = new Date();
  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
  const xAmzDate = now.toISOString().slice(0, 19).replace(/[-:]/g, '').replace('.', '') + 'Z';

  // 2. Payload Hash 계산
  const payloadHash = crypto.createHash('sha256').update(body).digest('hex');

1. Canonical Request 생성

요청 내용(Host, Action, Header 등)을 표준 형식으로 정렬한다.
Canonical Request는 나중에 String to Sign을 생성하는 데 들어가는 Input 중 하나다.

Canonical Request 구조

<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>

이런 식으로 \n 줄 바꿈 문자로 구분해서 연결하는 형태다.

// 3. CANONICAL REQUEST 구성 코드
const headers = {
	'host': urlObj.hostname,
	'x-amz-content-sha256': payloadHash,
	'x-amz-date': xAmzDate
};

const canonicalHeaderParts = [];
for (const key of Object.keys(headers).sort()) {
	canonicalHeaderParts.push(`${key}:${headers[key]}`);
}

const canonicalHeaders = canonicalHeaderParts.join('\n') + '\n';
console.log('canonicalHeaders: ', canonicalHeaders);

// 4. Signed Headers 구성
const signedHeaders = Object.keys(headers).sort().join(';');

// 5. Canonical Request 구성
const canonicalRequest = [
	method,
	path,
	'', // query string 없음
	canonicalHeaders,
	signedHeaders,
	hashedPayload
].join('\n');

2. 표준 요청(Canonical Request)의 해시 생성

hashedPayload를 생성하는 데 사용한 것과 동일한 알고리즘을 사용하여 canonical request를 해시한다.
(Canonical Request의 해시는 소문자 16진수 문자의 문자열이다.)

// 6. hashedCanonicalRequest 생성
const hashedCanonicalRequest = crypto.createHash('sha256').update(canonicalRequest).digest('hex');

3. 서명할 문자열(String to Sign) 생성

Canonical Request와 추가 정보(알고리즘, 요청 날짜, 자격 증명 범위, 표준 요청의 해시)를 사용하여 String to Sign을 생성한다.

`Algorithm` \n `RequestDateTime` \n `CredentialScope` \n `HashedCanonicalRequest`

* 주의: 맨 끝에는 \n를 쓰면 안 된다.

// 7. String to Sign 구성
const credentialScope = `${date}/${region}/${service}/aws4_request`;

const stringToSign = [
    'AWS4-HMAC-SHA256',
    xAmzDate,
    credentialScope,
    hashedCanonicalRequest
].join('\n');

4. 서명 키(Signing Key) 추출

시크릿 액세스 키를 사용하여 요청에 서명하는 데 사용되는 키를 파생한다.

DateKey = HMAC-SHA256("AWS4"+"`<SecretAccessKey>`", "`<YYYYMMDD>`") 
DateRegionKey = HMAC-SHA256(`<DateKey>`, "`<aws-region>`") 
DateRegionServiceKey = HMAC-SHA256(`<DateRegionKey>`, "`<aws-service>`") 
SigningKey = HMAC-SHA256(`<DateRegionServiceKey>`, "aws4_request")

Key - 시크릿 액세스 키를 포함하는 문자열.
Date - 자격 증명 범위에 사용되는 날짜(YYYYMMDD 형식)를 포함하는 문자열.
Region - 리전 코드(예: us-east-1)를 포함하는 문자열.
Service - 서비스 코드(예: ec2)를 포함하는 문자열.

// 8. Signing Key 생성
const kDate = crypto.createHmac('sha256', 'AWS4' + secretAccessKey).update(date).digest();
const kRegion = crypto.createHmac('sha256', kDate).update(region).digest();
const kService = crypto.createHmac('sha256', kRegion).update(service).digest();
const kSigning = crypto.createHmac('sha256', kService).update('aws4_request').digest();

5. 서명(Signature) 계산

파생된 서명 키(Signing Key)를 해시 키로 사용하여, 서명할 문자열(String to Sign)에 Key가 추가된 해시 계산을 한다.

// 9. Signature 계산
const signature = crypto.createHmac('sha256', signingKey).update(stringToSign).digest('hex');

6. 요청에 서명 추가

HTTP 헤더 또는 요청의 쿼리 문자열에 계산된 서명을 추가.
나는 Authorization 헤더에 추가하는 방법을 사용했다.

아래와 같은 형태를 만들어내야 한다.

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20220830/us-east-1/ec2/aws4_request, SignedHeaders=host;x-amz-date, Signature=`calculated-signature`

// 10. Authorization 구성
const authorization = `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;

이렇게 만든 Authorization을 최종 요청 헤더에 포함시켜 요청을 보내면 된다.

AWS 측에서는 이렇게 만들어진 요청을 받으면, Body와 요청 시간을 바탕으로 동일한 계산을 진행해서 동일한지 체크한다.

// 11. 최종 요청 헤더 구성
const finalHeaders = {
    'content-type': 'application/json',
    'Authorization': authorization,
    'x-amz-date': xAmzDate,
    'x-amz-content-sha256': payloadHash
};

console.log("Signed Headers:", finalHeaders);

// 12. 서명된 요청 보내기
try {
const axiosResponse = await axios({
    method: method,
    url,
    headers: finalHeaders,
    data: body,
});

    console.log("Response status:", axiosResponse.status);
    console.log("Response data(OUTPUT):", axiosResponse.data);

} catch (error) {
    console.error("Request error:", error.response?.data || error.message);
}

참고 자료

https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/reference_sigv.html

CKA 쿠버네티스 자격증 취득과정 기록 (2025. 02 변경 이후)

LOGPOSE 로그포스 — Fri, 25 Jul 2025 20:00:36 +0900

취득 동기

Cloud, MSA에 관심을 가진 후로 적합한 기술을 찾다 보니 쿠버네티스에 관심을 갖게 됐다
그때부터 3개월 정도 스터디를 해보니까, 리소스를 기반으로 여러 서비스 배포는 물론이고 Security, Networking, Scheduling까지 마치 농장 운영하듯이 운영 가능한 게 굉장히 짜임새 있게 느껴졌다. 클러스터에서 필요한 개념들이 추상화가 매우 잘 되어 있어서, yaml로 이렇게 명쾌하게 시스템을 구성할 수 있구나 싶었다. 예를 들면 Ingress로 룰을 정의하고 Ingress Controller Pod가 실질적으로 처리하도록 역할이 분리되어 있으면서도, 이 모든 건 특정 종류의 리소스로 정의된 것이라는 점 등이다.
공부를 하면 할수록, 앞으로 더 작은 단위의 더 많은 서비스를 체계적으로 운영하기 위해서 이 기술이 실질적으로 쓸모 있겠다는 생각이 들었다. 그래서 쿠버네티스 관리자의 첫 단추로 CKA를 따보기로 했다.

2025. 02 이후 변경 내용

2025. 02 이후 CKA 시험 내용 및 문제 비중이 변경됐다. (심지어 비슷한 시기에 가격도 $395 ->$445로 바뀌었다ㅠㅠ)
기존 시험에서 주요 출제 내용이었던 etcd 백업/복원, Kubernetes 버전 업그레이드 관련 내용은 우선순위가 내려갔다.
(7월 중순 기준, 시험에도 출제되지 않았다.)

대신, Helm/Kustomize, Gateway API, HPA, CRDs/Operators 등에 대한 이해가 더 필요하다.
시험에서도 Helm을 통해 argo-cd차트를 설치하는 문제, 기존 Ingress를 Gateway API&HttpRoute로 Migrating 하는 등 형식의 문제가 출제되었다. CNI설치 또한 CRDs/Operators기반이므로 반드시 학습해야 한다. (Kustomize문제는 7월 중순 기준 출제되지 않았다.)
또한, Storageclass기반으로 동적 프로비저닝하는 부분도 중요하다.

그 외에는 Sidecar 구성, Configmap수정, 각종 리소스를 만들기, 서비스를 expose 등 비교적 평이하고 예상 가능한 문제들로 구성됐다.
추가적인 변경 정보는 아래 영상을 참고하면 좋다. K8s기본 개념이 있는 상태에서, CKA 준비 초반에 보기 좋은 영상이다.
타임스탬프에 카테고리가 나뉘어있으니, 특정 파트를 간단히 확인하기 좋았다. 그리고 개그 욕심이 좀 있으신 듯

어떻게 준비했나

기본 준비 사항

Udemy 강의 전체 듣고 Practice test 3바퀴 돌렸다.
1번 돌릴 때는 이런 게 있구나~였고, 2번째는 내가 뭘 모르는지 확인, 3번째는 이렇게도 될까? 하며 상세 내용을 중심으로 확인했다.
마지막 1-2주는 Lightning Lab과 MockExam1, 2, 3을 마찬가지로 3번씩 풀었다. 이 문제들도 이제 2025 기준으로 업데이트가 되었기 때문에 실제 시험과 개념적으로 비슷하고 분명 도움 된다.
시험인 걸 고려해서(2시간, 17문제) 명령형으로 풀 수 있는 문제는 최대한 명령형으로 연습해야 한다.(예를 들면 create deploy / pod run / expose service / hpa autoscale / create priorityclass / create serviceaccount, create role...)

❗️주요 준비 사항

가장 중요한 것은 변경된 기출문제를 풀고 정보를 얻는 것이다.
기존 CKA기준으로 준비하다가, 유형이 생각보다 많이 다르다는 후기를 듣고 시험을 1주일 미룬 후 신규 유형으로 바짝 다시 준비했다.
(이게 신의 한 수였다고 생각한다...)

1. 2025 기출 정보

My CKA Story (with New CKA 2025 February Changes)

I faced the Certified Kubernetes Administrator (CKA) exam on 26th May 2025. The CKA exam was changed after February 2025. I got to know…

medium.com

The CKA Exam Changed After February 18 — Here’s What You Actually Need to Practice Now

For the Certified Kubernetes Administrator (CKA) exam in 2025, the main thing you need is not just to memorize commands. The exam has…

medium.com

여기 기출문제를 Udemy Practice test환경(아무거나)에서 다양하게 테스트해보고,
그 기출문제들을 기반으로 GPT에게 시나리오 및 풀이를 만들어 달라고 해서 풀어보고 관련 개념 정보를 얻었다.
그 과정에서 helm으로 argo 설치 시 발생 가능한 실수, CNI설치 관련 돌발 에러 등을 미리 확인할 수 있다.

2. Reddit
Reddit에서 기출문제 / 시험 후기 / 명령어 꿀팁 / 숨은 풀이 방법을 싹싹 긁어모았다.
2025 변경 이후 한국 커뮤니티에는 아직 자료가 많이 없기 때문에 아주 든든한 자료가 된다.

r/CKAExam

A Subreddit to discuss and help each other prepare for the Kubernetes Certified Administrator (CKA) Exam.

www.reddit.com

소소한 팁

아주 기본적이지만 유용한 팁을 혹시 몰라 기록해 둔다.
1. kubectl explain
리소스 정의 구조를 설명해 주는 명령어이다.
HPA, VPA, gateway api나 비교적 새로 나온 리소스들은 공식문서에서 정확한 예시 자료를 찾기 어렵거나 없을 때가 있다.
그 외에도 가물가물한 것들을 빠르게 파악하고 yaml을 작성하기 유용하다.
특히, --recursive옵션을 사용하면, 세부 필드들까지 형식 맞춰서 한눈에 볼 수 있기 때문에, 참고 자료가 없는(VPA 등) 리소스 정의서를 작성하기에 좋다. (참고로 시험에서도 리소스 정보 명세하라며 이 명령어의 출력 결과를 저장하라는 등 문제도 출제될 수 있다.)

2. ps aux / ps -ef
실행 중인 프로세스 정보 중 웬만큼 필요한 것들은 다 찾아지니까 일단 확인해 보면 여러모로 시간을 단축할 수 있다.
예를 들면, 특정 컨트롤 플레인 컴포넌트 프로세스가 어떤 설정파일 쓰고 있는지 등.... 가닥을 잡기가 쉽고 빨라진다.

3. k api-resource
네임스페이스 스콥의 리소스인지, 단축 이름 뭔지 갑자기 헷갈릴 때 후다닥 확인하기 좋다.
또 api version 같은 거 헷갈릴 때도 좋다.
물론 crd도 등록하면 이 명령어 실행 시 포함되어 확인할 수 있다. 그래서 시험에서도 crd 이름 등 간단히 확인할 때 사용했었다.

4. --show-labels
리소스들이 labels selector기준으로 묶이는 만큼 K8s에서 라벨 확인은 매우 중요하다.
시험 문제를 예로 들면, Network Policy에서 PodSelector를 통해 적용되는 Pod/Namespace는 무엇일지 확인해야 될 때가 있다.
그 외에도 Replicas, Deployment, Service 등의 기본 연결 메커니즘이 라벨이고, 이게 다르면 트래픽 전달도 스케일링도 무용지물이 되므로 labels를 확인 가능한 해당 명령어가 매우 유용했다.

Killer.sh

Killer.sh도 2025.02 변경사항이 적용됐다. 시험 날짜 결정 후, 2회 풀 수 있고 문제 set은 다르다.
풀어보니 공부 목적보다는 시험 환경 적응에 중점을 둬도 괜찮을 것 같다. 그런데 안 풀어보는 건 반대한다. 적응하는 시간이 꽤 걸렸다.
문제마다 ssh로 노드 바꿔서 작업하는 것, 터미널 등 여는 방법(메모장은 그냥 쓰지 않고 vim으로 충분했다), 복붙 적응에 도움 됐다.
난이도 극악이라는 기존 버전 후기와 달리, 문제가 바뀌어서 그런가? 별로 안 어려운데!?!?라고 생각하며 풀었다
하지만 웬 걸.. 40점대 나옴 충격... 그래도 시험이 더 쉽고, 나 또한 실전에서 2배 이상의 점수를 받았으니 너무 걱정하지 않아도 된다!!

시험 환경, 준비물

집에서 봤다. 원룸이라 티비, 각종 짐을 전부 부엌에 몰아넣고 부엌이 안 보이는 쪽에서 시험을 봤다.
행거에 걸린 옷들은 담요로 가려뒀는데, 뭐냐고 물으셔서 그대로 말씀드리고 넘어갔다.
티비 선을 뽑으라고 하기도 한다는데, 나는 꺼져있는 것만 보여드렸다.

신분증은 뒷면에 영문이 있는 운전면허증을 준비했다.
한글 부분에만 얼굴이 있어서, 앞면 뒷면을 각각 보여주기를 요구받았다.
혹시 몰라 체크카드도 준비했는데, 필요하지는 않았다.

개인적인 소감

마지막 1-2주는 시험을 위한 공부로 흘러가긴 했지만, 스터디 기간 3개월을 포함하여 쿠버네티스를 공부한 5개월 간
기본적인 쿠버네티스 운영 능력과 자신감을 얻어서 개인적으로 준비해 보길 잘했다고 생각이 드는 자격증이다.

마침 취득할 무렵에 회사에서도 쿠버네티스 관련 업무를 작게나마 다루게 되어서,
역시 어떤 성취이든 일단 해 놓으면 분명 확장하고 활용하는 때가 오는구나 라는 생각을 다시금 하게 됐다.

첫 단추를 꿰는데 함께해 준 스터디원들한테도 고맙고, 앞으로 이 기술로 시도해 볼 많은 여정이 기대가 된다~

Amazon S3 Vectors 출시, OpenAI embeddings 넣어보기

LOGPOSE 로그포스 — Thu, 24 Jul 2025 12:00:55 +0900

개요

며칠 전 AWS에서 벡터 클라우드 스토리지를 공개했다. S3 기반이기에 경제성과 내구성을 기대할 수 있을 것 같다.
나는 Qdrant로 벡터 DB를 구성하고 있었는데, Amazon S3 Vectors로 교체해볼까 한다.
Embeddings는 우선 Bedrock 대신, OpenAI embedding model을 사용했다.

Introducing Amazon S3 Vectors: First cloud storage with native vector support at scale (preview) | Amazon Web Services

Amazon S3 Vectors is a new cloud object store that provides native support for storing and querying vectors at massive scale, offering up to 90% cost reduction compared to conventional approaches while seamlessly integrating with Amazon Bedrock Knowledge B

aws.amazon.com

사용하기

1. Bucket 생성

Sydney Region으로 테스트해본다. 현재 버지니아 북부(us-east-1), 오하이오(us-east-2), 오레곤(us-west-2), 프랑크푸르트(eu-central-1), 시드니(ap-southeast-2) 리전에서만 평가판으로 제공되고 있다.
서울에서 개인적으로 속도 테스트 해봤을때는, 오레곤 리전이 평균적으로 빠른 응답을 보였다.

Encryption type은 선택하지 않으면 기본적으로 Amazon S3 managed keys (SSE-S3) 기반의 server-side encryption을 한다.
이보다 advanced를 원하면 AWS Key Management Service 키를 사용한 서버 측 암호화(SSE-KMS)를 선택할 수도 있다.

버킷 네이밍은 벡터 데이터 목적을 나타내도록 descriptive한 것이 권장된다. (product-recommendations / document-embeddings 등)

2. Index 생성

Name과 Dimensionality를 지정한다.
물론 입력되는 Vector값은 여기 입력되는 dimensionality와 동일해야 한다.
Distance metric은 Cosine / Euclidean을 제공한다.
사용할 임베딩 모델의 recommended distance metric for more accurate results와 벡터 차원 수를 확인하여 선택하면 되겠다.

나는 OpenAI text-embedding-3-small을 사용하기 때문에 DIMENSIONS는 1536, METRIC은 Cosine으로 지정해 주었다.

메타데이터 구성도 보인다. 벡터 인덱스 만들고 나면 Vector data를 인덱스에 넣을 텐데, 그때 medata를 key-value 쌍 형태로 각 벡터에 붙일 수가 있다. 이는 Qdrant에서 payload의 metadata 기반으로 필터링하는 기능과 유사하게 보인다. (예를 들면 날짜/카테고리 등...)

메타데이터는 Filterable과 Non-filterable이 있는데, 위 단계에서 Non-filterable 메타데이터 key를 추가할 수 있다. (최대 10개)
크기는 벡터 당 전체 메타데이터(Filterable, Non-filterable 합쳐서) 40KB까지 가능하고, Filterable은 최대 2KB다.

Limitations and restrictions - Amazon Simple Storage Service

Limitations and restrictions Amazon S3 Vectors is in preview release for Amazon Simple Storage Service and is subject to change. Amazon S3 Vectors has certain limitations and restrictions that you should be aware of when planning your vector storage and se

docs.aws.amazon.com

[더 자세한 용량 / 개수 제한은 위 문서를 참고]

3. Vector embeddings 넣기, 쿼리

AWS CLI, AWS SDKs 또는 Amazon S3 REST API로 해당 작업이 가능한데,
AWS 블로그 SDK 예시 코드를 기반으로 했고, Embedding model만 Bedrock대신 openAI로 수정했다.

참고) 콘솔에서 UI로 확인할 수 있는 사항들이 제한적이다. 주로 AWS CLI를 통해 조회했고, 커맨드는 아래를 참고하자.

s3vectors — AWS CLI 2.27.58 Command Reference

Description Amazon S3 vector buckets are a bucket type to store and search vectors with sub-second search times. They are designed to provide dedicated API operations for you to interact with vectors to do similarity search. Within a vector bucket, you use

docs.aws.amazon.com

Step 1. 임베딩 생성

import openai
import boto3
import json
import os
from dotenv import load_dotenv

load_dotenv()

# OpenAI 클라이언트 생성
client = openai.OpenAI()

# 텍스트 입력
texts = [
    "Star Wars: A farm boy joins rebels to fight an evil empire in space",
    "Jurassic Park: Scientists create dinosaurs in a theme park that goes wrong",
    "Finding Nemo: A father fish searches the ocean to find his lost son"
]

# 임베딩 모델 지정
model = "text-embedding-3-small"

# 텍스트 → 임베딩
embeddings = []
for text in texts:
    response = client.embeddings.create(
        model=model,
        input=text
    )
    embedding = response.data[0].embedding
    embeddings.append(embedding)

Step 2. 임베딩 저장

# S3Vectors 클라이언트 생성
s3vectors = boto3.client("s3vectors", region_name="ap-southeast-2")  # S3 Vector Store 지원 리전 - Sydney

# 임베딩 저장
s3vectors.put_vectors(
    vectorBucketName="document-embeddings",
    indexName="document-embeddings-index",
    vectors=[
        {
            "key": "v1",
            "data": {"float32": embeddings[0]},
            "metadata": {"id": "key1", "source_text": texts[0], "genre": "scifi"}
        },
        {
            "key": "v2",
            "data": {"float32": embeddings[1]},
            "metadata": {"id": "key2", "source_text": texts[1], "genre": "scifi"}
        },
        {
            "key": "v3",
            "data": {"float32": embeddings[2]},
            "metadata": {"id": "key3", "source_text": texts[2], "genre": "family"}
        }
    ]
)

Step 3. 쿼리

# 쿼리 텍스트를 임베딩
input_text = "List the movies about adventures in space"
query_response = client.embeddings.create(
    model=model,
    input=input_text
)
query_vector = query_response.data[0].embedding

# 벡터 유사도 검색
query = s3vectors.query_vectors(
    vectorBucketName="document-embeddings",
    indexName="document-embeddings-index",
    queryVector={"float32": query_vector},
    topK=3,
    filter={"genre": "scifi"},
    returnDistance=True,
    returnMetadata=True
)

# 결과 출력
results = query["vectors"]
print(json.dumps(results, indent=2))

결과는 아래와 같다. filter={"genre": "scifi"}에 의해 1차 '니모를 찾아서("genre": "family")'는 필터링되었다.
movies about adventures in space에 가장 가까운 Star Wars가 가장 가까운 distance로 검색됐다.

# 검색 결과
[
  {
    "key": "v1",
    "metadata": {
      "source_text": "Star Wars: A farm boy joins rebels to fight an evil empire in space",
      "genre": "scifi",
      "id": "key1"
    },
    "distance": 0.7688703536987305
  },
  {
    "key": "v2",
    "metadata": {
      "source_text": "Jurassic Park: Scientists create dinosaurs in a theme park that goes wrong",
      "genre": "scifi",
      "id": "key2"
    },
    "distance": 0.8421887755393982
  }
]

문서 Loading - Chunking - S3 Vectors 저장 예시

기존에 Langchain으로 RAG를 구현해서 Qdrant 저장했었는데,
데이터 Ingestion 할 때만 Qdrant metatdata구성과 비슷한 구조로 S3 Vectors에 저장하도록 구현해 보았다.
물론 S3 Vectors는 지난주에 발표된 만큼, 아직 Langchain에서 Vectorstores로 제공하지는 않는다.

# 1. Loading
def load_file(file_url: str):
    response = requests.get(file_url)
    response.raise_for_status()

    content_type = response.headers.get('Content-Type', '').split(';')[0]
    print("[Header] Content-Type:", content_type)

    # normalize to internal type: "pptx", "docx", "pdf"
    normalized_type = get_normalized_type(content_type)

    with tempfile.NamedTemporaryFile(delete=False, suffix=f".{normalized_type}") as tmp:
        tmp.write(response.content)
        tmp_path = tmp.name
        print(f"[TempFile] 저장됨: {tmp_path}")

    # 로더 매핑
    loader_map = {
        "pptx": UnstructuredPowerPointLoader,
        "docx": UnstructuredWordDocumentLoader,
        "pdf": PyPDFLoader
    }

    loader = loader_map[normalized_type](tmp_path)
    return loader.load()


# 2. Chunking
def chunk_document(docs, chunk_size = 500, chunk_overlap = 100):
    splitter = RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap
    )
    return splitter.split_documents(docs)


# 3. Embedding & Vector storing
def store_vectors(chunks):

    # Chunk text → Vector
    client = openai.OpenAI()
    embeddings = []
    for chunk in chunks:
        response = client.embeddings.create(
            model=EMBEDDING_MODEL_NAME,
            input=chunk.page_content
        )
        embedding = response.data[0].embedding
        embeddings.append(embedding)


    # S3Vectors 벡터 저장
    s3vectors = boto3.client("s3vectors", region_name="us-west-2")  
    vectors = []

    # chunks: List[Document]
    # embeddings: List[List[float]]
    for i, (chunk, embedding) in enumerate(zip(chunks, embeddings)):
        metadata = dict(chunk.metadata)
        metadata["source_text"] = chunk.page_content  

        vector = {
            "key": f"v{i+1}",                    
            "data": {"float32": embedding},        
            "metadata": metadata              
        }
        vectors.append(vector)
        

    # 벡터 일괄 업로드
    s3vectors.put_vectors(
        vectorBucketName=VECTOR_BUCKET_NAME,
        indexName=INDEX_NAME,
        vectors=vectors
    )

    print(f"\nIngestion 완료: {len(chunks)}개의 청크가 S3 Vectors에 저장되었습니다.")

참고자료

Getting Started
https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-getting-started.html

Vector buckets 사용자 가이드
https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-buckets.html

s3 vectors CLI 커맨드 레퍼런스
https://docs.aws.amazon.com/cli/latest/reference/s3vectors/#cli-aws-s3vectors

OpenAI Vector Embeddings 가이드
https://platform.openai.com/docs/guides/embeddings

PV 확장 원리, Kubernetes CSI Driver

LOGPOSE 로그포스 — Wed, 9 Jul 2025 19:00:51 +0900

Kubernetes에서의 Volume, File System 확장

AWS를 예로 들자. EC2에서 EBS 등 스토리지를 사용하는 상황에서 볼륨 용량을 늘리려면,
콘솔 등에서 EBS Volume 크기를 조정하고, EC2 인스턴스에서 파티션 및 File System 확장을 했었다.

그렇다면 쿠버네티스에서는 어떤 방법으로 Pod에 연결된 PVC의 PV를 늘릴 수 있는지,
Volume확장과 File System확장은 어떤 과정을 통해 일어나는지 살펴본다.

Persistent Volume Expansion

기존에는 PVC를 확장하려면 PVC 및 PV 삭제/재생성 같은 귀찮은 작업들이 필요했다.
Kubernetes v1.11부터 정식 베타로 Persistent Volume Expansion가 도입되었다.
덕분에 allowVolumeExpansion필드를 True로 설정한 Strorageclass가 있을때,
그 Storageclass를 사용하는 PVC들은 손쉽게 볼륨을 확장할 수 있다.

아래처럼 PVC의 storage 필드(용량 부분)만 수정해주면 간단히 확장이 된다.
다시 말해, 내부적으로 Volume확장과 File System 확장이 일어났다는 것이다.

사진 출처: https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/

Container Storage Interface (CSI)

PVC만 살짝 수정하면 자동으로 Volume확장과 File System 확장이 일어난다니?
어떻게 그럴 수 있을까를 찾아봤다. 결론부터 말하자면 CSI 드라이버와 kubelet 덕분이다.

CSI는 쿠버네티스같은 Container Orchestration Systems (COs)가 스토리지 시스템에 컨테이너를 노출시키는 표준 인터페이스다. 이 인터페이스는 Identity Service, Controller Service, Node Service로 구성되어 있다.
Controller plugin은 CSI의 Controller Service를 구현한 것이고, Node plugin은 CSI의 Node Service를 구현한 것이다. Identity Service는 두 Plugin에서 모두 구현해야 한다.
쿠버네티스에서 일반적으로 CSI드라이버는 이 plugin을 포함하는 `controller component`, `per-node component`로 배포된다.

참고) CSI Spec: https://github.com/container-storage-interface/spec/blob/master/spec.md#rpc-interface

1. Controller Component

CSI의 Controller Service를 구현한 'Controller plugin' & 하나 이상의 'Controller Sidecar' 로 구성되는 컴포넌트이다.
여기서 Sidecar들의 목적은 쿠버네티스 오브젝트와 상호작용하면서 드라이버가 구현한 CSI Controller Service를 호출하는 것이다.
가령, PVC의 Storage 용량을 늘리면 resizer Sidecar가 이를 감지해서 CSI Controller Service에 구현된 ControllerExpandVolume을 호출하는 것이다.

Controller Sidecar 종류는 아래와 같다.
물론 이 외에도 더 있는데, 어떤 Sidecar Conatiner를 포함할지는 Controller개발자가 필요에 따라 선택했을 것이다.

provisioner: PVC 생성 요청 시 볼륨 생성
attacher: 볼륨을 노드에 attach
snapshotter: 볼륨 스냅샷 기능 지원
resizer: PVC 용량 증가 감지 및 확장 요청

이렇게 Controller plugin과 Sidecar들로 구성된 Controller Component는 Deployment나 StaefulSet등 형태로 배포가 된다.
일반적으로 CSI Controller와 같은 이름을 가지는 Pod에 해당한다.

나는 Amazon EBS를 사용하면서 ebs-csi-controller를 사용하고 있는데, 컨테이너 이름을 조회해 보니,
앞서 학습한대로 controller plugin(ebs-plugin)과 Sidecar들을 포함하고 있었다.

 kubectl get pod ebs-csi-controller-657c7f6895-ffhj7 -n kube-system -o jsonpath="{.spec.containers[*].name}"
 
 # ebs-plugin csi-provisioner csi-attacher csi-snapshotter csi-resizer liveness-probe

자세한 구성은 아래 aws-ebs-csi-driver의 helm charts를 참고했다.
https://github.com/kubernetes-sigs/aws-ebs-csi-driver/tree/master/charts/aws-ebs-csi-driver

2. Per-Node Component

CSI의 Node Service를 구현한 'Node Plugin' & 'node-driver-registrar'(Sidecar)로 구성되는 컴포넌트이다.
node-driver-registrar는 Node Plugin을 Kubelet에 등록하기 위한 Sidecar container다. 이를 통해 CSI 드라이버와 gRPC 통신을 할 수 있게 된다. 가령, 볼륨이 확장됐을때 Kubelet이 Node Plugin에 구현된 NodeExpandVolume 요청을 함으로써 실제 파일 시스템 확장(resize2fs 등..)을 하는 등 작업이 가능해지는 것이다.
이 컴포넌트는 kubelet과 상호작용하는 만큼, 워커 노드마다 설치되어야 할 CSI 컴포넌트다. 따라서 DaemonSet을 통한 배포가 적절하다.

참고) node-driver-registrar https://kubernetes-csi.github.io/docs/node-driver-registrar

PV Expansion 과정 확인

직접 확장을 해보며 plugin 호출 등 과정을 살펴보았다. 시나리오는 아래와 같다.

1. 사용자가 PVC의 storage 요청량을 증가시킴 (예: 30Gi → 40Gi)
   ↓
2. external-resizer(csi-resizer)가 이를 감지
   ↓
3. CSI Controller에게 ControllerExpandVolume RPC 호출
   ↓
4. CSI Controller가 스토리지 백엔드 API 호출 (예: AWS EBS)
   ↓
5. 디스크가 확장됨 → PV 객체의 capacity.storage 필드가 업데이트됨
   ↓
6. PVC에 FileSystemResizePending 조건이 추가됨
   ↓
7. Kubelet이 해당 PVC를 사용하는 Pod을 통해 이를 감지
   ↓
8. Kubelet이 CSI Node Plugin에게 NodeExpandVolume RPC 호출
   ↓
9. CSI Node Plugin이 마운트 경로의 파일 시스템을 확장 (resize2fs 등 작업)
   ↓
10. PVC의 Status부분이 정상화됨 → 확장 완료

나는 EKS에서 EBS를 사용하는 statefulset Pod 3개를 배포해둔 상태이다.
gp3라는 Storageclass를 사용 중이며, 확장을 위해서는 Storageclass에 allowVolumeExpansion=true가 명시되어 있어야 한다.
기존 pvc는 30Gi를 Claim하고 있는데, 40Gi로 올려보았다.

kubectl edit <pvc-name>
# storage 부분 수정

Edit 직후에는 status에 allocatedResources부분이 40Gi로 추가되었다.

# PVC Edit 후 status를 확인해보자
k get pvc <pvc-name> -oyaml

잠시 기다리면 conditions부분에 type이 FileSystemResizePending으로 바뀌었다.

즉, PV Resizing은 끝난 것이다. 실제로 매칭된 PV를 describe해보면 아래와 같이 확장이 되어있다.

conditions이 FileSystemResizePending이라는 것은
다시 말해, kubelet이 CSI Node Plugin에 NodeExpandVolume요청을 통해 FileSystemResizing을 진행할 차례라는 것이다.
여기서 조금 더 기다려보면 최종적으로 pvc의 capacity가 40Gi로 변경되었고, FileSystemResizePending도 사라졌다.
kubelet이 제 역할을 했음을 유추할 수 있다.

kubelet의 Node Plugin요청 여부를 명확히 확인하려면
해당 Pod를 describe해서 Events를 보면 된다.

Events:
  Type    Reason                      Age   From     Message
  ----    ------                      ----  ----     -------
  Normal  FileSystemResizeSuccessful  13m   kubelet  MountVolume.NodeExpandVolume succeeded for volume "pvc-98d52b3c-ce38-49ee-baa4-a36bf4f60b72" i-0f2a5c9c120e30cbc

FileSystemResizing이 성공했음을 알 수 있다. 또 그 주체는 From 부분의 Kubelet임을 확인했다.
MountVolume.NodeExpandVolume succeeded라는 메시지를 보니, NodeExpandVolume을 요청 했음도 알 수 있다.

마지막으로 Pod의 Volume Mount정보를 명확하게 확인해보자.

kubectl exec -it <your-pod-name> -- df -h

이 pod의 pv 마운트 위치는 /qdrant/storage이었다.
해당 Mounted의 Available 부분을 보면 40G로 잘 변경되어있다.
기존에는 해당 부분이 약 30G로 표시되어있었다.

참고자료

https://github.com/kubernetes-sigs/aws-ebs-csi-driver
https://kubernetes.io/docs/concepts/storage/persistent-volumes/
https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/
https://kubernetes-csi.github.io/docs/volume-expansion.html

k8s csi-resizer(external-resizer)
https://github.com/kubernetes-csi/external-resizer/blob/master/cmd/csi-resizer/main.go
aws-ebs-csi-driver의 헬름 차트
https://github.com/kubernetes-sigs/aws-ebs-csi-driver/tree/master/charts/aws-ebs-csi-driver
K8s에서의 CSI Driver 배포
https://kubernetes-csi.github.io/docs/deploying.html

Dockerfile(ENTRYPOINT, CMD) => YAML Definition file(command, args) 덮어쓰기 과정

LOGPOSE 로그포스 — Mon, 30 Jun 2025 19:00:55 +0900

1. Dockerfile의 ENTRYPOINT는 YAML Definition file의 command에 의해 덮어쓰기된다.

아래 처럼 도커파일이 있고, 이 도커파일로 만들어진 이미지가 webapp-color에 올라가있는데
그 이미지를 Pod Definition file에서 활용해서 pod을 만든다면,
기존 도커 파일의 `ENTRYPOINT`는 Pod Definition file의 `command`에 의해 덮어쓰기 된다.

Dockerfile에 설정한 ENTRYPOINT는 YAML 정의서에 command가 명시되면 무시되어 YAML의 command가 실행 대상이 된다.

# DockerFile
controlplane ~/webapp-color-2 ➜  cat Dockerfile 
FROM python:3.6-alpine
RUN pip install flask
COPY . /opt/
EXPOSE 8080
WORKDIR /opt
ENTRYPOINT ["python", "app.py"]
CMD ["--color", "red"]

# Pod Definition file
controlplane ~/webapp-color-2 ➜  cat webapp-color-pod.yaml 
apiVersion: v1 
kind: Pod 
metadata:
  name: webapp-green
  labels:
      name: webapp-green 
spec:
  containers:
  - name: simple-webapp
    image: kodekloud/webapp-color
    command: ["--color","green"]

위의 경우, ENTRYPOINT인 `python app.py`가 pod Definition file의 command에 의해 덮어쓰기된다.

ENTRYPOINT가 덮어쓰기되면 CMD도 무시된다.

최종적으로 pod definition file에서의 `--color green`만 남는 것이 결과가 된다.

2. Dockerfile과 YAML definition file의 command/args 대응 관계

YAML Definition file(Pod, Deployment...)에서
`command`가 실행 대상 (= Docker `ENTRYPOINT`)
`args`는 그에 대한 인자 (= Docker `CMD`)

# DOCKERFILE
FROM python:3.6-alpine
RUN pip install flask
COPY . /opt/
EXPOSE 8080
WORKDIR /opt
ENTRYPOINT ["python", "app.py"]     ✅
CMD ["--color", "red"]              ✅

# Pod Definition file
controlplane ~/webapp-color-3 ➜  cat webapp-color-pod-2.yaml 
apiVersion: v1 
kind: Pod 
metadata:
  name: webapp-green
  labels:
      name: webapp-green 
spec:
  containers:
  - name: simple-webapp
    image: kodekloud/webapp-color
    command: ["python", "app.py"]     ✅
    args: ["--color", "pink"]         ✅

ENTRYPONIT는 command로 덮어쓰고
CMD는 agrs로 덮어쓰니

결과는 `python app.py --color pink`

3. ENTRYPOINT는 유지하고 CMD만 바꾸고 싶을 때

Dockerfile이 아래와 같을 때

# Dockerfile
ENTRYPOINT ["node", "index.js"]
CMD ["--env=prod"]

Kubernetes에서 CMD만 바꾸고 싶다면

containers:
- image: my-app
  args: ["--env=dev"]   # ENTRYPOINT는 유지됨

결과는 `node index.js --env=dev`

참고 자료

https://learn.kodekloud.com/user/courses/udemy-labs-certified-kubernetes-administrator-with-practice-tests

Qdrant 구성 요소

LOGPOSE 로그포스 — Mon, 23 Jun 2025 11:33:13 +0900

개요

Qdrant는 벡터 유사도 검색 엔진 & VectorDB의 역할을 한다.
REST API를 통해 벡터를 저장, 검색 할 수 있으며 페이로드를 통해 벡터를 관리할 수 있다.
벡터 유사도 검사에서 Similarity Metric으로 Cosine, Dot, Euclid 등 선택할 수 있으며,
Collections, Points 등 몇 가지 구성요소를 기반으로 동작한다.

Qdrant 구성 요소

1. Points

Qdrant 기본 Entity다. Vector + Payload + Optional ID로 구성된다.
Vector: 이미지/문서/사운드/비디오 등을 벡터화 한 값
Payload: 벡터에 관한 부가데이터를 JSON형태로 저장한 값.
ID: 벡터의 식별자

point는 이런 형태로 넣게 된다.
ID는 64-bit unsigned integers 또는 UUID 로 넣을 수 있다.

PUT /collections/{collection_name}/points
{
    "points": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        }
    ]
}

Langchain으로 저장한 point를 조회해보면 payload로 page_content, metadata 등이 함께 들어갔다.
JSON을 사용하여 표현할 수 있는 어떤 정보든 넣을 수 있다.

{
  "id": "08af50f3-6606-4073-953f-57ae668e7b30",
  "vector": [
    0.009180975, -0.0057382825, ..., 0.003189075
  ],
  "payload": {
    "page_content": "4 \n \nQ3.  다른 국가들에 적용되는 상호관세율은? \nA3. 중국 34%, 유럽연합 20%, 일본 24% 등으로 책정되어 ...",
    "metadata": {
      "producer": "PDFium",
      "creator": "PDFium",
      "creationdate": "",
      "source": "/var/folders/zz/tn93_s4p00gn/T/tmp__eaypdf",
      "total_pages": 11,
      "page": 3,
      "page_label": "4",
      ...
    }
  }
}

이런식으로 덧붙인 Payload는 아래와 같이 Search시 Filtering에 활용할 수 있다.

POST /collections/{collection_name}/points/query
{
    "query": [0.2, 0.1, 0.9, 0.79],
    "filter": {
        "must": [
            {
                "key": "city",
                "match": {
                    "value": "London"
                }
            }
        ]
    },
    "params": {
        "hnsw_ef": 128,
        "exact": false
    },
    "limit": 3
}

2. Distance Metrics

벡터 간의 유사성을 측정하는 데 사용한다. 아래에 설명할 Collections 생성할때 함께 지정해야한다.
어떤 Metrics를 사용할지는 어떤 임베딩 모델을 썼느냐에 따라 달라진다.

3. Collections

Point의 집합을 의미한다.

Collection을 만들때는 vectorParams으로 Vector Dimension과 Distance Metrics을 넣어준다.
즉, 한 Collection 내 Point들은 모두 동일한 Vector Dimension(= 벡터 차원 수 = 임베딩 크기)를 가지고,

단일 Metric으로 비교되는 것이다.

예를 들면 1번 point의 예시에서 vector부분 배열 길이가 Collection의 벡터 차원 수와 동일해야만

그 Collection에 해당 Point를 넣을 수 있으며, Collection 내 Point들은 동일한 Distance Metrics에 의해 비교된다.

(다만 Named Vector는 단일 점에 여러 Vector를 가지고 고유의 차원 수와 메트릭을 쓸 수 있다고 한다)

아래는 Collection 생성 예시이다.

qdrant.create_collection(
    collection_name=collection_name,
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
)

물론 임베딩한 벡터 차원 수가 안 맞으면 DB에 넣을때 당연히 에러가 나는데,

임베딩 시 벡터 차원 수는 임베딩 모델마다 다르다.
가령, text-embedding-3-small(차원 수 1536)을 쓴다면 Qdrant VectorParams의 size도 위 예시처럼 1536으로 맞춰줘야한다.

/collection으로 Collection 목록을 조회해볼 수 있으며,
특정 collection에 값을 저장한 후 collection_name으로 조회해보면 아래와 같다.

{
  "result": {
    "status": "green",  // 컬렉션 상태 정상
    "points_count": 35,  // 현재 저장된 벡터 개수
    "config": {
      "params": {
        "vectors": {
          "size": 1536,         // 벡터 차원 수 (예: OpenAI 임베딩용)
          "distance": "Cosine"  // 유사도 계산 방식 (코사인 거리)
        },
        "on_disk_payload": true  // payload 디스크 저장 여부
      },
      "hnsw_config": {
        "m": 16,
        "ef_construct": 100,
        "on_disk": false  // 인덱스는 메모리에 존재
      },
      "optimizer_config": {
        "flush_interval_sec": 5,  // 디스크로 flush되는 주기 (5초)
        "indexing_threshold": 20000  // 인덱싱 시작 기준 
      }
    }
  },
  "status": "ok"
}

4. Storage

벡터를 저장할 스토리지는 2종류가 제공된다.

Memory 저장 (RAM 저장하니까 액세스 속도가 더 빠른 옵션이다.)
Memmap 저장 (파일로 만들어서 디스크에 저장)

Collection 생성시에 아래와 같이 지정할 수 있다.

client.recreate_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(
        size=1536,
        distance=Distance.COSINE
    ),
    on_disk_payload=True,  # payload를 디스크에 저장
    hnsw_config={
        "on_disk": False       # 인덱스는 메모리에 유지
    }
)

번외) Install

클라우드와의 없이 자체 인프라에서 실행하고자 하는 경우

Qdrant Private Cloud Enterprise Operator를 이용하여 Kubernetes 클러스터에 설치할 것을 권장

테스트 또는 개발 환경에서는 Qdrant를 컨테이너로 실행하거나, 바이너리 실행 파일로 직접 구동할 수 있음.
또한, Kubernetes에 손쉽게 설치할 수 있도록 Helm 차트를 함께 제공함.

Installation Guide

https://qdrant.tech/documentation/guides/installation/

Helm

https://artifacthub.io/packages/helm/qdrant/qdrant](https://artifacthub.io/packages/helm/qdrant/qdrant)

K8s

Helm Install

k create -n qdrant

helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo update
helm upgrade -i qdrant -n qdrant qdrant/qdrant #install

k get all -n qdrant

NodePort svc로 변경 (테스트 용도)

helm upgrade -i qdrant qdrant/qdrant \
  --set service.type=NodePort \
  --namespace qdrant

Docker

docker run -p 6333:6333 -d qdrant/qdrant