지원 종료 공지: 2026년 10월 7일에는에 대한 지원을 중단할 AWS 예정입니다 AWS IoT Greengrass Version 1. 2026년 10월 7일 이후에는 더 이상 AWS IoT Greengrass V1 리소스에 액세스할 수 없습니다. 자세한 내용은 [에서 마이그레이션 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)을 참조하세요.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 그룹의 대량 배포 생성
간단한 API 호출을 사용하여 한 번에 많은 수의 Greengrass 그룹을 배포할 수 있습니다. 이러한 배포는 상한이 고정된 가변 레이트로 트리거됩니다.
이 자습서에서는를 사용하여에서 대량 그룹 배포를 AWS CLI 생성하고 모니터링하는 방법을 설명합니다 AWS IoT Greengrass. 이 자습서에 나오는 대량 배포 예제에는 여러 그룹이 포함되어 있습니다. 구현 시 이러한 예제를 사용해 필요한 수 만큼 그룹을 추가할 수 있습니다.
자습서에는 다음과 같은 상위 수준 단계가 포함됩니다.
1. [대량 배포 입력 파일 생성 및 업로드](#bulk-deploy-cli-create-input-file)
1. [벌크 배포를 위한 IAM 실행 역할 생성 및 구성](#bulk-deploy-cli-create-role)
1. [실행 역할이 S3 버킷에 액세스하도록 허용](#bulk-deploy-cli-modify-bucket)
1. [그룹 배포](#bulk-deploy-cli-start-bulk-deployments)
1. [배포 테스트](#bulk-deploy-cli-test)
## 사전 조건
이 자습서를 완료하려면 다음이 필요합니다.
+ 배포 가능한 Greengrass 그룹 한 개 이상. AWS IoT Greengrass 그룹 및 코어 만들기에 대한 자세한 내용은 [시작하기 AWS IoT Greengrass](gg-gs.md) 단원을 참조하십시오.
+ 시스템에 AWS CLI 설치 및 구성된 입니다. 자세한 내용은 [AWS CLI 사용 설명서](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)를 참조하십시오.
+ AWS 리전 와 동일한에서 생성된 S3 버킷입니다 AWS IoT Greengrass. 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*에서 [첫 S3 버킷 생성 및 구성](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-configure-bucket.html)을 참조하세요.
**참고**
현재 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"
}
```
1. 다음 예제에서 선택한 컴퓨터 터미널 또는 편집기에서 *MyBulkDeploymentInputFile* 파일을 생성합니다. 이 파일에는 대량 배포에 포함할 각 AWS IoT Greengrass 그룹에 대한 정보가 포함되어 있습니다. 자습서에서 사용하기 위해 이 예제에서 여러 그룹을 정의하더라도 파일에 한 그룹만 포함할 수 있습니다.
**참고**
이 파일의 크기는 100MB 미만이어야 합니다.
```
{"GroupId":"groupId1", "GroupVersionId":"groupVersionId1", "DeploymentType":"NewDeployment"}
{"GroupId":"groupId2", "GroupVersionId":"groupVersionId2", "DeploymentType":"NewDeployment"}
{"GroupId":"groupId3", "GroupVersionId":"groupVersionId3", "DeploymentType":"NewDeployment"}
...
```
각 레코드(또는 행)에는 그룹 객체가 포함되어 있습니다. 각 그룹 객체에는 해당하는 `GroupId`, `GroupVersionId` 및 `DeploymentType`이 들어 있습니다. 현재는 `NewDeployment` 대량 배포 유형만 AWS IoT Greengrass 지원합니다.
파일을 저장하고 닫습니다. 파일의 위치를 메모해 둡니다.
1. 터미널에서 다음 명령을 사용해 Amazon S3 버킷에 입력 파일을 업로드합니다. 파일의 위치 및 이름으로 파일 경로를 바꿉니다. 자세한 내용은 [버킷에 객체 추가](https://docs.aws.amazon.com/AmazonS3/latest/gsg/PuttingAnObjectInABucket.html)를 참조하십시오.
```
aws s3 cp path/MyBulkDeploymentInputFile s3://amzn-s3-demo-bucket/
```
## 2단계: IAM 실행 역할 생성 및 구성
이 단계에서는 IAM 콘솔을 사용하여 독립 실행형 실행 역할을 생성합니다. 그런 다음 역할과 간에 신뢰 관계를 설정하고 IAM 사용자에게 실행 역할에 대한 `PassRole` 권한이 있는지 AWS IoT Greengrass 확인합니다. 이렇게 하면 AWS IoT Greengrass 가 실행 역할을 수임하고 사용자를 대신하여 배포를 생성할 수 있습니다.
1. 다음 정책에 따라 실행 역할을 생성합니다. 이 정책 문서를 통해 AWS IoT Greengrass 에서는 사용자를 대신해 배포를 생성할 때마다 대량 배포 입력 파일에 액세스할 수 있습니다.
IAM 역할 생성 및 권한 위임에 대한 자세한 내용은 [IAM 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)을 참조하십시오.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "greengrass:CreateDeployment",
"Resource": [
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId1",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId2",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId3"
]
}
]
}
```
------
**참고**
AWS IoT Greengrass에서 대량 배포 입력 파일의 각 그룹 또는 그룹 버전을 배포하려면 이 정책에는 리소스가 있어야 합니다. 모든 그룹에 대한 액세스를 허용하려면 다음과 같이 `Resource`에 별표를 지정합니다.
```
"Resource": ["*"]
```
1. AWS IoT Greengrass를 포함하도록 실행 역할에 대한 신뢰 관계를 수정합니다. 그러면 AWS IoT Greengrass 에서는 사용자의 실행 역할과 해당 역할에 연결된 권한을 사용할 수 있습니다. 자세한 내용은 [기존 역할에서 신뢰 관계를 편집](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/edit_trust.html)을 참조하십시오.
혼동된 대리자 보안 문제를 방지하려면 신뢰 정책에 `aws:SourceArn` 및 `aws:SourceAccount` 글로벌 조건 컨텍스트 키도 포함하는 것이 좋습니다.** 조건 컨텍스트 키는 지정된 계정 및 Greengrass 작업 영역에서 들어오는 요청만 허용하도록 액세스를 제한합니다. 혼동된 대리자 문제에 대한 자세한 내용은, [교차 서비스 혼동된 대리인 방지](cross-service-confused-deputy-prevention.md)를 참조하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "greengrass.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:greengrass:us-east-1:123456789012:*"
}
}
}
]
}
```
------
1. IAM 사용자에게 실행 역할에 대한 IAM `PassRole` 권한을 부여합니다. 이 IAM 사용자는 대량 배포를 시작하기 위해 사용한 사용자입니다. `PassRole` 권한을 사용하면 IAM 사용자가 실행 권한을 AWS IoT Greengrass 에 사용할 수 있도록 전달할 수 있습니다. 자세한 내용은 [AWS 서비스에 역할을 전달할 수 있는 사용자 권한 부여를 참조하세요](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html).
다음 예제를 사용하여 실행 역할에 연결된 IAM 정책을 업데이트합니다. 필요에 따라 이 예제를 수정하십시오.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1508193814000",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:user/executionRoleArn"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "greengrass.amazonaws.com"
}
}
}
]
}
```
------
## 3단계: 실행 역할이 S3 버킷에 액세스하도록 허용
대량 배포를 시작하려면 실행 역할이 Amazon S3 버킷에서 대량 배포 입력 파일을 읽을 수 있어야 합니다. `GetObject` 권한이 실행 역할에 액세스할 수 있도록 Amazon S3 버킷에 다음 정책 예제를 연결합니다.
자세한 내용은 [S3 버킷 정책을 추가하려면 어떻게 해야 합니까?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-bucket-policy.html)를 참조하십시오.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "examplePolicy",
"Statement": [
{
"Sid": "Stmt1535408982966",
"Effect": "Allow",
"Principal": {
"AWS": [
"executionRoleArn"
]
},
"Action": "s3:GetObject",
"Resource":
"arn:aws:s3:::amzn-s3-demo-bucket/objectKey"
}
]
}
```
------
터미널에서 다음 명령을 사용해 버킷의 정책을 확인할 수 있습니다.
```
aws s3api get-bucket-policy --bucket amzn-s3-demo-bucket
```
**참고**
Amazon S3 버킷의 `GetObject` 권한에 권한을 부여하도록 실행 역할을 직접 수정할 수 있습니다. 이렇게 하려면 실행 역할에 다음 정책 예제를 연결합니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-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 이벤트 규칙을 생성할 수 있습니다. 자세한 내용은 [배포 알림 받기](deployment-notifications.md) 단원을 참조하십시오.
1. 다음 명령을 사용하여 대량 배포 상태를 확인합니다.
```
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
```
이 오류는 주어진 입력 파일 행이 지정된 파라미터를 등록할 수 없음을 나타냅니다. 누락될 수 있는 파라미터는 `GroupId` 및 `GroupVersionId`입니다.
+
```
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 로그를 사용한 모니터링](greengrass-logs-overview.md).
## 다음 사항도 참조하세요.
자세한 정보는 다음 자료를 참조하세요.
+ [AWS IoT Greengrass 코어에 AWS IoT Greengrass 그룹 배포](deployments.md)
+ *AWS CLI 명령 참조*에서 [Amazon S3 API 명령](https://docs.aws.amazon.com/cli/latest/reference/s3api)
+ [AWS IoT Greengrass 명령](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html) *AWS CLI 참조의 명령*