Postgres on Google Cloud / Reference
Where several words exist for one thing, this course picks one. The rejected spellings are listed so you recognise them elsewhere.
| Term | Definition |
|---|---|
| Project | The container every Google Cloud resource lives in, and the boundary for permissions, billing and API enablement. Identified by a globally unique project ID. |
| Principal | Anything that can be granted access: a user, a service account, or a group. Avoid: member, identity (both are used loosely elsewhere). |
| Service account | A principal that represents code rather than a person. Has no password and cannot log in interactively. |
| Role | A named bundle of permissions, written roles/service.name.
You grant roles; you never grant permissions directly. Note: a
PostgreSQL role is a different thing entirely — see below. |
| Binding | The three-part fact that a principal holds a role on a resource. Creating one takes about a minute to propagate. |
| ADC — Application Default Credentials | The fixed search order every Google library uses to find an identity:
the GOOGLE_APPLICATION_CREDENTIALS file, then the well-known
gcloud file, then the host's metadata server. |
| Metadata server | A local endpoint on Google Cloud compute that hands out credentials for the attached service account. The reason a workload on Google Cloud needs no key. |
| Attached service account | A service account bound to a VM, container or function, delivered through the metadata server. The best available workload identity. |
| Workload identity federation | Exchanging an external platform's OIDC token for a short-lived Google token. Gives a workload outside Google Cloud an identity with no key. Avoid: WIF, in prose. |
| Impersonation | Acting as a service account using your own credentials. Requires
roles/iam.serviceAccountTokenCreator on that service
account. Statements are attributed to the service account, not to
you. |
| Service account key | A JSON file holding a private key. Long-lived, portable, and a bearer credential — anyone holding it is the service account. The last resort. Avoid: credentials file, keyfile. |
| Organization policy constraint | A rule inherited from above your project that can forbid something the
project would otherwise allow — for example
iam.disableServiceAccountKeyCreation. |
| Term | Definition |
|---|---|
| Instance | One managed PostgreSQL server. Holds many databases. Addressed by
instance URI:
PROJECT_ID:REGION:INSTANCE_NAME. Avoid: connection
name, server. |
| Auth Proxy | A binary you run locally. Listens on a loopback port, tunnels to the instance over mutual TLS, and supplies your access token as the password. Avoid: the proxy, unqualified, when a connector is also in play. |
| Connector | A library doing the Auth Proxy's job inside your process. Java, Python, Go, Node.js. Avoid: driver — it is not one, it wraps one. |
| IAM database authentication | Using a Google identity as the PostgreSQL username, with a short-lived access token as the password. |
| Automatic IAM database authentication | The variant where the proxy or connector fetches and refreshes the token for you. What you should always use. The manual variant means handling the token yourself, and it stops working after an hour. |
| Access token | The short-lived OAuth 2.0 credential that fills the password field. Valid for one hour. |
| Ephemeral client certificate | The mutual-TLS certificate the proxy or connector obtains and rotates. Expires in about an hour. You never manage one. |
| IAM database user | A record on the instance mapping a Google principal to a PostgreSQL username. Arrives with no privileges. |
| Authorized networks | The IP allowlist. Under this model it stays empty — the connectors do not need it, and adding an address weakens the instance for no benefit. |
| Term | Definition |
|---|---|
| Role (PostgreSQL) | PostgreSQL's single concept for both users and groups. A role with
LOGIN can connect; one without is used as a group. Unrelated to
a Google Cloud role. |
| Group role | A NOLOGIN role that holds privileges, which principals
receive by membership rather than by direct grant. |
| Membership | The fact that one role is a member of another, and so inherits its privileges. Recorded in a shared catalog — therefore cluster-wide. |
| Shared catalog | A system table holding one set of data for the whole instance rather than
per database. pg_authid and pg_auth_members are
shared, which is why roles and memberships span every database on an
instance while privileges do not. |
| Ownership | The role an object belongs to. An owner holds ALTER,
DROP and TRUNCATE on it unconditionally;
no grant is consulted and no revoke applies. Assigned to the login
role that created the object. |
| Default privileges | A standing rule attaching privileges to objects a named role creates in
future. Set with ALTER DEFAULT PRIVILEGES FOR ROLE …; the
FOR ROLE clause is what makes it work. |
| Stale grants | The state after a migration or restore creates tables a previous
GRANT … ON ALL TABLES could not have covered. Silent until
someone reads a new table. |
| The diagonal | This course's name for the verification that each principal reaches its
own database and no other. One true per row, on the diagonal. |
| Layer | Question | Fails |
|---|---|---|
| 1 — Project IAM | May this identity reach the instance? | Before the proxy works |
| 2 — IAM database user | Does this identity exist on the instance? | At login, after the proxy works |
| 3 — PostgreSQL grants | What may it do once inside? | On the first query |