Gerenciar a autenticação do IAM

Esta página contém instruções sobre tarefas comuns do recurso de autenticação do IAM para o Memorystore for Valkey. 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 Valkey que usa a autenticação do IAM, execute o comando create:

gcloud memorystore instances create INSTANCE_ID --region=REGION_ID --network=NETWORK --node-type=NODE_TYPE --shard-count=SHARD_COUNT --authorization-mode=iam-auth

Substitua:

• INSTANCE_ID é o ID da instância do Memorystore for Valkey 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.

• 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ó da instância.

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

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

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

Para conceder um acesso do IAM, conceda ao principal o roles/memorystore.dbConnectionUser papel usando as instruções Conceder papel do IAM.

Por padrão, conceder um principal ao papel roles/memorystore.dbConnectionUser permite que ele acesse todas as instâncias no 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 seguinte formato para o nome da instância: projects/PROJECT/locations/REGION/instances/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 da instância sem conceder acesso total de administrador do IAM. Isso pode ser feito criando um administrador limitado do IAM para o papel roles/memorystore.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 sua instância do Valkey, 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, ative o escopo da API 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 Valkey.

   API Memorystore for Valkey

4. Instale valkey-cli na VM do Compute Engine seguindo as instruções em Instalar o Valkey.

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:

   valkey-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 Visualizar informações da instância.

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

   • 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 na instância, anexe as flags do Transport Layer Security (TLS). Exemplo:

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

   Importante: se você tiver uma instância com o modo de cluster desativado, não use a flag -c.

7. Opcional: se você tiver uma instância com o modo de cluster ativado, execute o comando CLUSTER SHARDS para conferir a topologia do nó. Anote um dos endereços IP e números de porta do nó.

   Se você tiver uma instância com o modo de cluster desativado, pule esta etapa.

8. Para usar valkey-cli para autenticar e se conectar ao nó, use o seguinte comando:

   valkey-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 Valkey.

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

Automatizar a recuperação de tokens de acesso

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.

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 memorystore.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: memorystore.dbConnectionUser.

3. Autentique seu aplicativo como a conta de serviço especificada. Consulte Contas de serviço para mais informações.

   Para exemplos de código que mostram como autenticar seu aplicativo usando bibliotecas de cliente conhecidas, consulte Exemplos de código de biblioteca de cliente.

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

Para conferir um exemplo de código compatível com o Valkey sobre como configurar uma biblioteca de cliente para se conectar a uma instância que usa a autenticação do IAM, consulte Exemplo de código para autenticação do IAM e criptografia em trânsito.

Resolver 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 Valkey 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 Valkey.	O aplicativo não está fornecendo um token de acesso ao servidor do Memorystore for Valkey. 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 Valkey. 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 Valkey 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.