PowerShell을 사용하여 Azure Data Lake Storage Gen2에서 ACL 관리

아티클
02/25/2024

이 문서에서는 PowerShell을 사용하여 디렉터리 및 파일의 액세스 제어 목록을 가져오고, 설정 및 업데이트하는 방법을 보여줍니다.

부모 디렉터리 아래에 만들어진 새 자식 항목에서는 이미 ACL 상속을 사용할 수 있는 상태입니다. 그러나 각 자식 항목을 개별적으로 변경할 필요 없이 부모 디렉터리의 기존 자식 항목에서 ACL을 재귀적으로 추가, 업데이트, 제거할 수도 있습니다.

참조 | 피드백 제공

필수 구성 요소

Azure 구독 자세한 내용은 Azure 무료 평가판 가져오기 를 참조하세요.
HNS(계층 구조 네임스페이스)를 사용하도록 설정된 스토리지 계정입니다. 이러한 지침에 따라 라이브러리를 만듭니다.
Azure CLI 버전 2.6.0 이상.
다음 보안 권한 중 하나입니다.
- 대상 컨테이너, 스토리지 계정, 부모 리소스 그룹 또는 구독으로 범위가 할당된 Storage Blob 데이터 소유자 역할이 할당된 프로비전된 Microsoft Entra ID 보안 주체입니다.
- ACL 설정을 적용하려는 대상 컨테이너 또는 디렉터리를 소유하는 담당 사용자. ACL을 재귀적으로 설정하기 위해 대상 컨테이너 또는 디렉터리의 모든 자식 항목을 포함합니다.
- 스토리지 계정 키.

PowerShell 모듈 설치

다음 명령을 사용하여 설치된 PowerShell 버전이 5.1 이상인지 확인합니다.
```
echo $PSVersionTable.PSVersion.ToString()
```
PowerShell 버전을 업그레이드하려면 기존 Windows PowerShell 업그레이드를 참조하세요.
Az.Storage 모듈을 설치합니다.
```
Install-Module Az.Storage -Repository PSGallery -Force  
```
PowerShell 모듈 설치 방법에 대한 자세한 내용은 Azure PowerShell 모듈 설치를 참조하세요.

계정에 연결

명령으로 스토리지 계정에 대해 권한 부여를 획득하는 방법을 선택합니다.

옵션 1: Microsoft Entra ID를 사용하여 권한 부여 획득

참고 항목

Microsoft Entra ID를 사용하여 액세스를 권한 부여하는 경우 보안 주체에 Storage Blob 데이터 소유자 역할이 할당되었는지 확인합니다. ACL 권한이 적용되는 방식과 권한 변경의 영향에 대한 자세한 내용은 Azure Data Lake Storage Gen2의 액세스 제어 모델을 참조하세요.

이 접근 방식을 사용할 때 시스템은 사용자 계정에 적절한 Azure RBAC(역할 기반 액세스 제어) 할당 및 ACL 권한이 포함되었는지 확인합니다.

Windows PowerShell 명령 창을 연 후 Connect-AzAccount 명령으로 Azure 구독에 로그인하고 화면 안내를 따릅니다.
```
Connect-AzAccount
```
ID가 둘 이상의 구독에 연결되어 있으면 활성 구독을 디렉터리를 만들고 관리할 스토리지 계정의 구독으로 설정합니다. 이 예제에서는 <subscription-id> 자리 표시자 값을 해당 구독의 ID로 바꿉니다.
```
Select-AzSubscription -SubscriptionId <subscription-id>
```

스토리지 계정 컨텍스트를 가져옵니다.

$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount

옵션 2: 스토리지 계정 키를 사용하여 권한 부여 획득

이 방법에서는 시스템이 Azure RBAC 또는 ACL 권한을 확인하지 않습니다. 계정 키를 사용하여 스토리지 계정 컨텍스트를 가져옵니다.

$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -StorageAccountKey '<storage-account-key>'

ACL 가져오기

Get-AzDataLakeGen2Item cmdlet을 사용하여 디렉터리 또는 파일의 ACL을 가져옵니다.

다음 예제에서는 컨테이너의 루트 디렉터리의 ACL을 가져온 후 ACL을 콘솔에 출력합니다.

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

이 예제에서는 디렉터리의 ACL을 가져온 후 ACL을 콘솔에 출력합니다.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

이 예제에서는 파일의 ACL을 가져온 후 ACL을 콘솔에 출력합니다.

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

다음 이미지는 디렉터리의 ACL을 가져온 후 출력을 보여 줍니다.

Get ACL output for directory

이 예제에서 소유 사용자에게 읽기, 쓰기 및 실행 권한이 있습니다. 소유 그룹에는 읽기 및 실행 권한만 있습니다. 액세스 제어 목록에 대한 자세한 내용은 Azure Data Lake Storage Gen2의 액세스 제어를 참조하세요.

ACL 설정

ACL을 설정하는 경우 모든 항목을 포함하여 전체 ACL을 바꿉니다. 보안 주체의 권한 수준을 변경하거나 다른 기존 항목에 영향을 주지 않고 ACL에 새 보안 주체를 추가하려면 대신 ACL을 업데이트해야 합니다. ACL을 바꾸는 대신 업데이트하려면 이 문서의 ACL 업데이트 섹션을 참조하세요.

ACL을 설정하도록 선택한 경우 소유 사용자에 대한 항목, 소유 그룹에 대한 항목, 다른 모든 사용자에 대한 항목을 추가해야 합니다. 소유 사용자, 소유 그룹, 다른 모든 사용자에 대한 자세한 내용은 사용자 및 ID를 참조하세요.

이 섹션에서는 다음 방법을 보여줍니다.

ACL 설정
반복적으로 ACL 설정

ACL 설정

Set-AzDataLakeGen2ItemAclObject cmdlet을 사용하여 소유 사용자, 소유 그룹 또는 다른 사용자에 대한 ACL을 만듭니다. 그런 후 Update-AzDataLakeGen2Item cmdlet을 사용하여 ACL을 커밋합니다.

이 예제에서는 소유 사용자, 소유 그룹 또는 다른 사용자에 대해 컨테이너의 루트 디렉터리에 ACL을 설정한 후 ACL을 콘솔에 출력합니다.

$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

이 예제에서는 소유 사용자, 소유 그룹 또는 다른 사용자의 디렉터리에 대해 ACL을 설정한 후 ACL을 콘솔에 출력합니다.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

참고 항목

기본 ACL 항목을 설정하려면 Set-AzDataLakeGen2ItemAclObject 명령을 실행할 때 -DefaultScope 매개변수를 사용합니다. 예: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope

다음 예제에서는 소유 사용자, 소유 그룹 또는 기타 사용자의 파일에 대해 ACL을 설정하고 이 ACL을 콘솔에 출력합니다.

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

참고 항목

특정 그룹 또는 사용자의 ACL, 서비스 주체 또는 관리 ID를 설정하려면 해당 개체 ID를 사용합니다. 예를 들어, 그룹의 ACL을 설정하려면 group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx를 사용합니다. 사용자의 ACL을 설정하려면 user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx를 사용합니다.

다음 이미지는 파일의 ACL을 설정한 후 출력을 보여 줍니다.

Get ACL output for file

다음 예제에서는 소유 사용자 및 소유 그룹에 읽기 및 쓰기 권한만 있습니다. 다른 모든 사용자에게는 쓰기 및 실행 권한이 있습니다. 액세스 제어 목록에 대한 자세한 내용은 Azure Data Lake Storage Gen2의 액세스 제어를 참조하세요.

반복적으로 ACL 설정

Set-AzDataLakeGen2AclRecursive cmdlet을 사용하여 재귀적으로 ACL을 설정합니다.

다음 예시에서는 my-parent-directory라는 디렉터리의 ACL을 설정합니다. 이러한 항목은 소유 사용자에게 읽기, 쓰기 및 실행 권한을 부여하고, 소유 그룹에는 읽기 및 실행 권한만 부여하고, 다른 모든 사용자에게는 액세스 권한을 부여하지 않습니다. 이 예제의 마지막 ACL 항목은 개체 ID가 “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”인 특정 사용자에 읽기와 실행 권한을 부여합니다.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl

Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

참고 항목

일괄 처리 크기를 지정하여 일괄 처리에서 ACL을 재귀적으로 설정하는 예제를 보려면 Set-AzDataLakeGen2AclRecursive 참조 문서를 확인하세요.

ACL 업데이트

ACL을 업데이트할 때 ACL을 바꾸는 대신 ACL을 수정합니다. 예를 들어 ACL에 나열된 다른 보안 주체에 영향을 주지 않고 ACL에 새 보안 주체를 추가할 수 있습니다. ACL을 업데이트하지 않고 바꾸려면 이 문서의 ACL 설정 섹션을 참조하세요.

이 섹션에서는 다음 방법을 보여줍니다.

ACL 업데이트
재귀적으로 ACL 업데이트

ACL 업데이트

먼저 ACL을 가져옵니다. 그런 후 Set-AzDataLakeGen2ItemAclObject cmdlet을 사용하여 ACL 항목을 추가하거나 업데이트합니다. Update-AzDataLakeGen2Item cmdlet을 사용하여 ACL을 커밋합니다.

이 예제에서는 사용자의 디렉터리에서 ACL을 만들고 업데이트합니다.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

참고 항목

기본 ACL 항목을 업데이트하려면 Set-AzDataLakeGen2ItemAclObject 명령을 실행할 때 -DefaultScope 매개변수를 사용합니다. 예: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope

재귀적으로 ACL 업데이트

Update-AzDataLakeGen2AclRecursive cmdlet을 사용하여 재귀적으로 ACL을 업데이트합니다.

이 예시에서는 쓰기 권한이 있는 ACL 항목을 업데이트합니다.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx

Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

참고 항목

일괄 처리 크기를 지정하여 일괄 처리에서 ACL을 재귀적으로 업데이트하는 예제를 보려면 Update-AzDataLakeGen2AclRecursive 참조 문서를 확인하세요.

ACL 항목 제거

이 섹션에서는 다음 방법을 보여줍니다.

ACL 항목 제거
ACL 항목의 재귀적 제거

ACL 항목 제거

이 예제에서는 기존 ACL에서 항목을 제거합니다.

$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl

foreach ($a in $aclnew)
{
    if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
    {
        $aclnew.Remove($a);
        break;
    }
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew

ACL 항목의 재귀적 제거

하나 이상의 ACL 항목을 재귀적으로 제거할 수 있습니다. ACL 항목을 제거하려면 제거할 ACL 항목에 대해 새 ACL 개체를 만든 다음, ACL 제거 작업에 이 개체를 사용합니다. 기존 ACL을 가져오지 않고 제거할 ACL 항목만 제공합니다.

Remove-AzDataLakeGen2AclRecursive cmdlet을 사용하여 ACL 항목을 제거합니다.

이 예제에서는 컨테이너의 루트 디렉터리에서 ACL 항목을 제거합니다.

$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"

Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName  -Acl $acl

참고 항목

기본 ACL 항목을 제거하려면 Set-AzDataLakeGen2ItemAclObject 명령을 실행할 때 -DefaultScope 매개변수를 사용합니다. 예: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope

일괄 처리 크기를 지정하여 일괄 처리에서 ACL을 재귀적으로 제거하는 예제를 보려면 Remove-AzDataLakeGen2AclRecursive 참조 문서를 확인하세요.

오류에서 복구

ACL을 재귀적으로 수정할 때 런타임 또는 권한 오류가 발생할 수 있습니다.

런타임 오류의 경우 처음부터 프로세스를 다시 시작합니다. 수정되는 디렉터리 계층 구조에 있는 디렉터리 또는 파일의 ACL을 수정할 수 있는 권한이 보안 주체에게 없는 경우에 권한 오류가 발생할 수 있습니다. 권한 문제를 해결한 다음 연속 토큰을 사용하여 오류 지점에서 프로세스를 다시 시작하거나 프로세스를 처음부터 다시 시작하도록 선택합니다. 처음부터 다시 시작하기를 선호하는 경우 연속 토큰을 사용할 필요는 없습니다. 부정적인 영향 없이 ACL 항목을 다시 적용할 수 있습니다.

이 예제에서는 결과를 변수에 반환한 후 실패한 항목을 형식이 지정된 테이블로 파이프합니다.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft

테이블의 출력에 따라 권한 오류를 수정한 후 연속 토큰을 사용하여 실행을 재개할 수 있습니다.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result

일괄 처리 크기를 지정하여 일괄 처리에서 ACL을 재귀적으로 설정하는 예제를 보려면 Set-AzDataLakeGen2AclRecursive 참조 문서를 확인하세요.

권한 오류가 발생해도 프로세스가 중단 없이 완료되도록 하기 위해 이를 지정할 수 있습니다.

이 예제에서는 ContinueOnFailure 매개변수를 사용하여 작업 중 권한 오류가 발생하더라도 실행이 계속되도록 합니다.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalFilesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)

일괄 처리 크기를 지정하여 일괄 처리에서 ACL을 재귀적으로 설정하는 예제를 보려면 Set-AzDataLakeGen2AclRecursive 참조 문서를 확인하세요.

모범 사례

이 섹션에서는 ACL을 재귀적으로 설정하는 몇 가지 모범 사례를 제공합니다.

런타임 오류 처리

런타임 오류는 여러 가지 이유(예: 중단 또는 클라이언트 연결 문제)로 발생할 수 있습니다. 런타임 오류가 발생하는 경우 재귀 ACL 프로세스를 다시 시작하세요. 부정적인 영향 없이 항목에 ACL을 다시 적용할 수 있습니다.

권한 오류 처리(403)

재귀 ACL 프로세스를 실행하는 동안 액세스 제어 예외가 발생하는 경우 디렉터리 계층 구조에 있는 하나 이상의 자식 항목에 ACL을 적용하는 데 충분한 권한이 AD 보안 주체에게 없을 수 있습니다. 권한 오류가 발생하면 프로세스가 중지되고 연속 토큰이 제공됩니다. 권한 문제를 해결한 다음 연속 토큰을 사용하여 나머지 데이터 세트를 처리하세요. 이미 성공적으로 처리된 디렉터리와 파일은 다시 처리하지 않아도 됩니다. 재귀 ACL 프로세스를 다시 시작하도록 선택할 수도 있습니다. 부정적인 영향 없이 항목에 ACL을 다시 적용할 수 있습니다.

자격 증명

대상 스토리지 계정 또는 컨테이너 범위에서 Storage Blob 데이터 소유자 역할이 할당된 Microsoft Entra 보안 주체를 프로비전하는 것이 좋습니다.

성능

대기 시간을 줄이려면 스토리지 계정과 동일한 지역에 있는 Azure VM(가상 머신)에서 재귀 ACL 프로세스를 실행하는 것이 좋습니다.

ACL 한도

디렉터리 또는 파일에 적용할 수 있는 최대 ACL 수는 액세스 ACL 32개 및 기본 ACL 32개입니다. 자세한 내용은 Azure Data Lake Storage Gen2의 액세스 제어를 참조하세요.

참고 항목

알려진 문제
스토리지 PowerShell cmdlet
Azure Data Lake Storage Gen2의 액세스 제어 모델
Azure Data Lake Storage Gen2의 ACL(액세스 제어 목록)

다음을 통해 공유

PowerShell을 사용하여 Azure Data Lake Storage Gen2에서 ACL 관리

필수 구성 요소

PowerShell 모듈 설치

계정에 연결

옵션 1: Microsoft Entra ID를 사용하여 권한 부여 획득

옵션 2: 스토리지 계정 키를 사용하여 권한 부여 획득

ACL 가져오기

ACL 설정

ACL 설정

반복적으로 ACL 설정

ACL 업데이트

ACL 업데이트

재귀적으로 ACL 업데이트

ACL 항목 제거

ACL 항목 제거

ACL 항목의 재귀적 제거

오류에서 복구

모범 사례

런타임 오류 처리

권한 오류 처리(403)

자격 증명

성능

ACL 한도

참고 항목

추가 리소스