Red Hat OpenShift 설치

사전 요구사항

• OpenShift 클러스터, 4.13+
• 대상 클러스터에 설정된 oc CLI
• helm 3

방법 1: Red Hat Ecosystem Catalog (인증됨)

Red Hat 인증 Helm 차트와 Red Hat UBI 기반 이미지를 사용합니다.

• 제품 페이지: https://catalog.redhat.com/en/software/container-stacks/detail/6889da8b7d210ca6f32ec53a (opens in a new tab)
• Helm 차트 저장소: https://charts.openshift.io/
• 이미지 레지스트리: registry.connect.redhat.com/stclab-inc/*

Red Hat Ecosystem Catalog 페이지는 제품의 인증 상태를 확인하는 용도이며, 실제 helm install은 OpenShift Helm Charts 저장소를 사용합니다. registry.connect.redhat.com 레지스트리는 차트가 가져오는 인증된 컨테이너 이미지의 출처입니다.

Red Hat 이미지 pull secret 발급받기

이 pull secret은 Helm 차트 저장소가 아니라 registry.connect.redhat.com(이미지 pull)에 대한 인증에 사용됩니다.

1. https://access.redhat.com/terms-based-registry/accounts (opens in a new tab) 에 접속합니다.
2. Red Hat 계정으로 로그인하고 Service Account를 생성합니다.
3. Service Account의 상세 페이지를 열고 OpenShift Secret 탭을 선택합니다.
4. Download secret을 클릭하거나 내용을 직접 확인해 Secret YAML을 확보합니다.
5. Secret YAML에서 data[".dockerconfigjson"] 값을 복사해 아래 values-redhat.yaml의 redhat.dockerconfigjson에 붙여넣습니다.

values-redhat.yaml

redhat:
  enabled: true
  dockerconfigjson: "<REDHAT_REGISTRY_SERVICE_ACCOUNT_DOCKERCONFIGJSON>"
 
license:
  key: "<LICENSE_KEY>"
 
spec:
  # Option A: create a new PVC and specify a StorageClass.
  storageClassName: "<STORAGE_CLASS_NAME>"
 
  # Option B: use a pre-existing PVC.
  # existingPvcName: "<EXISTING_PVC_NAME>"

설치

<CHART_VERSION>을 인증된 Wave Autoscale OpenShift 차트 버전으로 바꾸세요.

helm repo add wave-autoscale-helm https://charts.openshift.io/
helm repo update
 
helm install wave-autoscale-helm wave-autoscale-helm/wave-autoscale-helm \
  -f values-redhat.yaml \
  --version <CHART_VERSION> \
  --create-namespace \
  -n wave-autoscale

방법 2: GHCR (OpenShift 차트)

Wave가 배포하는 OpenShift Helm 차트와 GHCR에 호스팅된 이미지를 사용합니다. 이 차트에는 OpenShift 리소스와 SCC 설정이 포함되어 있습니다.

• Helm 차트: https://release.waveautoscale.io/helm-chart-openshift
• 이미지 레지스트리: ghcr.io/stclab-inc/*
• Pull secret: Wave 팀이 제공하는 GHCR pull secret

values-openshift-ghcr.yaml

ghcr:
  enabled: true
  dockerconfigjson: "<GHCR_PULL_SECRET_DOCKERCONFIGJSON>"
 
license:
  key: "<LICENSE_KEY>"
 
spec:
  # Option A: create a new PVC and specify a StorageClass.
  storageClassName: "<STORAGE_CLASS_NAME>"
 
  # Option B: use a pre-existing PVC.
  # existingPvcName: "<EXISTING_PVC_NAME>"

설치

<CHART_VERSION>을 OpenShift Helm 차트 버전으로 바꾸세요.

helm repo add wave-autoscale-helm https://release.waveautoscale.io/helm-chart-openshift
helm repo update
 
helm install wave-autoscale-helm wave-autoscale-helm/wave-autoscale-helm \
  -f values-openshift-ghcr.yaml \
  --version <CHART_VERSION> \
  --create-namespace \
  -n wave-autoscale

방법 3: Red Hat 인증 Operator (OperatorHub)

Red Hat 인증 Operator를 사용하면 Helm CLI 없이 클러스터 내 OperatorHub에서 한 번의 클릭으로 Wave를 설치할 수 있습니다. Operator Lifecycle Manager(OLM)가 Wave 컨트롤러와 wavek8s.com CRD를 설치하며, 이후 Wave 커스텀 리소스 하나만 생성하면 플랫폼이 배포됩니다. 인증된 이미지는 OpenShift의 클러스터 전역 pull secret을 통해 registry.connect.redhat.com/stclab-inc/*에서 가져오므로 dockerconfigjson 값이 필요하지 않습니다.

설치

1. OpenShift 웹 콘솔에서 Operators → OperatorHub로 이동해 Wave Autoscale을 검색합니다.
2. Install을 클릭하고 wave-autoscale 네임스페이스를 선택한 뒤(OLM이 자동으로 생성할 수 있습니다) 확인합니다. OLM이 컨트롤러와 CRD를 설치합니다.
3. Operator 상태가 Succeeded가 되면 Operator의 Create Wave 폼을 사용하거나 아래 YAML을 적용해 Wave 커스텀 리소스를 생성합니다. spec은 Helm values 파일과 동일한 키를 사용합니다.

apiVersion: wavek8s.com/v1alpha1
kind: Wave
metadata:
  name: wave-autoscale
  namespace: wave-autoscale
spec:
  # The Wave CR .spec accepts the same keys as the Helm values file.
  license:
    key: "<LICENSE_KEY>"          # or: existingSecret: "<SECRET_NAME>"
  # Other chart values nest here too, e.g. storage:
  # spec:
  #   storageClassName: "<STORAGE_CLASS_NAME>"

oc apply -f wave-cr.yaml

업그레이드하려면 OLM이 자동으로 Operator를 갱신하도록 두거나(Automatic approval) InstallPlan을 직접 승인합니다(Manual). operand 이미지 태그를 변경하려면 Subscription의 spec.config.env에서 설정하세요.

OpenShift 관련 참고 사항

• 세 가지 방법 모두 **OpenShift 4.13+**가 필요합니다.
• 두 Helm 차트 모두 OpenShift 전용 리소스인 SecurityContextConstraints(SCC), ServiceAccount RBAC, OpenShift를 인식하는 DaemonSet 설정을 포함합니다.
• Wave의 StatefulSet은 Agent DaemonSet을 위해 privileged SCC로 실행되며, 인증 차트는 wave-autoscale-priority와 wave-autoscale-agent-priority SCC를 사용합니다.

임의 UID 지원

Wave 3.4.4+.

OpenShift의 기본 restricted-v2 SCC는 namespace마다 정해진 범위에서 UID를 임의로 배정하고, 컨테이너를 그 UID와 GID 0으로 실행합니다. Wave의 Core와 Intelligence 이미지는 이 방식을 지원합니다. home, cache, data 디렉터리의 소유 그룹이 0이고 그룹 쓰기 권한이 있으며, HOME을 /etc/passwd 조회에 맡기지 않고 명시적으로 지정합니다.

이게 중요한 이유는, 예상하지 못한 UID로 실행된 컨테이너에는 대응하는 passwd 항목이 없어서 HOME이 조용히 /로 잡히기 때문입니다. 3.4.4 이전에는 이 때문에 OpenShift에서 시작 직후 두 가지가 깨졌습니다. DuckDB가 ICU 확장을 //.duckdb에서 찾았고, Python 런타임이 캐시 디렉터리를 만들지 못했습니다. 둘 다 권한 오류 메시지가 아니라 설치 직후 crash loop로 나타났습니다.

기본값이 아닌 namespace UID 범위를 쓰는 OpenShift 클러스터거나 runAsUser를 고정하는 커스텀 SCC를 쓰더라도, 3.4.4 이상에서는 별도 설정이 필요 없습니다. 그 이전 버전에서 Core나 Intelligence Pod가 시작 직후 crash loop에 빠진다면, SCC를 느슨하게 푸는 대신 업그레이드하세요.

설치 확인

oc get pods -n wave-autoscale

웹 콘솔을 엽니다:

oc port-forward -n wave-autoscale svc/wave-autoscale-svc 3025:3025

http://localhost:3025로 접속합니다.

업데이트

helm repo update
 
helm upgrade wave-autoscale-helm wave-autoscale-helm/wave-autoscale-helm \
  -f values-redhat.yaml \
  --version <CHART_VERSION> \
  -n wave-autoscale

(선택한 방법에 맞는 values 파일을 사용하세요.)

제거

helm uninstall wave-autoscale-helm -n wave-autoscale

다음 단계

• 중요: 시작하기 전에: 알아둬야 할 런타임 동작입니다.
• Helm Values & 환경 변수: 전체 환경 변수와 Helm 값입니다.
• 문제 해결: 자주 발생하는 문제입니다.