JupyterHub + HAProxy 설치 및 운용 (Standalone)

hooni

기존에 사용하던 Jupyter-lab을 HAProxy와 연동하려다 이런저런 문제가 생겨서 JupyterHub를 도입하게 되었다.
JupyterHub는 Jupyter-lab과 달리 멀티 유저환경을 지원하며 프록시 또한 제공한다.
그러한 까닭에 JupyterHub는 Jupyter-lab과 달리 구조가 복잡하다.

../_images/architecture.png
image from https://z2jh.jupyter.org/en/stable/administrator/architecture.html

JupyterHub는 프록시와 허브, 파드로 구성되어있다.
프록시, 허브, 파드는 각각 인터페이스, 코어, 유저를 의미한다.
공식문서가 친절한 편은 아니기에 각 모듈의 설명을 한눈에 확인하기 어려운 편이나 구조를 이해하고나면 나름 사용방법을 알아내기도 쉽다.

JupyterHub의 각 모듈은 독립된 서비스로 동작한다.
허브는 The Littlest JupyterHub(TLJH)로 동작하며 jupyterhub라는 서비스 형태로 운용된다. [docs]
JupyterHub는 프록시로 configurable-http-proxy(CHP)를 사용한다. [docs]
다만, 그와 별도로 traefik HTTP 프록시 서비스를 사용하여 보다 강력한 리버스 프록시 기능을 제공한다. [docs]
왜 이렇게 복잡하게 구성했는지는 필자도 잘 이해되지 않는다.
사용자 계정은 OS와 연동되어 관리된다.
이는 jupyter에서의 파일 생성, 실행 등이 OS의 파일시스템 위에서 이루어지기 때문이다.
그러므로 JupyterHub에서 생성된 계정은 OS에서 생성된 계정이 연동된 것이다.

이후 목차는 다음과 같다.

  1. JupyterHub 설치
  2. JupyterHub 설정 변경
  3. HAProxy 연동 (선택)
  4. 계정 생성 및 비밀번호 수정
  5. 계정별 conda 설정

1. JupyterHub 설치

Ubuntu에 JupyterHub를 설치한다. [docs]
curl을 통해 JupyterHub를 내려받고 python으로 설치한다.
이 과정에서 admin 계정이 필요하다.

$ curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin root

그 이후 JupyterHub 서비스를 실행하면 80 포트를 통해 JupyterHub에 접속할 수 있다.

위의 설치 과정에서 /opt/tljh 경로에 tljh와 traefik이 설치된다.
tljh hub는 15001 포트를, CHP 프록시는 8000 포트를 디폴트로 사용하며 traefik은 80 포트를 디폴트로 사용한다. [docs]

2. JupyterHub 설정 변경

2-1. Hub 설정 변경

Hub는 /opt/tljh/hub/lib/python3.11/site-packages/tljh/jupyterhub_config.py에서 설정할 수 있다. [docs]

2-2. traefik 설정 변경

traefik은 /opt/tljh/traefik.toml에서 설정할 수 있다.
HAProxy를 사용하는 경우 :80 포트를 임의의 포트(예: 12345)로 설정하여 충돌을 피해야 한다.

3. HAProxy 연동 (선택)

HAProxy가 이미 설치되어있다고 가정한다.
/etc/haproxy/haproxy.cfg에서 다음 예시와 같이 설정을 변경하면 된다.

frontend http
        mode http
        bind :80

        acl is_jupyter hdr_end(host) -i <YOUR-URL>

        use_backend jupyter if is_jupyter
        default_backend deny

# Backend
backend deny
        mode http
        http-request deny deny_status 503

backend jupyter
        mode http
        server jupyter 127.0.0.1:<YOUR-PORT-NUMBER>

https로 서비스하고싶은 경우 위에서 ssl과 https를 사용하도록 설정하면 된다.
그 결과 JupyterHub는 15001, 8000 포트에서 서비스되고 traefik은 12345(예시) 포트에서 서비스되며
HAProxy는 <YOUR-URL>:80으로 들어오는 요청을 traefik으로 포워딩한다.

4. 계정 생성 및 비밀번호 수정

JupyterHub에 접속한 후 JupyterHub 설치 시 입력했던 admin 계정으로 접속한다.
비밀번호로는 OS의 admin 계정 비밀번호를 사용하면 된다.

JupyterHub log-in page

이후 상단의 Control Panel에서 Admin을 들어간 후 계정을 생성할 수 있다.
비밀번호를 바꾸기 위해서는 각 계정으로 로그인하여 직접 바꾸어야 한다.
계정 생성 시 비밀번호는 Admin의 비밀번호와 동일하기에 Admin 권한이 있는 사람이 직접 비밀번호를 바꾸어야 한다.

JupyterHub 웹 인터페이스에서는 비밀번호 변경 기능을 제공하지 않는다.
그러므로 비밀번호를 바꾸기 위해서는 <URL>/hub/auth/change-password을 입력하여 접속하여야 한다.
도대체 왜 이런 프로세스로 설계했는지 전혀 이해가지 않는다.

계정을 생성한 후에는 OS에서도 jupyter-<username>으로 계정이 자동 생성된다.
이 계정은 sh을 기본 쉘로 사용하며 각자의 home 경로 또한 만들어진다.
OS에서의 계정 비밀번호는 JupyterHub가 별도로 관리하기 때문에 위에서 변경한 비밀번호로는 로그인이 불가능하다.

5. 계정별 conda 설정

각각의 계정에서 conda를 설정한다.
JupyterHub에서 conda를 지원하기 때문에 별도로 conda를 설치할 필요는 없다.
다음과 같은 과정을 통해 conda를 설정한다.

$ conda init bash  # 이후 터미널 재시작
$ conda create -n <env-name> python=3.11  # 가상환경 생성
$ echo "source activate <env-name>" ~/.bashrc  # 디폴트 가상환경 설정

그 이후 conda를 JupyterHub의 커널에 등록한다.
미리 생성한 가상환경의 이름을 env-name에 넣어주고, 커널에 표시될 이름을 display-name에 넣어주면 된다.
user 플래그는 현재 사용자의 수준으로 커널을 등록하기 위해 사용한다.

$ conda install ipykernel
$ python -m ipykernel install --user --name <env-name> --display-name "<display-name>"

만약 커널을 제거하고 싶다면 다음의 커맨드를 사용하면 된다.

$ upyter kernelspec remove <env-name>

그 결과 다음과 같이 가상환경을 사용할 수 있다.
필자의 가상환경 이름은 default이다.

댓글 남기기