envoyadmin으로 Envoy 상태를 터미널에서 확인한다

envoyadmin은 Envoy 관리 API를 실시간으로 보여주는 터미널 UI다. 클러스터, 리스너, 시크릿의 상태와 세부 정보를 확인할 수 있어 config_dump를 직접 읽지 않아도 된다.

화면은 세 탭으로 나뉘며, 각 탭에서 왼쪽 목록과 오른쪽 세부 정보를 확인한다. Tab 키로 탭을 바꾸고, 상단에서 연결 상태와 오류를 확인할 수 있다.

클러스터 탭은 유형, 정상 호스트 수와 전체 호스트 수를 보여준다. 비정상 상태이거나 제외된 호스트가 있으면 색상 표시가 나타난다. e를 누르면 엔드포인트 주소와 상태 플래그, 가중치, 영역, rq_active·rq_error·cx_active를 확인할 수 있다. c를 누르면 /config_dump의 클러스터 설정을 줄 번호와 구문 강조가 적용된 YAML로 보여주며, version_info와 last_updated도 표시한다.

리스너 탭은 활성·정적 상태, 준비 중·드레이닝 상태, 거부된 업데이트를 구분한다. 문제가 있는 항목은 목록 위쪽에 정렬된다. o를 누르면 바인딩 주소와 상태, 마지막 업데이트, 거부된 업데이트의 오류를 확인할 수 있다. 이전 설정이 계속 서비스 중인 경우도 표시하며, 모든 필터 체인과 매치 조건, 필터를 보여준다. HTTP 필터는 트리 형태로 나타나고, c를 누르면 리스너 설정을 줄 번호가 붙은 YAML로 볼 수 있다.

시크릿 탭은 로드된 시크릿의 상태와 이름, version_info를 보여준다. 준비 중이거나 만료된 항목은 목록 위에 나타난다. o를 누르면 시크릿 종류와 버전, 마지막 업데이트, 인증서의 일련번호·SAN·만료 시점, 해당 시크릿을 사용하는 클러스터와 리스너를 확인할 수 있다. 시크릿 내용은 가져오거나 표시하지 않으며 공개 인증서만 읽는다. 클러스터와 리스너 화면에는 사용하는 시크릿이 표시되고, Envoy가 로드하지 않은 시크릿에는 (not loaded)가 붙는다.

모든 목록에서 /를 눌러 이름으로 퍼지 필터링할 수 있으며, 리스너 목록은 주소도 검색한다. 데이터는 자동으로 갱신되고 HTTP 호출은 UI 스레드를 막지 않는다. 요청에 실패하면 Envoy가 다시 응답할 때까지 빨간 오류 배너가 표시된다. 리스너나 시크릿 덤프만 실패한 경우에는 해당 탭에 Listeners (!), Secrets (!) 표시와 인라인 메시지가 나타나고 다른 탭은 계속 사용할 수 있다. 시크릿 탭의 Secrets (!) 표시는 시크릿이 준비 중이거나 만료된 경우에도 나타난다.

최신 릴리스는 Linux와 macOS의 amd64·arm64용으로 설치할 수 있다. 기본 설치 위치는 /usr/local/bin이다.

curl -fsSL https://raw.githubusercontent.com/regeda/envoyadmin/main/install.sh | sh

설치 스크립트는 운영체제와 CPU에 맞는 바이너리를 선택하고 릴리스 체크섬으로 확인한다. 설치 폴더에 쓸 수 없을 때만 sudo를 사용한다. VERSION으로 버전을 고정하고 INSTALL_DIR로 설치 위치를 바꿀 수 있다.

curl -fsSL https://raw.githubusercontent.com/regeda/envoyadmin/main/install.sh | VERSION=v0.1.0 INSTALL_DIR=$HOME/.local/bin sh

또는 GitHub 릴리스에서 바이너리를 내려받거나 Go로 설치할 수 있다.

go install github.com/regeda/envoyadmin/cmd/envoyadmin@latest

소스에서 빌드하고 실행하는 명령은 다음과 같다. make run은 클러스터 없이 내장 가짜 Envoy로 시험할 수 있다.

make build # bin/envoyadmin
make run # try it with the built-in fake Envoy, no cluster needed
bin/envoyadmin --admin http://localhost:15000

주요 옵션은 다음과 같다.

envoyadmin version은 버전을 출력하며, NO_COLOR=1을 설정하면 색상을 끌 수 있다. 위·아래 화살표 또는 j·k로 목록을 이동하고, PgUp·PgDn, g·G로 페이지를 이동하거나 목록의 처음과 끝으로 갈 수 있다. 필터 입력 중에는 Ctrl+N·Ctrl+P로 이동한다. Enter는 세부 정보에 초점을 맞추며, Esc는 목록으로 돌아간다. c는 설정, o는 개요, 클러스터에서 e는 엔드포인트 화면을 연다. r은 즉시 새로고침, x는 오류 배너 닫기, ?는 전체 키 목록 표시, q 또는 Ctrl+C는 종료다.

쿠버네티스 파드에서 사용하려면 관리 포트를 로컬로 포워딩한 뒤 --admin에 연결 주소를 지정한다. 일반 파드나 배포는 deploy/<name> 또는 svc/<name>도 포워딩 대상으로 쓸 수 있다. Istio 사이드카의 관리 포트는 istio-proxy 컨테이너의 15000이며, 같은 방식으로 포워딩하면 된다. istioctl dashboard envoy <pod>.<ns>도 포워딩을 여는 대안이다. 독립 실행형 Envoy는 부트스트랩의 admin.address에 지정된 포트를 사용하며, 흔히 9901이다.

포워딩은 다른 터미널에서 계속 실행해야 한다. 관리 인터페이스에는 인증이 없으므로 127.0.0.1에만 바인딩하고 외부에 노출하지 않아야 한다. 포워딩이 끊기면 오류 배너가 나타나며, 포워딩이 복구되면 envoyadmin도 자동으로 회복한다. client-go 포트 포워딩을 사용하는 내장 --pod <ns>/<name> 옵션은 계획 중이며, 같은 admin.Client 인터페이스를 사용하도록 할 예정이다.

MIT 라이선스이며 자세한 내용은 LICENSE를 참고하면 된다.