Gerenciar a autenticação do IAM

Esta página fornece instruções sobre tarefas comuns do recurso de autenticação do IAM para o Memorystore for Redis Cluster. Para mais detalhes sobre o recurso, consulte Sobre a autenticação do IAM.

Criar uma instância com a autenticação do IAM

Para criar uma instância do Memorystore for Redis Cluster que usa a autenticação do IAM, execute o comando create:

gcloud redis clusters create INSTANCE_ID --region=REGION_ID --network=NETWORK --node-type=NODE_TYPE --shard-count=SHARD_COUNT --auth-mode=iam-auth

Substitua:

• INSTANCE_ID é o ID da instância do Memorystore for Redis Cluster que você está criando. O ID da instância precisa ter de 1 a 63 caracteres e usar apenas letras minúsculas, números ou hifens. Ele precisa começar e terminar com uma letra minúscula ou um número.

• REGION_ID é a região em que você quer que a instância seja colocada.

  Observação: só é possível criar instâncias nas regiões compatíveis com o Memorystore for Redis Cluster. Nem todas as regiões com suporte atual do Memorystore for Redis estão disponíveis para o Memorystore for Redis Cluster. Os comandos gcloud redis regions list mostram as regiões com disponibilidade para o Memorystore for Redis, não para o Memorystore for Redis Cluster.

• NETWORK é a rede usada para criar a instância. Ela precisa usar o formato: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. O ID de rede usado aqui precisa corresponder ao ID de rede usado pela política de conexão de serviço. Caso contrário, a operação create falhará. Para mais detalhes, consulte Rede.

• NODE_TYPE é o tipo de nó do cluster.

  Cuidado: recomendamos que você use o redis-shared-core-nano tipo de nó apenas para fins de desenvolvimento ou teste porque ele não tem SLA. Se você executar o Memorystore for Redis Cluster em um ambiente de produção, recomendamos usar outro tipo de nó.

• SHARD_COUNT determina o número de fragmentos na sua instância. A contagem de fragmentos determina a capacidade total de memória para armazenar dados de cluster. Para mais detalhes sobre a especificação do cluster, consulte Especificação de cluster e nó.

Conceder permissões para a autenticação do IAM

Para conceder acesso ao IAM, use as instruções em Conceder um papel do IAM para conceder o roles/redis.dbConnectionUser papel ao principal. O principal é uma identidade a que você pode conceder acesso a recursos em Google Cloud. Por exemplo, um principal pode ser uma conta de serviço que pode acessar seu Google Cloud projeto.

Por padrão, conceder a um principal o papel roles/redis.dbConnectionUser permite que ele acesse todas as instâncias do seu projeto.

**Observação**: para instruções sobre como limitar o acesso do usuário por instância, consulte Conceder acesso a um grupo de recursos com base em prefixos de nomes de recursos. Ao conceder acesso limitado à instância, use o atributo resource.name e o formato a seguir para o nome da instância: projects/PROJECT/locations/REGION/clusters/INSTANCE_NAME.

Criar um papel de administrador limitado do IAM para uma instância

Talvez você queira criar um papel que possa modificar as permissões do IAM de conexão de instância sem conceder acesso total de administrador do IAM. Isso pode ser feito criando um administrador limitado do IAM para o papel roles/redis.dbConnectionUser. Para mais detalhes, acesse Criar administradores limitados do IAM.

Conectar-se a uma instância que usa a autenticação do IAM

1. Se você ainda não tem uma VM do Compute Engine que usa a mesma rede autorizada que o cluster do Redis, crie uma e se conecte a ela seguindo o Guia de início rápido sobre como usar uma VM do Linux.

2. Para seu projeto, use o gcloud compute instances set-service-account comando para definir uma conta de serviço e ativar o escopo da API Cloud Platform para sua VM do Compute Engine.

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

   Faça as seguintes substituições:

   • VM_NAME: o nome da sua VM do Compute Engine
   • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da sua conta de serviço
   • SCOPE: o escopo da API Cloud Platform para a VM (cloud-platform)

   Por exemplo, o comando a seguir atribui a conta de serviço [e-mail] a uma VM chamada example-VM e define o escopo de acesso nessa VM para a API Cloud Platform:

   gcloud compute instances set-service-account example-VM \
   --service-account=[e-mail] \
   --scopes=cloud-platform
   

   Para mais informações sobre como ativar esse escopo de acesso, consulte Anexar a conta de serviço e atualizar o escopo de acesso. Para mais informações sobre as práticas recomendadas para esse escopo, consulte Práticas recomendadas de escopos.

3. Para seu projeto, ative a API Memorystore for Redis.

   API Memorystore for Redis

4. Instale redis-cli na VM do Compute Engine executando o seguinte comando no terminal SSH do Compute Engine:

   sudo apt-get install redis-tools
   

5. Execute o comando a seguir para recuperar um token de acesso para o usuário do IAM:

   gcloud auth print-access-token
   

   Os tokens de acesso expiram em uma hora. Para mais informações, consulte Período do token de acesso do IAM.

6. Conecte-se ao endpoint de descoberta da instância:

   redis-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c
   

   Substitua:

   • NETWORK_ADDRESS: o endereço de rede da instância. Para conferir o endereço de rede, consulte Conferir informações do cluster.

   • PORT: o número da porta da instância. Para conferir o número da porta, consulte Conferir informações do cluster.

   • ACCESS_TOKEN: o token de acesso que você recuperou na etapa anterior.

   Se você especificar um nome de usuário, use o nome de usuário default ou o endereço de e-mail principal do IAM. Além disso, as conexões autenticadas permanecem válidas após a expiração do token. Para mais informações, consulte Período do token de acesso do IAM.

   Se você ativar a criptografia em trânsito no cluster, anexe as flags do Transport Layer Security (TLS). Exemplo:

   redis-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c --tls --cacert /tmp/server_ca.pem
   

7. Execute o comando CLUSTER SHARDS para conferir a topologia do cluster. Anote um dos endereços IP e números de porta do nó.

8. Para usar redis-cli para autenticar e se conectar ao nó, use o comando a seguir:

   redis-cli -h NODE_IP_ADDRESS -p NODE_PORT -a ACCESS_TOKEN -c
   

   Substitua:

   • NODE_IP_ADDRESS: o endereço IP do nó que você anotou na etapa anterior
   • NODE_PORT: o número da porta do nó que você anotou na etapa anterior
   • ACCESS_TOKEN: o token de acesso do IAM que você recuperou anteriormente neste procedimento

9. Para verificar se você tem uma conexão autenticada com o nó, execute um comando SET e GET do Redis.

10. Exclua a VM do Compute Engine que você usou para se conectar ao cluster. Isso ajuda a evitar cobranças na sua conta do Cloud Billing.

Automatizar a recuperação de tokens de acesso

Observação : recomendamos que você automatize a recuperação de tokens de acesso no seu aplicativo. Devido ao curto período de validade de um token de acesso, é difícil codificar o token.

Para um exemplo de código que mostra como autenticar seu aplicativo usando bibliotecas de cliente conhecidas, consulte Exemplo de código da biblioteca de cliente de autenticação do IAM.

1. (Opcional) Se ainda não tiver feito isso, crie uma conta de serviço para seu aplicativo (consulte Criar e gerenciar uma conta de serviço).

   gcloud iam service-accounts create SA_NAME \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Substitua:

   • SA_NAME é o nome da conta de serviço.
   • DESCRIPTION é uma descrição opcional da conta de serviço.
   • DISPLAY_NAME é um nome de conta de serviço a ser exibido no Google Cloud console.

2. Conceda à conta de serviço o papel redis.dbConnectionUser no seu projeto.

   gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role=roles/"ROLE_NAME"
   

   Substitua:

   • PROJECT_ID: o ID do projeto;
   • SA_NAME: o nome da conta de serviço.
   • ROLE_NAME: um nome de papel. Para este exemplo: redis.dbConnectionUser.

3. Autentique seu aplicativo como a conta de serviço especificada. Para mais informações, consulte Contas de serviço.

Exemplo de código para se conectar a uma instância que usa a autenticação do IAM

Você pode conferir um exemplo de código que mostra como autenticar seu aplicativo usando bibliotecas de cliente conhecidas. Além disso, você pode conferir como usar esse exemplo de código para se conectar a uma instância que usa a autenticação do IAM.

Solução de problemas de mensagens de erro com a autenticação do IAM

Mensagem de erro	Ação recomendada	Descrição
-WRONGPASS invalid username-password pair or user is disabled	Verifique o token de acesso fornecido ao servidor do Memorystore for Redis Cluster e confira se o usuário da ACL correspondente está ativado.	O principal do IAM não tem as permissões necessárias, o token de acesso fornecido é inválido ou o usuário da ACL correspondente está desativado. Verifique se o token de acesso não expirou e se você o recuperou seguindo as instruções em Conectar-se a uma instância que usa a autenticação do IAM. Se você mudou as permissões do IAM recentemente, elas podem levar alguns minutos para serem propagadas.
-NOAUTH Authentication required	Verifique se o aplicativo está configurado para fornecer um token de acesso do IAM ao servidor do Memorystore for Redis Cluster.	O aplicativo não está fornecendo um token de acesso ao servidor do Memorystore for Redis Cluster. Verifique se o aplicativo está configurado para fornecer um token de acesso e se você o recuperou seguindo as instruções em Conectar-se a uma instância que usa a autenticação do IAM.
-ERR (ERR_IAM_EXHAUSTED) Memorystore IAM authentication backend quota exceeded.	Tentar novamente com a espera exponencial.	O back-end do IAM está sobrecarregado e retornou um erro de cota excedida para o servidor do Memorystore for Redis Cluster. Para evitar mais falhas de conexão, recomendamos que os aplicativos tentem novamente esse erro com espera exponencial.
-ERR (ERR_IAM_OTHER) Memorystore IAM authentication backend error.	Verifique o nome de usuário ou tente novamente com a espera exponencial.	Esse erro ocorre pelos seguintes motivos: O nome de usuário fornecido não é válido. Você pode usar o default nome de usuário, omitir o nome de usuário ou usar o endereço de e-mail principal do IAM. O back-end do IAM retornou um erro temporário para o Memorystore for Redis Cluster server. Se o nome de usuário for válido, recomendamos que o aplicativo tente novamente esse erro com espera exponencial para evitar mais falhas de conexão.