Faça a gestão da autenticação IAM

Esta página fornece instruções sobre tarefas comuns para a funcionalidade de autenticação do IAM para o Memorystore for Valkey. Para mais detalhes sobre a funcionalidade, consulte o artigo Acerca da autenticação do IAM.

Crie uma instância com autenticação IAM

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

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

Substitua o seguinte:

• INSTANCE_ID é o ID da instância do Memorystore for Valkey que está a criar. O ID da instância tem de ter entre 1 e 63 carateres e usar apenas letras minúsculas, números ou hífenes. Tem de começar com uma letra minúscula e terminar com uma letra minúscula ou um número.

• REGION_ID é a região onde quer colocar a instância.

• NETWORK é a rede usada para criar a sua instância. Tem de usar o formato: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. O ID da rede usado aqui tem de corresponder ao ID da rede usado pela política de ligação de serviços. Caso contrário, a operação create falha. Para mais detalhes, consulte a secção Redes.

• NODE_TYPE é o tipo de nó escolhido. Os valores aceites são:

  • shared-core-nano
  • standard-small
  • highmem-medium
  • highmem-xlarge
  Aviso: recomendamos que use o tipo de nó shared-core-nano apenas para fins de desenvolvimento ou teste. Se executar o Memorystore for Valkey num ambiente de produção, recomendamos que use os tipos de nós standard-small, highmem-medium ou highmem-xlarge. Para mais informações sobre estes tipos de nós, consulte Escolha um 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 instâncias. Para ver mais detalhes sobre a especificação de instâncias, consulte o artigo Especificação de instâncias e nós.

Conceda autorizações para a autenticação IAM

Para conceder acesso à IAM, conceda ao principal a função roles/memorystore.dbConnectionUser através das instruções para conceder funções da IAM.

Por predefinição, a atribuição da função roles/memorystore.dbConnectionUser a um principal permite que o principal aceda a todas as instâncias no seu projeto.

Nota: para obter instruções sobre como limitar o acesso dos utilizadores por instância, consulte o artigo Conceda acesso a um grupo de recursos com base nos prefixos dos nomes dos recursos. Quando conceder acesso limitado à sua instância, use o atributo resource.name e o seguinte formato para o nome da instância: projects/PROJECT/locations/REGION/instances/INSTANCE_NAME.

Crie uma função de administrador do IAM limitada para uma instância

Pode querer criar uma função que possa modificar as autorizações do IAM de ligação à instância sem conceder acesso total de administrador do IAM. Isto pode ser feito através da criação de um administrador do IAM limitado para a função roles/memorystore.dbConnectionUser. Para mais detalhes, visite o artigo Crie administradores da IAM limitados.

Estabeleça ligação a uma instância que usa a autenticação IAM

1. Se ainda não tiver uma VM do Compute Engine que use a mesma rede autorizada que a sua instância do Valkey, crie uma e ligue-se a ela seguindo o Início rápido com uma VM do Linux.

2. Para o seu projeto, ative o âmbito da API Cloud Platform. Para mais informações sobre como ativar este âmbito de acesso, consulte Anexe a conta de serviço e atualize o âmbito de acesso. Para mais informações acerca das práticas recomendadas para este âmbito, consulte Práticas recomendadas de âmbitos.

3. Para o seu projeto, ative a API Memorystore for Valkey.

   API Memorystore for Valkey

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

5. Execute o seguinte comando para obter um token de acesso para o seu utilizador do IAM:

   gcloud auth print-access-token
   

   Nota: os tokens de acesso expiram dentro de uma hora. Para mais informações, consulte o artigo Intervalo de tempo do token de acesso da IAM.

6. Ligue-se ao ponto final de deteção da sua instância:

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

   Substitua o seguinte:

   • NETWORK_ADDRESS é o endereço de rede da instância. Para ver o endereço de rede, consulte Ver informações da instância.

   • PORT é o número da porta das instâncias. Para ver o número da porta, consulte o artigo Ver informações da instância.

   • ACCESS_TOKEN é o token de acesso da IAM obtido nos passos anteriores.

   Nota: as associações autenticadas são válidas durante 12 horas. Para mais informações, consulte o artigo Intervalo de tempo do token de acesso da IAM.

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

8. Estabeleça ligação ao nó escolhido executando o seguinte comando:

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

   Substitua o seguinte:

   • NODE_IP_ADDRESS é o endereço IP do nó que encontrou no passo anterior.
   • NODE_PORT é o número da porta do nó que encontrou no passo anterior.

9. Execute um comando SET e GET do Valkey para verificar se estabeleceu uma ligação autenticada ao nó da sua instância.

10. Quando terminar de testar a ligação à instância do Valkey, deve considerar eliminar a VM do Compute Engine que usou para se ligar à instância do Valkey. Deste modo, evita incorrer em custos na sua conta de faturação do Google Cloud.

11. Execute o seguinte comando para usar o valkey-cli para autenticar e estabelecer ligação à sua instância, substituindo as variáveis por valores adequados:

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

    Substitua o seguinte:

    • NETWORK_ADDRESS é o endereço de rede da instância. Para ver o endereço de rede, consulte Ver informações da instância.

    • PORT é o número da porta das instâncias. Para ver o número da porta, consulte o artigo Ver informações da instância.

    • ACCESS_TOKEN é o token de acesso da IAM obtido nos passos anteriores.

    Nota: as associações autenticadas são válidas durante 12 horas. Para mais informações, consulte o artigo Intervalo de tempo do token de acesso da IAM.

12. Execute um comando SET e GET do Valkey para verificar se estabeleceu uma ligação autenticada à sua instância.

13. Quando terminar de testar a ligação à instância do Valkey, deve considerar eliminar a VM do Compute Engine que usou para se ligar à instância do Valkey. Deste modo, evita incorrer em custos na sua conta de faturação do Google Cloud.

Automatize a obtenção de tokens de acesso

Recomendamos que automatize a obtenção de chaves de acesso na sua aplicação, uma vez que não é fácil codificar as chaves de acesso devido à sua curta duração.

1. (Opcional) Se ainda não o fez, crie uma conta de serviço para a sua aplicação (consulte o artigo Criar e gerir uma conta de serviço).

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

   Substitua o seguinte:

   • 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 apresentar na consolaGoogle Cloud .

2. Conceda à sua conta de serviço a autorização memorystore.dbConnectionUser no seu projeto.

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

   Substitua o seguinte:

   • PROJECT_ID é o ID do projeto.
   • SA_NAME é o nome da conta de serviço.
   • ROLE_NAME é um nome de função, como roles/compute.osLogin.

3. Autentique a sua aplicação como a conta de serviço fornecida. Consulte as contas de serviço para mais informações.

   Para ver exemplos de código que mostram como pode autenticar a sua aplicação através de bibliotecas cliente populares, consulte Exemplos de código de bibliotecas cliente.

Exemplo de código para estabelecer ligação a uma instância que usa a autenticação IAM

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

Resolução de problemas de mensagens de erro com a autenticação da IAM

Mensagem de erro	Ação recomendada	Descrição
-WRONGPASS invalid username-password pair or user is disabled	Valide o nome de utilizador e o token de acesso fornecidos ao servidor do Memorystore for Valkey	O nome de utilizador ou o token de acesso fornecido é inválido. "default" é o único nome de utilizador suportado. Se a sua aplicação já estiver a usar o nome de utilizador "predefinição", verifique se o token de acesso não expirou e se é obtido seguindo as instruções em Estabeleça ligação a uma instância que use a autenticação IAM. As autorizações de IAM podem demorar alguns minutos a propagar-se se tiverem sido alteradas recentemente.
-NOAUTH Authentication required	Verifique se a aplicação está configurada para fornecer um token de acesso do IAM ao servidor do Memorystore for Valkey	A aplicação não está a fornecer uma chave de acesso ao servidor do Memorystore for Valkey. Verifique se a aplicação está configurada para fornecer um token de acesso seguindo as instruções em Estabeleça ligação a uma instância que use a autenticação IAM
-ERR (ERR_IAM_EXHAUSTED) Memorystore IAM authentication backend quota exceeded. See https://cloud.google.com/memorystore/docs/valkey/manage-iam-auth#error_messages.	Tente novamente com retirada exponencial	O back-end do IAM está sobrecarregado e devolveu um erro de quota excedida ao servidor do Memorystore for Valkey. As aplicações devem tentar novamente este erro com retirada exponencial para evitar mais falhas de ligação.
-ERR (ERR_IAM_OTHER) Memorystore IAM authentication backend error. See https://cloud.google.com/memorystore/docs/valkey/manage-iam-auth#error_messages.	Tente novamente com retirada exponencial	O back-end do IAM devolveu um erro transitório ao servidor do Memorystore for Valkey. As aplicações devem tentar novamente este erro com retirada exponencial para evitar mais falhas de ligação.