소스에 대한 액세스 구성: Cloud Storage

Storage Transfer Service는 서비스 에이전트라고 하는 Google 관리 서비스 계정을 사용하여 Cloud Storage 소스 버킷에서 데이터를 이동합니다. 이 서비스 에이전트는 googleServiceAccounts.get을 처음 호출할 때 생성됩니다.

소스 버킷은 서비스 에이전트와 동일한 프로젝트에 속하지 않아도 됩니다. 단계는 버킷이 포함된 프로젝트에 관계없이 동일합니다.

사용자 권한

서비스 에이전트에 필수 권한을 부여하려면 소스 버킷에 대한 관련 권한이 있어야 합니다.

• storage.buckets.getIamPolicy
• storage.buckets.setIamPolicy

스토리지 기존 버킷 소유자 역할(roles/storage.legacyBucketOwner) 또는 스토리지 관리자 역할(roles/storage.admin)이 필수 권한을 제공합니다.

Google Cloud 콘솔에서 권한 자동 부여

Google Cloud 콘솔을 사용하여 전송을 만들고 사용자 권한에 나열된 권한이 있는 경우 서비스 에이전트는 소스 버킷에 대한 필수 권한을 자동으로 부여받습니다.

이 페이지의 단계를 건너뛰고 전송 만들기로 직접 이동할 수 있습니다.

필수 권한

서비스 에이전트에는 다음과 같은 소스 버킷 권한이 있어야 합니다.

권한	설명
storage.buckets.get	서비스 에이전트가 버킷의 위치를 가져올 수 있게 합니다.
storage.objects.list	서비스 에이전트가 버킷의 객체를 나열할 수 있게 합니다.
storage.objects.get	서비스 에이전트가 버킷의 객체를 읽을 수 있게 합니다.
storage.objects.create	서비스 에이전트가 버킷의 객체를 만들 수 있게 합니다. 파일 시스템으로 전송하는 경우에 필수입니다. Storage Transfer Service는 소스 버킷에서 2개의 폴더를 만들고 채웁니다. cloud-ingest/에는 파일 시스템 정보가 포함되고 storage-transfer/에는 전송 로그가 포함됩니다.
storage.objects.delete	서비스 에이전트가 버킷의 객체를 삭제할 수 있게 합니다. deleteObjectsFromSourceAfterTransfer를 true로 설정한 경우에 필요합니다.

다음 사전 정의된 역할은 함께 필수 권한을 부여합니다.

• 다음 중 하나:
  • 다른 Cloud Storage 버킷으로 전송되는 경우 스토리지 객체 뷰어(roles/storage.objectViewer)
  • 전송이 파일 시스템으로 전송되는 경우 스토리지 객체 생성자(roles/storage.objectCreator)
• 그리고 다음 중 하나가 적용됩니다.
  • 객체 삭제 권한이 필요한 경우 스토리지 기존 버킷 작성자(roles/storage.legacyBucketWriter)
  • 객체 삭제 권한이 필요하지 않은 경우 스토리지 기존 버킷 리더(roles/storage.legacyBucketReader)

legacy 역할로 표시된 모든 Cloud Storage 역할은 버킷 수준에서만 부여될 수 있습니다.

Cloud Storage 역할과 이 역할에 포함된 권한의 전체 목록은 IAM 역할을 참조하세요.

ACL_PRESERVE가 설정된 객체 ACL의 경우 소스 객체에 대해 스토리지 기존 객체 소유자 역할(roles/storage.legacyObjectOwner)이 추가로 필요합니다. ACL_PRESERVE의 경우 스토리지 기존 객체 소유자 역할을 갖도록 서비스 계정을 수동으로 추가하여 소스 객체에 storage.objects.getIamPolicy 권한을 부여하세요.

필수 권한 부여

서비스 에이전트에 필수 권한을 부여하려면 다음 단계를 따르세요.

서비스 에이전트의 이메일 찾기

1. googleServiceAccounts.get 참조 페이지로 이동하세요.

   이 메서드 사용해 보기라는 제목의 대화형 패널이 열립니다.

2. 패널의 요청 매개변수에 프로젝트 ID를 입력합니다. 여기에서 지정하는 프로젝트는 Storage Transfer Service 관리를 위해 사용 중인 프로젝트여야 하고, 이 프로젝트는 소스 버킷의 프로젝트와 다를 수 있습니다.

3. 실행을 클릭합니다.

   서비스 에이전트의 이메일이 accountEmail 값으로 반환됩니다. 이 값을 복사합니다.

   서비스 에이전트의 이메일에는 [e-mail] 형식이 사용됩니다.

버킷 수준 정책에 서비스 에이전트 추가

콘솔

1. Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
   

   버킷으로 이동

2. 주 구성원에 역할을 부여할 버킷과 관련된 버킷 더보기 메뉴()를 클릭합니다.

3. 액세스 수정을 선택합니다.

4. + 주 구성원 추가 버튼을 클릭합니다.

5. 새 주 구성원 필드에 서비스 에이전트의 계정 이메일을 입력합니다.

6. 역할 선택 드롭다운 메뉴에서 Storage Object Viewer 또는 Storage Object Creator를 선택합니다.

7. 다른 역할 추가를 클릭합니다.

8. Storage Legacy Bucket Writer 또는 Storage Legacy Bucket Reader를 선택합니다.

9. 저장을 클릭합니다.

gcloud

gcloud storage buckets add-iam-policy-binding 명령어를 사용합니다.

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.objectViewer

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.legacyBucketReader

각 항목의 의미는 다음과 같습니다.

• BUCKET_NAME은 주 구성원에게 액세스 권한을 부여할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
• YOUR_AGENT_EMAIL은 서비스 에이전트 이메일 찾기에서 복사한 에이전트 계정 이메일입니다.

코드 샘플

C++

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage C++ API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& role, std::string const& member) {
  auto policy = client.GetNativeBucketIamPolicy(
      bucket_name, gcs::RequestedPolicyVersion(3));

  if (!policy) throw std::move(policy).status();

  policy->set_version(3);
  for (auto& binding : policy->bindings()) {
    if (binding.role() != role || binding.has_condition()) {
      continue;
    }
    auto& members = binding.members();
    if (std::find(members.begin(), members.end(), member) == members.end()) {
      members.emplace_back(member);
    }
  }

  auto updated = client.SetNativeBucketIamPolicy(bucket_name, *policy);
  if (!updated) throw std::move(updated).status();

  std::cout << "Updated IAM policy bucket " << bucket_name
            << ". The new policy is " << *updated << "\n";
}

C#

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage C# API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class AddBucketIamMemberSample
{
    public Policy AddBucketIamMember(
        string bucketName = "your-unique-bucket-name",
        string role = "roles/storage.objectViewer",
        string member = "serviceAccount:[e-mail]")
    {
        var storage = StorageClient.Create();
        var policy = storage.GetBucketIamPolicy(bucketName, new GetBucketIamPolicyOptions
        {
            RequestedPolicyVersion = 3
        });
        // Set the policy schema version. For more information, please refer to https://cloud.google.com/iam/docs/policies#versions.
        policy.Version = 3;

        Policy.BindingsData bindingToAdd = new Policy.BindingsData
        {
            Role = role,
            Members = new List<string> { member }
        };

        policy.Bindings.Add(bindingToAdd);
        var bucketIamPolicy = storage.SetBucketIamPolicy(bucketName, policy);
        Console.WriteLine($"Added {member} with role {role} " + $"to {bucketName}");
        return bucketIamPolicy;
    }
}

Go

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage Go API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/iam"
	"cloud.google.com/go/storage"
)

// addBucketIAMMember adds the bucket IAM member to permission role.
func addBucketIAMMember(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	policy, err := bucket.IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("Bucket(%q).IAM().Policy: %w", bucketName, err)
	}
	// Other valid prefixes are "serviceAccount:", "user:"
	// See the documentation for more values.
	// https://cloud.google.com/storage/docs/access-control/iam
	identity := "group:[e-mail]"
	var role iam.RoleName = "roles/storage.objectViewer"

	policy.Add(identity, role)
	if err := bucket.IAM().SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("Bucket(%q).IAM().SetPolicy: %w", bucketName, err)
	}
	// NOTE: It may be necessary to retry this operation if IAM policies are
	// being modified concurrently. SetPolicy will return an error if the policy
	// was modified since it was retrieved.
	fmt.Fprintf(w, "Added %v with role %v to %v\n", identity, role, bucketName)
	return nil
}

Java

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage Java API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

import com.google.cloud.Binding;
import com.google.cloud.Policy;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

public class AddBucketIamMember {
  /** Example of adding a member to the Bucket-level IAM */
  public static void addBucketIamMember(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // For more information please read:
    // https://cloud.google.com/storage/docs/access-control/iam
    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Policy originalPolicy =
        storage.getIamPolicy(bucketName, Storage.BucketSourceOption.requestedPolicyVersion(3));

    String role = "roles/storage.objectViewer";
    String member = "group:[e-mail]";

    // getBindingsList() returns an ImmutableList and copying over to an ArrayList so it's mutable.
    List<Binding> bindings = new ArrayList(originalPolicy.getBindingsList());

    // Create a new binding using role and member
    Binding.Builder newMemberBindingBuilder = Binding.newBuilder();
    newMemberBindingBuilder.setRole(role).setMembers(Arrays.asList(member));
    bindings.add(newMemberBindingBuilder.build());

    // Update policy to add member
    Policy.Builder updatedPolicyBuilder = originalPolicy.toBuilder();
    updatedPolicyBuilder.setBindings(bindings).setVersion(3);
    Policy updatedPolicy = storage.setIamPolicy(bucketName, updatedPolicyBuilder.build());

    System.out.printf("Added %s with role %s to %s\n", member, role, bucketName);
  }
}

Node.js

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage Node.js API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The role to grant
// const roleName = 'roles/storage.objectViewer';

// The members to grant the new role to
// const members = [
//   'user:[e-mail]',
//   'group:[e-mail]',
// ];

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addBucketIamMember() {
  // Get a reference to a Google Cloud Storage bucket
  const bucket = storage.bucket(bucketName);

  // For more information please read:
  // https://cloud.google.com/storage/docs/access-control/iam
  const [policy] = await bucket.iam.getPolicy({requestedPolicyVersion: 3});

  // Adds the new roles to the bucket's IAM policy
  policy.bindings.push({
    role: roleName,
    members: members,
  });

  // Updates the bucket's IAM policy
  await bucket.iam.setPolicy(policy);

  console.log(
    `Added the following member(s) with role ${roleName} to ${bucketName}:`
  );

  members.forEach(member => {
    console.log(`  ${member}`);
  });
}

addBucketIamMember().catch(console.error);

PHP

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage PHP API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

use Google\Cloud\Storage\StorageClient;

/**
 * Adds a new member / role IAM pair to a given Cloud Storage bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $role The role to which the given member should be added.
 *        (e.g. 'roles/storage.objectViewer')
 * @param string[] $members The member(s) to be added to the role.
 *        (e.g. ['group:[e-mail]'])
 */
function add_bucket_iam_member(string $bucketName, string $role, array $members): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $policy = $bucket->iam()->policy(['requestedPolicyVersion' => 3]);
    $policy['version'] = 3;

    $policy['bindings'][] = [
        'role' => $role,
        'members' => $members
    ];

    $bucket->iam()->setPolicy($policy);

    printf('Added the following member(s) to role %s for bucket %s' . PHP_EOL, $role, $bucketName);
    foreach ($members as $member) {
        printf('    %s' . PHP_EOL, $member);
    }
}

Python

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage Python API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

from google.cloud import storage


def add_bucket_iam_member(bucket_name, role, member):
    """Add a new member to an IAM Policy"""
    # bucket_name = "your-bucket-name"
    # role = "IAM role, e.g., roles/storage.objectViewer"
    # member = "IAM identity, e.g., user: [e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    policy = bucket.get_iam_policy(requested_policy_version=3)

    policy.bindings.append({"role": role, "members": {member}})

    bucket.set_iam_policy(policy)

    print(f"Added {member} with role {role} to {bucket_name}.")

Ruby

Cloud Storage용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Cloud Storage 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Cloud Storage Ruby API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

def add_bucket_iam_member bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  role   = "roles/storage.objectViewer"
  member = "group:[e-mail]"

  bucket.policy requested_policy_version: 3 do |policy|
    policy.bindings.insert role: role, members: [member]
  end

  puts "Added #{member} with role #{role} to #{bucket_name}"
end

JSON

참고: 이 메서드는 버킷에 설정된 기존 IAM 정책을 대체합니다. 기존 정책을 수정하려면 getIamPolicy 메서드를 사용하여 검색하고, 필요에 따라 수정하고, setIamPolicy 요청에서 수정된 버전을 사용합니다.

1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

2. 다음 정보를 포함하는 JSON 파일을 만듭니다.

   {
   "bindings":[
     {
       "role": "roles/storage.objectViewer",
       "members":[
         "YOUR_AGENT_EMAIL"
       ]
     },
     {
       "role": "roles/storage.legacyBucketReader",
       "members":[
         "YOUR_AGENT_EMAIL"
       ]
     }
   ]
   }

   각 항목의 의미는 다음과 같습니다.

   • YOUR_AGENT_EMAIL은 서비스 에이전트 이메일 찾기에서 복사한 에이전트 계정 이메일입니다.

3. cURL을 사용하여 PUT setIamPolicy 요청으로 JSON API를 호출합니다.

   curl -X PUT --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   -H "Content-Type: application/json" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"

   각 항목의 의미는 다음과 같습니다.

   • JSON_FILE_NAME은 2단계에서 만든 파일의 경로입니다.
   • OAUTH2_TOKEN은 1단계에서 생성한 액세스 토큰입니다.
   • BUCKET_NAME은 주 구성원에게 액세스 권한을 부여할 버킷의 이름입니다. 예를 들면 my-bucket입니다.