Autenticação do Terraform

Este documento descreve como se autenticar no Google Cloud ao usar o Terraform.

O Application Default Credentials (ADC, na sigla em inglês) é a maneira recomendada de autenticação no Google Cloud ao usar o Terraform. O ADC é uma estratégia usada pelas bibliotecas de autenticação do Google para encontrar credenciais automaticamente com base no ambiente do aplicativo. Quando você usa o ADC, o Terraform pode ser executado em um ambiente de desenvolvimento ou produção sem alterar a forma como ele se autentica nos serviços e nas APIs do Google Cloud. Para mais informações sobre onde o ADC procura credenciais e em que ordem, consulte Como o Application Default Credentials funciona.

Autenticar ao usar o Terraform em um ambiente de desenvolvimento local

Quando você usa o Terraform em um ambiente de desenvolvimento local, como uma estação de trabalho de desenvolvimento, é possível autenticar usando as credenciais associadas com a sua conta de usuário ou conta de serviço.

Autenticar usando uma conta do Google

Para configurar o ADC com uma Conta do Google, use a CLI do Google Cloud:

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

   gcloud init

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

   Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Autenticar usando uma conta externa

Para configurar o ADC para uma conta de usuário gerenciada por um provedor de identidade externo:

1. Configure a federação de identidade de colaboradores

2. Configure a gcloud CLI para usar a federação de identidade de colaboradores.

3. Configure o ADC executando o seguinte comando:

   gcloud auth application-default login

   Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Autenticar usando a identidade temporária de conta de serviço

Você pode usar a identidade temporária de conta de serviço para configurar um arquivo ADC local. O Terraform usa essas credenciais automaticamente.

1. Verifique se você tem o papel do IAM de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço que está representando. Para mais informações, consulte Papéis necessários.

2. Use a identidade temporária de conta de serviço para criar um arquivo ADC local executando o seguinte comando:

   gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL
   

Se você quiser permitir que os usuários usem uma fonte de autenticação primária compartilhada e uma conta de serviço variável por ambiente, defina o campo impersonate_service_account no arquivo de configuração do Terraform:

provider "google" {
  impersonate_service_account = "SERVICE_ACCT_EMAIL"
}

Autenticar ao executar o Terraform no Google Cloud

Ao executar o Terraform em um ambiente de desenvolvimento baseado na nuvem do Google Cloud, como o Cloud Shell, a ferramenta usa as credenciais fornecidas ao fazer login para autenticação.

Ao usar o Terraform com serviços do Google Cloud, como o Compute Engine, o App Engine e as funções do Cloud Run, é possível anexar uma conta de serviço gerenciada pelo usuário aos recursos. Geralmente, a anexação de uma conta de serviço acontece quando os recursos desse serviço podem ser executados ou incluem o código do aplicativo. Quando você vincula uma conta de serviço a um recurso, o código em execução no recurso pode usar essa conta de serviço como identidade.

Anexar uma conta de serviço gerenciada pelo usuário é a maneira preferida de fornecer credenciais ao ADC para código de produção em execução no Google Cloud.

Observação :muitos desses serviços do Google Cloud também oferecem uma conta de serviço padrão. Não recomendamos o uso da conta de serviço padrão porque, por padrão, a conta de serviço padrão é altamente privilegiada, o que viola o princípio do privilégio mínimo.

Se precisar de ajuda para determinar os papéis que você precisa fornecer à conta de serviço, consulte Escolher papéis predefinidos.

Para informações sobre quais recursos podem ser anexados a uma conta de serviço e ajuda para anexar a conta de serviço ao recurso, consulte a Documentação do IAM sobre como anexar uma conta de serviço.

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
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
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

Autenticar ao executar o Terraform no local ou em outro provedor de nuvem

Se o aplicativo estiver sendo executado fora do Google Cloud, será necessário fornecer credenciais reconhecidas pelo Google Cloud para usar os serviços do Google Cloud.

Autenticar usando a federação de identidade da carga de trabalho

A maneira mais comum de autenticar com o Google Cloud usando credenciais de um IdP externo é usar a federação de identidade da carga de trabalho. É possível criar um arquivo de configuração de credenciais e definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para apontar para ele. Essa abordagem é mais segura do que criar uma chave de conta de serviço. Para instruções sobre como configurar a federação de identidade da carga de trabalho para o ADC, consulte Federação de identidade da carga de trabalho com outras nuvens.

Autenticar usando chaves de conta de serviço

Ao executar o Terraform em um ambiente de desenvolvimento local, no local ou em um provedor de nuvem diferente, é possível criar uma conta de serviço, conceder a ela os papéis do IAM necessários para o aplicativo e criar uma chave para a conta de serviço.

Observação: as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura do que as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

Para criar uma chave de conta de serviço e disponibilizá-la para o ADC, faça o seguinte:

1. Crie uma conta de serviço com os papéis de que seu aplicativo precisa e uma chave para essa conta de serviço. Para fazer isso, siga as instruções em Como criar uma chave de conta de serviço.

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

Autenticar nos back-ends do Cloud Storage

O Terraform permite configurar o Cloud Storage como um back-end para armazenar arquivos de estado. Para fazer a autenticação em um back-end do Cloud Storage, use qualquer um dos métodos descritos nesta página. Para informações sobre variáveis de configuração relacionadas à autenticação para back-ends do Cloud Storage, consulte a Página de back-ends do Terraform para o Cloud Storage.

A seguir

• Trabalhe no Guia de início rápido do Terraform para Google Cloud
• Saiba mais sobre os comandos básicos do Terraform.