Best practices for using the AlloyDB Auth proxy

Keep the Auth proxy client up-to-date

Google occasionally releases new versions of the Auth proxy. You can see what the current version is by checking the AlloyDB Auth proxy GitHub releases page.

Keep the Auth proxy client Docker image up to date

The AlloyDB Auth proxy Docker image is based on a specific version of the AlloyDB Auth proxy. When a new version of the AlloyDB Auth proxy becomes available, pull the new version of the AlloyDB Auth proxy Docker image to keep your environment up to date. You can see the current version of the AlloyDB Auth proxy by checking the AlloyDB Auth proxy GitHub releases page.

In production environments run the Auth proxy client as a persistent service

If the Auth proxy client process is stopped, all existing connections through it are dropped, and your application cannot create any more connections to the AlloyDB instance with the AlloyDB Auth proxy. To prevent this scenario, be sure to run the Auth proxy client as a persistent service, so that if the Auth proxy client exits for any reason, it is automatically restarted. This can be accomplished by using a service such as systemd, upstart, or supervisor. For the Windows operating system, run the Auth proxy client as a Windows Service. In general, make sure the AlloyDB Auth proxy has the same uptime requirements as your application process.

When you run the Auth proxy client as a service, keep in mind that it uses a secure connection to communicate with AlloyDB instances, but connections from your application to the Auth proxy client are not encrypted. For this reason, ensure that only trusted users are able to access the address and port that the Auth proxy client is listening on.

Note: The Auth proxy client is a Windows executable but is not a Windows Service. There are several third-party service managers that you can use to run it as a service. For example, you can use NSSM to configure the AlloyDB Auth proxy as a Windows service, and NSSM monitors the Auth proxy client and restarts it automatically if it stops responding. See the NSSM documentation for more information.

Running the Auth proxy client as a service can also be convenient for local development and testing. When you need to access your AlloyDB instance, you can start the service in the background and stop it when you are finished.

Use a service account for authorization

The AlloyDB Auth proxy requires authenticating as a AlloyDB IAM principal to authorize your connections to a AlloyDB instance.

The advantage of using a service account for this purpose is that you can create a credential file specifically for the AlloyDB Auth proxy, and it is explicitly and permanently linked to the AlloyDB Auth proxy as long as it is running. For this reason, using a service account is the recommended method for production instances not running on a Compute Engine instance.

The credential file can be duplicated in a system image if you need to invoke the AlloyDB Auth proxy from multiple machines.

To use this method, you must create and manage the credential file. Only users with the resourcemanager.projects.setIamPolicy permission (such as project owners) can create the service account. If your Google Cloud user does not have this permission, you must have someone else create the service account for you, or use another method to authenticate the AlloyDB Auth proxy.

Required permissions for service accounts

When you use a service account to provide the credentials for the AlloyDB Auth proxy, you must create it with sufficient permissions. The predefined AlloyDB roles that provide these permissions are Cloud AlloyDB Client (roles/alloydb.client) and Cloud AlloyDB Admin (roles/alloydb.admin).

If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.

Procedure

If you are using a Compute Engine instance as your client host, make sure it has the https://www.googleapis.com/auth/cloud-platform access scope so that it can to use the AlloyDB API. If necessary, change its access scope to include this scope.

1. In the Google Cloud console, go to the Service accounts page.

   Go to Service accounts

2. Select the project that contains your AlloyDB instance.
3. Click Create service account.
4. In the Service account name field, enter a descriptive name for the service account.
5. Change the Service account ID to a unique, recognizable value and then click Create and continue.
6. Click the Select a role field and select one of the following roles:
   • Cloud AlloyDB Client
   • Cloud AlloyDB Admin
   Note: To create a service account with the required permissions, you must have resourcemanager.projects.setIamPolicy permission. This permission is included in the Project Owner, Project IAM Admin, and Organization Administrator roles.
   You must also have enabled the AlloyDB API. If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.
7. Click Done to finish creating the service account.
8. Click the action menu for your new service account and then select Manage keys.
9. Click the Add key drop-down menu and then click Create new key.
10. Confirm that the key type is JSON and then click Create.

    The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.