K9s 마우스 스크롤 시 터미널 화면이 밀리는 문제 해결하기

| 서론

안녕하세요, 팡일입니다.

최근 K9s 를 사용하면서 꽤 답답한 문제를 하나 겪었습니다. Pod 로그나 리스트 화면에서 마우스 휠로 스크롤을 하려고 하면, 내부 내용이 움직이는 게 아니라 터미널 화면 자체가 위로 밀려 올라가는 현상이었습니다.

처음에는 단순히 K9s 설정 문제라고 생각했는데, 실제로는 터미널 환경 설정까지 함께 수정해야 해결되는 문제였습니다.

이번 글에서는 제가 직접 겪었던 시행착오와 함께, K9s 스크롤 문제를 해결하는 방법을 정리해보겠습니다.

| 문제 현상

다음과 같은 증상이 발생한다면 같은 문제일 가능성이 높습니다.

• Pod 목록이나 로그 화면에서 마우스 스크롤이 정상 동작하지 않음

• 로그 내부가 이동하는 대신 터미널 전체 화면이 위로 밀림

• 이전 터미널 출력(Scrollback Buffer)이 보이면서 화면이 깨져 보임

특히 macOS + iTerm2 조합에서 자주 발생합니다.

| 해결 방법

1) K9s 설정에서 마우스 활성화하기

가장 먼저 K9s가 마우스 입력을 사용할 수 있도록 설정해야 합니다.

(1) 설정 파일 경로 확인

: 인터넷에서는 보통 아래 경로를 많이 안내합니다.

~/.config/k9s/config.yaml

하지만 실제로는 운영체제나 설치 방식에 따라 경로가 다를 수 있습니다.

아래 명령어로 현재 사용 중인 설정 파일 경로를 먼저 확인해 주세요.

k9s info

예를 들어 macOS에서는 아래처럼 나오는 경우가 많습니다.

Configuration:
/Users/username/Library/Application Support/k9s/config.yml

여기서 중요한 점은 아래와 같습니다.

• .yaml 이 아니라 .yml 일 수도 있음

• 경로가 ~/.config 가 아닐 수도 있음

(2) 설정 수정

: 확인한 설정 파일을 열고 아래 옵션을 추가하거나 수정합니다.

k9s:
  ui:
    enableMouse: true

이 설정을 통해 K9s가 마우스 입력을 받을 수 있게 됩니다.

2) iTerm2 설정 변경하기

여기까지 했는데도 해결되지 않는다면, 대부분은 터미널 설정 문제입니다.

iTerm2 에서 Alternate Screen Mode 상태일 때 마우스 스크롤을 방향키 입력처럼 전달하도록 설정해야 합니다.

(1) 설정 방법

1. iTerm2 실행
2. Cmd + , 로 Settings 열기
3. Advanced 탭 이동
4. 검색창에 scroll wheel 입력
5. 아래 옵션 찾기
- Scroll wheel sends arrow keys when in alternate screen mode
6. 값을 Yes 로 변경

3) K9s 완전히 재실행하기

설정 파일 수정과 iTerm2 옵션 변경을 모두 완료했더라도, 기존 세션에서는 즉시 반영되지 않는 경우가 있습니다.

그래서 반드시 아래의 과정까지 해주는 것을 추천드립니다.

• 실행 중인 K9s 종료 (Ctrl + C 또는 :q)

• 터미널 탭 새로 열기

• 필요하면 iTerm2 자체 재실행

이 과정을 거친 뒤 다시 k9s 를 실행하면 정상적으로 스크롤이 동작하는 경우가 많습니다.

| 함께 알아두면 좋은 K9s 스크롤 단축키

마우스 없이 사용할 때도 아래 단축키를 익혀두면 정말 편합니다.

특히 로그를 볼 때 gg, G 는 꽤 자주 사용하게 됩니다.

| 결론

처음에는 단순히 K9s 자체의 문제라고 생각했지만, 실제로는 K9s 설정과 터미널 환경 설정이 함께 맞물려 있던 문제였습니다.

특히 아래 3가지가 핵심이었습니다.

• enableMouse: true 설정

• iTerm2 Alternate Screen Mode 옵션 변경

• K9s 완전 재실행

저처럼 K9s 사용 중 마우스 스크롤 때문에 불편함을 겪고 계셨다면, 위 설정들을 차근차근 확인해보시는 걸 추천드립니다.