Manage IAM authentication

This page provides instructions on common tasks for the IAM Authentication feature for Memorystore for Redis Cluster. For more details on the feature, see About IAM authentication.

Create an instance with IAM authentication

To create a Memorystore for Redis Cluster instance that uses IAM authentication, run the create command:

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

Replace the following:

• INSTANCE_ID is the ID of the Memorystore for Redis Cluster instance you're creating. Your instance ID must be 1 to 63 characters and use only lowercase letters, numbers, or hyphens. It must start with a lowercase letter and end with a lowercase letter or number.

• REGION_ID is the region where you want the instance placed.

  Note: You can only create instances in the supported regions for Memorystore for Redis Cluster. Not all of the regions currently supported by Memorystore for Redis are available for Memorystore for Redis Cluster. The gcloud redis regions list commands shows supported regions for Memorystore for Redis, not Memorystore for Redis Cluster.

• NETWORK is the network used to create your instance. It must use the format: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. The network ID used here must match the network ID used by the service connection policy. Otherwise, the create operation fails. For more details, see Networking.

• NODE_TYPE is your chosen node type. Accepted values are:

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

  For more details on node types and cluster configurations, see Cluster and node specification.

• SHARD_COUNT determines the number of shards in your instance. Shard count determines the total memory capacity for storing cluster data. To see more details about cluster specification, see Cluster and node specification.

Grant permissions for IAM authentication

To grant an IAM access, grant the principal the roles/redis.dbConnectionUser role using the Grant IAM role instructions.

By default, granting a principal the roles/redis.dbConnectionUser role allows the principal to access all instances in your project.

Note: For instructions on limiting user access on a per-instance basis, see Grant access to a group of resources based on resource name prefixes. When granting limited access for your instance, use the resource.name attribute and the following format for the instance name - projects/PROJECT/locations/REGION/clusters/INSTANCE_NAME.

Create a limited IAM admin role for an instance

You might want to create a role that can modify instance connection IAM permissions without granting full IAM admin access. This can be done by creating a limited IAM admin for the roles/redis.dbConnectionUser` role. For more details, visit Create limited IAM admins.

Connect to an instance that uses IAM authentication

1. If you don't already have a Compute Engine VM that uses the same authorized network as your Redis cluster, create one and connect to it by following Quickstart Using a Linux VM.

2. To connect to your instance, you must enable the following access scopes and APIs for your project:

   • Cloud Platform API scope. For instructions on enabling this scope, see Attach the service account and update the access scope. For a description of best practices for this access scope, see Scopes best practice.

   • Memorystore for Redis Cluster API. For a link to enable the API, click the following button:
     Memorystore for Redis Cluster

3. Install redis-cli on the Compute Engine VM by running the following command from the Compute Engine SSH terminal:

   sudo apt-get install redis-tools
   

4. Run the following command to get an access token for your IAM user:

   gcloud auth print-access-token
   

   Note: Access tokens will expire in one hour. For more information, see IAM access token timeframe.

5. Connect to your instance's discovery endpoint:

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

   Replace the following:

   • NETWORK_ADDRESS is the instance's network address. To view the network address, see View instance information.

   • PORT is the instances port number. To view the port number, see View instance information.

   • ACCESS_TOKEN is the IAM access token retrieved in previous steps.

   Note: Authenticated connections are valid for 12 hours. For more information, see Authentication time frame.

6. Run the CLUSTER SHARDS command to view your cluster topology. Take a note of one of the node's IP addresses and port numbers.

7. Connect to your desired node by running the following command:

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

   Replace the following:

   • NODE_IP_ADDRESS is the node's IP address you found in the previous step.
   • NODE_PORT is the node's port number you found in the previous step.

8. Run a Redis SET and GET command to verify that you have established an authenticated connection to your cluster node.

9. Once you are done testing your connection to the Redis instance, you should consider deleting the Compute Engine VM you used to connect to the Redis cluster. Doing so helps you avoid incurring charges to your Cloud Billing account.

10. Run the following command to use redis-cli to authenticate and connect to your instance, replacing variables with appropriate values:

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

    Replace the following:

    • NETWORK_ADDRESS is the instance's network address. To view the network address, see View instance information.

    • PORT is the instances port number. To view the port number, see View instance information.

    • ACCESS_TOKEN is the IAM access token retrieved in previous steps.

    Note: Authenticated connections are valid for 12 hours. For more information, see Authentication time frame.

11. Run a Redis SET and GET command to verify that you have established an authenticated connection to your instance.

12. Once you are done testing your connection to the Redis cluster, you should consider deleting the Compute Engine VM you used to connect to the Redis cluster. Doing so helps you avoid incurring charges to your Cloud Billing account.

Automate access token retrieval

It is recommended that you automate access token retrieval in your application, as access tokens can not be easily hard coded due to their short lifetime.

1. (Optional) If you haven't already, create a service account for your application (see Creating and managing a service account).

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

   Replace the following:

   • SA_NAME is the name of the service account.
   • DESCRIPTION is an optional description of the service account.
   • DISPLAY_NAME is a service account name to display in the Google Cloud console.

2. Grant your service account redis.dbConnectionUser permission on your project.

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

   Replace the following:

   • PROJECT_ID is the project ID.
   • SA_NAME is the name of the service account.
   • ROLE_NAME is a role name, such as roles/compute.osLogin.

3. Authenticate your application as the given service account. See service accounts for more information.

   For code samples that show how you can authenticate your application using popular client libraries, see IAM authentication client library code samples.

Code sample for connecting to an instance that uses IAM Auth

To view a code sample on how to set up a client library to connect to an instance that uses IAM Auth, see IAM Authentication client library code sample.