> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/secure-gateway-microshift.md). # MicroShift에서의 Secure Gateway Secure Gateway를 Red Hat Device Edge에 배포합니다. 게이트웨이와 암호화된 캐시는 Roboflow Deployment Manager가 관리하는 MicroShift 작업으로 실행됩니다. [보안 게이트웨이](/deployment/ko/self-hosted/enterprise/secure-gateway.md) 또한 Red Hat Device Edge에서 MicroShift(엣지 디바이스용 Red Hat의 Kubernetes 배포판)를 사용하여 실행됩니다. 전용 설치 프로그램은 게이트웨이와 암호화된 캐시를 Kubernetes 워크로드로 배포하며, RHEL 호스트에서 실행되는 Roboflow Deployment Manager(`rfdm`)가 RHEL 호스트에서 실행됩니다. Docker 배포와 동일한 게이트웨이(Roboflow API를 프록시하고, 플릿을 위한 모델 가중치와 컨테이너 이미지를 캐시하는 하나의 통제된 외부 통신 지점)가 Red Hat Device Edge를 표준으로 하는 호스트용으로 패키징되어 제공됩니다. {% hint style="info" %} 이 페이지는 MicroShift 배포를 다룹니다. MicroShift 또는 Docker가 없는 RHEL 호스트는 [RHEL의 Podman에서 Secure Gateway](/deployment/ko/self-hosted/enterprise/secure-gateway-podman.md). Docker 호스트와 게이트웨이의 구성 참조(캐싱, TLS 변수, 로그 내보내기)는 [보안 게이트웨이](/deployment/ko/self-hosted/enterprise/secure-gateway.md) 및 [보안 게이트웨이 매뉴얼](https://secure-gateway.roboflow.com/manual/). {% endhint %} ## 아키텍처 * Roboflow Deployment Manager는 RHEL 호스트에서 systemd 서비스로 실행되며 MicroShift의 Kubernetes API를 통해 워크로드를 관리합니다. 게이트웨이가 구성되고, 업데이트되고, 실행 중이도록 유지합니다. * 게이트웨이와 캐시 백엔드(SeaweedFS, at-rest 암호화를 지원하는 S3 호환 저장소)는 `roboflow-edge` 네임스페이스에서 실행됩니다. * 하나의 `로드밸런서` Service는 장치 IP에서 게이트웨이를 노출합니다: 포트 `443` 및 포트 `80`. * 캐시는 MicroShift의 LVMS 스토리지 프로비저너가 프로비저닝한 영구 볼륨에 저장됩니다. 볼륨 클레임은 60GB이며, 게이트웨이의 50GB 캐시와 여유 공간을 고려해 설정됩니다. * 모든 워크로드는 MicroShift의 기본 제한 보안 프로필에서 비특권으로 실행됩니다. 권한 있는 컨테이너도, root 사용자도, 사용자 지정 보안 컨텍스트 권한 부여도 없습니다. 이것은 단일 노드 배포입니다. 고가용성과 다중 노드 클러스터는 지원되지 않습니다. ## 사전 요구 사항 * 유효한 Red Hat 구독이 있는 x86\_64의 Red Hat Enterprise Linux 9.6 호스트입니다. 설치 프로그램 번들은 `linux-amd64` 에만 해당합니다. * OpenShift pull secret가 구성된 상태로 설치되어 실행 중인 Red Hat build of MicroShift 4.16 이상. 4.20(EUS)이 권장됩니다. 다음을 참조하세요. [지원 매트릭스](#support-matrix). * 최소 60GB의 여유 공간이 있는 LVM 볼륨 그룹입니다. MicroShift의 LVMS 프로비저너가 이를 사용해 게이트웨이의 캐시 볼륨을 생성합니다. 볼륨 그룹이 없거나 여유 공간이 너무 적으면 스토리지 요청은 계속 `보류 중` 로 유지되고 캐시는 시작되지 않습니다. * `skopeo` 호스트에 설치되어 있어야 합니다(`sudo dnf install skopeo`). 설치 프로그램은 이를 사용해 번들 이미지를 CRI-O의 저장소로 복사하며, 없으면 중단합니다. * OpenShift CLI(`oc`)가 호스트에 설치되어 있어야 하며, 버전은 MicroShift 릴리스와 일치해야 합니다. MicroShift는 이를 설치하지 않으며, 이 페이지의 검증 및 문제 해결 명령은 이를 사용합니다. sudo의 `secure_path` (`/usr/bin` 에서 동작해야 합니다): `sudo` 에서 제외하므로 `/usr/local/bin` 에서 `PATH`, 따라서 `oc` 거기에 압축을 풀면 `sudo: oc: command not found`. * 포트 `80` 및 `443` 장치 IP에서 게이트웨이에 사용할 수 있습니다 * 연결된 설치의 경우, 다음으로의 아웃바운드 HTTPS `api.roboflow.com` 및 `repo.roboflow.com` stock RHEL 설치에서는 firewalld가 실행 중이므로, 설치하기 전에 게이트웨이의 포트를 열고 MicroShift의 pod 네트워크를 trusted 영역에 넣으세요. 이렇게 하지 않으면 pod 네트워킹과 클라이언트 접근이 모두 실패합니다: ```bash sudo firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16 sudo firewall-cmd --permanent --zone=trusted --add-source=169.254.169.1 sudo firewall-cmd --permanent --add-service=http --add-service=https sudo firewall-cmd --reload ``` firewalld를 다시 로드하면 OVN pod가 다시 시작될 때까지 MicroShift pod 네트워킹이 깨진 상태로 남으므로, 다시 로드한 뒤 다음의 복구 단계를 수행하세요: [문제 해결](#troubleshooting). {% hint style="warning" %} 설치 프로그램은 게이트웨이가 장치의 포트 80과 443을 소유할 수 있도록 MicroShift의 기본 ingress 라우터를 비활성화합니다. 이 호스트의 라우터를 통해 이미 다른 워크로드를 제공하고 있다면, 이 배포 모델은 그것들과 충돌합니다. 게이트웨이 전용 장치를 사용하세요. {% endhint %} ## 연결된 호스트에 설치 MicroShift 설치 프로그램 번들을 다운로드하고 무결성을 확인하세요: ```bash curl -fOL https://repo.roboflow.com/rfdm/secure-gateway/microshift/latest/secure-gateway-microshift-installer-linux-amd64.tar.gz curl -fOL https://repo.roboflow.com/rfdm/secure-gateway/microshift/latest/secure-gateway-microshift-installer-linux-amd64.tar.gz.sha256 echo "$(cat secure-gateway-microshift-installer-linux-amd64.tar.gz.sha256) secure-gateway-microshift-installer-linux-amd64.tar.gz" \ | sha256sum -c - ``` 압축을 풀고 root로 설치 프로그램을 실행하세요: ```bash tar xzf secure-gateway-microshift-installer-linux-amd64.tar.gz cd secure-gateway-microshift-installer sudo ./install-microshift.sh \ --api-key \ --device-id \ --workspace ``` 설치 프로그램: 1. MicroShift가 실행 중이고 지원되는 버전인지, 그리고 스토리지에 사용할 수 있는 LVM 볼륨 그룹이 있는지 확인합니다. 2. 번들된 Secure Gateway와 SeaweedFS 이미지를 호스트의 컨테이너 저장소로 로드합니다. 레지스트리에서 가져오는 것은 없습니다. 3. CRI-O 구성에서 이미지를 고정하여 Kubernetes의 디스크 압박 가비지 컬렉션이 절대 제거하지 못하게 합니다. 4. MicroShift의 기본 ingress 라우터를 비활성화하고 MicroShift를 다시 시작하여 게이트웨이를 위해 포트 80과 443을 비웁니다. 5. Roboflow Deployment Manager를 systemd 서비스로 설치하고 장치 구성을 작성합니다. 6. Deployment Manager를 시작하며, 이는 `roboflow-edge` 네임스페이스를 생성하고 게이트웨이와 캐시를 배포합니다. 배포를 확인하세요: ```bash sudo systemctl is-active rfdm sudo oc get pods -n roboflow-edge \ --kubeconfig /var/lib/microshift/resources/kubeadmin/kubeconfig curl -fk https:///health ``` 두 pod는 모두 `실행 중`이며, 헬스 체크는 HTTP 200을 반환해야 합니다. `-k` 플래그는 게이트웨이의 인증서를 신뢰할 때까지 필요합니다. 다음을 참조하세요: [TLS 및 신뢰](#tls-and-trust). ## 에어갭 환경에 설치 동일한 번들은 인터넷 액세스가 없는 호스트에도 설치할 수 있습니다. 컨테이너 이미지는 OCI 아카이브로 포함되어 있으며 호스트의 컨테이너 저장소에 직접 로드됩니다. 워크로드는 정확한 버전 태그를 참조하므로 설치 시점이나 그 이후에도 레지스트리에서 가져오는 일은 없습니다. 연결된 머신에서 번들을 다운로드하고 확인한 다음, 이동식 미디어나 내부 파일 전송 절차를 통해 장치로 옮기고, 그 후 압축을 풀어 `install-microshift.sh` 를 위와 동일하게 실행하세요. 검증도 동일합니다. ## TLS 및 신뢰 기본적으로 Roboflow Deployment Manager는 게이트웨이용 자체 서명 인증서를 생성하여 `secure-gateway-tls` Secret(유형 `kubernetes.io/tls`)에 저장합니다. 이 `roboflow-edge` 네임스페이스에 저장합니다. 게이트웨이 pod는 이 Secret을 마운트하고 포트 443에서 HTTPS를 제공합니다. 인증서는 Deployment Manager 재설치를 거쳐도 유지됩니다. Deployment Manager는 인증서가 없을 때, 만료까지 30일 이내일 때, 인증서와 개인 키가 더 이상 일치하지 않을 때, 또는 새 인증서가 포함해야 할 모든 이름을 더 이상 포함하지 않을 때 이를 교체합니다. 사용자 고유의 인증서는 이러한 모든 이름을 포함해야 하며, 그렇지 않으면 다음 reconcile 때 Deployment Manager가 이를 자체 서명 인증서로 교체합니다: * `repo.roboflow.com`, `*.roboflow.com`, 그리고 `localhost`. 클라이언트는 다음 이름으로 게이트웨이에 접근합니다: `repo.roboflow.com`, 따라서 인증서가 이를 포함하지 않으면 컨테이너 이미지 가져오기가 실패합니다. * `secure-gateway`, `secure-gateway.roboflow-edge.svc`, 그리고 `secure-gateway.roboflow-edge.svc.cluster.local` * 장치의 호스트 이름 * IP 주소 `127.0.0.1` 및 장치 IP 자체 인증서를 사용하려면 Secret의 내용을 교체하고 게이트웨이를 다시 시작하세요: ```bash export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig sudo -E oc create secret tls secure-gateway-tls -n roboflow-edge \ --cert=/path/to/gateway.crt --key=/path/to/gateway.key \ --dry-run=client -o yaml | sudo -E oc apply -f - sudo -E oc rollout restart deployment/secure-gateway -n roboflow-edge ``` 인증서가 만료되기 30일 이상 전에 갱신하세요. Secret의 인증서가 마지막 30일에 들어가면 Deployment Manager가 새로 생성한 자체 서명 인증서로 교체합니다. 장치의 IP 주소나 호스트 이름을 변경해도 같은 효과가 있으므로, 둘 중 하나를 변경하기 전에 인증서를 다시 발급하세요. Deployment Manager는 다음과 같이 신뢰 번들도 게시합니다: `roboflow-trust-bundle` ConfigMap으로, 게이트웨이에 마운트됩니다. 게이트웨이는 이를 사용해 플릿의 다른 Roboflow 관리 장치가 제시한 TLS 인증서를 신뢰하므로, 사용자가 인증서를 수동으로 배포하지 않아도 장치가 게이트웨이에 인증할 수 있습니다. ## Inference Server 연결 Roboflow Inference Server를 실행하는 각 머신에서 게이트웨이의 클라이언트 설치 스크립트를 실행하세요. 이 스크립트는 게이트웨이의 인증서를 머신의 신뢰 저장소에 추가하고, 해당 머신의 Roboflow 트래픽(API 호출, 모델 가중치, 컨테이너 이미지 가져오기)을 게이트웨이를 통해 라우팅합니다: ```bash curl -fsSLk https:///install-client.sh | sudo bash -s -- --server ``` 다음 `-k` 여기서는 이 플래그가 필요합니다. 머신이 아직 게이트웨이의 인증서를 신뢰하지 않기 때문이며, 바로 그 인증서를 스크립트가 설치합니다. 이 작업은 직접 제어하는 네트워크 경로에서만 실행하거나, 스크립트를 직접 복사한 뒤 먼저 확인하세요. 또는 개별 Inference Server를 게이트웨이로 지정할 수 있습니다. `SECURE_GATEWAY` 환경 변수를 사용합니다. 다음을 참조하세요: [Inference Server 연결](/deployment/ko/self-hosted/enterprise/secure-gateway.md#connecting-inference-servers). 명시적 스킴(`SECURE_GATEWAY=https://`)을 버전 전반에 걸쳐 사용하세요. 인증서는 해당 IP를 포함해야 합니다. 예정된 런타임 강화 빌드는 다음에서 설명하듯이, 주소만 있는 경우와 평문 동작을 변경합니다: [보안 구성 마이그레이션](/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#gateway-transport). Inference Server도 게이트웨이의 인증서를 신뢰해야 하는데, 이는 클라이언트 설치 스크립트가 처리해 줍니다. 아웃바운드 액세스가 필요한 것은 게이트웨이뿐입니다: `api.roboflow.com` 및 `repo.roboflow.com`. ## 문제 해결
증상조치
캐시 볼륨이 멈춤 보류 중LVM 볼륨 그룹이 없거나 60GB의 여유 공간이 있는 그룹이 없습니다. 다음으로 여유 공간을 확인하세요: sudo vgs; 볼륨 그룹에 용량이 생기면 볼륨이 자동으로 바인딩됩니다. 더 작은 볼륨에서 실행하려면 storage_size 및 CACHE_MAX_SIZE_GB 를 함께 /opt/rfdm/config/rfconfig.json.
게이트웨이 로드밸런서 Service가 멈춤 <pending>장치의 포트 80/443이 여전히 점유되어 있습니다. 보통 기본 라우터가 아직 활성화되어 있기 때문입니다. 설치 프로그램은 다음 위치의 스니펫을 통해 이를 설정합니다: /etc/microshift/config.d/10-roboflow-ingress.yaml, 다음이 아니라 /etc/microshift/config.yaml. 다음을 확인하세요: sudo microshift show-config --mode effective 가 보고하는지 ingress.status: Removed, 스니펫이 사라졌다면 복원한 다음 MicroShift를 다시 시작하세요. 또한 다른 호스트 프로세스가 80 또는 443에 바인딩하지 않는지 확인하세요.
firewalld 다시 로드 후 연결 실패firewalld를 다시 로드하면 OVN 네트워킹 pod가 다시 시작될 때까지 MicroShift pod 네트워킹이 깨집니다. 다음의 pod를 삭제하세요: openshift-ovn-kubernetes 네임스페이스에서 다시 생성되도록 하거나 MicroShift를 다시 시작하세요.
노드가 계속 NotReady; ovnkube-master pod가 다음 오류로 크래시 루프합니다: 네트워크 인터페이스의 MTU(...)가 지정된 오버레이 MTU(1500)보다 너무 작습니다네트워크 인터페이스 MTU가 1500 미만입니다(클라우드 VPC와 VPN 링크에서 흔하며, GCP는 1460을 사용합니다). 다음에서 pod MTU를 인터페이스 MTU에서 100을 뺀 값으로 설정하세요: /etc/microshift/ovn.yaml: 1460 인터페이스의 경우 파일에 다음 한 줄만 있어야 합니다: mtu: 1360. 그런 다음 다음을 실행하세요: sudo systemctl stop microshift, echo 1 | sudo microshift-cleanup-data --ovn, 그리고 sudo systemctl start microshift정리 단계는 이전 MTU가 OVN 데이터베이스에 저장되어 있기 때문에 필요합니다.
게이트웨이 pod가 멈춤 ImagePullBackOff 호스트 이미지 정리 후이미지 고정은 번들에 포함된 정확한 참조를 보호하지만, podman rmi 또는 podman image prune 호스트에서 실행한 이 명령은 여전히 CRI-O가 사용하는 동일한 저장소에서 형제 이미지와 공유 레이어를 제거할 수 있습니다. 장치에서 컨테이너 저장소 정리를 피하세요. 이미지가 사라졌다면 설치 프로그램을 다시 실행하여 다시 로드하세요.
게이트웨이 로그 초기 핸드셰이크 실패 ... 로컬 캐시 전용 모드로 시작합니다게이트웨이가 시작 시 Roboflow API에 도달하지 못했습니다(잘못된 API 키, 아웃바운드 연결 없음, 또는 캐시가 아직 시작 중). 트래픽은 계속 제공하고 로컬 캐시는 유지하지만, S3 기반 캐시 없이 실행되며 다음 재시작 전까지 백엔드로 텔레메트리나 이벤트를 보고할 수 없습니다. 원인을 해결한 다음 다음을 실행하세요: sudo oc rollout restart deployment/secure-gateway -n roboflow-edge --kubeconfig /var/lib/microshift/resources/kubeadmin/kubeconfig.
로그 위치Deployment Manager: sudo journalctl -u rfdm. 게이트웨이와 캐시: sudo oc logs deployment/secure-gateway -n roboflow-edge (및 deployment/seaweedfs), 다음을 사용: --kubeconfig /var/lib/microshift/resources/kubeadmin/kubeconfig.
## 지원 매트릭스
MicroShiftRHEL참고
4.199.6
4.20 (EUS)9.6권장
4.219.6RHEL 10의 MicroShift 4.21은 Red Hat Technology Preview이며 Secure Gateway에서는 지원되지 않습니다.
MicroShift 4.16이 최소 지원 버전입니다. 짝수 번호의 MicroShift 릴리스에는 Extended Update Support(EUS)가 포함되므로, 장기 운영되는 엣지 배포에는 4.20이 가장 좋은 선택입니다.