Multi-Project Isolation
GCP resource names follow projects/{project}/.... floci-gcp uses the GCP project ID as the multi-tenancy boundary: resources created in one project are invisible to another.
How It Works
Every GCP resource name is scoped to a project:
projects/my-project/topics/my-topic
projects/my-project/subscriptions/my-sub
projects/my-project/databases/(default)/documents/...
projects/my-project/secrets/my-secret
floci-gcp keeps projects apart in one of two ways, depending on the service:
- By resource name. Most services store each resource under a key that names its project,
normally the full resource name, which starts with
projects/{project}/. Pub/Sub, Firestore, Datastore, Secret Manager, Cloud KMS, Cloud Tasks, Cloud Scheduler, Cloud Run, GKE, Eventarc, Managed Kafka, IAM and Cloud Logging work this way. GKE operations are the exception: they are stored by operation ID and matched to a project through theirselfLink. - By request project. BigQuery, Cloud SQL, Cloud Monitoring and Cloud Functions resolve the project of each request and prefix every stored key with it. BigQuery Storage Write API streams are stored under their full name instead.
- Cloud Storage follows GCP: bucket names are global, so a name taken in one project cannot be created in another. Each bucket records the project that owns it, and listing buckets returns only those of the project you ask for.
Either way, two requests that name different projects see independent data. A project does not have to be created first: any project ID you use exists.
Project ID Resolution Order
For REST requests floci-gcp resolves the project in this order:
- URL path segment:
projects/{project}/... projectquery parameter (for exampleGET /storage/v1/b?project=my-project)x-goog-request-paramsheader:project=...FLOCI_GCP_DEFAULT_PROJECT_IDfallback (default:floci-local)
On REST requests, a project number in any of these positions resolves to the ID of the project it belongs to. Projects named in a request are registered on first use and then show up in the Resource Manager API.
gRPC requests resolve the project in this order: the request message's own target
(projects/{project}/topics/{topic}, or a project_id field), then the x-goog-request-params
routing header, then the default project. As on REST, the project found this way is registered
on first use, and a known project's number resolves to its ID as the project of the call.
The resource names in the request message reach the service with a known project's number
replaced by its ID, so projects/{number}/topics/t and projects/{id}/topics/t name the same
topic, and responses return the ID form. A number that belongs to no known project is passed
on unchanged.
Strict Mode
By default any project ID works. Set FLOCI_GCP_PROJECTS_STRICT=true to make only the
default project and projects created with POST /v1/projects exist. REST requests for any
other project then return 403 PERMISSION_DENIED, as GCP does for a project you cannot
see, and gRPC calls fail with PERMISSION_DENIED. A gRPC call is checked against the project
that decides its context, so another project a request only refers to is not checked. See
Resource Manager: strict mode.
Working with Multiple Projects
export PUBSUB_EMULATOR_HOST=localhost:4588
# Create the same topic name in two different projects: fully isolated
gcloud pubsub topics create my-topic --project=project-a
gcloud pubsub topics create my-topic --project=project-b
# List topics in each project independently
gcloud pubsub topics list --project=project-a
gcloud pubsub topics list --project=project-b
Default Project
The default project ID is floci-local. Change it with:
Or via Docker Compose:
SDK Examples
// Pub/Sub: specify project explicitly
TopicName topicA = TopicName.of("project-a", "my-topic");
TopicName topicB = TopicName.of("project-b", "my-topic");
topicAdminClient.createTopic(topicA);
topicAdminClient.createTopic(topicB);
// These are fully independent: listing topics for project-a won't show project-b
Project IDs and Project Numbers
Every project has a stable 12-digit project number derived from its ID, so the same ID always
gets the same number and no setup is needed. Resource Manager reports it
(GET /v1/projects/{project}), Cloud Storage uses it in bucket resources (projectNumber,
projects/{projectNumber}), and Firebase Auth uses it in securetoken responses.
Cloud Storage accepts either the ID or the number when listing buckets. Over gRPC, a known
project's number is mapped to its ID in the request's own name, parent, resource,
project, project_id and database fields and repeated name lists, and in every field the
API's protos annotate as a resource name, nested ones included. Firestore also maps the document
names of writes, cursors and listen targets. Over REST, other services expect the project ID
there.
The - Wildcard
Where GCP documents - as a wildcard, floci-gcp accepts it:
| Request | Meaning |
|---|---|
projects/-/serviceAccounts/{EMAIL_ADDRESS\|UNIQUE_ID} (IAM) |
The project that owns the account. A missing account returns 403 PERMISSION_DENIED, as on GCP. |
projects/{project}/locations/-/clusters and .../operations (GKE) |
Every location. |
projects/{project}/locations/-/functions (Cloud Functions) |
Every location. |
.../services/-/revisions (Cloud Run) |
Every service. Listing services with locations/- is rejected with INVALID_ARGUMENT, as on GCP. |
Persistence
In the persistent, hybrid and wal storage modes the project is saved with
every resource (in its name, as a key prefix, or as the owner of a bucket), so projects stay
isolated across restarts. Firestore documents that an earlier version saved under a known
project's number are moved to the project ID at startup; a document already saved under the ID
is kept, and the number-form copy is left unchanged.
Opt-in Modes
By default floci-gcp is lenient: any project exists, any location is accepted, and no policy is evaluated. These settings make it stricter. All are off by default.
| Setting | Environment variable | Effect |
|---|---|---|
floci-gcp.locations.strict |
FLOCI_GCP_LOCATIONS_STRICT |
Reject locations that are not in the catalog with INVALID_ARGUMENT. See Locations. |
floci-gcp.services.iam.authorization-mode=enforce |
FLOCI_GCP_SERVICES_IAM_AUTHORIZATION_MODE |
Evaluate stored IAM allow policies for the services that support it. See IAM. |
Known Gaps
- No organizations or folders: every project stands alone, and there are no organization policies.
- On REST, services that store by the resource name in the path keep the project as the request
names it, so
projects/{number}/...andprojects/{id}/...address different data there. A number maps to the ID for the request project, for Service Usage enablement, and for project IAM policies. Cloud Storage bucket listing accepts a number directly. - Over gRPC, a name in a nested field that the API's protos do not annotate as a resource name is kept as the request names it. Firestore is the exception: its document names are mapped wherever they appear.
- A gRPC response names the project by ID even when the request used its number. Real Secret Manager returns the project number in resource names whichever form the request used.
- Only the first message of a gRPC stream is mapped; later messages of the same stream (upload chunks, appended rows, acknowledgements) are passed on as sent.
- Project numbers are derived from the ID. They are stable, but they are not the numbers real GCP would assign.