Configurar el acceso a un receptor: Cloud Storage

Cloud Storage usa una cuenta de servicio gestionada por Google, conocida como agente de servicio, para mover datos a un segmento de Cloud Storage. Este agente de servicio se crea la primera vez que llamas al googleServiceAccounts.get.

El segmento de destino no tiene por qué pertenecer al mismo proyecto que el agente de servicio. Los pasos son los mismos independientemente del proyecto en el que se encuentre el segmento.

Permisos de usuario

Para conceder los permisos necesarios al agente de servicio, debe tener los permisos correspondientes en el segmento de destino:

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

El rol Propietario de segmentos heredados de Storage (roles/storage.legacyBucketOwner) o el rol Administrador de Storage (roles/storage.admin) proporcionan los permisos necesarios.

Conceder permisos automáticamente en la consola Google Cloud

Si usas la Google Cloud consola para crear la transferencia y tienes los permisos que se indican en Permisos de usuario, se concederán automáticamente al agente de servicio los permisos necesarios en tu segmento de destino.

Puedes saltarte los pasos de esta página. Si es necesario, configura el acceso a tu fuente y, a continuación, crea una transferencia.

Permisos obligatorios

El agente de servicio debe tener los siguientes permisos en el cubo de destino:

Permiso Descripción
storage.buckets.get Permite que la cuenta de servicio obtenga la ubicación del segmento.
storage.objects.get Permite que la cuenta de servicio vea los objetos y sus metadatos, pero no las ACLs. Obligatorio si la transferencia está configurada para [sobrescribir objetos](/storage-transfer/docs/reference/rest/v1/TransferOptions#OverwriteWhen) en el receptor cuando sean diferentes o nunca. No es necesario si la opción de transferencia es Sobrescribir siempre.
storage.objects.create Permite que la cuenta de servicio añada objetos al segmento.
storage.objects.delete

Permite que la cuenta de servicio elimine objetos del segmento. Obligatorio si asignas el valor true a overwriteObjectsAlreadyExistingInSink o deleteObjectsUniqueInSink.

Tenga en cuenta que, si el segmento de destino tiene habilitada la gestión de versiones de objetos, ni overwriteObjectsAlreadyExistingInSink ni deleteObjectsUniqueInSink eliminarán ningún objeto de forma permanente. En su lugar, las versiones de los objetos activos pertinentes dejan de ser actuales.

storage.objects.list Permite a la cuenta de servicio enumerar los objetos del segmento. Obligatorio si asignas el valor false a overwriteObjectsAlreadyExistingInSink o el valor true a deleteObjectsUniqueInSink.

El siguiente rol predefinido concede los permisos necesarios:

  • Editor de segmentos heredados de Storage (roles/storage.legacyBucketWriter)

Además, en las transferencias configuradas para sobrescribir objetos en el receptor cuando sean diferentes o nunca, asigna el siguiente rol predefinido al agente de servicio:

  • Lector de objetos de Storage (roles/storage.objectViewer)

Para ver una lista completa de los roles de Cloud Storage y los permisos que contienen, consulta Roles de gestión de identidades y accesos.

Concede los permisos necesarios

Para conceder los roles Escritor de segmentos heredados de Storage y Visor de objetos de Storage al agente de servicio, sigue estos pasos.

Buscar el correo del agente de servicio

  1. Ve a la página de referencia de googleServiceAccounts.get.

    Se abrirá un panel interactivo titulado Prueba este método.

  2. En el panel, en Parámetros de solicitud, introduce tu ID de proyecto. El proyecto que especifiques aquí debe ser el que utilices para gestionar el Servicio de transferencia de almacenamiento, que puede ser diferente del proyecto del segmento de destino.

  3. Haz clic en la opción para ejecutar.

    La dirección de correo de tu agente de asistencia se devuelve como el valor de accountEmail. Copia este valor.

    El correo del agente de servicio utiliza el formato project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Añade el agente de servicio a una política a nivel de contenedor

Consola

  1. En la Google Cloud consola, ve a la página Segmentos de Cloud Storage.

    Ir a Contenedores

  2. Haz clic en el menú Desbordamiento de contenedor () asociado al contenedor al que quieras asignar un rol a un principal.

  3. Selecciona Editar acceso.

  4. Haz clic en el botón + Añadir principal.

  5. En el campo Nuevos principales, introduce la dirección de correo de la cuenta de tu agente de servicio.

  6. Selecciona Storage Legacy Bucket Writer en el menú desplegable Seleccionar un rol.

  7. Haz clic en Guardar.

  8. Repite este paso para añadir el rol Storage Object Viewer si tu transferencia está configurada para sobrescribir objetos en el receptor cuando sean diferentes o nunca.

gcloud

Usa el comando 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.legacyBucketWriter

Donde:

  • BUCKET_NAME es el nombre del segmento al que le vas a dar acceso al principal. Por ejemplo, my-bucket.
  • YOUR_AGENT_EMAIL es la dirección de correo de la cuenta de agente que has copiado en Buscar el correo del agente de servicio.

Para conceder el rol Storage Object Viewer, usa el mismo comando, pero sustituye roles/storage.legacyBucketWriter por roles/storage.objectViewer:

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

Códigos de ejemplo

C++

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API C++ de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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#

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


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:dev@iam.gserviceaccount.com")
    {
        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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API Go de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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:cloud-logs@google.com"
	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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API Java de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


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:example@google.com";

    // 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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API Node.js de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

/**
 * 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:jdoe@example.com',
//   'group:admins@example.com',
// ];

// 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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API PHP de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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:example@google.com'])
 */
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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API Python de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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: name@example.com"

    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

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Storage, consulta las bibliotecas de cliente de Cloud Storage. Para obtener más información, consulta la documentación de referencia de la API Ruby de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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:example@google.com"

  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

  1. Tener instalada e inicializadala CLI de gcloud, que te permite generar un token de acceso para el encabezado Authorization.

  2. Crea un archivo JSON que contenga la siguiente información:

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

    Donde:

  3. Usa cURL para llamar a la API JSON con una solicitud PUT setIamPolicy:

    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"

    Donde:

    • JSON_FILE_NAME es la ruta del archivo que has creado en el paso 2.
    • OAUTH2_TOKEN es el token de acceso que has generado en el paso 1.
    • BUCKET_NAME es el nombre del segmento al que quieres dar acceso al principal. Por ejemplo, my-bucket.

Para obtener más información sobre cómo asignar roles de gestión de identidades y accesos a recursos de Cloud Storage, consulta la documentación de gestión de identidades y accesos de Cloud Storage.