Criar uma VM que use uma conta de serviço gerenciada pelo usuário

Neste documento, explicamos como criar uma instância de máquina virtual (VM) configurada para usar uma conta de serviço gerenciada pelo usuário. Uma conta de serviço é um tipo especial de conta normalmente usada por um aplicativo ou uma carga de trabalho de computação para fazer chamadas de API autorizadas.

As contas de serviço são necessárias nos cenários em que uma carga de trabalho, como um aplicativo personalizado, precisa acessar os recursos do Google Cloud ou executar ações sem o envolvimento do usuário final. Para mais informações sobre quando usar contas de serviço, consulte Práticas recomendadas para usar contas de serviço.

Se você tiver aplicativos que precisam fazer chamadas para as APIs do Google Cloud, o Google recomenda anexar uma conta de serviço gerenciada pelo usuário à VM em que o aplicativo ou a carga de trabalho está sendo executado. Em seguida, você concede à conta de serviço papéis do IAM, o que dá à conta de serviço e, por extensão, aos aplicativos em execução na VM, acesso aos recursos do Google Cloud.

Antes de começar

  • Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine da seguinte maneira.

    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. Terraform

      Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a gcloud CLI e, em seguida, configure o Application Default Credentials com suas credenciais de usuário.

      1. Install the Google Cloud CLI.

      2. To initialize the gcloud CLI, run the following command: 

        gcloud init

      3. If you're using a local shell, then create local authentication credentials for your user account: 

        gcloud auth application-default login

        You don't need to do this if you're using Cloud Shell.

      Confira mais informações em Set up authentication for a local development environment.

      REST

      Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

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

        gcloud init

      Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Funções exigidas

Para receber as permissões necessárias para criar VMs que usam contas de serviço, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos contêm as permissões necessárias para criar VMs que usam contas de serviço. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar VMs que usam contas de serviço:

  • Para criar contas de serviço: todas as permissões no papel serviceAccountCreator
  • Para criar VMs:
    • compute.instances.create no projeto
    • Para usar uma imagem personalizada para criar a VM: compute.images.useReadOnly na imagem
    • Usar um snapshot para criar a VM: compute.snapshots.useReadOnly no snapshot
    • Usar um modelo de instância para criar a VM: compute.instanceTemplates.useReadOnly no modelo de instância
    • Atribuir uma rede legada à VM: compute.networks.use no projeto
    • Especificar um endereço IP estático para a VM: compute.addresses.use no projeto
    • Atribuir um endereço IP externo à VM ao usar uma rede legada: compute.networks.useExternalIp no projeto
    • Especificar uma sub-rede para a VM: compute.subnetworks.use no projeto ou na sub-rede escolhida
    • Atribuir um endereço IP externo à VM ao usar uma rede VPC: compute.subnetworks.useExternalIp no projeto ou na sub-rede escolhida
    • Definir os metadados da instância de VM para a VM: compute.instances.setMetadata no projeto
    • Definir tags para a VM: compute.instances.setTags na VM
    • Definir rótulos para a VM: compute.instances.setLabels na VM
    • Definir uma conta de serviço para a VM usar: compute.instances.setServiceAccount na VM
    • Criar um disco para a VM: compute.disks.create no projeto
    • Anexar um disco atual no modo somente leitura ou de leitura e gravação: compute.disks.use no disco
    • Anexar um disco atual no modo somente leitura: compute.disks.useReadOnly no disco

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Informações gerais

É recomendável configurar contas de serviço para suas VMs da seguinte maneira:

  1. Crie uma nova conta de serviço gerenciada pelo usuário em vez de usar a conta de serviço padrão do Compute Engine e conceda papéis do IAM a essa conta de serviço apenas para os recursos e operações de que ela precisa.
  2. Anexe a conta de serviço à VM.
  3. Defina o escopo do Cloud Platform (https://www.googleapis.com/auth/cloud-platform) na sua VM. Isso permite que a conta de serviço da VM chame as APIs do Google Cloud que tem permissão para usar.
    • Se você especificar a conta de serviço usando o console do Google Cloud, o escopo de acesso da VM será definido automaticamente como cloud-platform.
    • Se você especificar a conta de serviço usando a Google Cloud CLI ou a API Compute Engine, poderá usar o parâmetro scopes para definir o escopo de acesso.

Configurar uma conta de serviço

Crie uma conta de serviço e atribua os papéis do IAM necessários. Atribua quantos papéis do IAM forem necessários. É possível modificar os papéis do IAM na sua conta de serviço conforme necessário.

O Google recomenda limitar os privilégios das contas de serviço e verificar regularmente as permissões delas para garantir que estejam atualizadas.

Use um dos métodos a seguir para configurar a conta de serviço.

Console

    In the Google Cloud console, go to the Create service account page.

    Go to Create service account
  1. Select your project.

  2. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

    In the Service account description field, enter a description. For example, Service account for quickstart.

  3. Click Create and continue.

  4. Grant the required roles to the service account.

    To grant a role, find the Select a role list, then select the role.

    To grant additional roles, click Add another role and add each additional role.

  5. Click Continue.

  6. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

    This is typically the email address for a Google Account.

  7. Click Done to finish creating the service account.

gcloud

    Set up authentication:

    1. Create the service account: 

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

    2. To provide access to your project and your resources, grant a role to the service account: 

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
    3. To grant another role to the service account, run the command as you did in the previous step.

    4. Grant the required role to the principal that will attach the service account to other resources. 

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account

Terraform

Para criar uma conta de serviço, use o recurso google_service_account.

compute/service_account_for_instances/main.tf 
resource "google_service_account" "default" {
  account_id   = "service-account-id"
  display_name = "Service Account"
}

Lembre-se de substituir os valores do marcador de posição para account_id e os atributos display_name.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Criar uma VM e anexar a conta de serviço

Depois de criar a conta de serviço, crie uma VM e anexe a conta de serviço criada na seção anterior. Defina também o escopo de acesso da VM como cloud-platform.

Se você já tem uma VM e quer configurá-la para usar uma conta de serviço diferente, consulte Alterar a conta de serviço anexada.

Use um dos métodos a seguir para criar uma VM e anexar a conta de serviço.

Console

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

Acessar instâncias de VM

  1. Selecione o projeto e clique em Continuar.
  2. Clique em Criar instância.
  3. Especifique um Nome para sua VM.
  4. Role até a seção Identidade e acesso à API.
  5. Na lista Conta de serviço, selecione a conta de serviço que você criou. Ao anexar uma conta de serviço a uma VM, o escopo de acesso cloud-platform do Google Cloud é definido automaticamente na VM.
  6. Faça outras personalizações de VM conforme necessário.
  7. Para criar e iniciar a VM, clique em Criar.

gcloud

Para criar uma nova instância de VM e configurá-la para usar uma conta de serviço personalizada com a Google Cloud CLI, use o comando gcloud compute instances create e forneça a conta de serviço e o escopo de acesso cloud-platform à instância da VM.

gcloud compute instances create VM_NAME \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Substitua:

  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço que você criou. Por exemplo, my-sa-123@my-project-123.iam.gserviceaccount.com. Para ver o endereço de e-mail, consulte Como listar contas de serviço.
  • VM_NAME: o nome da instância de VM.

Exemplo:

gcloud compute instances create example-vm \
    --service-account 123-my-sa@my-project-123.iam.gserviceaccount.com \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Também é possível especificar o escopo usando o alias: --scopes=cloud-platform. Esses aliases são reconhecidos apenas pela CLI gcloud. A API e outras bibliotecas não os reconhecem. Portanto, é necessário especificar o URI de escopo completo.

Terraform

Para configurar uma nova VM para usar uma conta de serviço, use o recurso google_compute_instance.

compute/service_account_for_instances/main.tf 
resource "google_compute_instance" "default" {
  name         = "my-test-vm"
  machine_type = "n1-standard-1"
  zone         = "us-central1-a"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }

  // Local SSD disk
  scratch_disk {
    interface = "SCSI"
  }

  network_interface {
    network = "default"

    access_config {
      // Ephemeral public IP
    }
  }

  service_account {
    # Google recommends custom service accounts with `cloud-platform` scope with
    # specific permissions granted via IAM Roles.
    # This approach lets you avoid embedding secret keys or user credentials
    # in your instance, image, or app code
    email  = google_service_account.default.email
    scopes = ["cloud-platform"]
  }
}

REST

Use o método instances.insert para criar a VM e especificar o e-mail da conta de serviço e o escopo de acesso para a instância de VM.

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

{
   "machineType":"zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
   "name":"VM_NAME",

   "disks":[
      {
         "initializeParams":{
            "sourceImage":"projects/IMAGE_PROJECT/global/images/IMAGE"
         },
         "boot":true
      }
   ],

   "networkInterfaces":[
      {
         "network":"global/networks/NETWORK_NAME"
      }
   ],

  "serviceAccounts": [
      {
      "email": "SERVICE_ACCOUNT_EMAIL",
      "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
      }
   ],
   "shieldedInstanceConfig":{
      "enableSecureBoot":"ENABLE_SECURE_BOOT"
   }
}

Substitua:

  • PROJECT_ID: ID do projeto em que a VM será criada
  • ZONE: zona em que a VM será criada
  • MACHINE_TYPE_ZONE: a zona que contém o tipo de máquina que será usado para a nova VM.
  • MACHINE_TYPE: tipo de máquina, predefinida ou personalizada, para a nova VM.
  • VM_NAME: nome da nova VM.
  • IMAGE_PROJECT: o projeto que contém a imagem
    Por exemplo, se você especificar debian-10 como a família de imagens, especifique debian-cloud como projeto de imagem.
  • IMAGE or IMAGE_FAMILY: Especifique uma destas opções:
    • IMAGE: uma versão específica de uma imagem pública.
      Por exemplo, "sourceImage": "projects/debian-cloud/global/images/debian-10-buster-v20200309"
    • IMAGE_FAMILY: uma família de imagens
      Isso cria a VM a partir da imagem do SO mais recente e não descontinuada. Por exemplo, se você especificar "sourceImage": "projects/debian-cloud/global/images/family/debian-10", o Compute Engine criará uma VM usando a versão mais recente da imagem do SO na família de imagens Debian 10.
  • NETWORK_NAME: a rede VPC que você quer usar para a VM. Você pode especificar default para usar sua rede padrão.
  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço que você criou. Por exemplo, my-sa-123@my-project-123.iam.gserviceaccount.com. Para isso, consulte Receber um e-mail de conta de serviço.

  • ENABLE_SECURE_BOOT: opcional: se você escolher uma imagem compatível com recursos da VM protegida, o Compute Engine ativa, por padrão, o módulo de plataforma virtual confiável (vTPM) e o monitoramento de integridade. Por padrão, o Compute Engine não ativa a Inicialização segura.

    true Se você especificar enableSecureBoot para , o Compute Engine criará uma VM com todos os três recursos da VM protegida já ativados. Depois que o Compute Engine iniciar a VM, será preciso interrompê-la se você quiser modificar as opções de VM protegida.

Acessar e usar outros serviços do Google Cloud

Depois que a VM for configurada para usar a conta de serviço, os aplicativos poderão usá-la para autenticação. O método mais comum é a autenticação usando o Application Default Credentials e uma biblioteca de cliente. Algumas ferramentas do Google Cloud, como a CLI gcloud e gsutil, podem usar automaticamente a conta de serviço para acessar as APIs do Google Cloud em uma VM. Para mais informações, consulte Autenticar cargas de trabalho usando contas de serviço.

Se uma conta de serviço for excluída, os aplicativos não terão mais acesso aos recursos do Google Cloud por meio dela. Se você excluir as contas de serviço padrão do App Engine e do Compute Engine, as instâncias não terão mais acesso aos recursos no projeto. Caso não tenha certeza se uma conta de serviço está sendo utilizada, recomendamos que você desative a conta de serviço antes de excluí-la. As contas de serviço desativadas poderão ser reativadas se ainda forem necessárias.

Exemplo: acessar os recursos do Cloud Storage pela VM

Depois de configurar a VM para usar uma conta de serviço que tenha o papel storage.admin, use ferramentas como a CLI gcloud e gsutil para gerenciar os arquivos armazenados no Cloud Storage. Para acessar os recursos do Cloud Storage, faça o seguinte:

  1. Verifique se a conta de serviço anexada à sua VM tem o papel roles/storage.admin.

  2. Se a VM usar uma imagem de SO personalizada, instale a CLI gcloud. Por padrão, a CLI gcloud é instalada na maioria das imagens de SO públicas fornecidas pelo Google Cloud.

  3. Conecte-se à VM.

  4. Na VM, use uma das seguintes ferramentas para gerenciar os recursos do Cloud Storage.

A seguir