마스터 키 회전하기

마스터 키는 프록시의 관리자 자격 증명이에요. 관리자 API 호출을 인증하고 Admin UI 로그인에도 쓰이죠. 어떤 배포에서는 저장된 자격 증명을 암호화하는 키 역할도 겸하기 때문에, 마스터 키를 바꾸는 방법을 잘못 고르면 저장돼 있던 자격 증명을 아예 읽지 못하게 될 수 있어요. 이 장에서는 안전하게 회전하는 방법을 정리해요.

출처: 공식문서

어떤 역할을 하는지 먼저 파악하기

마스터 키는 두 가지 역할 중 하나를 해요.

순수 인증 키: 솔트 키(LITELLM_SALT_KEY)가 설정된 경우, 저장된 자격 증명은 솔트 키로 암호화되고 마스터 키는 인증만 담당해요.
암호화 키 겸용: 솔트 키가 없으면 마스터 키가 저장된 데이터를 암호화하는 데 그대로 쓰여요.

이 역할에 따라 회전 방법이 달라져요.

솔트 키가 설정된 경우 (권장)

솔트 키가 있으면 마스터 키를 바꿔도 저장된 데이터를 재암호화할 필요가 없어요.

새 마스터 키 값을 만듭니다.
LITELLM_MASTER_KEY 환경변수나 general_settings.master_key를 새 값으로 갱신합니다.
모든 프록시 인스턴스를 재시작해 새 값을 읽게 합니다.

이 경우 POST /key/regenerate에 new_master_key를 넣어 호출하면 안 돼요. 그렇게 하면 프록시가 복호화에 쓰지 않는 키로 전부 재암호화해서 자격 증명을 못 읽게 만들 수 있거든요.

솔트 키 자체는 바꾸면 안 됩니다. 마스터 키 회전 전에 전용 솔트 키를 설정해 두는 걸 권장할 만큼 중요한 값이에요.

솔트 키가 없는 경우

솔트 키가 없으면 마스터 키가 저장 데이터의 암호화 키를 겸하므로, 회전 시 저장된 데이터를 재암호화해야 해요. POST /key/regenerate에 현재 마스터 키와 새 마스터 키를 넘겨 호출하면, 저장된 모델·환경변수·자격 증명 등을 새 키로 재암호화해요.

호출 후에는 반드시 마무리 단계가 필요해요. 실행 중인 프록시는 스스로 새 키를 채택하지 않으므로:

새 마스터 키를 환경변수·시크릿 매니저·config.yaml 등 이전 값이 있던 모든 곳에 반영합니다. (general_settings.master_key가 환경변수보다 우선하니 그것도 확인합니다.)
모든 프록시 인스턴스를 재시작합니다.
Admin UI 로그인과 DB 저장 모델 호출로 정상 동작을 확인합니다.

주의사항

회전하기 전에 데이터베이스를 백업하는 게 안전해요. 모델 재암호화는 행을 삭제 후 재생성하거나, 실패한 행은 건너뛸 수 있어서 부분 실패 시 데이터가 끊길 수 있어요.
가상 키는 해시로 저장돼서 어떤 회전 방식이든 그대로 동작해요.
store_model_in_db로 DB에 저장된 모델만 재암호화 대상이고, config 파일에 정의된 모델은 영향이 없어요.
이 기능은 오픈소스 빌드에서 사용 가능하고, Admin UI 대신 API로만 수행돼요.

더 알아보기

솔트 키 설정 위치와 역할은 프로덕션 모범 사례 문서를 참고하세요.
키 회전 결과를 시크릿 매니저에 기록하는 방법도 참고하면 좋아요.