빠른 시작: K3s를 사용하여 GitHub Codespaces에서 Azure IoT 작업 실행

2025-06-24

이 빠른 시작에서는 Azure Arc 지원 Kubernetes 클러스터에 Azure IoT 작업을 배포하여 디바이스와 워크로드를 원격으로 관리할 수 있습니다. 빠른 시작을 마치면 클라우드에서 관리할 수 있는 클러스터가 생성됩니다. 이 엔드투엔드 시리즈의 나머지 빠른 시작은 이 빠른 시작을 기반으로 샘플 자산, 데이터 처리 파이프라인 및 시각화를 정의합니다.

시작하기 전에

이 빠른 시작 시리즈는 Azure IoT 작업을 최대한 빨리 시작하여 엔드투엔드 시나리오를 평가할 수 있도록 돕기 위해 작성되었습니다. 실제 개발 또는 프로덕션 환경에서는 여러 팀이 협력하여 이러한 작업을 수행하며, 일부 작업에는 관리자 권한의 권한이 필요할 수 있습니다.

최상의 새 사용자 환경을 위해 이러한 빠른 시작에서 리소스에 대한 소유자 권한이 있도록 Azure 체험 계정을 사용하는 것이 좋습니다.

또한 이 빠른 시작을 위해 GitHub Codespaces를 가상 환경으로 사용하여 고유의 컴퓨터에 새로운 도구를 설치하지 않고도 시나리오를 테스트할 수 있습니다. 그러나 Ubuntu 또는 AKS(Azure Kubernetes Service)의 로컬 클러스터에 Azure IoT 작업을 배포하려면 Azure Arc 지원 Kubernetes 클러스터 준비를 참조하세요.

중요합니다

현재 Ubuntu 24.04 및 Tanzu Kubernetes의 K3s는 프로덕션 환경에서 Azure IoT Operations를 배포하기 위한 유일한 플랫폼입니다. 자세한 내용은 지원되는 환경을 참조하세요.

필수 구성 요소

시작하기 전에 다음 필수 조건을 준비합니다.

Azure 구독 Azure 구독이 아직 없는 경우 시작하기 전에 무료 구독을 만듭니다.
GitHub 계정.
개발 컴퓨터에 Visual Studio Code를 설치했습니다. 자세한 내용은 Visual Studio Code 다운로드를 참조하세요.
리소스 그룹 수준에서 Microsoft.Authorization/roleAssignments/write 권한.

어떤 문제를 해결할 수 있나요?

Azure IoT 작업은 Kubernetes 클러스터에서 실행되는 데이터 서비스 모음입니다. 이러한 클러스터는 클라우드에서 원격으로 관리하고, 클라우드 리소스 및 엔드포인트와 안전하게 통신할 수 있습니다. 이 빠른 시작에서는 다음 작업을 통해 이러한 문제를 해결합니다.

GitHub Codespaces에서 Kubernetes 클러스터를 만듭니다.
원격 관리를 위해 클러스터를 Azure Arc에 연결합니다.
스키마 레지스트리를 만듭니다.
Azure IoT 작업을 클러스터에 배포합니다.

클러스터 만들기

Azure IoT 작업은 Ubuntu의 K3, AKS(Azure Kubernetes Service) 엣지에센셜 및 Azure Local의 AKS에 배포할 수 있습니다. 하지만 속도와 편의성을 위해 이 빠른 시작에서는 GitHub Codespaces를 사용하여 클러스터를 호스팅합니다. 대신 Windows 또는 Ubuntu에서 클러스터에 Azure IoT 작업을 배포하는 방법을 알아보려면 Azure Arc 지원 Kubernetes 클러스터 준비를 참조하세요.

참고

Codespace는 빠르게 설정하고 나중에 쉽게 분해할 수 있지만, 성능 평가 또는 크기 조정 테스트에는 적합하지 않습니다. GitHub Codespaces를 탐색 용도로만 사용합니다.

Codespaces 환경은 빠른 시작 단계를 완료하기에 충분하지만 고급 구성은 지원하지 않습니다.

이 섹션에서는 새로운 클러스터를 만듭니다. 이전에 Azure IoT 작업을 배포한 클러스터를 다시 사용하려면 계속하기 전에 리소스 정리에 나오는 단계를 참조해 Azure IoT 작업을 제거해야 합니다.

Azure-Samples/explore-iot-operations 코드스페이스는 다음으로 미리 구성됩니다.

경량 Kubernetes 클러스터를 위해 K3d에서 실행 중인 K3s
Azure CLI
Kubernetes 리소스 관리를 위한 Kubectl
Helm 및 k9s와 같은 기타 유용한 도구

codespace와 클러스터를 만들려면 다음 단계를 따릅니다.

GitHub Codespace에서 코드스페이스를 만듭니다.

코드 공간에 대해 다음 권장 비밀을 제공합니다.

매개 변수	값
구독 ID	Azure 구독 ID입니다.
리소스 그룹	클러스터를 생성할 새 Azure 리소스 그룹의 이름입니다.
LOCATION	가까운 Azure 지역입니다. 현재 지원되는 지역 목록은 지원되는 지역을 참조하세요.

팁

이 단계에서 비밀로 제공하는 값은 이 코드 공간과 향후 코드 공간에서 사용할 수 있도록 GitHub 계정에 저장됩니다. 이러한 환경 변수는 codespace 터미널에 환경 변수로 추가되며, 다음 섹션의 CLI 명령에서 해당 환경 변수를 사용할 수 있습니다.

또한 이 codespace는 codespace 이름으로 설정되는 CLUSTER_NAME 환경 변수를 만듭니다.

새 codespace 만들기를 선택합니다.
codespace가 준비되면 왼쪽 위에 있는 메뉴 단추를 선택한 다음 VS Code 데스크톱에서 열기를 선택합니다.
메시지가 표시되면 Visual Studio Code용 GitHub Codespaces 확장을 설치하고 GitHub에 로그인합니다.
Visual Studio Code에서 보기>터미널을 차례로 선택합니다.

이 터미널을 사용하면 클러스터를 관리하기 위한 모든 CLI 명령을 실행할 수 있습니다.

클러스터를 Azure Arc에 연결

클러스터를 Azure Arc에 연결하려면 다음을 수행합니다.

codespace 터미널에서 Azure CLI에 로그인합니다.
```
az login
```
팁

VS Code 데스크톱이 아닌 브라우저에서 GitHub codespace 환경을 사용하는 경우 az login을 실행하면 localhost 오류가 반환됩니다. 오류를 수정하려면 다음 중 하나를 수행합니다.
- VS Code 데스크톱에서 코드스페이스를 연 다음 브라우저 터미널로 돌아가 az login을 다시 실행합니다.
- 또는 브라우저에서 localhost 오류가 발생하면 브라우저에서 URL을 복사하여 새 터미널 탭에서 curl "<URL>"을 실행합니다. "Microsoft Azure에 로그인했습니다!"라는 메시지와 함께 JSON 응답이 표시됩니다.
로그인하면 Azure CLI에서 모든 구독이 표시되고 기본 구독은 별표 *로 표시됩니다. 기본 구독을 계속하려면 Enter를 선택합니다. 그렇지 않은 경우 사용하려는 Azure 구독 번호를 입력합니다.
필요한 리소스 공급자를 구독에 등록합니다.

참고

이 단계는 구독당 한 번만 실행하면 됩니다. 리소스 공급자를 등록하려면 구독 기여자 및 소유자 역할에 포함된 /register/action 작업을 수행할 수 있는 권한이 필요합니다. 자세한 내용은 Azure 리소스 공급자 및 형식을 참조하세요.
```
az provider register -n "Microsoft.ExtendedLocation"
az provider register -n "Microsoft.Kubernetes"
az provider register -n "Microsoft.KubernetesConfiguration"
az provider register -n "Microsoft.IoTOperations"
az provider register -n "Microsoft.DeviceRegistry"
az provider register -n "Microsoft.SecretSyncController"
```
az group create 명령을 사용하여 Azure 구독에 리소스 그룹을 만들어 모든 리소스를 저장합니다.
```
az group create --___location $LOCATION --resource-group $RESOURCE_GROUP
```
az connectedk8s connect 명령을 사용하여 Kubernetes 클러스터를 Arc로 사용하도록 설정하고 Azure 리소스 그룹의 일부로 관리합니다.
```
az connectedk8s connect --name $CLUSTER_NAME --___location $LOCATION --resource-group $RESOURCE_GROUP
```
팁

$CLUSTER_NAME 값은 자동으로 codespace의 이름으로 설정됩니다. 다른 이름을 사용하려면 환경 변수를 바꿉니다.
Azure Arc 서비스가 테넌트에서 사용하는 Microsoft Entra ID 애플리케이션의 objectId를 가져와 환경 변수로 저장합니다. GUID 값을 변경하지 않고 다음 명령을 정확히 작성된 대로 실행합니다.
```
export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
```
az connectedk8s enable-features 명령을 사용하여 클러스터에서 사용자 지정 위치 지원을 사용하도록 설정합니다. 이 명령은 Azure Arc 서비스에서 사용하는 Microsoft Entra ID 애플리케이션의 objectId를 사용합니다. Kubernetes 클러스터를 배포한 컴퓨터에서 이 명령을 실행합니다.
```
az connectedk8s enable-features -n $CLUSTER_NAME -g $RESOURCE_GROUP --custom-locations-oid $OBJECT_ID --features cluster-connect custom-locations
```

스토리지 계정 및 스키마 레지스트리 만들기

스키마 레지스트리는 클라우드와 에지 모두에 메시지 정의를 저장하는 동기화된 리포지토리입니다. Azure IoT 작업에는 클러스터에 스키마 레지스트리가 필요합니다. 스키마 레지스트리에는 클라우드에 저장된 스키마 정보를 위한 Azure Storage 계정이 필요합니다.

이 섹션에서 스키마 레지스트리를 만드는 명령에는 리소스 그룹 수준에서 Microsoft.Authorization/roleAssignments/write 권한이 필요합니다. 이 권한은 스키마 레지스트리에 기여자 역할을 부여하여 스토리지 계정에 쓸 수 있도록 하는 데 사용됩니다.

Codespaces 터미널에서 다음 CLI 명령을 실행합니다.

이 섹션에서 만드는 리소스에 대한 환경 변수를 설정합니다.

자리 표시자	값
<STORAGE_ACCOUNT_NAME>	스토리지 계정의 이름. 스토리지 계정 이름은 3~24자 길이여야 하며 숫자와 소문자만 포함할 수 있습니다.
<SCHEMA_REGISTRY_NAME>	스키마 레지스트리의 이름. 스키마 레지스트리 이름에는 숫자, 소문자, 하이픈만 포함될 수 있습니다.
<SCHEMA_REGISTRY_NAMESPACE>	스키마 레지스트리 네임스페이스의 이름. 네임스페이스는 테넌트 내의 스키마 레지스트리를 고유하게 식별합니다. 스키마 레지스트리 네임스페이스 이름에는 숫자, 소문자, 하이픈만 포함될 수 있습니다.

STORAGE_ACCOUNT=<STORAGE_ACCOUNT_NAME>
SCHEMA_REGISTRY=<SCHEMA_REGISTRY_NAME>
SCHEMA_REGISTRY_NAMESPACE=<SCHEMA_REGISTRY_NAMESPACE>

계층 구조 네임스페이스가 사용하도록 설정된 스토리지 계정을 만듭니다.

az storage account create --name $STORAGE_ACCOUNT --___location $LOCATION --resource-group $RESOURCE_GROUP --enable-hierarchical-namespace

스토리지 계정에 연결되는 스키마 레지스트리를 만듭니다. 이 명령은 또한 스토리지 계정에 schemas라는 Blob 컨테이너를 만듭니다.

az iot ops schema registry create --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP --registry-namespace $SCHEMA_REGISTRY_NAMESPACE --sa-resource-id $(az storage account show --name $STORAGE_ACCOUNT -o tsv --query id)

Azure IoT 작업 배포

이 섹션에서는 Azure IoT 작업 구성 요소에 대한 종속성으로 클러스터를 구성한 다음 Azure IoT 작업을 배포합니다.

Codespaces 터미널에서 다음 CLI 명령을 실행합니다.

Azure IoT 작업을 위해 클러스터를 초기화합니다.

팁

init 명령은 클러스터당 한 번만 실행하면 됩니다. 이미 최신 Azure IoT 작업 버전이 배포된 클러스터를 재사용하는 경우 이 단계를 건너뛸 수 있습니다.
```
az iot ops init --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP
```
이 명령을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 터미널의 배포 진행률 표시를 통해 진행률을 볼 수 있습니다.

Azure IoT 작업을 배포합니다.

az iot ops create --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP --name ${CLUSTER_NAME}-instance  --sr-resource-id $(az iot ops schema registry show --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP -o tsv --query id) --broker-frontend-replicas 1 --broker-frontend-workers 1  --broker-backend-part 1  --broker-backend-workers 1 --broker-backend-rf 2 --broker-mem-profile Low

이 명령을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 터미널의 배포 진행률 표시를 통해 진행률을 볼 수 있습니다.

리소스에 액세스하려면 디바이스를 관리해야 함 오류가 발생하면 az login을 다시 실행하고 브라우저를 사용하여 대화형으로 로그인해야 합니다.

클러스터의 리소스 보기

배포가 완료되면 kubectl 명령을 사용하여 클러스터의 변경 내용을 관찰할 수 있습니다. 또는 클러스터가 Arc를 지원하므로 Azure Portal을 사용할 수 있습니다.

클러스터에서 Pod를 보려면 다음 명령을 실행합니다.

kubectl get pods -n azure-iot-operations

Azure Portal에서 리소스를 보려면 다음 단계를 사용합니다.

Azure Portal에서 Azure IoT 작업 인스턴스가 포함된 리소스 그룹으로 이동하거나 Azure IoT 작업을 검색하여 선택합니다.
Azure IoT 작업 인스턴스의 이름을 선택합니다.
인스턴스의 개요 페이지에서 리소스 요약 탭을 선택하여 클러스터에 배포된 리소스의 프로비전 상태를 확인합니다.

문제를 어떻게 해결했나요?

이 빠른 시작에서는 Azure IoT 작업 구성 요소와 안전하게 통신할 수 있도록 Arc 지원 Kubernetes 클러스터를 구성했습니다. 그런 다음 이러한 구성 요소를 클러스터에 배포했습니다. 이 테스트 시나리오에서는 Codespaces에서 실행되는 단일 Kubernetes 클러스터가 있습니다. 그러나 프로덕션 시나리오에서는 동일한 단계를 사용하여, 여러 사이트에서 많은 클러스터에 워크로드를 배포할 수 있습니다.

리소스 정리

다음 빠른 시작을 진행하는 경우에는 모든 리소스를 유지해야 합니다.

Azure IoT 작업 배포를 제거하지만 클러스터는 유지하려면 az iot ops delete 명령을 사용합니다.

az iot ops delete --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP

이 빠른 시작을 위해 만든 모든 리소스를 삭제하려면 Azure IoT 작업을 배포한 Kubernetes 클러스터를 삭제한 다음, 해당 클러스터가 포함된 Azure 리소스 그룹을 제거합니다.

이러한 빠른 시작에서 Codespaces를 사용한 경우 GitHub에서 Codespace를 삭제합니다.

다음 단계

빠른 시작: 클러스터 구성