Gerenciar a autenticação do IAM

Esta página apresenta instruções sobre tarefas comuns para o recurso de autenticação do IAM no Memorystore para 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 para Valkey que usa 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 --auth-mode=iam-auth

Substitua:

• INSTANCE_ID é o ID da instância do Memorystore para 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 com uma letra minúscula e terminar com uma letra minúscula ou um número.

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

• NETWORK é a rede usada para criar a instância. Ele precisa usar o formato: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. O ID da rede usado aqui precisa corresponder ao ID 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ó escolhido. Os valores aceitos são:

  • shared-core-nano
  • standard-small
  • highmem-medium
  • highmem-xlarge

• 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 mais detalhes sobre a especificação da instância, consulte Especificação da instância e do nó.

Conceder permissões para autenticação do IAM

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

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

Criar uma função 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. Para isso, crie um administrador limitado do IAM para a função 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 conecte-se a ela seguindo o Guia de início rápido sobre como usar uma VM do Linux.

2. Para se conectar à sua instância, ative os seguintes escopos de acesso e APIs no seu projeto:

   • Escopo da API do Cloud Platform. Para instruções sobre como ativar esse escopo, consulte Anexar a conta de serviço e atualizar o escopo de acesso. Para uma descrição das práticas recomendadas para esse escopo de acesso, consulte Práticas recomendadas de escopos.

   • API Memorystore for Valkey. Para acessar um link e ativar a API, clique no botão a seguir:
     Memorystore for Valkey

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

4. Execute o seguinte comando para receber um token de acesso para seu usuário do IAM:

   gcloud auth print-access-token
   

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

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

   • ACCESS_TOKEN é o token de acesso do IAM recuperado nas etapas anteriores.

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

7. Conecte-se ao nó escolhido executando 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ê encontrou na etapa anterior.
   • NODE_PORT é o número da porta do nó encontrado na etapa anterior.

8. Execute os comandos SET e GET do Valkey para verificar se você estabeleceu uma conexão autenticada com o nó da instância.

9. Após concluir o teste de conexão com a instância do Valkey, exclua a VM do Compute Engine usada para se conectar à instância do Valkey. Isso ajuda a evitar cobranças na sua conta do Cloud Billing.

10. Execute o comando a seguir para usar valkey-cli e autenticar e se conectar à instância, substituindo as variáveis pelos valores apropriados:

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

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

    • ACCESS_TOKEN é o token de acesso do IAM recuperado nas etapas anteriores.

11. Execute os comandos SET e GET do Valkey para verificar se você estabeleceu uma conexão autenticada com a instância.

12. Após concluir o teste de conexão com a instância do Valkey, exclua a VM do Compute Engine usada para se conectar à instância do Valkey. 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, já que eles não podem ser codificados com facilidade devido à curta duração.

1. (Opcional) Se ainda não tiver feito isso, crie uma conta de serviço para seu aplicativo. Consulte Como 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 console Google Cloud .

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

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

   Substitua:

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

Como resolver mensagens de erro com a autenticação do IAM