Alterar a conta de serviço anexada

Neste documento, explicamos como configurar uma máquina virtual (VM) atual para usar uma conta de serviço diferente. Uma conta de serviço é um tipo especial de conta normalmente usado 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. 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 configurar contas de serviço na VM, peça ao administrador para conceder a você o papel Administrador da instância do Compute (v1) (roles/compute.instanceAdmin.v1) Papel do IAM na VM ou no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para configurar contas de serviço na sua VM. 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 configurar contas de serviço na sua VM:

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

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 a conta de serviço

É possível criar uma conta de serviço gerenciada pelo usuário ou usar a conta de serviço padrão do Compute Engine. É recomendável usar uma conta de serviço gerenciada pelo usuário.

Verifique se os papéis necessários do Identity and Access Management (IAM) foram atribuídos à conta de serviço selecionada.

Gerenciado pelo usuário

Se você ainda não tiver uma conta de serviço gerenciada pelo usuário, primeiro crie uma conta de serviço. Para instruções detalhadas, consulte Configurar uma conta de serviço.

Padrão

Se você está familiarizado com a conta de serviço padrão do Compute Engine e quer usar as credenciais fornecidas por ela, em vez de criar novas contas de serviço, poderá conceder funções do IAM para a conta de serviço padrão.

Antes de atribuir funções do IAM à conta de serviço padrão, observe que:

  • Conceder um papel do IAM à conta de serviço padrão afeta todas as instâncias que estão sendo executadas como a conta de serviço padrão. Por exemplo, se você conceder o papel roles/storage.objectAdmin à conta de serviço padrão, todas as instâncias em execução como a conta de serviço padrão com os escopos de acesso necessários terão as permissões concedidas pelo papel roles/storage.objectAdmin. Da mesma forma, se você limitar o acesso omitindo determinados papéis, isso afetará todas as VMs que estão sendo executadas como a conta de serviço padrão.

  • Dependendo da configuração da política da organização, a conta de serviço padrão pode receber automaticamente o papel de Editor no projeto. É altamente recomendável desativar a concessão automática de papéis aplicando a restrição da política da organização iam.automaticIamGrantsForDefaultServiceAccounts. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

    Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

    Se a conta de serviço padrão já tiver o papel de Editor, recomendamos que você o substitua por papéis menos permissivos. Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da alteração e, em seguida, conceda e revogue os papéis apropriados.

Se não tiver certeza sobre a atribuição de papéis do IAM para a conta de serviço padrão, crie uma nova conta de serviço.

Anexar a conta de serviço e atualizar o escopo de acesso

Para alterar a conta de serviço e os escopos de acesso de uma VM, a VM precisa ser interrompida temporariamente.

Se a conta de serviço estiver em um projeto diferente das instâncias, será preciso configurar a conta de serviço para um recurso em um projeto diferente.

Use um dos métodos a seguir para alterar a conta de serviço e os escopos de acesso na VM.

Console

  1. Acesse a página Instâncias da VM.

    Acessar instâncias de VM

  2. Clique no nome da instância de VM para que você quer alterar a conta de serviço.

  3. Se a instância não estiver parada, clique em Parar. Espere até que a VM seja totalmente interrompida.

  4. Clique em Editar.

  5. Role para baixo até a seção Conta de serviço.

  6. Na lista suspensa, selecione a conta de serviço a ser atribuída à VM.

    • Se você escolher uma conta de serviço gerenciada pelo usuário, o escopo de acesso da VM será definido por padrão como o escopo cloud-platform recomendado. Se você precisar de um escopo diferente para sua conta de serviço gerenciada pelo usuário, use a CLI gcloud ou a API Compute Engine para anexar a conta de serviço.
    • Se você escolher a conta de serviço padrão do Compute Engine, poderá modificar os escopos de acesso no console do Google Cloud.
      • Para alterar os escopos, na seção Escopos de acesso, selecione Definir acesso para cada API e defina os escopos apropriados para suas necessidades.
      • Recomendado Se não tiver certeza de quais escopos de acesso definir, escolha Permitir acesso total a todas as APIs do Cloud e restrinja o acesso definindo os papéis do IAM na conta de serviço.

  7. Clique em Salvar.

  8. Clique em Iniciar/Retomar para reiniciar a VM.

gcloud

  1. Interrompa a VM usando o comando instances stop: Substitua VM_NAME pelo nome da sua instância de VM.

    gcloud compute instances stop VM_NAME

  2. Anexe a conta de serviço. Para anexar a conta de serviço, use o comando instances set-service-account e forneça o nome da VM, o e-mail da conta de serviço e os escopos escolhidos. Para mais informações sobre como definir escopos de acesso, consulte Práticas recomendadas.

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

    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.

      Se você quiser remover a conta de serviço da VM, use a sinalização --no-service-account.

    • VM_NAME: o nome da instância de VM.

    • SCOPES: uma lista separada por vírgulas de URIs ou aliases de escopo fornecidas na descrição da sinalização --scopes.

      Se você quer remover todos os escopos da instância, use a sinalização --no-scopes.

    Por exemplo, com o comando a seguir, você atribui a conta de serviço my-sa-123@my-project-123.iam.gserviceaccount.com a uma instância chamada "example-instance". Além disso, você define escopos de acesso nessa instância para permitir o acesso de leitura/gravação ao Compute Engine e o acesso somente leitura ao 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. Inicie a VM usando o comando instances start: Substitua VM_NAME pelo nome da sua instância de VM.

    gcloud compute instances start VM_NAME

REST

  1. Interrompa a VM fazendo uma solicitação POST usando o método instances.stop:

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

    Substitua:

    • PROJECT_ID: o projeto em que a VM está.
    • ZONE: a zona em que a VM está localizada.
    • VM_NAME: o nome da VM que você quer parar

  2. Anexe a conta de serviço fazendo uma solicitação POST ao 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",
    ...
  ]
}

    Substitua:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona a que esta VM pertence.
    • VM_NAME: o nome da VM.
    • 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.
    • SCOPE_URI: o URI de escopo.

    Por exemplo, na solicitação a seguir, o e-mail da conta de serviço my-sa-123@my-project-123.iam.gserviceaccount.com é usado, e um escopo do Cloud Storage e do BigQuery é definido:

    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. Inicie a VM criando uma solicitação POST usando o método instances.start:

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

    Substitua:

    • PROJECT_ID: o projeto em que a VM está.
    • ZONE: a zona em que a VM está localizada.
    • VM_NAME: o nome da VM que você quer iniciar.

Verificar a conta de serviço usada por uma VM

Para ver todas as contas de serviço em um projeto, consulte Como listar contas de serviço.

Se você precisar identificar a conta de serviço usada por uma VM, conclua um dos seguintes procedimentos:

Console

  1. Acesse a página Instâncias da VM.

    Acessar instâncias de VM

  2. Clique no nome da instância de VM para que você quer alterar a conta de serviço.

  3. Acesse a seção Gerenciamento de APIs e identidades. Esta seção exibe a conta de serviço e o escopo de acesso usados pela VM.

gcloud

Execute o gcloud compute instances describecomando:

gcloud compute instances describe VM_NAME \
    --format json

O resultado será assim:

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

Se a instância não estiver usando uma conta de serviço, você receberá uma resposta sem a propriedade serviceAccounts.

Servidor de metadados

Consulte o servidor de metadados de dentro da própria instância. Faça uma solicitação para 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"

Se você ativou uma ou mais contas de serviço ao criar a instância, o comando curl retornará uma saída como esta:

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

Se a instância não estiver usando uma conta de serviço, você receberá uma resposta vazia.

Práticas recomendadas

A seguir