그룹의 대량 배포 생성 - AWS IoT Greengrass

다음에 대한 설명서를 보고 있습니다.AWS IoT Greengrass Version 1.AWS IoT Greengrass Version 2의 최신 주요 버전입니다AWS IoT Greengrass. 사용에 관한 자세한 내용은 단원을 참조하십시오.AWS IoT Greengrass V2에 대한 자세한 내용은AWS IoT Greengrass Version 2개발자 안내서.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

그룹의 대량 배포 생성

간단한 API 호출을 사용하여 한 번에 많은 수의 Greengrass 그룹을 배포할 수 있습니다. 이러한 배포는 상한이 고정된 가변 레이트로 트리거됩니다.

이 자습서에서는 AWS CLI를 사용하여 AWS IoT Greengrass에서 그룹 대량 배포를 생성 및 모니터링하는 방법을 설명합니다. 이 자습서에 나오는 대량 배포 예제에는 여러 그룹이 포함되어 있습니다. 구현 시 이러한 예제를 사용해 필요한 수 만큼 그룹을 추가할 수 있습니다.

자습서에는 다음과 같은 상위 수준 단계가 포함됩니다.

Prerequisites

이 자습서를 완료하려면 다음이 필요합니다.

  • 배포 가능한 Greengrass 그룹 한 개 이상. AWS IoT Greengrass 그룹 및 코어 만들기에 대한 자세한 내용은 AWS IoT Greengrass 시작하기 단원을 참조하십시오.

  • 시스템에 설치 및 구성된 AWS CLI. 자세한 정보는 AWS CLI 사용 설명서를 참조하십시오.

  • 동일한 에서 생성된 S3 버킷AWS 리전로AWS IoT Greengrass. 자세한 정보는 단원을 참조하십시오.S3 버킷 생성 및 구성Amazon Simple Storage Service 콘솔 사용자 안내서.

    참고

    현재 SSE KMS를 사용하는 버킷은 지원되지 않습니다.

1단계: 대량 배포 입력 파일 생성 및 업로드

이 단계에서는 배포 입력 파일을 생성하여 Amazon S3 버킷에 업로드합니다. 이 파일은 직렬화되어 행으로 구분된 JSON 파일로, 대량 배포의 각 그룹에 대한 정보를 포함하고 있습니다. AWS IoT Greengrass에서는 이러한 정보를 사용하여 대량 그룹 배포를 초기화할 때 사용자를 대신해 각 그룹을 배포합니다.

  1. 다음 명령을 실행하여 배포하려는 각 그룹의 groupId를 가져옵니다. AWS IoT Greengrass에서 배포할 각 그룹을 식별할 수 있도록 대량 배포 입력 파일에 groupId를 입력합니다.

    참고

    에서도 이러한 값을 찾을 수 있습니다.AWS IoT콘솔. 그룹 ID는 그룹의 설정 페이지에 표시됩니다. 그룹 버전 ID는 그룹의 배포 페이지에 표시됩니다.

    aws greengrass list-groups

    응답에는 AWS IoT Greengrass 계정의 각 그룹에 대한 정보가 들어 있습니다.

    { "Groups": [ { "Name": "string", "Id": "string", "Arn": "string", "LastUpdatedTimestamp": "string", "CreationTimestamp": "string", "LatestVersion": "string", "LatestVersionArn": "string" } ], "NextToken": "string" }

    다음 명령을 실행하여 배포하려는 각 그룹의 groupVersionId를 가져옵니다.

    list-group-versions --group-id groupId

    응답에는 그룹 내 모든 버전에 대한 정보가 들어 있습니다. 를 기록해 둡니다.Version사용할 그룹 버전에 대한 값을 지정합니다.

    { "Versions": [ { "Arn": "string", "Id": "string", "Version": "string", "CreationTimestamp": "string" } ], "NextToken": "string" }
  2. 다음 예제에서 선택한 컴퓨터 터미널 또는 편집기에서 MyBulkDeploymentInputFile 파일을 생성합니다. 이 파일에는 대량 배포에 포함되는 각 AWS IoT Greengrass 그룹에 대한 정보가 포함되어 있습니다. 자습서에서 사용하기 위해 이 예제에서 여러 그룹을 정의하더라도 파일에 한 그룹만 포함할 수 있습니다.

    참고

    이 파일의 크기는 100MB 미만이어야 합니다.

    {"GroupId":"groupId1", "GroupVersionId":"groupVersionId1", "DeploymentType":"NewDeployment"} {"GroupId":"groupId2", "GroupVersionId":"groupVersionId2", "DeploymentType":"NewDeployment"} {"GroupId":"groupId3", "GroupVersionId":"groupVersionId3", "DeploymentType":"NewDeployment"} ...

    각 레코드(또는 행)에는 그룹 객체가 포함되어 있습니다. 각 그룹 객체에는 해당하는 GroupId, GroupVersionIdDeploymentType이 들어 있습니다. 현재 AWS IoT Greengrass는 NewDeployment 대량 배포 유형만 지원합니다.

    파일을 저장하고 닫습니다. 파일의 위치를 메모해 둡니다.

  3. 터미널에서 다음 명령을 사용해 Amazon S3 버킷에 입력 파일을 업로드합니다. 파일의 위치 및 이름으로 파일 경로를 바꿉니다. 자세한 내용은 버킷에 객체 추가를 참조하십시오.

    aws s3 cp path/MyBulkDeploymentInputFile s3://my-bucket/

2단계: IAM 실행 역할 생성 및 구성

이 단계에서는 IAM 콘솔을 사용하여 독립 실행형 실행 역할을 생성합니다. 그런 다음 역할과 간에 신뢰 관계를 설정합니다.AWS IoT Greengrass에 로그인하고 IAM 사용자가PassRole권한을 실행합니다. 그러면 AWS IoT Greengrass에서는 사용자의 실행 역할을 맡아 사용자를 대신해 배포를 생성합니다.

  1. 다음 정책에 따라 실행 역할을 생성합니다. 이 정책 문서를 통해 AWS IoT Greengrass에서는 사용자를 대신해 배포를 생성할 때마다 대량 배포 입력 파일에 액세스할 수 있습니다.

    IAM 역할 생성 및 권한 위임에 대한 자세한 내용은 IAM 역할 생성을 참조하십시오.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "greengrass:CreateDeployment", "Resource": [ "arn:aws:greengrass:region:accountId:/greengrass/groups/groupId1", "arn:aws:greengrass:region:accountId:/greengrass/groups/groupId2", "arn:aws:greengrass:region:accountId:/greengrass/groups/groupId3", ... ] } ] }
    참고

    AWS IoT Greengrass에서 대량 배포 입력 파일의 각 그룹 또는 그룹 버전을 배포하려면 이 정책에는 리소스가 있어야 합니다. 모든 그룹에 대한 액세스를 허용하려면 다음과 같이 Resource에 별표를 지정합니다.

    "Resource": ["*"]
  2. AWS IoT Greengrass를 포함하도록 실행 역할에 대한 신뢰 관계를 수정합니다. 그러면 AWS IoT Greengrass에서는 사용자의 실행 역할과 해당 역할에 연결된 권한을 사용할 수 있습니다. 자세한 내용은 기존 역할에서 신뢰 관계를 편집을 참조하십시오.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  3. Give IAMPassRoleIAM 사용자에게 권한을 부여합니다. 이 IAM 사용자는 대량 배포를 시작하기 위해 사용한 사용자입니다.PassRole권한을 사용하면 IAM 사용자가 실행 역할을 에 전달할 수 있습니다.AWS IoT Greengrass에서 사용할 수 있습니다. 자세한 내용은 사용자에게 AWS 서비스 역할을 전달할 수 있는 권한 부여를 참조하세요.

    다음 예제를 사용하여 신뢰 정책 문서를 업데이트합니다. 필요에 따라 이 예제를 수정하십시오.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1508193814000", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:user/executionRoleArn" ] } ] }

3단계: 실행 역할이 S3 버킷에 액세스하도록 허용

대량 배포를 시작하려면 실행 역할이 Amazon S3 버킷에서 대량 배포 입력 파일을 읽을 수 있어야 합니다. 다음 정책 예제를 Amazon S3 버킷에 연결하여GetObject권한은 실행 역할에 액세스할 수 있습니다.

자세한 내용은 S3 버킷 정책을 추가하려면 어떻게 해야 합니까?를 참조하십시오.

{ "Version": "2008-10-17", "Id": "examplePolicy", "Statement": [ { "Sid": "Stmt1535408982966", "Effect": "Allow", "Principal": { "AWS": [ "executionRoleArn" ] }, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-bucket/objectKey" } ] }

터미널에서 다음 명령을 사용해 버킷의 정책을 확인할 수 있습니다.

aws s3api get-bucket-policy --bucket my-bucket
참고

실행 역할을 직접 수정하여 Amazon S3 버킷의 권한을 부여할 수 있습니다.GetObject권한을 대신 사용 권한이 있는 이렇게 하려면 실행 역할에 다음 정책 예제를 연결합니다.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-bucket/objectKey" } ] }

4단계: 그룹 배포

이 단계에서는 대량 배포 입력 파일에 구성된 모든 그룹 버전에 대해 대량 배포 작업을 시작합니다. 각 그룹 버전에 대한 배포 작업의 유형은 NewDeploymentType입니다.

참고

동일한 계정의 또 다른 대량 배포 작업이 실행 중인 경우에는 StartBulkDeployment를 호출할 수 없습니다. 요청이 거부됩니다.

  1. 다음 명령을 사용하여 대량 배포를 시작합니다.

    모든 StartBulkDeployment 요청에 X-Amzn-Client-Token 토큰을 포함하는 것이 좋습니다. 이러한 요청은 토큰 및 요청 파라미터에 관한 idempotent입니다. 이 토큰은 최대 64개의 ASCII 문자로 구성된 고유한 문자열일 수 있으며, 대소문자를 구분합니다.

    aws greengrass start-bulk-deployment --cli-input-json "{ "InputFileUri":"URI of file in S3 bucket", "ExecutionRoleArn":"ARN of execution role", "AmznClientToken":"your Amazon client token" }"

    이 명령은 다음 응답과 함께 성공한 상태 코드인 200을 반환해야 합니다.

    { "bulkDeploymentId": UUID }

    대량 배포 ID를 메모해 둡니다. 이 ID는 대량 배포의 상태를 확인하는 데 사용할 수 있습니다.

    참고

    현재 대량 배포 작업은 지원되지 않지만 개별 그룹에 대한 배포 상태 변경에 대한 알림을 받을 수 있는 Amazon EventBridge 이벤트 규칙을 생성할 수 있습니다. 자세한 정보는 배포 알림 받기을 참조하십시오.

  2. 다음 명령을 사용하여 대량 배포 상태를 확인합니다.

    aws greengrass get-bulk-deployment-status --bulk-deployment-id 1234567

    이 명령은 정보의 JSON 페이로드 이외에 성공한 상태 코드인 200을 반환해야 합니다.

    { "BulkDeploymentStatus": Running, "Statistics": { "RecordsProcessed": integer, "InvalidInputRecords": integer, "RetryAttempts": integer }, "CreatedAt": "string", "ErrorMessage": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ] }

    BulkDeploymentStatus에는 대량 실행의 현재 상태가 포함되어 있습니다. 실행의 상태는 6개 중 하나일 수 있습니다.

    • Initializing. 대량 배포 요청이 수신되었고 실행이 시작 준비 중입니다.

    • Running. 대량 배포 실행이 시작되었습니다.

    • Completed. 대량 배포 실행이 모든 레코드 처리를 마쳤습니다.

    • Stopping. 대량 배포 실행이 중지 명령을 수신했고 곧 종료됩니다. 이전 배포의 상태가 Stopping이면 새 대량 배포를 시작할 수 없습니다.

    • Stopped. 대량 배포 실행이 수동으로 중지되었습니다.

    • Failed. 대량 납품 실행에서 오류가 발생해 종료되었습니다. 오류에 대한 자세한 내용은 ErrorDetails 필드를 참조하십시오.

    또한 JSON 페이로드에는 대량 배포 진행에 대한 통계 정보가 들어 있습니다. 이 정보를 사용해 처리된 그룹 수와 실패한 그룹 수를 확인할 수 있습니다. 통계 정보는 다음과 같습니다.

    • RecordsProcessed: 시도한 그룹 레코드 수

    • InvalidInputRecords: 재시도할 수 없는 오류를 반환한 총 레코드 수. 예를 들어, 입력 파일의 그룹 레코드가 잘못된 형식을 사용하거나 존재하지 않는 버전을 지정한 경우 또는 실행이 그룹 또는 그룹 버전을 배포할 권한을 부여하지 않은 경우 이러한 정보가 생성될 수 있습니다.

    • RetryAttempts: 재시도할 수 있는 오류를 반환한 배포 시도 횟수. 예를 들어, 그룹 배포 시도가 조절 오류를 반환한 경우 재시도가 트리거됩니다. 그룹 배포는 최대 5회까지 재시도할 수 있습니다.

    또한 대량 배포 실행에 실패한 경우 이 페이로드에는 문제 해결에 사용할 수 있는 ErrorDetails 섹션이 포함됩니다. 이 섹션에는 실행 실패의 원인에 대한 정보가 들어 있습니다.

    대량 배포 상태를 정기적으로 확인해 예상한 대로 진행 중인지 확인할 수 있습니다. 배포가 완료되면 RecordsProcessed가 대량 배포 입력 파일의 배포 그룹 수와 동일해야 합니다. 이는 각 레코드가 처리되었음을 나타냅니다.

5단계: 배포 테스트

ListBulkDeployments 명령을 사용하여 대량 배포의 ID를 찾습니다.

aws greengrass list-bulk-deployments

이 명령을 BulkDeploymentId를 포함해 최근 대량 배포까지 모든 대량 배포 목록을 반환합니다.

{ "BulkDeployments": [ { "BulkDeploymentId": 1234567, "BulkDeploymentArn": "string", "CreatedAt": "string" } ], "NextToken": "string" }

이제, ListBulkDeploymentDetailedReports 명령을 호출해 각 배포에 대한 자세한 정보를 수집합니다.

aws greengrass list-bulk-deployment-detailed-reports --bulk-deployment-id 1234567

이 명령은 정보의 JSON 페이로드와 함께 성공한 상태 코드인 200을 반환해야 합니다.

{ "BulkDeploymentResults": [ { "DeploymentId": "string", "GroupVersionedArn": "string", "CreatedAt": "string", "DeploymentStatus": "string", "ErrorMessage": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ] } ], "NextToken": "string" }

일반적으로, 이 페이로드에는 최근까지 각 배포와 그 배포 상태로 구성된, 페이지가 매겨진 목록이 포함되어 있습니다. 또한 대량 배포 실행에 실패하면 추가 정보가 포함됩니다. 다시, 목록의 총 배포 수와 대량 배포 입력 파일에서 식별한 그룹 수가 동일해야 합니다.

배포가 종료 상태(성공 또는 실패)가 될 때까지 반환되는 정보가 바뀔 수 있습니다. 그때까지 이 명령을 정기적으로 호출할 수 있습니다.

대량 배포 문제 해결

대량 배포가 성공적이지 않은 경우 다음 문제 해결 단계를 시도할 수 있습니다. 터미널에서 이 명령을 실행합니다.

입력 파일 오류 문제 해결

대량 배포 입력 파일에 구문 오류가 있는 경우 대량 배포에 실패할 수 있습니다. 그러면 대량 배포 상태로 Failed가 반환되고 첫 번째 확인 오류의 행 번호를 나타내는 오류 메시지가 함께 표시됩니다. 다음과 같은 4가지 오류가 발생할 수 있습니다.

  • InvalidInputFile: Missing GroupId at line number: line number

    이 오류는 주어진 입력 파일 행이 지정된 파라미터를 등록할 수 없음을 나타냅니다. 누락될 수 있는 파라미터는 GroupIdGroupVersionId입니다.

  • InvalidInputFile: Invalid deployment type at line number : line number. Only valid type is 'NewDeployment'.

    이 오류는 주어진 입력 파일 줄에 잘못된 배포 유형이 나열되었음을 나타냅니다. 현재, 지원되는 유일한 배포 유형은 NewDeployment입니다.

  • Line %s is too long in S3 File. Valid line is less than 256 chars.

    이 오류는 주어진 입력 파일 행이 너무 길어 줄여야 함을 나타냅니다.

  • Failed to parse input file at line number: line number

    이 오류는 주어진 입력 파일 행이 올바른 json으로 간주되지 않음을 나타냅니다.

동시 대량 배포 확인

다른 배포가 실행 중이거나 종료 상태가 아닌 경우에는 새 대량 배포를 시작할 수 없습니다. 그러면 Concurrent Deployment Error가 발생할 수 있습니다. ListBulkDeployments 명령을 사용해 대량 배포가 현재 실행 중이 아닌지 확인할 수 있습니다. 이 명령은 최근까지 대량 배포를 나열합니다.

{ "BulkDeployments": [ { "BulkDeploymentId": BulkDeploymentId, "BulkDeploymentArn": "string", "CreatedAt": "string" } ], "NextToken": "string" }

맨 처음 나열된 대량 배포의 BulkDeploymentId를 사용하여 GetBulkDeploymentStatus 명령을 실행합니다. 최근 대량 배포의 상태가 실행 중이면(Initializing 또는 Running) 다음 명령을 사용하여 대량 배포를 중지합니다.

aws greengrass stop-bulk-deployment --bulk-deployment-id BulkDeploymentId

이 작업은 배포 상태가 Stopped가 될 때까지 Stopping 상태로 유지됩니다. 배포가 Stopped 상태가 되면 새 대량 배포를 시작할 수 있습니다.

오류 세부 정보 확인

GetBulkDeploymentStatus 명령을 실행하여 대량 배포 실행 실패에 대한 정보가 포함된 JSON 페이로드를 반환합니다.

"Message": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ]

오류가 있는 경우 이 호출로 반환된 ErrorDetails JSON 페이로드에는 대량 배포 실행 실패에 대한 추가 정보가 포함됩니다. 예를 들어, 400 시리즈의 오류 상태 코드는 입력 파라미터 또는 호출자 종속성에 대한 입력 오류를 나타냅니다.

AWS IoT Greengrass 코어 로그 확인

AWS IoT Greengrass 코어 로그를 보고 문제를 해결할 수 있습니다. runtime.log를 보려면 다음 명령을 사용하십시오.

cd /greengrass/ggc/var/log sudo cat system/runtime.log | more

AWS IoT Greengrass 로깅에 대한 자세한 내용은 AWS IoT Greengrass 로그를 사용하여 모니터링 단원을 참조하십시오.

다음 사항도 참조하세요.

자세한 내용은 다음 자료를 참조하십시오.