빠른 시작: IoT Edge 디바이스에 연결된 레지스트리 배포

아티클
10/31/2023

이 빠른 시작에서는 Azure CLI를 사용하여 연결된 레지스트리를 Azure IoT Edge 디바이스에 모듈로 배포합니다. IoT Edge 디바이스는 클라우드의 부모 Azure Container Registry에 액세스할 수 있습니다.

IoT Edge에서 연결된 레지스트리를 사용하는 방법에 대한 개요는 Azure IoT Edge에서 연결된 레지스트리 사용을 참조하세요. 이 시나리오는 IoT Edge 계층 구조의 최상위 계층에 있는 디바이스에 해당합니다.

사전 요구 사항

Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
- 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
- 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
- az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

Azure IoT Hub 및 IoT Edge 디바이스 배포 단계는 빠른 시작: 가상 Linux 디바이스에 첫 번째 IoT Edge 모듈 배포를 참조하세요.

Important

IoT Edge 디바이스에 배포된 모듈에 나중에 액세스하려면 디바이스에서 포트 8000, 5671 및 8883을 열어야 합니다. 구성 단계는 Azure Portal을 사용하여 가상 머신에 대한 포트를 여는 방법을 참조하세요.
Azure에서 연결된 레지스트리 리소스입니다. 배포 단계는 Azure CLI 또는 Azure Portal을 사용한 빠른 시작을 참조하세요.
- 이 시나리오에서는 ReadWrite 또는 ReadOnly 모드의 연결된 레지스트리를 사용할 수 있습니다.
- 이 문서의 명령에서는 연결된 레지스트리의 이름이 환경 변수 CONNECTED_REGISTRY_RW에 저장됩니다.

클라우드 레지스트리로 이미지 가져오기

az acr import 명령을 사용하여 클라우드 레지스트리로 다음 컨테이너 이미지를 가져옵니다. 이러한 이미지를 이미 가져온 경우에는 이 단계를 건너뜁니다.

연결된 레지스트리 이미지

중첩된 IoT Edge 시나리오를 지원하려면 연결된 레지스트리 런타임에 대한 컨테이너 이미지를 프라이빗 Azure 컨테이너 레지스트리에서 사용할 수 있어야 합니다. az acr import 명령을 사용하여 연결된 레지스트리 이미지를 프라이빗 레지스트리로 가져옵니다.

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry
REGISTRY_NAME=<container-registry-name>

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/acr/connected-registry:0.8.0

IoT Edge 및 API 프록시 이미지

중첩된 IoT Edge에서 연결된 레지스트리를 지원하려면 IoT Edge 및 API 프록시용 모듈을 배포해야 합니다. 이러한 이미지를 프라이빗 레지스트리로 가져옵니다.

IoT Edge API 프록시 모듈을 사용하면 IoT Edge 디바이스에서 443과 같은 동일한 포트에서 HTTPS 프로토콜을 사용하여 여러 서비스를 노출할 수 있습니다.

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-agent:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-hub:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-api-proxy:1.1.2

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-diagnostics:1.2.4

Hello-world 이미지

연결된 레지스트리를 테스트하려면 hello-world 이미지를 가져옵니다. 이 리포지토리는 연결된 레지스트리에 동기화되며 연결된 레지스트리 클라이언트에서 가져옵니다.

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/hello-world:1.1.2

연결된 레지스트리 구성 검색

연결된 레지스트리를 IoT Edge 디바이스에 배포하기 전에 Azure의 연결된 레지스트리 리소스에서 구성 설정을 검색해야 합니다.

az acr connected-registry get-settings 명령을 사용하여 연결된 레지스트리를 설치하는 데 필요한 설정 정보를 얻습니다. 다음 예제에서는 HTTPS를 부모 프로토콜로 지정합니다. 부모 레지스트리가 클라우드 레지스트리인 경우 이 프로토콜이 필요합니다.

az acr connected-registry get-settings \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --parent-protocol https

기본적으로 설정 정보에는 연결된 레지스트리를 배포하는 데 필요한 동기화 토큰 암호가 포함되어 있지 않습니다. 필요에 따라 --generate-password 1 또는 generate-password 2 매개 변수를 전달하여 암호 중 하나를 생성합니다. 생성된 암호를 안전한 위치에 저장합니다. 암호는 다시 검색할 수 없습니다.

Warning

암호를 다시 생성하면 동기화 토큰 자격 증명이 회전됩니다. 이전 암호를 사용하여 디바이스를 구성한 경우 해당 구성을 업데이트해야 합니다.

명령 출력에는 레지스트리 연결 문자열 및 관련 설정이 포함됩니다. 다음 예제 출력에서는 부모 레지스트리 contosoregistry가 있는 myconnectedregistry라는 연결된 레지스트리에 대한 연결 문자열을 보여줍니다.

{
  "ACR_REGISTRY_CONNECTION_STRING": "ConnectedRegistryName=myconnectedregistry;SyncTokenName=myconnectedregistry-sync-token;SyncTokenPassword=xxxxxxxxxxxxxxxx;ParentGatewayEndpoint=contosoregistry.eastus.data.azurecr.io;ParentEndpointProtocol=https"
}

IoT Edge에 대한 배포 매니페스트 구성

배포 매니페스트는 어떤 모듈을 IoT Edge 디바이스에 배포할지 설명하는 JSON 문서입니다. 자세한 내용은 IoT Edge 모듈을 사용, 구성 및 다시 사용하는 방법 이해를 참조하세요.

Azure CLI를 사용하여 연결된 레지스트리 및 API 프록시 모듈을 배포하려면 다음 배포 매니페스트를 로컬에 manifest.json 파일로 저장합니다. 명령을 실행하여 디바이스에 구성을 적용할 때 다음 섹션에서 파일 경로를 사용합니다.

연결된 레지스트리 모듈 설정

이전 섹션의 토큰 자격 증명 및 연결 문자열을 사용하여 env 노드의 관련 JSON 값을 업데이트합니다.

다음 환경 변수는 env 노드에서 선택 사항입니다.

변수	설명
`ACR_REGISTRY_LOGIN_SERVER`	고유한 호스트 이름 또는 FQDN을 지정합니다. 사용되는 경우 연결된 레지스트리는 이 로그인 서버 값에 대한 요청만 수락합니다. 값이 제공되지 않으면 모든 로그인 서버 값을 사용하여 연결된 레지스트리를 액세스할 수 있습니다.
`ACR_REGISTRY_CERTIFICATE_VOLUME`	HTTPS를 통해 연결된 레지스트리를 액세스할 수 있는 경우 HTTPS 인증서가 저장된 볼륨을 가리킵니다. 설정되지 않은 경우 기본 위치는 `/var/acr/certs`입니다.
`ACR_REGISTRY_DATA_VOLUME`	연결된 레지스트리에 의해 이미지가 저장될 기본 위치 `/var/acr/data`를 덮어씁니다. 이 위치는 컨테이너의 볼륨 바인딩과 일치해야 합니다.

Important

연결된 레지스트리가 80 및 443과 다른 포트에서 수신 대기하는 경우 ACR_REGISTRY_LOGIN_SERVER 값(지정된 경우)에 포트가 포함되어야 합니다. 예: 192.168.0.100:8080

API 프록시 모듈을 사용하지 않는 경우 연결된 레지스트리에 대한 HostPort 바인딩을 설정해야 합니다. 예시:

 "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"],\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"8080\"}]}}}"

API 프록시 모듈 설정

API 프록시는 NGINX_DEFAULT_PORT로 구성된 8000 포트에서 수신 대기합니다. API 프록시 설정에 대한 자세한 내용은 IoT Edge GitHub 리포지토리를 참조하세요.

{
    "modulesContent": {
        "$edgeAgent": {
            "properties.desired": {
                "modules": {
                    "connected-registry": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/acr/connected-registry:0.8.0",
                            "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"]}}"
                        },
                        "type": "docker",
                        "env": {
                            "ACR_REGISTRY_CONNECTION_STRING": {
                                "value": "ConnectedRegistryName=<REPLACE_WITH_CONNECTED_REGISTRY_NAME>;SyncTokenName=<REPLACE_WITH_SYNC_TOKEN_NAME>;SyncTokenPassword=REPLACE_WITH_SYNC_TOKEN_PASSWORD;ParentGatewayEndpoint=<REPLACE_WITH_CLOUD_REGISTRY_NAME>.<REPLACE_WITH_CLOUD_REGISTRY_REGION>.data.azurecr.io;ParentEndpointProtocol=https"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    },
                    "IoTEdgeAPIProxy": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-api-proxy:1.1.2",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8000/tcp\":[{\"HostPort\":\"8000\"}]}}}"
                        },
                        "type": "docker",
                        "env": {
                            "NGINX_DEFAULT_PORT": {
                                "value": "8000"
                            },
                            "CONNECTED_ACR_ROUTE_ADDRESS": {
                                "value": "connected-registry:8080"
                            },
                            "BLOB_UPLOAD_ROUTE_ADDRESS": {
                                "value": "AzureBlobStorageonIoTEdge:11002"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    }
                },
                "runtime": {
                    "settings": {
                        "minDockerVersion": "v1.25",
                        "registryCredentials": {
                            "cloudregistry": {
                                "address": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io",
                                "password": "<REPLACE_WITH_SYNC_TOKEN_PASSWORD>",
                                "username": "<REPLACE_WITH_SYNC_TOKEN_NAME>"
                            }
                        }
                    },
                    "type": "docker"
                },
                "schemaVersion": "1.1",
                "systemModules": {
                    "edgeAgent": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-agent:1.2.4",
                            "createOptions": ""
                        },
                        "type": "docker",
                        "env": {
                            "SendRuntimeQualityTelemetry": {
                                "value": "false"
                            }
                        }
                    },
                    "edgeHub": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-hub:1.2.4",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
                        },
                        "type": "docker",
                        "status": "running",
                        "restartPolicy": "always"
                    }
                }
            }
        },
        "$edgeHub": {
            "properties.desired": {
                "routes": {
                    "route": "FROM /messages/* INTO $upstream"
                },
                "schemaVersion": "1.1",
                "storeAndForwardConfiguration": {
                    "timeToLiveSecs": 7200
                }
            }
        }
    }
}

IoT Edge에 연결된 레지스트리 및 API 프록시 모듈 배포

다음 명령을 사용하여 이전 섹션에서 만든 배포 매니페스트를 사용하여 IoT Edge 디바이스에 연결된 레지스트리 및 API 프록시 모듈을 배포합니다. IoT Edge 최상위 계층 디바이스의 ID와 표시된 IoT Hub의 이름을 제공합니다.

# Set the IOT_EDGE_TOP_LAYER_DEVICE_ID and IOT_HUB_NAME environment variables for use in the following Azure CLI command
IOT_EDGE_TOP_LAYER_DEVICE_ID=<device-id>
IOT_HUB_NAME=<hub-name>

az iot edge set-modules \
  --device-id $IOT_EDGE_TOP_LAYER_DEVICE_ID \
  --hub-name $IOT_HUB_NAME \
  --content manifest.json

자세한 내용은 Azure CLI를 사용하여 Azure IoT Edge 모듈 배포를 참조하세요.

연결된 레지스트리의 상태를 확인하려면 다음 az acr connected-registry show 명령을 사용합니다. 연결된 레지스트리의 이름은 $CONNECTED_REGISTRY_RW 값입니다.

az acr connected-registry show \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --output table

성공적으로 배포되면 연결된 레지스트리에서 Online 상태를 표시합니다.

다음 단계

이 빠른 시작에서는 연결된 레지스트리를 IoT Edge 디바이스에 배포하는 방법을 배웠습니다. 다음 가이드를 계속 진행하여 새로 배포된 연결된 레지스트리에서 이미지를 가져오거나 중첩된 IoT Edge 디바이스에 연결된 레지스트리를 배포하는 방법을 알아봅니다.

연결된 레지스트리에서 이미지 끌어오기

자습서: 중첩된 IoT Edge 디바이스에 연결된 레지스트리 배포

다음을 통해 공유