무중단 애플리케이션 비밀값 교체를 운영 절차로 만드는 법
애플리케이션 비밀값을 한 번에 바꾸지 않고 이중 허용, 점진 전환, 검증, 폐기 순서로 교체해 장애 없이 완료하는 운영 절차와 실패 시 되돌림 기준을 정리합니다.
비밀값 교체는 새 값을 저장하는 작업이 아니라 읽기·쓰기 경로를 잠시 겹치게 만든 뒤 트래픽을 관찰하면서 이전 값을 제거하는 변경입니다. 한 번에 환경변수만 바꾸면 이미 실행 중인 프로세스가 옛 값을 계속 들고 있거나, 일부 인스턴스가 새 값과 맞지 않아 인증 실패가 섞입니다. 무중단을 목표로 한다면 v2를 먼저 준비하고 v1과 v2를 함께 검증할 수 있는 짧은 전환 창을 설계해야 합니다.
중단 없는 교체의 조건을 먼저 고정하기
첫 조건은 새 비밀값을 등록해도 기존 요청이 계속 처리되는 것입니다. 둘째는 어떤 인스턴스가 어느 버전을 읽는지 로그나 메트릭으로 구분할 수 있어야 합니다. 셋째는 실패했을 때 v1을 다시 허용하는 되돌림 경로가 남아 있어야 합니다. 이 세 조건을 충족하지 못하면 교체는 배포가 아니라 점검 창을 잡는 별도 작업으로 다뤄야 합니다.
읽기 전용 API 키는 새 키를 발급하고 두 키를 허용한 뒤 클라이언트를 전환할 수 있지만, 단일 비밀번호만 받는 데이터베이스 계정은 같은 계정의 비밀번호를 즉시 덮어쓰는 순간 구형 연결이 끊길 수 있습니다. 후자의 경우 계정 두 개, 프록시 계층, 또는 연결 재생성 절차 중 하나가 필요합니다. 전환 가능성은 비밀값의 형식이 아니라 상대 시스템이 복수 자격 증명을 허용하는지로 판단합니다.
단계별 실행과 남겨야 할 산출물
준비 단계에서는 대상 서비스, 읽기 경로, 캐시와 프로세스 재시작 방식, 담당자를 표로 적습니다. 새 값은 운영자가 채팅에 붙여 넣지 않고 비밀 저장소에서 생성하며, 버전 ID와 만료 예정 시각만 변경 티켓에 남깁니다. 이 산출물은 값 자체를 노출하지 않으면서도 나중에 어떤 변경이었는지 재현하게 해 줍니다.
v2를 저장하고 저장소의 읽기 권한과 감사 로그를 확인합니다.
검증 환경에서 v1·v2를 모두 허용하고 읽기·쓰기 프로브를 실행합니다.
작은 인스턴스 묶음부터 v2를 읽도록 배포하고 오류율을 비교합니다.
모든 인스턴스가 v2를 확인한 뒤에만 v1을 폐기합니다.
전환 중에는 비밀값을 출력하는 디버그 로그를 켜지 않습니다. 대신 secret_version 같은 비민감한 식별자, 인증 결과 코드, 재시도 횟수, 영향받은 인스턴스 수를 함께 기록합니다. 배포 직후 성공률만 보지 말고 연결 풀에 남은 오래된 연결이 교체되는 시간까지 관찰해야 합니다.
예시: 외부 결제 API 키를 v1에서 v2로 바꾸기
예시의 입력은 결제 API가 v1 키를 7개 애플리케이션 인스턴스에서 사용하고 있고, 공급자가 키 두 개를 동시에 활성화할 수 있다는 조건입니다. 결정은 v2를 먼저 발급한 뒤 인증 헤더 생성기가 활성 키 목록을 순서대로 시도하게 하고, 성공한 버전을 메트릭에 남기는 것입니다. 중간 산출물은 키 값이 없는 전환 기록표이며 대상, v2 버전 ID, 프로브 결과, 단계별 시작·종료 시각을 포함합니다. 예상 결과는 모든 인스턴스의 최근 요청이 v2로 성공하고 v1 시도 횟수가 0이 되는 것입니다.
작은 묶음에서 15분 동안 인증 오류와 지연이 기준선 안에 있으면 다음 묶음으로 진행합니다. 오류가 나타나면 v1을 다시 허용하고 해당 인스턴스의 배포 버전, 캐시 갱신 시각, 공급자 응답 코드를 비교합니다. 복구가 끝나기 전에는 v1을 폐기하지 않으며, 원인이 공급자 측 제한이면 새 키를 더 발급하는 대신 공급자 상태와 한도를 확인해 에스컬레이션합니다.
실패 경계와 되돌림 규칙
가장 위험한 실패는 일부 인스턴스만 새 값을 읽고 나머지는 옛 값을 읽는 상태를 성공으로 오판하는 것입니다. 버전별 성공률을 분리하지 않으면 전체 평균이 정상처럼 보일 수 있습니다. 또 다른 경계는 배치 작업이나 별도 워커가 웹 프로세스와 다른 캐시를 사용하는 경우입니다. 웹 요청만 확인한 뒤 v1을 삭제하면 야간 배치가 실패할 수 있으므로 모든 실행 주체를 목록에 넣습니다.
되돌림은 코드와 비밀값을 함께 되돌리는 절차가 아니라 인증 상대가 v1을 다시 받도록 허용하고, 문제가 난 인스턴스의 프로세스를 재시작하는 순서로 정의합니다. 단, v1 자체가 노출됐거나 공급자가 폐기한 경우에는 되돌림이 보안상 금지됩니다. 이때는 트래픽을 중지할 영향 범위를 선언하고 새 자격 증명으로 장애 대응을 전환합니다.
완료 조건과 다음 회전 준비
완료는 ‘배포가 끝남’이 아니라 모든 실행 주체가 v2를 사용하고, 정해진 관찰 창에서 인증 오류가 기준선을 넘지 않으며, v1 폐기와 감사 로그 확인이 기록된 상태입니다. 전환 기록에는 담당자, 시작·종료 시각, 버전 ID, 프로브 명령과 결과, 롤백 여부, 남은 후속 조치를 적습니다. 값은 기록하지 않습니다.
마지막으로 다음 회전의 개선점을 남깁니다. 자동 알림이 만료일만 알려 주는지, 실제 프로브까지 실행하는지 구분하고, 새 인스턴스가 어느 버전을 기본으로 읽는지 배포 템플릿에서 확인합니다. 이 기록과 버전별 메트릭을 함께 갖추면 다음 교체는 개인의 기억이 아니라 반복 가능한 운영 절차가 됩니다.