스크린샷을 누르면 원본 크기로 열려요. 표·코드·구성도는 좌우로 밀어서 볼 수 있어요.

1. 개요와 구성도

1.1 BizCoder 온프렘이 하는 일

사내 Kubernetes 에 BizCoder 를 올리면, 직원이 사내 브라우저로 접속해 AI 코딩 에이전트에게 일을 시킬 수 있어요. 코딩 작업은 사내 onpod 가 띄우는 샌드박스에서 실행되고, 결과물은 사내 GitLab 에 커밋·푸시·MR 로 쌓여요. 배포하면 사내 onpod 가 https://<앱 이름>.<onpod 도메인> 주소를 만들어 줘요. LLM 은 Azure OpenAI(또는 OpenAI 호환 사내 게이트웨이)를 쓰고, 인터넷으로 나가는 호출은 없어요.

1. 직원이 사내 브라우저로 BizCoder 웹 화면에 접속해 저장소 주소와 하고 싶은 일을 적어요.
2. BizCoder 가 사내 onpod 에 샌드박스 Pod 를 만들어요. 코딩 에이전트는 이 Pod 안에서 일하고, 샌드박스는 소스 파일만 받아요.
3. LLM 호출은 BizCoder 의 LLM 프록시를 거쳐 Azure OpenAI 로 가요. LLM 키와 Git 토큰은 BizCoder 서버에만 있어요.
4. 결과는 사내 GitLab 에 브랜치로 커밋·푸시되고 Merge Request 가 자동으로 만들어져요. 클론·푸시·MR 은 BizCoder 가 대신해요.
5. 「배포까지 한 번에」를 켜면 사내 onpod 에 배포돼 https://<이름>.<onpod 도메인> 주소가 나와요. 기본 공개 범위는 「우리 회사 사람만」(로그인 필요)이에요.

1.2 구성도

실선은 BizCoder 가 거는 호출, 점선은 샌드박스 Pod 가 BizCoder 로 거는 호출이에요. GitLab 과는 양방향이에요(웹훅은 GitLab → BizCoder).

2. 준비물과 용량 산정

2.1 준비물

2.2 설치 전에 꼭 확인할 세 가지

2.3 용량 산정 — 동시에 몇 건까지 코딩할 수 있나요

코딩 작업 1건은 onpod 샌드박스 1개를 써요. 그래서 동시 코딩 작업 수는 onpod 가 가진 해당 크기 슬롯의 수예요. 샌드박스 크기는 values 의 onpod.sandbox.class(nano | micro | small | medium)로 정하고, 기본값 small 은 2 vCPU · 4 GiB 한도로 onpod 의 cpu_medium 슬롯 1개를 써요.

온프렘 onpod 는 호스트(클러스터)의 RAM 에서 슬롯을 잘라 내요.

예) RAM 16 GiB 서버 — 사용 가능 12.8 GiB 중 medium 몫은 3.2 GiB 이고 슬롯 하나가 4 GiB 라서 계산상 1개에 못 미치지만 최소 1개가 보장돼요. 그래서 medium 슬롯 1개, 곧 동시 코딩 1건이에요.

BizCoder 자체 요구량(차트 기본값)

3. 설치 (5단계)

설치는 번들 폴더 안에서 실행해요. 예시의 bizcoder 는 네임스페이스이자 릴리스 이름이에요. 아래 5단계를 순서대로 하면 끝나요.

3.1 번들 구성

bizcoder-onprem-<태그>-amd64/
├─ images/
│   ├─ bizcoder-app.tar                  앱 이미지
│   ├─ bizcoder-sandbox-rootfs.tar.gz    샌드박스 이미지의 rootfs
│   └─ postgres.tar                      번들 DB 이미지
├─ Dockerfile.sandbox                    샌드박스 이미지 정의 (FROM scratch + ADD rootfs)
├─ helm/bizcoder/                        Helm 차트
├─ scripts/                              provision.sh · preflight.sh · seed-sandbox-image.sh · lib.sh
├─ argocd/                               Application · ExternalSecret · SealedSecret 안내
├─ values.example.yaml                   OpenAI 호환 게이트웨이용 예시 values
├─ values.azure.example.yaml             Azure OpenAI 용 예시 values
└─ bundle.env · SHA256SUMS · MANUAL.ko.md

3.2 1단계 — 번들 확인 · 이미지 올리기

sha256sum -c bizcoder-onprem-<태그>-amd64.tar.gz.sha256        # macOS: shasum -a 256 -c …
tar xzf bizcoder-onprem-<태그>-amd64.tar.gz && cd bizcoder-onprem-<태그>-amd64
sha256sum -c SHA256SUMS                                          # 모든 파일이 OK 여야 해요
docker load -i images/bizcoder-app.tar                           # 앱 이미지
docker load -i images/postgres.tar                               # 번들 DB 를 쓸 때만
# 사내 레지스트리로 재태그해서 push (노드에 직접 로드하는 환경이면 건너뛰어도 돼요)
docker tag  $(sed -n 's/^APP_IMAGE=//p' bundle.env) registry.corp.example/bizcoder/wrks-code:$(sed -n 's/^APP_TAG=//p' bundle.env)
docker push registry.corp.example/bizcoder/wrks-code:$(sed -n 's/^APP_TAG=//p' bundle.env)

• 번들 버전과 태그는 번들 안의 bundle.env 에 있어요. 3단계 values 의 image.tag 에는 bundle.env 의 APP_TAG 값을 넣어요.
• 번들 DB(postgres.tar)도 같은 방식으로 사내 레지스트리에 올리고, 올린 주소를 values 의 postgres.image.repository 에 적어요. 사내 DB 를 쓰면 이 이미지는 필요 없어요.
• bizcoder-sandbox-rootfs.tar.gz 는 docker 로 올리지 않아요. 2단계 provision.sh 가 사내 onpod 서버 빌드로 샌드박스 이미지를 만들 때 써요.

3.3 2단계 — 서비스 키 · Secret · 샌드박스 이미지 만들기 (provision.sh)

scripts/provision.sh \
  --onpod-url https://api.onpod.corp.example --cacert ca.crt \
  --license bizcoder.lic --azure-key-from-stdin \
  --public-base-url https://bizcoder.corp.example

이 한 번으로 아래 8단계가 끝나요. 여러 번 실행해도 이미 만든 비밀은 건드리지 않아요. Azure 키는 표준입력(없으면 프롬프트)에서 읽어요.

만들어지는 Secret

서비스 키 스코프

자주 쓰는 옵션

# onpod 차트 values — Helm/Argo 로 운영하면 이 방법을 권장해요 (재배포해도 유지돼요)
controlplane:
  extraEnv:
    ONPOD_SANDBOX_API_ENABLED: "1"

출력: values.generated.yaml

3단계에서 my-values.yaml 과 함께 쓰는 값 조각이에요. 비밀값은 없고 Secret 이름만 들어 있어요.

publicBaseUrl: https://bizcoder.corp.example
onpod:
  apiUrl: https://api.onpod.corp.example
  tokenSecret: {name: bizcoder-onpod, key: token}
  caSecret: {name: bizcoder-ca, key: ca.crt}
  sandbox: {image: "onpod://bizcoder-sandbox:<버전>", class: small}   # 샌드박스 이미지 별칭
secretKey: {existingSecret: bizcoder-app, key: WRKS_SECRET_KEY}
postgres:
  auth: {existingSecret: bizcoder-db, passwordKey: password}
license: {existingSecret: bizcoder-license, key: license.json}
llm:
  azure: {existingSecret: bizcoder-azure, keyKey: api-key}
auth:
  devLogin:
    secretRef: {name: bizcoder-dev-login, key: code}

3.4 3단계 — values 작성

번들의 values.azure.example.yaml(OpenAI 호환 게이트웨이는 values.example.yaml)을 복사해 my-values.yaml 로 고쳐요. values.generated.yaml 이 채워 준 값은 다시 적지 않아도 돼요.

Azure OpenAI 예시 (my-values.yaml 의 핵심)

image:
  repository: registry.corp.example/bizcoder/wrks-code   # 1단계에서 올린 사내 레지스트리 주소
  tag: <bundle.env 의 APP_TAG>

publicBaseUrl: https://bizcoder.corp.example             # 직원이 접속하는 HTTPS 주소(ALB)

llm:
  kind: azure
  azure:
    endpoint: https://<리소스 이름>.openai.azure.com    # Azure OpenAI 리소스 주소
    apiVersion: v1                  # GA v1 API. 날짜 버전이면 클래식(배포 이름) 주소
    auth: api-key                   # api-key | bearer | both
    existingSecret: bizcoder-azure  # provision.sh 가 만든 Secret
    keyKey: api-key
  models:
    main: gpt-4.1                   # 사용자 화면의 모델 id (= Azure 배포 이름)
    fallback: gpt-4.1-mini
    curated: [gpt-4.1, gpt-4.1-mini]
  modelMap: {}                      # 배포 이름이 다르면 매핑. 예: {gpt-4.1: my-gpt41-deployment}
  prices:                           # KRW / 1M tokens — 예산·사용액 집계 기준
    gpt-4.1:      {input_krw_per_1m: <입력 단가>, output_krw_per_1m: <출력 단가>}
    gpt-4.1-mini: {input_krw_per_1m: <입력 단가>, output_krw_per_1m: <출력 단가>}
  sidecallModel: gpt-4.1-mini       # 제목·요약 같은 보조 호출용

auth:
  devLogin:
    enabled: true
    allowlist: [admin@corp.example] # 첫 관리자 한 명만
    secretRef: {name: bizcoder-dev-login, key: code}
  superadminEmails: [admin@corp.example]

ingress:
  enabled: true
  className: alb
  annotations:                      # AWS Load Balancer Controller 예 — 환경에 맞게 조정
    alb.ingress.kubernetes.io/scheme: internal
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/certificate-arn: <ACM 인증서 ARN>
    alb.ingress.kubernetes.io/healthcheck-path: /api/auth/mode
    alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=300   # 스트리밍 응답이 끊기지 않게

• 모델 단가표(llm.prices)는 예산·사용액 집계의 기준이에요. 표에 없는 모델의 작업은 시작할 때 「단가를 찾지 못했어요」로 막혀요. 모든 모델을 적지 않으려면 llm.priceOptional: true(단가표에 없는 모델을 0원으로 집계해 허용, 토큰은 기록)를 쓸 수 있어요.
• auth.devLogin.allowlist 에는 첫 관리자 한 명만 넣어요. 이메일마다 별도 조직이 만들어지기 때문이에요. 다른 관리자는 4장 이후 초대로 추가해요.
• ALB 가 TLS 를 끝내면(권장) ingress.tls.secretName 은 비워 둬요. Ingress 컨트롤러가 TLS 를 끝내는 환경이면 인증서 Secret 이름을 넣어요. ALB 대상 유형이 instance 면 service.type 을 NodePort 로 맞춰요.

환경에 따라 더 채우는 값

3.5 4단계 — helm 으로 설치

helm upgrade --install bizcoder ./helm/bizcoder -n bizcoder --create-namespace \
  -f values.generated.yaml -f my-values.yaml
kubectl -n bizcoder rollout status deploy/bizcoder

앱은 시작할 때 DB 마이그레이션을 실행해서 첫 기동에 시간이 걸릴 수 있어요(시작 프로브는 최대 약 6분을 기다려요). 설치가 끝나면 NOTES 로 접속 주소와 확인 명령, 첫 관리자 로그인 방법이 나와요.

kubectl -n bizcoder logs deploy/bizcoder --tail=50
curl -sS https://bizcoder.corp.example/api/auth/mode

3.6 5단계 — 점검(preflight.sh)과 첫 로그인

scripts/preflight.sh --from-release bizcoder/bizcoder --cacert ca.crt \
  --gitlab-url https://gitlab.corp.example --license bizcoder.lic --smoke-sandbox

• --from-release bizcoder/bizcoder 는 helm 릴리스 값(helm get values)과 Secret 에서 주소·모델·키를 읽어 채워 줘요. 직접 준 옵션이 우선이에요.
• --smoke-sandbox 는 샌드박스를 실제로 하나 띄웠다가 지워요(가장 작은 nano). 샌드박스 이미지·도구·코딩 에이전트 실행·BizCoder 로의 도달을 한 번에 확인해요.
• FAIL 이 하나라도 있으면 종료 코드가 1 이에요. 모두 PASS 면 다음 장으로 가요.

4. 첫 로그인과 초기 설정

4.1 첫 관리자 로그인

1. 접근 코드를 확인해요. 코드는 화면에 직접 출력되지 않아요.

   kubectl -n bizcoder get secret bizcoder-dev-login -o jsonpath='{.data.code}' | base64 --decode; echo

2. 브라우저로 https://<BizCoder 주소>/?dev=1 에 접속해요(주소 뒤에 ?dev=1). 일반 주소(/)에는 「사내 SSO로 로그인」 단추만 보여요.
3. 「이메일로 시작」 칸에 auth.devLogin.allowlist 에 적은 이메일을 넣고 단추를 눌러요. 접근 코드를 물으면 1번의 값을 입력해요.
4. 첫 관리자는 조직 소유자가 돼요.

4.2 회사 이름 입력 (처음 한 번)

첫 관리자가 처음 들어오면 「회사 이름을 알려주세요」 창이 떠요. 직원을 초대할 때, 만든 사이트를 공유할 때, 사용 내역서에 이 이름이 보여요.

처음에는 임시 이름으로 되어 있고, 나중에 조직 관리에서 바꿀 수 있어요. 이름을 적고 「저장하고 시작하기」를 누르면 콘솔로 들어가요.

4.3 라이선스 확인

콘솔에서 조직 관리 → 라이선스 로 가서 사용 중 좌석 / 전체, 만료일, 상태를 확인해요. 좌석은 활성 멤버 + 아직 합류하지 않은 초대를 합한 수예요. 좌석이 다 차면 새 멤버를 초대하거나 회사 SSO 로 새로 들어올 수 없어요(6.1절).

캡처의 좌석 수·만료일은 예시예요.

4.4 회사 SSO(OIDC) 설정

SSO 를 설정하면 직원은 별도 가입 없이 회사 계정으로 들어와요. 퇴사자는 IdP 에서 계정을 끊는 즉시 차단돼요. OIDC 가 기준이고, SAML 전용 IdP 는 도입 문의가 필요해요(설정 화면 안내).

1. 사내 IdP(Okta·Entra 등)에 OIDC 앱(클라이언트)을 만들고, 리디렉션 URI 로 https://<BizCoder 주소>/api/auth/oidc/callback 을 등록해요. SSO 설정 화면의 「리디렉션 URI (IdP 앱에 등록)」에 표시되는 값이에요.
2. BizCoder 에서 조직 관리 → 정책 → 「회사 SSO」 로 가서 발급자(issuer, https), 클라이언트 ID / 시크릿, 회사 이메일 도메인을 입력해요.
3. 저장하면 「연결됨 · 도메인」으로 바뀌고 직원 로그인 주소(…/api/auth/oidc/start?domain=<이메일 도메인>)가 표시돼요. 「변경」·「해제」 단추로 바꾸거나 끌 수 있어요.

직원이 로그인하는 모습 — 직원은 일반 주소의 「사내 SSO로 로그인」 → 회사 이메일 입력 → 사내 IdP 로그인 순서로 들어오고, 자동으로 조직 멤버로 합류해요.

4.5 초기 설정 체크리스트

• 라이선스의 상태·만료일·좌석을 확인했어요 (4.3절)
• 회사 이름을 입력했어요 (4.2절)
• 회사 SSO 를 설정하고 직원 계정으로 로그인해 봤어요 (4.4절)
• 배포 정책을 확인했어요 — 기본은 승인제예요 (6.3절)
• 직원에게 GitLab 개인 액세스 토큰 발급·연결 방법을 안내했어요 (5.2절)
• 다른 관리자는 멤버 초대로 추가했어요 (6.1절)

5. 직원 사용법

직원이 BizCoder 로 코딩을 맡기고 결과를 받는 순서예요. 필요한 것은 사내 SSO 계정과 사내 GitLab 개인 액세스 토큰이에요.

5.1 콘솔 둘러보기

로그인하면 콘솔이 열려요. 왼쪽 위의 「새 작업」으로 작업을 시작하고, 아래로 내 작업 목록이 쌓여요. 「내 배포 사이트」에서 내가 올린 사이트를 볼 수 있고, 왼쪽 아래에는 연결된 저장소 계정이 표시돼요.

5.2 GitLab 연결 (처음 한 번)

작업 결과를 사내 GitLab 에 푸시하고 MR 을 만들려면 직원마다 개인 액세스 토큰을 한 번 등록해요.

1. 사내 GitLab 에서 개인 액세스 토큰(Personal Access Token)을 만들어요. 권장 범위는 api · read_repository · write_repository 예요.
2. BizCoder 에서 내 계정 → 연결 계정 으로 가서 GitLab 줄의 「연결」을 눌러요.
3. GitLab 호스트(예: gitlab.corp.example)와 Personal Access Token 을 입력하고 「연결」을 눌러요.
4. GitLab 줄에 초록 점이 켜지고 서버 주소가 보이면 끝이에요. 끊으려면 「해제」를 눌러요.

5.3 새 작업 시작

1. 왼쪽 위 「새 작업」(단축키 N)을 눌러요.
2. 입력창에 하고 싶은 일을 평소 말투로 적어요. 예: 「팀 회식 장소를 투표로 정하는 간단한 한 페이지 웹앱을 index.html 하나로 만들어 줘. 장소를 추가하고 항목마다 투표 수를 올릴 수 있게, 결과는 막대로. 외부 CDN 없이.」
3. 아래 줄에 저장소 URL을 적어요. 예: https://gitlab.corp.example/dev/hello.git. 저장소 없이도 작업할 수 있고, 이때는 결과를 내려받아요.
4. 결과를 바로 사내 서버에 올리려면 「배포까지 한 번에」 스위치를 켜요. 「완성되면 사내 서버에 자동 배포돼요. 결과가 웹앱일 때만요」라고 안내돼요.
5. 「코딩 시작」을 눌러요. 모델 선택 칸에는 관리자가 values 의 llm.models 로 정한 모델이 나와요.

5.4 진행 보기

작업이 시작되면 가운데에 샌드박스 준비됨 → 툴체인 설치됨 → 리포 클론됨 → 에이전트 시작 → 에이전트가 작업 중 순서로 단계가 쌓이고, 도구 실행과 테스트가 실시간으로 보여요. 이 창을 닫거나 다른 일을 해도 작업은 서버에서 계속되고, 나중에 다시 들어오면 이어서 볼 수 있어요. 중간에 말을 걸려면 아래 입력창에 후속 메시지를 보내고(Enter 전송 · Shift+Enter 줄바꿈), 멈추려면 위쪽 「작업 중단」을 눌러요.

오른쪽 탭은 파일(만든·고친 파일), 바뀐 곳(줄 단위 변경), 작업 기록, GitLab(MR) 이에요.

5.5 결과 확인 — MR 과 바뀐 곳

작업이 끝나면 위쪽에 「완료」와 함께 「PR」·「사이트 열기」·「다시 배포」·「결과 다운로드」 단추가 생겨요. 가운데에는 MR 링크와 라이브 사이트 주소가 나와요. 카드에는 「Merge Request 생성됨」과 주소(…/-/merge_requests/<번호>), 「GitLab에서 열기」 단추가 나와요.

「바뀐 곳」 탭에서는 무엇이 달라졌는지 파일별·줄 단위로 볼 수 있어요. 새로 추가된 줄은 초록, 지워진 줄은 빨강이에요. 파일 이름 옆의 +264 −0 같은 숫자는 추가·삭제된 줄 수예요.

사내 GitLab 에서도 같은 MR 을 볼 수 있어요. 작업마다 MR 이 하나씩 생기고, 제목에는 요청한 내용이 들어가요. 검토와 머지는 평소 쓰는 GitLab 방식으로 하면 돼요.

5.6 배포된 사이트 열기

「배포까지 한 번에」를 켰다면 결과 화면의 「사이트 열기」로 https://<이름>.<onpod 도메인> 주소를 열어요. 기본 공개 범위는 「우리 회사 사람만」이라 사내 로그인이 필요해요.

이미 올린 사이트는 콘솔 왼쪽 위 「내 배포 사이트」에서 다시 열고 관리해요. 사이트마다 주소·상태(「실행 중」)·작업 이름·공개 범위가 보이고, 줄 끝에 「수정하기」 등의 단추가 있어요.

조직 배포 정책이 승인제(기본)이면 사이트는 올라가지만 관리자가 승인하기 전에는 다른 직원에게 열리지 않아요. 결과 화면에 「관리자 승인 대기 — 아직 아무도 볼 수 없어요」가 표시되고, 승인 요청은 관리자에게 자동으로 가요. 승인되면 다시 올릴 필요 없이 곧바로 열려요(6.3절).

5.7 Git 자동 배포 (push 하면 사이트가 갱신)

저장소의 한 브랜치에 push 할 때마다 사이트를 다시 올리고 싶을 때 써요.

1. 「내 배포 사이트」에서 사이트의 Git 아이콘을 눌러 「Git 자동 배포」 창을 열어요.
2. 「저장소 연결」 탭에서 연결된 계정(GitLab)을 고르고, 저장소 목록에서 저장소·브랜치를 골라 「연결하기」를 눌러요.
3. 저장소에 웹훅이 자동으로 등록돼요. 연결한 다음 push 부터 자동으로 올라가요.

6. 관리자 운영

소유자·관리자 역할은 콘솔에서 조직 관리 화면을 쓸 수 있어요. 왼쪽 메뉴는 아래처럼 구성돼 있고, 이 장은 굵게 표시한 항목을 다뤄요.

6.1 멤버와 좌석

조직 관리 → 멤버 에서 멤버별 작업 수·누적 비용·최근 로그인을 보고 역할을 바꿔요. 역할은 세 가지예요.

• 회사 SSO 를 설정했다면 직원은 SSO 로 처음 로그인할 때 자동으로 멤버가 돼요. 별도 초대가 필요 없어요.
• 다른 관리자는 「메일로 초대」 또는 「초대 링크 만들기」로 초대한 뒤 역할을 관리자로 바꿔요. 초대 링크는 하나를 슬랙·메일에 올려 두면 받은 사람이 눌러서 스스로 들어와요. 유효기간·인원·메일 도메인은 링크마다 정하고, 언제든 사용을 중지할 수 있어요.
• 좌석 = 활성 멤버 + 아직 합류하지 않은 초대 수예요. 가득 차면 새 직원의 SSO 로그인이 막혀요.

좌석이 가득 찬 상태에서 새 직원이 SSO 로 로그인하면 로그인 화면에 「라이선스 좌석이 모두 사용 중이거나 라이선스가 유효하지 않아 새로 들어올 수 없어요. 관리자에게 문의해 주세요.」가 뜨고, 주소에 ?sso_error=license_seats 가 붙어요.

좌석을 비우거나 라이선스를 늘려야 해요.

6.2 라이선스 만료와 갱신

• 만료되면 유예 14일이 지난 뒤부터 새 작업만 막혀요(「라이선스 유효기간이 지나서 새 작업을 시작할 수 없어요…」). 기존 작업과 기록은 계속 볼 수 있어요.
• 현재 상태는 조직 관리 → 라이선스(4.3절), 파일 자체는 scripts/preflight.sh --license <파일> 로 서명·만료·좌석을 오프라인으로 확인해요.

1. 새 .lic 파일을 받아 위 명령으로 먼저 점검해요.
2. Secret bizcoder-license(키 license.json)를 새 파일로 교체해요.

   kubectl -n bizcoder create secret generic bizcoder-license \
     --from-file=license.json=<새 라이선스 파일> --dry-run=client -o yaml | kubectl apply -f -

3. 반영해요. values 에 license.hotReload: true 를 줬다면 재시작 없이 약 1분 안에 반영돼요. 아니면 파드를 다시 띄워요.

   kubectl -n bizcoder rollout restart deploy/bizcoder

4. 조직 관리 → 라이선스에서 만료일과 좌석이 바뀌었는지 확인해요.

6.3 배포 정책과 승인

직원이 올린 사이트는 사내 주소로 열려요. 누가 올릴 수 있고 누가 볼 수 있는지는 조직 관리 → 정책 → 배포 통제 의 「배포 허용 범위」에서 정해요.

부서 단위 공개 범위는 온프렘에서 지원하지 않고 「우리 회사」로 처리돼요. 정책과 별개로 관리자는 배포 사이트 탭에서 사이트별로 「범위 변경」을 할 수 있어요.

승인 처리 순서

1. 조직 관리 → 배포 사이트 로 가요. 승인 대기가 있으면 「승인 대기 중」 칸이 주황색으로 바뀌고 왼쪽 메뉴에 건수 배지가 떠요. 이 화면에서 우리 회사 직원들이 올린 사이트와 공개 범위, Git 자동 배포(연결된 사이트·일시정지·마지막 배포 실패)도 한눈에 볼 수 있어요.

1. 대기 중인 사이트 줄에 「관리자 승인 대기 — 아직 아무도 볼 수 없어요」가 붙고 「공개 승인」·「거절」 단추가 있어요. 주소를 열어 내용을 확인한 뒤 「공개 승인」을 눌러요.

1. 공개 범위를 골라 「이 범위로 승인」을 눌러요. 선택지는 「요청대로 — 우리 회사 사람만」과 「주소를 아는 누구나」예요. 직원이 요청한 범위보다 넓히거나 좁혀도 돼요. 승인하면 그 범위로 바로 열려요.

1. 승인이 끝나면 사이트에 「우리 회사 사람만」 표시가 붙고 「승인 대기 중」이 0 으로 돌아와요. 직원은 다시 올릴 필요 없이 곧바로 사이트를 열 수 있어요.

Git 자동 배포와 승인제 — 직원이 연결한 브랜치에 push 하면 사이트가 바로 바뀌지 않고 검토용 주소에 먼저 올라가요. 관리자가 승인(커밋 확인)하면 실제 사이트에 반영되고, 그동안 기존 사이트는 그대로예요(5.7절).

6.4 감사 로그

조직 관리 → 감사 로그 에는 작업·정책 변경·보안 플래그가 시간순으로 남아요. 위쪽 탭은 활동 · LLM 호출 로그 · 불변 감사 원장 · 전문 기록 이고, 활동 탭에서는 전체 · 작업 · 크레딧 · 변경 · 플래그로 걸러 볼 수 있어요. 작업 시작·종료, 사이트 배포, MR 생성(외부 전송), 정책 변경이 한 줄씩 기록돼요. 정책 화면 아래의 「정책 변경 이력」에서도 최근 변경을 볼 수 있어요.

• 웹 작업은 진행 기록을 다시 볼 수 있어요. 요청·응답 본문은 「전문 기록」을 켠 뒤부터 쌓이고, 저장된 기록은 암호화돼요. 열람·내려받기도 감사 로그에 남아요(화면 안내).
• 금칙어를 정하면(정책 → 접근·보안) 작업 프롬프트에 포함될 때 감사 로그에 플래그가 남아요.

7. 업그레이드 · 삭제 · Argo CD

7.1 업그레이드

새 번들을 받으면 이미지를 올리고 image.tag 만 바꿔 helm upgrade 해요. 앱은 시작할 때 DB 마이그레이션을 실행하므로 기본값을 replicas: 1, strategy: Recreate 로 두었어요(새·옛 버전이 같은 DB 를 동시에 만지지 않게). 그래서 교체되는 동안 잠시 접속이 안 될 수 있으니 직원이 적은 시간대에 하세요.

1. 새 번들의 체크섬을 확인하고 이미지를 올려요(3.2절).
2. 샌드박스 이미지가 바뀐 번들이면 scripts/provision.sh 를 같은 옵션으로 다시 실행해요. 새 샌드박스 이미지가 만들어지고, onpod.sandbox.image 별칭을 새 값으로 갱신해요(기존 Secret 은 유지돼요).
3. my-values.yaml 의 image.tag 를 새 번들 bundle.env 의 APP_TAG 로 바꾸고 3.5절의 helm upgrade --install 을 다시 실행해요.
4. kubectl -n bizcoder rollout status deploy/bizcoder 로 끝났는지 보고, preflight.sh(3.6절)를 다시 돌려요.

기존 Secret 의 내용만 바뀌었을 때는 파드가 자동으로 다시 뜨지 않아요. kubectl -n bizcoder rollout restart deploy/bizcoder 를 하거나 values 의 secretsRevision 을 아무 문자열로 바꿔 반영해요.

7.2 삭제

helm uninstall bizcoder -n bizcoder

실수 방지를 위해 번들 DB 의 데이터(PVC data-bizcoder-postgres-0)와 provision.sh 가 만든 Secret 은 남아요. 완전히 지우려면 직접 삭제하세요.

kubectl -n bizcoder delete pvc data-bizcoder-postgres-0
kubectl -n bizcoder delete secret bizcoder-onpod bizcoder-app bizcoder-db bizcoder-azure bizcoder-license bizcoder-ca bizcoder-dev-login

서비스 키(이름 bizcoder-service)는 onpod 콘솔의 API 키 화면에서 회수해요.

7.3 Argo CD 로 배포하기

차트는 Argo CD 로도 배포할 수 있게 설계했어요. 비밀값을 무작위로 만들지 않고, 설치 순서 훅이 없고, lookup 같은 함수를 쓰지 않아서 같은 입력은 항상 같은 결과를 내요(렌더 결과가 같은지는 시험했어요. 다만 실제 Argo CD 로 동기화해 본 시험은 아직 하지 않았으니, 처음 적용할 때는 Argo CD 의 Diff 화면으로 변경 내용을 먼저 확인해 주세요). 번들의 argocd/ 에 application.yaml.example(Application + AppProject), externalsecret.yaml.example, sealedsecret.md 가 있어요.

준비

• 사내 GitLab 에 번들의 helm/bizcoder 디렉터리와 환경별 values 를 올려 둬요. 예: https://gitlab.corp.example/platform/bizcoder-deploy.git 의 helm/bizcoder/(차트)와 envs/prod/values.yaml(비밀값은 넣지 않아요).
• 비밀은 Git 밖에 둬요. provision.sh 로 한 번 만들거나(Argo 가 관리하지 않는 Secret 이라 prune 대상이 아니에요), ExternalSecret·SealedSecret 으로 선언해요.
• Argo CD 가 사내 레지스트리·GitLab 의 사설 인증서를 신뢰해야 해요(저장소 등록 때 CA 지정).
• Application 이름은 릴리스 이름(bizcoder)과 같게 둬요. 차트가 app.kubernetes.io/instance=<릴리스 이름> 라벨을 쓰기 때문이에요. 다르게 하려면 argocd-cm 에 application.resourceTrackingMethod: annotation 을 설정해요.

Application 예시 (argocd/application.yaml.example 발췌)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: bizcoder
  namespace: argocd
spec:
  project: bizcoder
  source:
    repoURL: https://gitlab.corp.example/platform/bizcoder-deploy.git
    targetRevision: main
    path: helm/bizcoder
    helm:
      releaseName: bizcoder
      valueFiles:
        - ../../envs/prod/values.yaml      # source.path 기준 상대 경로 (같은 저장소 안)
  destination:
    server: https://kubernetes.default.svc
    namespace: bizcoder
  syncPolicy:
    automated:
      prune: false          # 비밀·DB 가 걸린 앱이라 prune 은 끈 채로 시작해요
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - PruneLast=true
      - PrunePropagationPolicy=foreground
    # retry 등 나머지는 번들의 application.yaml.example 참고

알아둘 점

• AppProject 는 같은 파일에 함께 있어요. 허용 리소스는 ConfigMap · Secret · Service · ServiceAccount · Deployment · StatefulSet · Ingress · NetworkPolicy · PodDisruptionBudget 이고, 이 차트는 클러스터 범위 리소스를 만들지 않아요. 샌드박스 NetworkPolicy(8.5절)를 쓰면 onpod 샌드박스 네임스페이스에도 리소스가 생기니 AppProject 의 destinations 에 그 네임스페이스를 넣어 주세요.
• 업그레이드는 Git 의 values 에서 image.tag 를 바꿔 커밋하는 것으로 끝나요. 샌드박스 이미지가 바뀐 번들이면 먼저 provision.sh 를 다시 실행하세요(7.1절).
• 기존 Secret 의 내용만 바뀐 경우 파드는 자동으로 다시 뜨지 않아요 → secretsRevision 값을 바꿔 동기화하면 선언적으로 재시작할 수 있어요.
• SealedSecret: provision.sh --emit-yaml ./secrets-plain 으로 평문 Secret 매니페스트를 파일로만(권한 600) 만들고, kubeseal 로 봉인해 *.sealed.yaml 만 Git 에 올려요. 평문 폴더는 지워요. 봉인 범위 기본값(strict)은 이름 + 네임스페이스에 묶이니 bizcoder-… 이름과 bizcoder 네임스페이스를 바꾸지 마세요. 사내에 Vault 가 있으면 ExternalSecret 이 회전·감사 면에서 나아요.

8. 보안 구성

8.1 컨테이너와 클러스터

• 컨테이너는 비루트(uid 10001)로 실행돼요. 루트 파일시스템은 읽기 전용(/tmp, /home/app 만 쓰기)이고, 모든 capability 를 제거했고, 서비스 어카운트 토큰은 마운트하지 않아요.

8.2 비밀과 신뢰 경계

샌드박스에는 비밀키가 하나도 없고, 클러스터 안에서 BizCoder :8077 만 불러요.

8.3 사내 CA

onpod.caSecret 로 준 CA 는 컨테이너 기본 CA 목록과 합쳐져서(시작 시 initContainer) onpod·GitLab·Azure 호출 모두에 쓰여요. caBundle.mergeSystemRoots: false 로 끄면 사내 CA 만 신뢰해요. 이때는 공인 인증서를 쓰는 엔드포인트(예: Azure OpenAI)에 연결이 안 돼요. GitLab 웹훅(자동 재배포)은 GitLab 이 BizCoder 의 인증서를 신뢰해야 동작해요(ALB 인증서의 발급 CA 를 GitLab 에 등록).

8.4 설치본의 제한과 알아둘 점

• GitHub·구글 로그인, 결제(토스), 이미지·영상 생성처럼 외부 SaaS 에 의존하는 기능은 설치본에서 꺼져 있어요. 로그인은 라이선스와 사내 SSO 로 대신하고, 과금은 계약 방식에 따라요.
• 동적 앱(Node·Python) 배포의 빌드가 npm/PyPI 를 쓰면 사내 미러를 build.npmRegistry · build.pipIndexUrl 로 지정해요. 주소에는 사용자 이름·비밀번호를 넣지 마세요(ConfigMap 에 평문으로 남아요). 인증이 필요한 미러는 extraEnvFrom 의 Secret 으로 WRKS_BUILD_NPM_REGISTRY · WRKS_BUILD_PIP_INDEX_URL 을 주세요.
• 부서 단위 공개 범위는 지원하지 않고 「우리 회사」로 처리돼요.
• 번들 PostgreSQL 은 소규모·PoC 용이에요. 운영에는 사내 DB(postgres.enabled=false + database.urlSecret)를 권장해요.

8.5 샌드박스 송신 제한 (선택, 기본 꺼짐)

sandbox.networkPolicy.enabled 는 샌드박스 Pod 의 송신을 「BizCoder 8077 + 클러스터 DNS」로만 좁혀요. 다만 onpod 는 앱·빌더·샌드박스 Pod 에 같은 라벨(app.kubernetes.io/managed-by=onpod 등)만 붙여서 이 정책으로 샌드박스만 골라낼 수 없어요. 그래서 샌드박스 전용 네임스페이스(별도 onpod 에이전트)에서만 켜도록 confirmSandboxOnlyNamespace 확인을 요구해요.

sandbox:
  namespace: <샌드박스 전용 네임스페이스>
  networkPolicy:
    enabled: true
    confirmSandboxOnlyNamespace: true     # 이 네임스페이스에는 샌드박스 Pod 만 뜬다는 걸 확인했어요
    dnsCidrs: []                          # NodeLocal DNSCache 면 [169.254.20.10/32]
    extraEgress: []                       # NetworkPolicy egress 규칙 원문 (예: 사내 npm 미러)

9. 문제 해결

먼저 scripts/preflight.sh --from-release bizcoder/bizcoder --smoke-sandbox 의 PASS/FAIL 표를 보세요. 대부분의 설치·연동 문제는 FAIL 항목으로 바로 드러나요.

9.1 설치 · 기동

9.2 로그인 · 라이선스

9.3 작업 · GitLab · LLM

9.4 배포

부록

A. values 요약표 (주요 항목)

전체 목록과 설명은 helm/bizcoder/values.yaml 의 주석이고, 형식 검사는 values.schema.json 이에요(알 수 없는 키·잘못된 값은 거절돼요).

B. 자주 쓰는 명령

kubectl -n bizcoder rollout status deploy/bizcoder           # 기동·업그레이드 확인
kubectl -n bizcoder logs deploy/bizcoder --tail=50           # 로그
curl -sS https://bizcoder.corp.example/api/auth/mode         # 응답 확인 (JSON)
kubectl -n bizcoder get secret bizcoder-dev-login \
  -o jsonpath='{.data.code}' | base64 --decode; echo        # 첫 관리자 접근 코드
scripts/preflight.sh --from-release bizcoder/bizcoder --smoke-sandbox     # 점검 표
scripts/provision.sh --dry-run --onpod-url https://api.onpod.corp.example # 변경 없이 계획만 확인
helm get values bizcoder -n bizcoder                         # 적용된 values

C. 지원 문의

설치·운영 중 막히면 support@onpod.ai 로 문의해 주세요. 아래를 함께 보내 주시면 빨리 확인할 수 있어요.

• scripts/preflight.sh 의 PASS/FAIL 표 전체
• 증상이 난 시각과 화면(스크린샷), 어떤 단계(설치·로그인·작업·배포)에서 났는지
• kubectl -n bizcoder logs deploy/bizcoder --tail=200 의 출력과 번들 버전을 확인할 수 있는 bundle.env

보내면 안 되는 것 — API 키·GitLab 토큰·로그인 접근 코드·라이선스 파일·Secret 의 값은 메일에 넣지 마세요.