Linkerd 문서
Linkerd 문서 (Docs)
Linkerd는 Kubernetes용 서비스 메시로, 컨트롤 플레인과 데이터 플레인으로 구성돼요. 이 문서는 Linkerd를 시작하는 방법부터 기능, 태스크, 참조 자료까지 안내해요.
출처: Linkerd Docs
본문
시작하기 (Getting Started)
Linkerd에 오신 걸 환영해요! 🎈
이 가이드에서는 Kubernetes 클러스터에 Linkerd를 설치하는 방법을 차근차근 안내해요. 그다음 예제 애플리케이션을 배포해서 Linkerd가 무엇을 할 수 있는지 보여드릴게요.
이 가이드는 Linkerd의 기초를 익히도록 설계됐어요. 먼저 로컬 머신에 CLI(커맨드라인 인터페이스)를 설치해요. 이 CLI를 사용해서 Kubernetes 클러스터에 컨트롤 플레인을 설치해요. 마지막으로 애플리케이션에 Linkerd의 데이터 플레인을 추가해서 "메시"로 만들어요.
Edge 릴리스 콘텐츠
이 페이지는 Linkerd의 최신 edge 릴리스를 사용하는 지침을 담고 있어요. 안정 릴리스를 포함한 다른 유형의 릴리스에 대해서는 Linkerd Releases를 참고하세요.
Step 0: 설정
그 무엇보다도 먼저, 최신 Kubernetes 클러스터에 접근할 수 있고 로컬 머신에서 kubectl 명령어가 동작하는지 확인해야 해요. (아직 Kubernetes 클러스터가 없다면 로컬 머신에서 실행하는 것도 쉬운 방법이에요. kind, k3d, Docker for Desktop 등 다양한 방법이 있어요.)
다음을 실행해서 Kubernetes 설정을 검증해 보세요:
kubectl version
Client Version과 Server Version 컴포넌트가 모두 있는 출력이 보여야 해요.
이제 클러스터가 준비됐으니 Linkerd CLI를 설치하고, 이 CLI로 클러스터가 Linkerd를 호스팅할 수 있는지 검증할 거예요.
참고 GKE "private cluster"를 쓰거나 Cilium을 CNI로 쓰는 경우, 다음 단계로 진행하기 전에 클러스터별 구성이 필요할 수 있어요.
Step 1: CLI 설치
Linkerd를 처음 실행하는 경우, 로컬 머신에 linkerd CLI를 다운로드해야 해요. 이 CLI로 Linkerd 배포와 상호작용할 수 있어요.
CLI를 수동으로 설치하려면 다음을 실행하세요:
# Setting LINKERD2_VERSION sets the version to install.
# If unset, you'll get the latest available edge version.
export LINKERD2_VERSION=edge-26.9.3
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh
PATH에 추가하는 지침을 반드시 따라 하세요:
export PATH=$HOME/.linkerd2/bin:$PATH
이렇게 하면 Linkerd의 최신 edge 릴리스 CLI가 설치돼요. (edge 릴리스가 무엇인지에 대한 자세한 내용은 Releases and Versions 페이지를 참고하세요.)
설치가 끝나면 다음으로 CLI가 제대로 동작하는지 확인하세요:
linkerd version
CLI 버전과 함께 Server version: unavailable이 보인다면 아직 클러스터에 컨트롤 플레인을 설치하지 않았다는 뜻이에요. 걱정 마세요, 곧 해결할 거예요.
Linkerd의 지원 Kubernetes 버전을 확인해서 Linkerd 버전과 Kubernetes 버전이 호환되는지 확인하세요.
Step 2: Gateway API 설치
Linkerd의 여러 기능은 인가 정책과 동적 요청 라우팅을 포함해 Gateway API 프로젝트의 CRD로 구성돼요. 많은 Kubernetes 클러스터에서 이 CRD는 이미 제공되지만, 없는 경우에는 먼저 설치해야 해요.
Gateway API가 설치돼 있는지 확인하고 설치하는 방법에 대한 지침을 따라 하세요.
Step 3: Kubernetes 클러스터 검증
Kubernetes 클러스터는 다양한 방식으로 구성될 수 있어요. Linkerd 컨트롤 플레인을 설치하기 전에 모든 것이 올바르게 구성됐는지 확인하고 검증해야 해요. 클러스터가 Linkerd를 설치할 준비가 됐는지 확인하려면 다음을 실행하세요:
linkerd check --pre
통과하지 못한 검사가 있다면, 제공된 링크를 따라 진행하기 전에 그 문제들을 고치세요.
Step 4: 클러스터에 Linkerd 설치
이제 CLI를 로컬에서 실행 중이고 클러스터도 준비됐으니, Kubernetes 클러스터에 Linkerd를 설치할 차례예요. 이렇게 하려면 다음을 실행하세요:
linkerd install --crds | kubectl apply -f -
그다음에:
linkerd install | kubectl apply -f -
이 명령어들은 Linkerd에 필요한 모든 핵심 리소스를 가진 Kubernetes 매니페스트를 생성해요 (궁금하다면 이 출력을 살펴봐도 좋아요). 이 매니페스트를 kubectl apply로 파이프하면 Kubernetes에 그 리소스들을 클러스터에 추가하라고 지시하게 돼요. install --crds 명령어는 먼저 설치해야 하는 Linkerd의 Custom Resource Definitions(CRD)를 설치하고, install 명령어는 Linkerd 컨트롤 플레인을 설치해요.
참고 여기서 소개하는 CLI 기반 설치는 빠르고 쉽지만, Helm 차트를 사용하거나 Kubernetes 제공업체의 마켓플레이스 설치를 사용하는 등 Linkerd를 설치하는 다양한 방법이 있어요.
클러스터 인터넷 연결 속도에 따라 컨트롤 플레인 설치가 완료되는 데 1~2분 걸릴 수 있어요. 다음을 실행해서 컨트롤 플레인이 준비될 때까지 기다리고(그리고 설치를 검증하고) 하세요:
linkerd check
Step 5: 데모 앱 설치
축하해요, Linkerd가 설치됐어요! 하지만 아직 아무것도 하고 있지 않아요. Linkerd가 동작하는 모습을 보려면 애플리케이션이 필요해요.
Emojivoto라는 데모 애플리케이션을 설치해 볼게요. Emojivoto는 gRPC와 HTTP 호출을 섞어서 사용자가 좋아하는 이모지에 투표할 수 있게 해주는 간단한 독립형 Kubernetes 애플리케이션이에요.
emojivoto 네임스페이스에 Emojivoto를 설치하려면 다음을 실행하세요:
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/emojivoto.yml \
| kubectl apply -f -
이 명령어는 Emojivoto를 클러스터에 설치하지만, 아직 Linkerd는 활성화되지 않았어요. Linkerd가 마법을 부리기 전에 애플리케이션을 "메시"로 만들어야 해요.
메시로 만들기 전에 Emojivoto가 자연스러운 상태로 어떻게 생겼는지 살펴볼게요. 브라우저로 접근할 수 있게 web-svc 서비스로 트래픽을 포워딩해서 확인할 거예요. 다음을 실행해서 web-svc를 로컬 8080 포트로 포워딩하세요:
kubectl -n emojivoto port-forward svc/web-svc 8080:80
이제 http://localhost:8080에 방문해 보세요. 짠! Emojivoto의 멋진 모습이 보일 거예요.
Emojivoto를 클릭하며 돌아다니다 보면 뭔가 고장난 것처럼 보일 거예요! 예를 들어 도넛 이모지에 투표하려고 하면 404 페이지가 나와요. 걱정 마세요, 이 오류들은 의도된 거예요. (나중 가이드에서 Linkerd로 이 문제를 찾아내는 방법을 보여드릴게요.)
Emojivoto가 설치되어 실행 중이니 이제 메시로 만들 준비가 됐어요. 즉, 여기에 Linkerd 데이터 플레인 프록시를 추가하는 거예요. Kubernetes의 롤링 배포 덕분에 다운타임 없이 실행 중인 애플리케이션에 이 작업을 할 수 있어요. 다음을 실행해서 Emojivoto 애플리케이션을 메시로 만들어 보세요:
kubectl get -n emojivoto deploy -o yaml \
| linkerd inject - \
| kubectl apply -f -
이 명령어는 emojivoto 네임스페이스에서 실행 중인 모든 디플로이먼트를 가져와서 각 매니페스트를 linkerd inject로 처리한 다음 클러스터에 다시 적용해요. (linkerd inject 명령어는 파드가 생성될 때 Linkerd가 프록시를 주입하도록 지시하는 어노테이션을 파드 스펙에 추가할 뿐이에요.)
install과 마찬가지로 inject는 순수한 텍스트 연산이에요. 즉, 사용하기 전에 입력과 출력을 살펴볼 수 있어요. kubectl apply로 파이프되면 Kubernetes가 롤링 배포를 실행해 각 파드를 데이터 플레인의 프록시로 업데이트해요.
축하해요! 이제 애플리케이션에 Linkerd를 추가했어요! 컨트롤 플레인과 마찬가지로 데이터 플레인 쪽에서도 모든 것이 제대로 동작하는지 확인할 수 있어요. 다음으로 데이터 플레인을 확인하세요:
linkerd -n emojivoto check --proxy
그리고 당연히 http://localhost:8080을 방문해서 메시로 감싸진 Emojivoto의 모습을 다시 볼 수 있어요.
Step 6: Linkerd 탐험하기!
마지막 단계가 조금 아쉬웠을지도 몰라요. Emojivoto에 Linkerd를 추가했지만 애플리케이션에 눈에 띄는 변화가 없거든요! 그것은 Linkerd 설계의 일부예요. Linkerd는 동작 중인 애플리케이션을 방해하지 않도록 최선을 다해요.
Linkerd가 실제로 무엇을 하고 있는지 자세히 살펴볼게요. 이렇게 하려면 확장을 설치해야 해요. Linkerd의 핵심 컨트롤 플레인은 매우 최소한이라서, Linkerd는 대시보드 같은 중요하지 않지만 종종 유용한 기능을 추가하는 확장과 함께 배포돼요.
클러스터 내 메트릭 스택과 대시보드를 설치할 viz 확장을 설치해 볼게요.
viz 확장을 설치하려면 다음을 실행하세요:
linkerd viz install | kubectl apply -f - # install the on-cluster metrics stack
확장을 설치했으면 마지막으로 모든 것을 한 번 검증해 보세요:
linkerd check
컨트롤 플레인과 확장이 설치되어 실행 중이니 이제 Linkerd를 탐험할 준비가 됐어요! 다음으로 대시보드에 접근하세요:
linkerd viz dashboard &
다음과 같은 화면이 보여야 해요:
동작 중인 모습을 보여주는 Linkerd 대시보드
클릭하며 탐험하고 재미있게 놀아보세요! 보너스 과제로, 각 Emojivoto 컴포넌트의 실시간 메트릭을 찾아서 어느 컴포넌트에 부분 장애가 있는지 알아내 보세요. (이에 대한 더 자세한 내용은 아래 디버깅 튜토리얼을 참고하세요.)
바로 그거예요! 👏
축하해요, 당신은 이제 Linkerd 사용자라는 높은 반열에 올랐어요! 스스로 등을 토닥여 주세요.
다음은 뭐가 있을까요?
다음 단계를 추천해요:
- Linkerd로 Emojivoto의 오류를 디버깅하는 방법 배우기.
- 다운타임 없이 자기 서비스를 Linkerd에 추가하는 방법 배우기.
- Jaeger와 multicluster 확장 같은 다른 Linkerd 확장을 설치하는 방법 배우기.
- Linkerd의 아키텍처에 대해 더 알아보기.
- 오래 운영되는 클러스터를 위해 자동 컨트롤 플레인 mTLS 자격 증명 순환을 설정하는 방법 배우기.
- 인가 정책으로 서비스 접근을 제한하는 방법 배우기.
- Linkerd Slack의 #linkerd 채널에 들러서 인사하기!
무엇보다도: Linkerd 커뮤니티에 온 것을 환영합니다!
Linkerd는 원래 Buoyant가 만들었어요.