1 · The ground floor — Postgres on Google Cloud

You do not need to learn Google Cloud to connect to a database on it. You need four ideas. This lesson is those four and nothing else. The rest of the platform is deliberately left out.

If you already work on GCP daily, skim the boxes and go to lesson 2.

1. A project is the container and the billing boundary

Every resource on Google Cloud — a database instance, a storage bucket, a virtual machine — lives inside exactly one project. A project has a human-readable name, and a globally unique project ID that you will type constantly. Throughout this course it is written PROJECT_ID.

Three things follow from this, and they are the reason projects matter to you:

Property	Why you care
Permissions attach to the project	Granting someone access to "the project" usually grants them access to every database in it. Splitting environments across projects is the most common way teams make that boundary real.
Billing attaches to the project	Cost questions are answered per project, not per resource.
APIs are enabled per project	A brand-new project cannot talk to the Cloud SQL Admin API until someone turns that API on. This is a real and confusing first failure.

Above projects sit folders and the organization. You inherit policy from them and can rarely change them. The one place this will bite you is lesson 6, where an organization-level policy can forbid something your project needs.

2. A principal is anything that can be granted access

Google Cloud calls these principals (older docs say "members"). There are two you will meet:

A user — a human with a Google identity

Written user:you@example.com. This is your corporate Google Workspace login or a personal Google account.

A service account — an identity for code

Written serviceAccount:app@PROJECT_ID.iam.gserviceaccount.com. It is not a person, has no password, and exists so that a running program can be someone.

A third form matters enormously for access management: a group, written group:team@example.com. A group is not a new kind of identity — it is a bag of users and service accounts that you can grant once. Grant the group, manage the membership. That is how access gets revoked in one action instead of twelve.

The habit worth forming now

Grant to groups, never to individuals. You will not feel the benefit on day one. You will feel it the first time someone leaves and you have to find every place their email was written down.

3. A role is a named bundle of permissions

You never grant a permission directly. You grant a role, which contains permissions. The grant itself is a three-part sentence:

on this resource this principal gets this role ───────────────── ─────────────── ────────────── project PROJECT_ID group:team@… roles/cloudsql.client

Permissions are named service.resource.verb — cloudsql.instances.connect, cloudsql.instances.login. Roles are named roles/service.shortname. You will use exactly two roles in this whole course, and they are the subject of lesson 4.

The trap

roles/owner looks like it contains everything. It does not. An owner can administer a database instance, reset its passwords, and read its secrets — but an owner is still not automatically a database user, and cannot necessarily impersonate a service account. Being an owner and being unable to connect is a normal, correct state, not a bug.

4. Application Default Credentials is how tools find your identity

Every Google client library and command-line tool answers the question "who am I?" the same way. The mechanism is called Application Default Credentials, always abbreviated ADC. It searches a fixed list of places, in order, and uses the first thing it finds:

#	Where ADC looks	Typical situation
1	The file path in `GOOGLE_APPLICATION_CREDENTIALS`	You explicitly pointed it at a credential file
2	The well-known local file written by `gcloud auth application-default login`	Your laptop
3	The metadata server of the machine it is running on	Code on a Google Cloud VM or container, using an attached service account. No file, no key.

On your laptop you run this once, and again whenever it expires:

gcloud auth application-default login

Two commands, easily confused

gcloud auth login authenticates the gcloud command itself. gcloud auth application-default login writes the credential that libraries and other tools read. Running the first and expecting the second to work is a very common half-hour.

ADC credentials expire. On a laptop under a corporate reauthentication policy this is often about a day. When they expire, things that worked yesterday fail today with nothing having changed — and the failure is rarely a clear "your credentials expired" message. Remember this; it comes back in lesson 3 as the single most misdiagnosed failure in this course.

Check yourself

A new engineer joins and needs database access. What do you change?

Add them to the group. The role binding already exists and never has to change again, and the day they leave, removing them from the group removes every access it carried — in one action, in one place.

Your Python script cannot find credentials on your laptop. Which command fixes it?

Libraries read Application Default Credentials, which is written by the second command. The first authenticates only the gcloud tool itself — useful, but invisible to your script.

From memory: name the three places ADC looks, in order.

1. The file named by GOOGLE_APPLICATION_CREDENTIALS. 2. The well-known file written by gcloud auth application-default login. 3. The metadata server of the host it is running on.

The order is the useful part: an environment variable left set from last week silently wins over the login you just ran.