Cambiar la cuenta de servicio conectada

En este documento, se explica cómo configurar una máquina virtual (VM) existente para usar una cuenta de servicio diferente. Una cuenta de servicio es un tipo especial de cuenta que, por lo general, es usada por una carga de trabajo de aplicación o procesamiento para realizar llamadas autorizadas a la API.

Las cuentas de servicio son necesarias para situaciones en las que una carga de trabajo, como una aplicación personalizada, necesita acceder a los recursos de Google Cloud o realizar acciones sin la participación del usuario final. Si deseas obtener más información sobre cuándo usar las cuentas de servicio, consulta Prácticas recomendadas para usar cuentas de servicio.

Si tienes aplicaciones que necesitan realizar llamadas a las APIs de Google Cloud, Google recomienda que conectes una cuenta de servicio administrada por el usuario a la VM en la que se ejecuta la aplicación o la carga de trabajo. Luego, otorgas los roles de IAM de la cuenta de servicio, que otorga a la cuenta de servicio (y, por extensión, a las aplicaciones que se ejecutan en la VM) acceso a los recursos de Google Cloud.

Antes de comenzar

  • Configura la autenticación si aún no lo hiciste. La autenticación es el proceso mediante el cual se verifica tu identidad para acceder a los servicios y las API de Google Cloud. Para ejecutar un código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine de la siguiente manera.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      Para usar las muestras de la API de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a la CLI de gcloud.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Si deseas obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud.

Funciones obligatorias

Si quieres obtener los permisos que necesitas para configurar cuentas de servicio en tu VM, pídele a tu administrador que te otorgue el rol de IAM Administrador de instancias de Compute (v1) (roles/compute.instanceAdmin.v1) en la VM o en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Este rol predefinido contiene los permisos necesarios para configurar cuentas de servicio en tu VM. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para configurar cuentas de servicio en tu VM:

  • compute.instances.setServiceAccount
  • compute.instances.stop
  • compute.instances.start

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Descripción general

Se recomienda que configures las cuentas de servicio para las VMs de la siguiente manera:

  1. Crea una cuenta de servicio nueva administrada por el usuario en lugar de usar la cuenta de servicio predeterminada de Compute Engine y otórgale roles de IAM solo a los recursos y las operaciones que necesita.
  2. Conecta la cuenta de servicio a tu VM.
  3. Configura el permiso de la plataforma en la nube (https://www.googleapis.com/auth/cloud-platform) en tu VM. Esto permite que la cuenta de servicio de la VM llame a las APIs de Google Cloud que tiene permiso para usar.
    • Si especificas la cuenta de servicio con la consola de Google Cloud, el permiso de acceso de la VM se establece automáticamente en el permiso cloud-platform.
    • Si especificas la cuenta de servicio con Google Cloud CLI o la API de Compute Engine, puedes usar el parámetro scopes para configurar el permiso de acceso.

Configura la cuenta de servicio

Puedes crear una cuenta de servicio administrada por el usuario o usar la cuenta de servicio predeterminada de Compute Engine. Se recomienda una cuenta de servicio administrada por el usuario.

Para la cuenta de servicio seleccionada, asegúrate de que estén asignados los roles de Identity and Access Management (IAM) necesarios.

Administrada por el usuario

Si aún no tienes una cuenta de servicio administrada por el usuario, primero crea una cuenta de servicio. Para obtener instrucciones detalladas, consulta Configura una cuenta de servicio.

Predeterminada

Si estás familiarizado con la cuenta de servicio predeterminada de Compute Engine y deseas usar las credenciales proporcionadas por la cuenta de servicio predeterminada en lugar de crear cuentas de servicio nuevas, puedes otorgar roles de IAM a la cuenta de servicio predeterminada.

Antes de asignar roles de IAM a la cuenta de servicio predeterminada, ten en cuenta la siguiente información:

  • Otorgar un rol de IAM a la cuenta de servicio predeterminada afecta a todas las VMs que se ejecutan como la cuenta de servicio predeterminada. Por ejemplo, si le otorgas a la cuenta de servicio predeterminada el rol roles/storage.objectAdmin, todas las VMs que se ejecutan como la cuenta de servicio predeterminada con los permisos de acceso requeridos tendrán los permisos que les otorga el rol roles/storage.objectAdmin. Del mismo modo, si limitas el acceso por omisión de ciertos roles, esto afectará a todas las VMs que se ejecutan como la cuenta de servicio predeterminada.

  • Según la configuración de la política de la organización, es posible que a la cuenta de servicio predeterminada se le otorgue automáticamente el rol de editor en tu proyecto. Te recomendamos inhabilitar la concesión automática de roles; para ello, aplica la restricción de la política de la organización iam.automaticIamGrantsForDefaultServiceAccounts. Si creaste tu organización después del 3 de mayo de 2024, esta restricción se aplica de forma predeterminada.

    Si inhabilitas la concesión automática de roles, debes decidir qué roles se deben otorgar a las cuentas de servicio predeterminadas y, luego, otorgar estos roles a ti mismo.

    Si la cuenta de servicio predeterminada ya tiene el rol de editor, te recomendamos que reemplaces el rol de editor por roles menos permisivos. Para modificar de forma segura los roles de la cuenta de servicio, usa Policy Simulator para ver el impacto del cambio y, luego, otorga y revoca los roles adecuados.

Si no estás seguro de otorgar roles de IAM a la cuenta de servicio predeterminada, crea una nueva cuenta de servicio administrada por el usuario.

Conecta la cuenta de servicio y actualiza el permiso de acceso

Para cambiar la cuenta de servicio de una VM y los permisos de acceso, la VM debe detenerse temporalmente.

Si la cuenta de servicio está en un proyecto diferente al de la VM, debes configurar la cuenta de servicio para un recurso en un proyecto diferente.

Usa uno de los siguientes métodos para cambiar la cuenta de servicio y los permisos de acceso en tu VM.

Console

  1. Ve a la página Instancias de VM.

    Ir a Instancias de VM

  2. Haz clic en el nombre de la instancia de VM para la que deseas cambiar la cuenta de servicio.

  3. Si la VM no se detiene, haz clic en Detener. Espera a que la VM se detenga.

  4. Haz clic en Editar.

  5. Desplázate hacia abajo hasta la sección Cuenta de servicio.

  6. En la lista desplegable, selecciona la cuenta de servicio que se asignará a la VM.

    • Si eliges una cuenta de servicio administrada por el usuario, el permiso de acceso de la VM se establecerá de forma predeterminada en el permiso cloud-platform recomendado. Si necesitas un permiso diferente para la cuenta de servicio administrada por el usuario, usa gcloud CLI o la API de Compute Engine para conectar la cuenta de servicio.
    • Si eliges la cuenta de servicio predeterminada de Compute Engine, puedes modificar sus permisos de acceso en la consola de Google Cloud.
      • Para cambiar los permisos, en la sección Permiso de acceso, selecciona Configurar acceso para cada API y configura los permisos adecuados según tus necesidades.
      • Recomendado Si no sabes con certeza qué permisos de acceso configurar, elige Permitir acceso completo a todas las APIs de Cloud y, luego, asegúrate de restringir el acceso configurando los roles de IAM en la cuenta de servicio.

  7. Haz clic en Guardar para guardar los cambios.

  8. Haz clic en Iniciar/Reanudar para reiniciar la VM.

gcloud

  1. Detén la VM con el comando instances stop. Reemplaza VM_NAME por el nombre de la instancia de VM.

    gcloud compute instances stop VM_NAME

  2. Conecta la cuenta de servicio. Para conectar la cuenta de servicio, usa el comando instances set-service-account y proporciona el nombre de la VM, el correo electrónico de la cuenta de servicio y los permisos deseados. Para obtener más información sobre la configuración de los permisos de acceso, consulta Prácticas recomendadas.

    gcloud compute instances set-service-account VM_NAME \
  --service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes=SCOPES

    Reemplaza lo siguiente:

    • SERVICE_ACCOUNT_EMAIL: la dirección de correo electrónico de la cuenta de servicio que creaste. Por ejemplo: my-sa-123@my-project-123.iam.gserviceaccount.com. Para ver la dirección de correo electrónico, consulta Enumera cuentas de servicio.

      Si deseas quitar la cuenta de servicio de la VM, usa la marca --no-service-account.

    • VM_NAME: El nombre de la instancia de VM

    • SCOPES: una lista separada por comas de alias o URIs de permiso proporcionados en la descripción de la marca --scopes.

      Si quieres quitar todos los permisos de la VM, usa la marca --no-scopes en su lugar.

    Por ejemplo, el siguiente comando permite asignar la cuenta de servicio my-sa-123@my-project-123.iam.gserviceaccount.com a una VM llamada example‑instance y establecer permisos de acceso en ella para permitir el acceso de lectura/escritura a Compute Engine y el acceso de solo lectura a Cloud Storage:

    gcloud compute instances set-service-account example-instance \
  --service-account=my-sa-123@my-project-123.iam.gserviceaccount.com \
  --scopes=compute-rw,storage-ro

  3. Inicia la VM con el comando instances start. Reemplaza VM_NAME por el nombre de la instancia de VM.

    gcloud compute instances start VM_NAME

REST

  1. Detén la VM realizando una solicitud POST con el método instances.stop:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop

    Reemplaza lo siguiente:

    • PROJECT_ID: El proyecto en el que se encuentra tu VM.
    • ZONE: La zona en la que se encuentra la VM.
    • VM_NAME: El nombre de la VM que deseas detener.

  2. Conecta la cuenta de servicio realizando una solicitud POST al método setServiceAccount:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount

{
  "email": "SERVICE_ACCOUNT_EMAIL",
  "scopes": [
    "SCOPE_URI",
    "SCOPE_URI",
    ...
  ]
}

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de esta solicitud.
    • ZONE: la zona a la que pertenece la VM.
    • VM_NAME: el nombre de la VM.
    • SERVICE_ACCOUNT_EMAIL: la dirección de correo electrónico de la cuenta de servicio que creaste. Por ejemplo: my-sa-123@my-project-123.iam.gserviceaccount.com. Para ver la dirección de correo electrónico, consulta Enumera cuentas de servicio.
    • SCOPE_URI: el URI de permiso necesario.

    Por ejemplo, la siguiente solicitud utiliza el correo electrónico de la cuenta de servicio my-sa-123@my-project-123.iam.gserviceaccount.com y establece un alcance de Cloud Storage y BigQuery:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount

{
  "email": "my-sa-123@my-project-123.iam.gserviceaccount.com",
  "scopes": [
    "https://www.googleapis.com/auth/bigquery",
    "https://www.googleapis.com/auth/devstorage.read_only"
  ]
}

  3. Para iniciar la VM, crea una solicitud POST con el método instances.start:

    POST https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start

    Reemplaza lo siguiente:

    • PROJECT_ID: El proyecto en el que se encuentra tu VM.
    • ZONE: La zona en la que se encuentra la VM.
    • VM_NAME: El nombre de la VM que deseas iniciar.

Visualiza la cuenta de servicio que usa una VM

Para ver todas las cuentas de servicio en un proyecto, consulta Enumera cuentas de servicio.

Si necesitas identificar la cuenta de servicio que usa una VM, completa uno de los siguientes procedimientos:

Console

  1. Ve a la página Instancias de VM.

    Ir a Instancias de VM

  2. Haz clic en el nombre de la instancia de VM para la que deseas cambiar la cuenta de servicio.

  3. Ve a la sección Administración de identidades y API. En esta sección, se muestra la cuenta de servicio y el permiso de acceso que usa la VM.

gcloud

Ejecuta el comando gcloud compute instances describe:

gcloud compute instances describe VM_NAME \
    --format json

El resultado es similar a este:

{
  ...
  "serviceAccounts":[
      {
        "email":"123845678986-compute@developer.gserviceaccount.com",
        "scopes":[
            "https://www.googleapis.com/auth/devstorage.full_control"
        ]
      }
  ]
  ...
   }

Si la VM no usa una cuenta de servicio, recibirás una respuesta sin la propiedad serviceAccounts.

Servidor de metadatos

Consulta el servidor de metadatos desde la propia VM. Haz una solicitud a http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" \
-H "Metadata-Flavor: Google"

Si habilitaste una o más cuentas de servicio cuando creaste la instancia, este comando curl mostrará un resultado similar al siguiente:

123845678986-compute@developer.gserviceaccount.com/
default/

Si la instancia no usa una cuenta de servicio, recibirás una respuesta vacía.

Prácticas recomendadas

Próximos pasos