> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/development/code_serving/ha-autoscale.md). # 코드 서빙 실행 확장(HA) ## 개요 실행 확장(HA)은 코드 서빙 리비전 하나를 여러 개의 인스턴스로 늘려 요청을 나눠 처리하는 기능입니다. 유지할 개수를 직접 지정할 수도 있고, 부하에 따라 자동으로 늘고 줄도록 맡길 수도 있습니다. **코드 서빙 → (서빙 선택) → 리비전 → 기본 정보** 탭의 "실행 확장(HA)" 영역에서 **HA 수정**을 눌러 설정합니다. 설정은 리비전마다 따로 관리되며, 배포 중인 리비전은 저장하는 즉시 반영되고 배포 중이 아닌 리비전은 다음 배포 때 적용됩니다.
실행 확장(HA) 영역 — 읽기 모드

실행 확장(HA) 영역 — 읽기 모드

## 주요 개념 | 개념 | 설명 | | -------- | --------------------------------------------------------------------------------- | | 확장 방식 | 개수를 어떻게 정할지 고르는 값입니다. **고정**은 지정한 개수를 그대로 유지하고, **자동**은 부하에 따라 최소\~최대 범위에서 조절합니다. | | 확장 신호 | 자동 방식에서 무엇을 부하로 볼지 고르는 값입니다. 큐·CPU·메모리 중 하나를 선택합니다. | | 최소·최대 개수 | 자동 방식의 조절 범위입니다. 최소는 부하가 없어도 항상 유지되고, 최대는 늘어날 수 있는 상한입니다. | | 증설 지속 시간 | 부하가 이 시간만큼 계속됐을 때만 개수를 늘립니다. 0이면 순간 부하에도 바로 늘립니다. | | 축소 대기 시간 | 부하가 내려간 뒤 이 시간을 기다린 다음 줄이기 시작합니다. | ## 설정하기 **HA 수정**을 누르면 편집 모드로 바뀝니다. **사용**을 켜고 확장 방식을 고른 뒤, 자동 방식이면 확장 신호와 최소·최대 개수를, 고정 방식이면 유지할 개수를 입력합니다. 필요하면 증설 지속 시간과 축소 대기 시간을 조정한 다음 저장합니다. 저장 전에 확인 창이 한 번 표시됩니다.
HA 수정을 누른 편집 모드

HA 수정을 누른 편집 모드

저장하면 설정 아래에 현재 실행 중인 개수가 표시되고 15초마다 갱신됩니다. 자동 방식에서는 `현재 3개 실행 중 (최대 5)`처럼 상한을 함께 보여줍니다.
저장 후 현재 실행 개수 표시

저장 후 현재 실행 개수 표시

배포 중이 아닌 리비전에서는 "현재 배포 중이 아닙니다 — 저장한 설정은 다음 배포 때 적용됩니다"가 표시됩니다. 이 상태에서도 설정을 저장할 수 있으며, 저장한 값은 다음 배포 때 적용됩니다. ## 확장 방식 고르기 고정 방식은 입력한 개수를 항상 그대로 유지합니다. 자동 방식은 확장 신호를 15초마다 확인해 최소\~최대 사이에서 개수를 조절합니다. 트래픽이 대체로 일정하거나 자원 사용량을 예측 가능하게 두고 싶다면 고정 방식이 적합합니다. 개수가 변하지 않으므로 동작을 예상하기 쉽습니다. 반대로 시간대나 이벤트에 따라 트래픽 편차가 크다면 자동 방식이 낫습니다. 한가한 시간에는 자원을 돌려주고 몰릴 때만 늘릴 수 있기 때문입니다. 자동 확장을 지원하지 않는 사이트에서는 저장할 때 안내 문구와 함께 거부되므로, 그런 환경에서는 고정 방식을 사용합니다.
고정 방식 — 유지할 개수 입력

고정 방식 — 유지할 개수 입력

## 확장 신호 고르기 자동 방식에서는 세 가지 중 무엇을 부하로 볼지 고릅니다. 큐는 처리를 기다리며 줄 서 있는 요청 수를, CPU와 메모리는 각각 인스턴스의 사용률을 봅니다. 여기서 중요한 점은 큐가 세는 대상이 "아직 처리에 들어가지 못한 요청"뿐이라는 것입니다. 이미 처리 중인 요청은 세지 않습니다. 그래서 요청 하나가 오래 걸리는 앱, 예를 들어 외부 AI를 호출하거나 문서를 변환하는 앱이라면 CPU를 고르는 것이 좋습니다. 이런 앱은 요청이 처리에 들어간 상태로 오래 머물기 때문에 줄이 길어지기 전에 인스턴스가 이미 바빠집니다. 이때 큐를 고르면 신호가 거의 0에 머물러 부하가 늘어도 인스턴스가 잘 늘어나지 않습니다. 반대로 요청 하나는 빨리 끝나는데 양이 많은 앱이라면 큐가 적합합니다. 처리 속도가 유입 속도를 따라가지 못하면 실제로 줄이 쌓이므로 신호가 부하를 잘 반영합니다. 메모리가 먼저 한계에 닿는 앱이라면 메모리를 고릅니다. 큐 신호를 지원하지 않는 사이트에서는 저장할 때 거부되므로 CPU나 메모리를 사용합니다.
확장 신호 선택 — 큐 / CPU / 메모리

확장 신호 선택 — 큐 / CPU / 메모리

> 확장 신호를 큐로 고르면 요청이 대기열을 거치도록 인스턴스 구성이 바뀝니다. 저장할 때 인스턴스가 교체되면서 짧은 순단이 생기고, 아래 [큐 신호를 사용할 때의 제한](#큐-신호를-사용할-때의-제한)이 추가로 적용됩니다. ## 최소·최대 개수 정하기 최소 개수는 부하가 없어도 항상 유지되는 개수이므로 그만큼 자원을 계속 점유합니다. 최대 개수는 상한이며, 부하가 크면 한 번에 최대까지 늘어날 수 있습니다. 새로 늘어난 인스턴스는 소스를 받고 앱이 기동하는 준비 시간이 지나야 요청을 받기 시작합니다. 최소 개수는 평상시 트래픽을 감당할 수 있는 값으로 잡습니다. 1로 두면 자원을 가장 적게 쓰지만, 갑작스러운 부하의 초반에는 새 인스턴스가 준비되는 동안 1개로 버텨야 합니다. 스파이크에 민감한 서비스라면 2 이상을 권장합니다. 최대 개수는 이 리비전에 허용할 자원 상한으로 생각하면 됩니다. 한 번에 최대까지 늘어날 수 있으므로 너무 크게 두면 순간적으로 그만큼의 자원을 점유합니다. 사이트 상한 안에서 감당할 수 있는 값으로 잡습니다. 사이트 상한은 **기본값이 10**이며, 시스템 설정 `max_code_serving_workers`로 조정합니다. 값을 `unlimited`로 두면 상한 없이 입력할 수 있습니다. 설정하지 않았거나 값이 잘못됐으면 자원이 무제한으로 늘어나지 않도록 기본값 10이 적용됩니다. 최소는 1 이상, 최대는 사이트 상한 이하여야 하며 이 범위를 벗어나면 저장할 때 안내 문구로 거부됩니다.
최소·최대 개수 입력

최소·최대 개수 입력

## 증설 지속 시간과 축소 대기 시간 정하기 증설 지속 시간은 부하가 이 시간만큼 계속됐을 때만 개수를 늘리도록 하는 값입니다. 0으로 두면 순간 부하에도 바로 늘립니다. 기본값은 확장 신호에 따라 다르며 큐는 0초, CPU와 메모리는 120초입니다. 확장 신호를 바꾸면 기본값도 함께 따라가지만, 직접 입력한 값은 신호를 바꿔도 유지됩니다. 큐 신호에서는 기본값 0을 그대로 쓰는 것을 권장합니다. 대기열의 요청은 오래 기다려주지 않으므로, 늘리는 판단이 늦으면 그 요청들이 이미 실패한 뒤에 인스턴스가 뜨게 됩니다. 반면 CPU와 메모리 신호에서는 기본값 120초가 적절합니다. 사용률은 가비지 컬렉션이나 앱 기동, 배치 작업 때문에 순간적으로 튀는 일이 흔하고, 그때마다 늘리면 곧 다시 줄이는 낭비가 생기기 때문입니다. 짧고 잦은 스파이크가 많아 불필요한 증설이 부담스러우면 값을 올리고, 부하가 오를 때의 응답 지연이 더 문제라면 값을 내립니다. 축소 대기 시간은 부하가 내려간 뒤 얼마나 기다린 다음 줄일지를 정하는 값으로 기본값은 300초입니다. 줄일 때는 한꺼번에 줄이지 않고 30초에 하나씩 내립니다. 처리 중이던 요청이 동시에 위험해지지 않게 하기 위한 동작입니다. 트래픽이 들쭉날쭉하다면 축소 대기 시간을 길게 두는 편이 좋습니다. 짧으면 줄였다가 곧 다시 늘리는 왕복이 생기고, 그때마다 준비 시간을 다시 기다리게 됩니다. 자원을 빨리 회수해야 하는 환경이라면 짧게 둘 수 있지만, 처리 시간이 긴 요청을 받는 앱이라면 너무 짧게 두지 않는 것이 좋습니다. 줄어드는 인스턴스가 처리 중인 요청을 끝내려면 시간이 필요합니다.
증설 지속 시간과 축소 대기 시간 입력

증설 지속 시간과 축소 대기 시간 입력

## 실행 확장을 켜고 끌 때 실행 확장을 켜면 저장 시점부터 인스턴스 개수를 이 설정이 관리합니다. 리비전을 만들 때 지정한 복제본 수는 더 이상 적용되지 않습니다.
켤 때 확인 창

켤 때 확인 창

실행 확장을 끄면 개수가 1개로 줄어듭니다. 만들 때 지정한 복제본 수로 돌아가지 않으므로, 원래 개수를 유지하고 싶다면 끄는 대신 확장 방식을 고정으로 바꿔 그 수를 직접 입력하는 것이 좋습니다. 끄는 동작은 "1개로 돌린다"는 뜻에 가깝습니다.
끌 때 확인 창

끌 때 확인 창

## 큐 신호를 사용할 때의 제한 큐 신호를 선택하면 요청이 대기열을 거쳐 처리됩니다. 호출 주소와 방식은 그대로지만 대기열을 지나는 만큼 아래 제한이 생기므로 앱을 만들 때 함께 고려해야 합니다. | 제한 | 내용 | 앱에서 할 일 | | ----- | -------------------------------------------- | --------------------------------------- | | 처리 시간 | 한 번에 60초, 대기까지 합쳐 120초를 넘기면 실패합니다. | 오래 걸리는 작업은 즉시 응답하고 결과는 별도로 조회하도록 설계합니다. | | 요청 본문 | 1MB를 넘기면 거부됩니다. | 큰 파일은 본문에 담지 않습니다. | | 응답 본문 | 1MB를 넘기면 뒷부분이 잘립니다. | 응답 크기를 상한 안으로 유지합니다. | | 예약 주소 | `/__bridge/healthz`는 상태 점검용이라 앱까지 전달되지 않습니다. | 앱에서 이 주소를 사용하지 않습니다. | ### 실패한 요청은 다시 시도하지 않습니다 앱이 요청 처리에 실패하면 그대로 실패로 응답합니다. 같은 요청을 두 번 실행하면 데이터가 중복될 수 있어 자동 재시도를 하지 않습니다. v1.9.1까지는 내부적으로 최대 3번까지 다시 시도했기 때문에 앱이 잠깐 불안정해도 성공으로 보이는 경우가 있었습니다. v1.9.2부터는 그 실패가 그대로 드러나므로 호출하는 쪽에서 재시도를 처리해야 합니다. 큐 신호로 바꾼 뒤 실패가 보이기 시작했다면 새로 생긴 장애가 아니라 원래 있던 일시적 실패가 드러난 것일 수 있으므로, 앱 쪽 안정성도 함께 점검하는 것이 좋습니다. ### 인스턴스가 줄어들 때 처리 중이던 요청 인스턴스가 줄거나 재배포될 때 그 시점에 처리 중이던 요청은 끝까지 응답을 받습니다. 아주 오래 걸리는 요청은 상한을 넘겨 실패할 수 있지만, 그 경우에도 같은 요청이 다시 실행되지는 않습니다. ## 자주 만나는 안내 문구 | 문구 | 의미와 해결 방법 | | ----------------------------------------------------------- | --------------------------------------- | | 자동 확장을 사용할 수 없습니다(KEDA 미설치). 고정 모드를 사용하세요 | 이 사이트는 자동 확장을 지원하지 않습니다. 고정 방식을 사용합니다. | | 큐 기반 자동 확장을 사용할 수 없습니다(대기열 Redis 미구성). cpu/memory 신호를 사용하세요 | 이 사이트는 큐 신호를 지원하지 않습니다. CPU나 메모리를 고릅니다. | | 자동 확장 범위는 1 ≤ 최소 ≤ 최대 ≤ (상한) 이어야 합니다 | 최소는 1 이상, 최대는 사이트 상한(기본 10) 이하로 입력합니다. | | 부하 지속 시간은 0 이상 3600 초 이하여야 합니다 | 증설 지속 시간과 축소 대기 시간을 0\~3600초 사이로 입력합니다. | | 현재 배포 중이 아닙니다 — 저장한 설정은 다음 배포 때 적용됩니다 | 지금은 반영되지 않고 다음 배포 때 적용됩니다. | | 실행 확장 설정을 불러오지 못했습니다 | 잠시 후 다시 시도합니다. | | 실행 확장(HA) 설정 저장에 실패했습니다 | 저장이 반영되지 않았습니다. 값을 확인하고 다시 저장합니다. |
배포 중이 아닐 때의 안내

배포 중이 아닐 때의 안내

## 사용자 시나리오 ### 외부 AI를 호출하는 API — 낮에만 트래픽이 몰리는 경우 요청당 처리 시간이 길어 대기열이 잘 쌓이지 않으므로 큐 신호로는 인스턴스가 잘 늘어나지 않습니다. 확장 방식을 자동으로, 확장 신호를 CPU로 고르고 최소 1 / 최대 4로 설정합니다. 증설 지속 시간은 기본값 120초를 유지합니다. 부하가 2분 이상 이어지면 인스턴스가 늘어나고, 한가해진 뒤 5분이 지나면 30초에 하나씩 줄어듭니다. ### 짧은 요청이 대량으로 들어오는 경우 처리 속도가 유입 속도를 따라가지 못해 대기열이 실제로 쌓이는 경우입니다. 확장 방식을 자동으로, 확장 신호를 큐로 고르고 증설 지속 시간은 기본값 0을 유지합니다. 대기가 생기는 즉시 인스턴스가 늘어납니다. 다만 요청 본문과 응답이 1MB를 넘지 않고 처리가 120초 안에 끝나는지 미리 확인해야 합니다. ### 개수를 고정으로 유지하려는 경우 야간 배치처럼 부하가 일정한 경우입니다. 확장 방식을 고정으로 고르고 개수를 2로 입력하면 자동 조절 없이 2개가 유지됩니다. ### 부하가 늘어나는 초반의 지연을 줄이려는 경우 인스턴스가 늘어나는 동안 초반 요청이 느려지는 경우입니다. 최소 개수를 1에서 2로 올리면 평상시에도 2개가 떠 있어 준비 시간을 기다리지 않습니다. 대신 한가한 시간에도 2개만큼 자원을 점유합니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/development/code_serving/ha-autoscale.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.