HTTPS 및 인증서

연결된 디바이스의 앱이 웹 인터페이스를 노출하면, 어플라이언스는 내장 터널을 통해 이를 접근 가능하게 만듭니다. 사용자는 브라우저가 어플라이언스에 도달하는 방법을 선택합니다 — 설정이 전혀 필요 없는 것부터 완전히 회사 서명을 받는 것까지 세 가지 모드가 있습니다. 하나를 골라 해당 단계를 따르십시오.

모드	사용자가 제공하는 것	브라우저 신뢰	적합한 경우
1. 일반 HTTP (기본값)	없음	— (HTTP)	신뢰할 수 있는 분리된 네트워크 (OT VLAN, 제어 캐비닛)
2. HTTPS, 자체 발급 CA	도메인 + 와일드카드 DNS; 클라이언트에 CA 루트 하나 배포	CA를 배포하면 신뢰됨	IT의 인증서를 기다리지 않고 HTTPS 사용
3. HTTPS, 회사 인증서	도메인 + 와일드카드 DNS + 회사 CA의 와일드카드 인증서	자동으로 신뢰됨 (조직 CA)	내부 CA가 있는 회사 네트워크

회사 프록시 환경 사용과는 다릅니다. 해당 페이지는 어플라이언스가 아웃바운드 트래픽을 위해 회사 CA를 신뢰하는 것(어플라이언스 → 클라우드, TLS 가로채기 프록시를 통해)에 관한 것입니다. 이 페이지는 반대 방향 — 네트워크의 브라우저에서 어플라이언스로 향하는 인바운드 트래픽에 관한 것입니다. 두 가지는 서로 독립적입니다.

모드 1 — 일반 HTTP (기본값)

얻는 것. 어플라이언스 주소에서 모든 것이 일반 HTTP로 제공됩니다:

인터페이스	주소
메인 어플라이언스 UI	`http://<APPLIANCE_HOST>`
앱 웹 UI	`http://<APPLIANCE_HOST>:<port>`

각 앱 UI는 자동으로 할당된 자체 포트에 게시되며, IronFlock UI가 각각의 정확한 링크를 보여줍니다. 앱 UI는 어플라이언스 로그인 뒤에 유지됩니다 — 하나를 열면 로그인되어 있고 해당 디바이스에 대한 권한이 없는 한 로그인 화면으로 리디렉션됩니다(원하는 경우 앱별로 포트를 **공개(public)**로 표시하여 개방할 수 있습니다).

해야 할 일. 없습니다. 이것이 기본값입니다 — 로컬 네트워크에서 어플라이언스의 IP 또는 호스트명을 사용하기만 하면 됩니다. DNS도, 인증서도, 회사 IT의 개입도 필요 없습니다.

사용하는 경우. 신뢰할 수 있는 분리된 네트워크에 있는 어플라이언스 — 머신/OT VLAN의 제어 캐비닛 — 로, 일반 HTTP가 표준이고 네트워크 분리와 물리적 보안으로 접근이 통제되는 경우입니다.

모드 2 — 자체 발급 CA를 사용하는 HTTPS

얻는 것. 어플라이언스가 내장 HTTPS 인그레스를 켜고 사용자의 도메인 아래에서 모든 것을 HTTPS로 제공합니다 — 스스로 생성한 인증서를 사용합니다. 실행할 리버스 프록시도, 다시 연결할 URL도 없습니다. 설치 프로그램이 모든 것을 연결해 줍니다.

인터페이스	주소
메인 어플라이언스 UI	`https://<APPLIANCE_DOMAIN>`
앱 웹 UI	`https://<device>-<app>-<port>.<APPLIANCE_DOMAIN>`
플랫폼 서비스	`api.` · `auth.` · `login.` · `ws.` · `ide.` · `registry.` `<APPLIANCE_DOMAIN>`

해야 할 일.

어플라이언스로 확인되는 도메인을 선택하십시오 — 이를 사용할 모든 브라우저와 디바이스에 대해 확인되어야 하며, APPLIANCE_HOST와 APPLIANCE_DOMAIN을 모두 이 값으로 설정하십시오. 어플라이언스가 인증서를 직접 발급하므로 어떤 이름이든 작동합니다 — 유일한 요구 사항은 이름이 확인된다는 것입니다. 빠른 테스트를 넘어서는 용도라면, 자체 DNS에 와일드카드 레코드가 있는 사용자가 통제하는 내부 도메인(예: appliance.corp.example.com)을 사용하십시오: 격리되거나 DNS가 제한된 어플라이언스 네트워크는 보통 기본 <host-ip>.nip.io 이름이 의존하는 공개 nip.io 서비스에 도달할 수 없습니다. (해당 기본값은 네트워크가 인터넷에 도달할 수 있는 경우 작동합니다 — 개발 머신에서 작동하는 이유가 바로 이것입니다.)
와일드카드 DNS를 추가하십시오 — 도메인에 대해 두 레코드 모두 어플라이언스 호스트 IP를 가리키도록 합니다:
- *.<APPLIANCE_DOMAIN> — 앱 UI와 모든 서비스 서브도메인을 포괄합니다.
- <APPLIANCE_DOMAIN> (apex) — 이름으로 접근하는 메인 UI.
(nip.io 같은 와일드카드 DNS 서비스는 이미 이들을 자동으로 확인하므로 추가할 레코드가 없습니다 — 하지만 이는 해당 외부 서비스에 도달할 수 있는지에 달려 있습니다.)
--tls로 설치하십시오:
```
curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
  | sudo bash -s -- <your-instance-key> --interactive --tls
```
--interactive는 APPLIANCE_HOST / APPLIANCE_DOMAIN을 입력하도록 요청합니다(무인 설치의 경우 IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN을 설정하십시오). 어플라이언스는 /opt/ironflock/certs/ca/rootCA.crt에 로컬 CA를 생성하고 이 CA로 서명된 와일드카드 인증서를 생성합니다.
CA 루트를 클라이언트 머신에 배포하십시오. MDM을 통해 rootCA.crt를 푸시하거나 각 머신의 OS/브라우저 신뢰 저장소에 추가하십시오. 머신이 이를 신뢰하기 전까지는 브라우저가 경고를 표시합니다.
1년 이내에 갱신하십시오. 서버 인증서는 약 1년으로 제한됩니다 — 브라우저는 더 오래 유효한 인증서를 거부합니다. 갱신하려면 인증서 디렉터리에서 tls.crt/tls.key를 삭제하고 설치 프로그램을 다시 실행하십시오. 동일한 CA에 대해 새 인증서를 다시 서명하므로, 배포해 둔 신뢰가 계속 작동합니다.

디바이스는 일반 IP 경로에 그대로 유지됩니다. 브라우저 측만 HTTPS로 이동합니다. 연결된 디바이스는 계속 IP를 통해 어플라이언스에 도달하므로, 모든 디바이스에 CA를 설치할 필요가 없습니다.

사용하는 경우. 공유 네트워크에서 HTTPS를 원하지만 회사 IT의 인증서가 없거나(또는 기다리고 싶지 않고), UI를 열 머신에 루트 CA를 푸시할 수 있는 경우입니다.

모드 3 — 회사 인증서를 사용하는 HTTPS

얻는 것. 모드 2와 동일한 전체 어플라이언스 HTTPS — 하지만 인증서가 조직의 CA에서 나오며, 그 루트는 모든 관리되는 머신에서 이미 신뢰됩니다. 브라우저 경고도, 배포할 것도 없습니다. 디바이스도 도메인으로 이동합니다.

해야 할 일.

사용자가 통제하는 내부 도메인을 선택하고 APPLIANCE_HOST와 APPLIANCE_DOMAIN을 이 값으로 설정하십시오(예: appliance.corp.example.com). 여기서는 반드시 사용자 소유의 도메인이어야 합니다 — CA는 사용자가 소유한 도메인에 대해서만 인증서를 발급하므로 이 모드에서는 nip.io 이름이 작동하지 않습니다.
와일드카드 DNS를 추가하십시오 — 모드 2의 2단계와 같이 *.<APPLIANCE_DOMAIN>와 apex가 어플라이언스 호스트 IP를 가리키도록 합니다.
내부 CA에서 *.<APPLIANCE_DOMAIN>에 대한 와일드카드 인증서를 발급받으십시오 — 두 개의 PEM 파일로: tls.crt(가급적 전체 체인)와 암호화되지 않은 tls.key.

사용자의 인증서로 설치하십시오:


curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
  | sudo bash -s -- <your-instance-key> --interactive \
      --tls-cert /path/to/wildcard.crt \
      --tls-key  /path/to/wildcard.key

--tls-cert는 --tls를 함축합니다. 동등한 환경 변수: IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY.

CA의 일정에 따라 교체하십시오. 새 PEM 파일을 인증서 디렉터리에 넣고 재시작하십시오:
```
sudo cp wildcard.crt /opt/ironflock/certs/tls.crt
sudo cp wildcard.key /opt/ironflock/certs/tls.key
sudo chmod 0600 /opt/ironflock/certs/tls.key
sudo systemctl restart ironflock.service
```
어플라이언스는 파일이 변경되면 인증서를 자동으로 다시 로드하며, 재시작은 이를 즉시 적용할 뿐입니다. 설치 프로그램을 다시 실행해도 --tls-cert를 전달하지 않는 한 기존 인증서를 덮어쓰지 않습니다.

디바이스도 도메인으로 이동합니다. 인증서가 플릿 전체에서 신뢰되므로, 디바이스 트래픽 — 디바이스 링크, 컨테이너 이미지 가져오기, 디바이스 에이전트 업데이트 — 도 도메인을 통해 TLS로 실행되며, insecure-registries 우회 방법이 더 이상 필요하지 않습니다. 이는 전환 이후에 빌드된 앱 이미지에 적용됩니다. 전환 전에 설치된 앱은 빌드 당시의 레지스트리 주소를 그대로 유지하지만, 에이전트 0.21.3 이상은 이 주소를 스스로 해석합니다. 아래 요건 4를 참조하세요.

이 모드에서 연결된 디바이스에 필요한 것

어플라이언스에 연결하는 각 엣지 디바이스는 다음을 충족해야 합니다:

도메인을 확인할 수 있어야 합니다. <APPLIANCE_DOMAIN>과 그 하위 도메인(와일드카드 레코드)이 디바이스의 네트워크에서 어플라이언스 IP로 확인되어야 합니다. 브라우저에 제공되는 것과 같은 DNS 레코드입니다.
포트 443으로 어플라이언스에 도달할 수 있어야 합니다. 플랫폼 연결, 디바이스 에이전트 업데이트(https://registry.<APPLIANCE_DOMAIN>/dl에서 제공되며, 이 모드에서는 포트 15002가 필요하지 않습니다), 그리고 전환 이후에 빌드된 앱 이미지를 위해 디바이스에 필요한 유일한 포트입니다(전환 전에 설치된 앱은 요건 4를 참조하세요). 이것이 바로 통제가 엄격한 네트워크의 디바이스에 모드 3이 적합한 이유입니다. 아웃바운드 443은 거의 모든 환경에서 허용되며, 연결은 회사 HTTP 프록시를 통해서도 작동합니다(회사 프록시 환경 사용 → 엣지 디바이스의 설명대로 에이전트에 프록시를 전달하세요). 반면 단순 모드에서는 디바이스가 어플라이언스의 여러 서비스 포트에 직접 접근해야 하는데, 회사 방화벽과 프록시는 이런 포트를 자주 차단합니다. 디바이스 연결을 참조하세요.
회사 루트 CA를 신뢰해야 합니다. 에이전트와 Docker는 디바이스 운영체제의 신뢰 저장소를 기준으로 어플라이언스의 인증서를 검증합니다:
- 관리 대상 머신(도메인에 가입된 Windows, MDM으로 관리되는 Linux)은 대개 이미 회사 루트를 신뢰합니다. 별도 조치가 필요하지 않습니다.
- 관리되지 않는 Windows: 관리자 권한 프롬프트에서 루트 CA를 컴퓨터 저장소에 설치하고(certutil -addstore -f Root corporate-root-ca.crt), 그다음 Docker Desktop(시작 시 Windows 저장소에서 신뢰된 루트를 가져옵니다)과 에이전트 서비스(Restart-Service reagent)를 다시 시작하세요.
- Linux: sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates를 실행한 뒤 Docker(sudo systemctl restart docker)와 에이전트를 다시 시작하세요.
- 앱 컨테이너는 이 신뢰를 자동으로 물려받습니다(에이전트 0.21.3 이상). 컨테이너는 베이스 이미지에 포함된 CA 번들만 가지고 있으며 사내 루트 CA를 담고 있는 베이스 이미지는 없습니다. 그래서 TLS로 어플라이언스에 연결하는 앱은 인증서를 검증할 수 없었습니다. 이제 에이전트가 디바이스 자체의 신뢰 저장소를 모든 앱 컨테이너에 읽기 전용으로 /etc/ironflock/certs/ca-bundle.crt 에 마운트하고 주요 런타임이 이를 사용하도록 지정합니다(SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS). 따로 설정할 것은 없지만, 에이전트가 전달하는 것은 디바이스의 신뢰이므로 디바이스 자체가 루트 CA를 신뢰하고 있어야 합니다. 앱이 자체 SSL_CERT_FILE 을 설정한 경우에는 그 값이 유지됩니다.
디바이스 에이전트를 0.21.3 이상으로 업데이트하거나, 전환 전에 설치된 앱을 다시 게시해야 합니다. 앱에 저장된 compose 파일에는 앱을 빌드할 때 고정된 정규화된 이미지 참조 — <APPLIANCE_IP>:15001/apps/… — 가 들어 있습니다. 이 참조는 데이터입니다. 어플라이언스를 도메인으로 옮겨도 compose 파일은 다시 작성되지 않습니다. 에이전트 0.21.3 이상은 그런 참조를 디바이스 자신에게 설정된 레지스트리로 해석하므로, 전환 전에 설치된 앱도 아무 조치 없이 도메인을 통해 계속 동작합니다. 업데이트 후 첫 시작에서 각 이미지를 새 이름으로 한 번 가져옵니다. 더 오래된 에이전트는 참조를 적힌 그대로 사용해 예전 IP와 포트로 계속 접속합니다. 그 디바이스는 앱을 다시 빌드해 registry.<APPLIANCE_DOMAIN>을 기준으로 다시 게시할 때까지 레지스트리 포트(15001)에 로컬 네트워크에서 접근할 수 있어야 하며 포트 443만으로는 부족합니다. 어플라이언스는 자기 쪽 문제를 자동으로 처리합니다. 자신의 에이전트가 0.21.3보다 오래되었고 그런 참조가 하나라도 남아 있는 동안에는 레지스트리를 로컬 네트워크에서 접근 가능한 상태로 유지하고, 영향받는 compose 파일을 설치 프로그램 출력에 나열합니다. 에이전트를 최신으로 올리거나 해당 앱을 다시 게시하면, 다음 sudo ironflock-update는 더 기다릴 것을 찾지 못하고 스스로 레지스트리를 로컬 네트워크에서 내립니다.

사용하는 경우. 표준적인 회사 온프레미스 경로: 조직이 이미 내부 CA를 운영하고 있어, 와일드카드 인증서를 한 번 발급받으면 머신별 설정 없이 모든 곳에서 신뢰됩니다.

문제 해결

앱 UI 링크가 열리지 않음 / 연결 거부됨. 일반 모드에서 앱 UI는 http://<host>:<port>에 있습니다 — IronFlock UI에 표시된 정확한 링크를 사용하고 있는지(포트는 앱별로 할당됨), 그리고 네트워크에서 해당 포트를 차단하는 것이 없는지 확인하십시오.

브라우저가 인증서를 신뢰할 수 없다고 경고함(--tls 이후). 클라이언트가 아직 인증서의 CA를 신뢰하지 않습니다. 모드 2에서는 어플라이언스가 생성한 CA(/opt/ironflock/certs/ca/rootCA.crt)를 클라이언트에 배포하십시오. 모드 3에서는 클라이언트가 내부 CA 루트를 신뢰하는지 확인하십시오.

인증서 만료됨(자체 발급). 자체 발급 서버 인증서는 약 1년간 유효합니다(브라우저는 더 오래 유효한 인증서를 거부합니다). 갱신하십시오: 인증서 디렉터리에서 tls.crt/tls.key를 삭제하고 설치 프로그램을 다시 실행하여 동일한, 여전히 신뢰되는 CA에 대해 다시 서명하십시오 — 또는 사용자 소유 CA의 --tls-cert로 전환하십시오.

인증서 이름 불일치. 인증서가 사용 중인 도메인에 대한 와일드카드가 아닙니다. *.<APPLIANCE_DOMAIN>를 포괄해야 하며, URL의 도메인이 APPLIANCE_DOMAIN과 일치해야 합니다.

서브도메인이 확인되지 않음(--tls 이후). 와일드카드 DNS가 없습니다. 어플라이언스 호스트를 가리키는 *.<APPLIANCE_DOMAIN> A 레코드를 추가하십시오 — 이는 앱 UI와 모든 서비스 서브도메인을 포괄합니다.

모드 3으로 전환한 뒤 앱이 시작되지 않거나 이미지를 가져오지 못함 — 포트 15001에서 “connection refused”. 해당 앱의 compose 파일은 빌드 당시의 대상이었던 어플라이언스 IP 주소로 레지스트리를 계속 참조하며, 그 디바이스의 에이전트는 0.21.3보다 오래된 버전입니다. 이 버전부터 에이전트는 그런 참조를 자신의 레지스트리로 직접 해석합니다. 디바이스 에이전트를 업데이트하거나, 이미지가 registry.<APPLIANCE_DOMAIN>을 통해 확인되도록 앱을 다시 빌드하고 다시 게시하세요. 그때까지는 레지스트리가 로컬 네트워크에서 접근 가능한 상태로 유지되어야 하며, 이는 어플라이언스가 스스로 처리합니다. 평범한 sudo ironflock-update 한 번으로 로컬 네트워크 바인딩이 복원되고, 아직 옛 참조를 지닌 compose 파일이 나열됩니다.

앱은 실행 중이지만 연결되지 않고, 로그에 몇 초마다 같은 연결 시도가 반복됨. 앱 컨테이너가 어플라이언스의 인증서를 검증하지 못하는 상태입니다. TLS 핸드셰이크가 서버 인증서 직후에 중단되고 SDK가 무한히 재시도합니다. 에이전트는 운영체제의 신뢰 저장소를 사용하지만 컨테이너는 그렇지 않기 때문에 디바이스 자체는 온라인으로 남습니다. 디바이스의 신뢰 저장소를 앱 컨테이너에 전달하는 0.21.3 이상으로 에이전트를 업데이트하고, 디바이스가 회사 루트 CA를 신뢰하는지 확인하십시오(위 요구 사항 3). 디바이스에서 docker logs <컨테이너> 를 실행하면 인증서 검증 오류를 볼 수 있습니다. 이전 버전 에이전트에서는 앱마다 대응해야 합니다. 루트 CA를 이미지에 추가하거나, 마운트한 뒤 앱의 compose 파일에서 SSL_CERT_FILE 을 설정하십시오.

모드 3으로 전환한 뒤 디바이스가 연결되지 않음. 위의 네 가지 디바이스 요건을 차례로 확인하세요. 도메인이 디바이스 네트워크에서 확인되어야 하고, 어플라이언스의 포트 443에 도달할 수 있어야 하며(직접 또는 디바이스의 프록시를 통해), 디바이스가 회사 루트 CA를 신뢰해야 하고, 전환 전에 설치된 앱은 레지스트리 포트가 더 이상 필요하지 않게 되기 전에 에이전트 0.21.3 또는 재게시가 필요합니다. Windows에서는 C:\ProgramData\IronFlock\Reagent\reagent.log(Linux에서는 /var/log/reagent.log)의 에이전트 로그에 정확한 연결 오류가 표시됩니다. DNS 실패, 시간 초과, 인증서 검증 오류는 각각 앞의 세 요건 중 하나를 가리킵니다.