> 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 Roboflow Deployment Manager가 관리하는 MicroShift 워크로드로 게이트웨이와 암호화된 캐시를 실행하면서 Red Hat Device Edge에 Secure Gateway를 배포합니다. [보안 게이트웨이](/deployment/ko/self-hosted/enterprise/secure-gateway.md) 또한 Red Hat Device Edge에서 MicroShift를 사용해 실행되며, 이는 엣지 장치를 위한 Red Hat의 Kubernetes 배포판입니다. 전용 설치 관리자가 게이트웨이와 암호화된 캐시를 Kubernetes 워크로드로 배포하며, Roboflow Deployment Manager(`rfdm`)가 RHEL 호스트에서 실행하도록 관리합니다. Red Hat Device Edge에 표준화된 호스트용으로 패키징된 Docker 배포와 동일한 게이트웨이(Roboflow API를 프록시하고 전체 장치에 대해 모델 가중치와 컨테이너 이미지를 캐시하는 하나의 제어된 송신 지점)를 제공합니다. {% hint style="info" %} 이 페이지는 MicroShift 배포를 다룹니다. MicroShift나 Docker가 없는 RHEL 호스트는 [RHEL의 Podman을 사용한 보안 게이트웨이](/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를 통해 워크로드를 관리합니다. 게이트웨이를 구성하고, 업데이트하고, 실행 상태로 유지합니다. * 게이트웨이와 캐시 백엔드(저장 시 암호화되는 S3 호환 저장소인 SeaweedFS)는 `roboflow-edge` 네임스페이스에서 Deployment로 실행됩니다. * 하나의 `LoadBalancer` Service가 장치 IP에서 게이트웨이를 게시합니다: 포트 `443` 의 HTTPS와 포트 `80`. * 의 HTTP-to-HTTPS 리디렉션입니다. 캐시는 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` 그곳에 압축을 푼 oc는 `sudo: oc: command not found`. * 포트 `80` 및 `443` 장치 IP에서 게이트웨이에 사용 가능 * 연결된 설치의 경우, 다음으로 나가는 HTTPS `api.roboflow.com` 및 `repo.roboflow.com` stock RHEL 설치에서는 firewalld가 실행 중이므로, 설치 전에 게이트웨이의 포트를 열고 MicroShift의 pod 네트워크를 신뢰된 영역에 넣으세요. 그렇지 않으면 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일 이내일 때, 인증서와 개인 키가 더 이상 일치하지 않을 때, 또는 새 인증서가 포함할 모든 이름을 더 이상 포함하지 않을 때 이를 교체합니다. 사용자 자신의 인증서는 이러한 모든 이름을 포함해야 하며, 그렇지 않으면 Deployment Manager가 다음 reconcile 시 자체 서명 인증서로 교체합니다: * `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는 이 장치 자체의 TLS 서비스 인증서에서 신뢰 번들도 생성하여 `roboflow-trust-bundle` ConfigMap으로 게시하고, 이를 게이트웨이에 마운트하며 다음 위치에서 제공합니다 `/trust-bundle.crt`. 클라이언트 설치 스크립트는 실행되는 각 머신에 이 번들을 설치하므로, 인증서를 수동으로 배포하지 않아도 해당 클라이언트는 이 장치의 모든 TLS 서비스를 신뢰합니다. ## Inference Server 연결 Roboflow Inference Server를 실행하는 각 머신에서 게이트웨이의 클라이언트 설치 스크립트를 실행하세요. 이 스크립트는 게이트웨이의 인증서를 머신의 신뢰 저장소에 추가하고 Roboflow 트래픽(API 호출, 모델 가중치, 컨테이너 이미지 가져오기)을 게이트웨이를 통해 라우팅합니다. Secret에서 게이트웨이의 인증서를 내보내고, 이미 신뢰하는 채널로 클라이언트에 복사하세요(예: `scp`, 조직의 파일 전송 프로세스, 이동식 미디어). 인증서 검증을 끈 상태로 게이트웨이 자체에서 가져오지 마세요: ```bash export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig sudo -E oc get secret secure-gateway-tls -n roboflow-edge \ -o jsonpath='{.data.tls\.crt}' | base64 -d > gateway-ca.crt scp gateway-ca.crt :/tmp/gateway-ca.crt ``` 클라이언트에서 해당 인증서에 대해 검증된 TLS 연결로 설치 스크립트를 다운로드한 다음 실행하세요: ```bash curl -fsSL --cacert /tmp/gateway-ca.crt \ https:///install-client.sh -o install-client.sh sudo bash install-client.sh --server ``` 스크립트를 따로 다운로드한 뒤 실행하면 root로 실행하기 전에 내용을 읽어볼 수도 있습니다. 직접 제어하는 네트워크 경로에서만 실행하세요: `install-client.sh` 는 `/ca.crt` 및 `/trust-bundle.crt` 를 연결을 검증하지 않고 게이트웨이 자체에서 가져오므로, 위에서 검증된 다운로드를 했더라도 그 경로의 중간자(interceptor)가 그 단계에서 여전히 신뢰할 수 있는 CA를 제공할 수 있습니다. 대안으로, 개별 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)에서 설명한 대로 bare-address 및 plaintext 동작을 변경합니다. Inference Server도 게이트웨이의 인증서를 신뢰해야 하는데, 이는 클라이언트 설치 스크립트가 처리해 줍니다. 게이트웨이만 다음으로 나가는 액세스가 필요합니다 `api.roboflow.com` 및 `repo.roboflow.com`. ## 문제 해결
증상조치
캐시 볼륨이 멈춤 보류 중LVM 볼륨 그룹이 없거나 60GB의 여유 공간이 있는 것이 없습니다. 다음으로 여유 공간을 확인하세요 sudo vgs; 볼륨 그룹에 용량이 생기면 볼륨은 자동으로 바인드됩니다. 더 작은 볼륨에서 실행하려면 다음 값을 낮추세요 storage_size 및 CACHE_MAX_SIZE_GB 를 함께 /opt/rfdm/config/rfconfig.json.
게이트웨이 LoadBalancer 서비스가 멈춤 <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를 다시 시작하세요.
노드가 준비 안 됨; 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이 장기 수명의 엣지 배포에 가장 좋은 선택입니다.