Linkerd 시작하기
Linkerd를 Kubernetes 클러스터에 설치하고, 샘플 애플리케이션을 배포해 Linkerd가 어떤 일을 하는지 살펴보는 가이드예요. CLI 설치부터 제어 플레인(control plane) 설치, 그리고 애플리케이션에 데이터 플레인(data plane)을 더하는 "메시(mesh)" 작업까지 순서대로 따라 해 볼게요. 이 실습은 Linkerd의 기초를 익히기 위해 설계되었어요.
본문
Linkerd에 오신 걸 환영해요! 🎈
이 가이드에서는 Linkerd를 Kubernetes 클러스터에 설치하는 방법을 차근차근 알려드릴게요. 그다음 샘플 애플리케이션을 배포해서 Linkerd가 어떤 일을 할 수 있는지 직접 확인해 볼 거예요.
이 가이드는 Linkerd의 기본을 익히도록 도와줘요. 먼저 로컬 머신에 CLI(명령줄 인터페이스)를 설치하고, 이 CLI를 이용해 Kubernetes 클러스터에 제어 플레인을 설치할 거예요. 마지막으로 애플리케이션에 Linkerd의 데이터 플레인을 더해서 "메시"를 만들 거예요.
엣지 릴리스 콘텐츠
이 페이지는 Linkerd 최신 엣지 릴리스를 기준으로 한 지침을 담고 있어요. 안정(stable) 릴리스를 포함한 다른 종류의 릴리스에 대해서는 Linkerd Releases 문서를 참고해 주세요.
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로 사용하는 경우, 다음 단계로 진행하기 전에 클러스터별 설정이 조금 필요할 수 있어요.
1단계: CLI 설치
Linkerd를 처음 사용하는 경우 로컬 머신에 linkerd CLI를 내려받아야 해요. 이 CLI를 통해 Linkerd 배포를 다룰 수 있어요.
CLI를 직접 설치하려면 다음을 실행해요.
`# LINKERD2_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 최신 엣지 릴리스용 CLI가 설치돼요. (엣지 릴리스가 무엇인지 자세히 알고 싶다면 Releases and Versions 페이지를 참고해 주세요.)
설치가 끝나면 CLI가 제대로 동작하는지 다음으로 확인해요.
`linkerd version
`
CLI 버전과 함께 Server version: unavailable이 보일 거예요. 아직 클러스터에 제어 플레인을 설치하지 않았기 때문이에요. 걱정하지 마세요. 곧 해결할게요.
Linkerd 버전과 Kubernetes 버전이 호환되는지 Linkerd의 supported Kubernetes versions 페이지에서 꼭 확인해 주세요.
2단계: Gateway API 설치
Linkerd의 여러 기능은 Gateway API 프로젝트의 CRD로 구성돼요. 인가(authorization) 정책과 동적 요청 라우팅이 대표적이에요. 많은 Kubernetes 클러스터에 이 CRD가 이미 있지만, 없다면 먼저 설치해야 해요.
Gateway API가 설치되어 있는지 확인하는 방법과 설치 방법은 이 안내를 따라 주세요.
3단계: Kubernetes 클러스터 검증
Kubernetes 클러스터는 다양한 방식으로 구성될 수 있어요. Linkerd 제어 플레인을 설치하기 전에 모든 것이 올바르게 설정되었는지 확인해야 해요. 클러스터가 Linkerd 설치를 받을 준비가 되었는지 검사하려면 다음을 실행해요.
`linkerd check --pre
`
통과하지 못한 검사가 있다면 제공된 링크를 따라 문제를 고친 뒤 계속 진행해 주세요.
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 제공업체의 marketplace 설치를 이용하는 등 다양한 방법으로도 Linkerd를 설치할 수 있어요.
클러스터 인터넷 연결 속도에 따라 제어 플레인 설치가 1~2분 걸릴 수 있어요. 제어 플레인이 준비될 때까지 기다렸다가(그리고 설치를 검증하려면) 다음을 실행해요.
`linkerd check
`
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 에 접속해 보세요. Voila! Emojivoto를 온전히 감상할 수 있을 거예요.
Emojivoto 주변을 둘러보면 조금 고장 나 있다는 걸 알 수 있어요! 예를 들어 도넛(donut) 이모지에 투표하려 하면 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를 다시 감상할 수 있어요.
6단계: Linkerd 탐험!
마지막 단계가 조금 시시했을 수도 있어요. Emojivoto에 Linkerd를 추가했는데 애플리케이션에 보이는 변화가 없으니까요! 그게 바로 Linkerd의 설계 의도예요. 동작 중인 애플리케이션을 최대한 방해하지 않으려고 하거든요.
Linkerd가 실제로 무엇을 하는지 자세히 살펴볼게요. 이를 위해 *확장(extension)*을 설치해야 해요. 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 커뮤니티에 오신 것을 환영해요!