Service Usage
floci-gcp emulates the Service Usage API (serviceusage.googleapis.com v1, and v1beta1
generateServiceIdentity) over REST JSON.
The API enables and lists a project's GCP services. It is the first thing most IaC
tooling touches: Terraform's google_project_service and Pulumi's gcp.projects.Service
call it before managing any other resource, and gcloud services is built on it.
The emulator is an accept-and-succeed control plane: enabling a service flips it to
ENABLED (persisted, project-namespaced), disabling reverses it, and get/list echo that
state. By default there is no API gating or dependency resolution: services work whether or
not they were "enabled". Turn on enforcement to make the
enable/disable state matter.
Configuration
| Variable | Default | Description |
|---|---|---|
FLOCI_GCP_SERVICES_SERVICEUSAGE_ENABLED |
true |
Enable/disable Service Usage |
FLOCI_GCP_SERVICES_SERVICEUSAGE_ENFORCEMENT_ENABLED |
false |
Reject calls to APIs that are not enabled in the caller's project |
FLOCI_GCP_SERVICES_SERVICEUSAGE_DEFAULT_ENABLED |
GCP default set (below) | APIs treated as enabled in every project until disabled (enforcement only) |
FLOCI_GCP_SERVICES_RESOURCEMANAGER_ENABLED |
true |
Enable/disable Resource Manager |
Endpoints
| Method | Path |
|---|---|
POST |
/v1/projects/{project}/services/{service}:enable |
POST |
/v1/projects/{project}/services/{service}:disable |
GET |
/v1/projects/{project}/services/{service} |
GET |
/v1/projects/{project}/services (?filter=state:ENABLED\|state:DISABLED) |
POST |
/v1/projects/{project}/services:batchEnable |
GET |
/v1/projects/{project}/services:batchGet?names=... |
GET |
/v1/operations/{operation}, /v1/operations |
POST |
/v1beta1/projects/{project}/services/{service}:generateServiceIdentity |
GET |
/v1beta1/operations/{operation} |
enable, disable, and batchEnable return an already-completed
google.longrunning.Operation (done: true) whose response carries the proto response
type, so SDK operation futures resolve immediately. Disabling a service that is not
enabled returns FAILED_PRECONDITION, matching real GCP.
Every method resolves {project} through the project registry. A
project number that belongs to no known project, such as the 00000000000 the Google
provider probes before it creates a project with a billing account, returns 403
PERMISSION_DENIED, as GCP answers for a project the caller cannot see. In
strict mode an unknown project ID does too.
Service identities
generateServiceIdentity returns the service agent of a service in a project, as Terraform's
google_project_service_identity and Pulumi's gcp.projects.ServiceIdentity read it. The
method exists only in v1beta1, as in GCP, so a provider that calls it needs its Service Usage
endpoint set to <endpoint>/v1beta1/; /v1/...:generateServiceIdentity returns 404. The call
returns a completed operation whose response is a ServiceIdentity:
The email is service-{projectNumber}@gcp-sa-{service}.iam.gserviceaccount.com, or the
agent's own domain for the services that have one: compute-system (Compute Engine),
container-engine-robot (GKE), gs-project-accounts (Cloud Storage, the same address as
Cloud Storage's projects.serviceAccount), serverless-robot-prod
(Cloud Run), gcf-admin-robot (Cloud Functions) and gcp-sa-cloud-sql (Cloud SQL). The
uniqueId is derived from the email, so repeated calls return the same identity. No service
account is created in IAM. Only projects/{project} parents are served, not folders or
organizations.
Enforcing API enablement
With floci-gcp.services.serviceusage.enforcement-enabled: true (FLOCI_GCP_SERVICES_SERVICEUSAGE_ENFORCEMENT_ENABLED=true)
every call to an emulated API checks the Service Usage state of that API in the caller's
project and fails unless it is ENABLED, the way real GCP does. Enforcement is off by
default; with it off nothing changes.
A rejected call gets the SERVICE_DISABLED error described in
google/api/error_reason.proto:
{
"error": {
"code": 403,
"message": "Cloud Pub/Sub API has not been used in project my-project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/pubsub.googleapis.com/overview?project=my-project then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
"status": "PERMISSION_DENIED",
"errors": [{"message": "...", "domain": "usageLimits", "reason": "accessNotConfigured"}],
"details": [{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "SERVICE_DISABLED",
"domain": "googleapis.com",
"metadata": {"service": "pubsub.googleapis.com", "consumer": "projects/my-project"}
}]
}
}
gRPC calls fail with PERMISSION_DENIED, the same message, and the same ErrorInfo in
the status details (grpc-status-details-bin), so ApiException.getReason() returns
SERVICE_DISABLED in the Java client.
The project is taken from the request. For REST it is the projects/{project} path segment
or the project query parameter. For gRPC it is the x-goog-request-params routing header
and every project named by the fields the API declares as resource names (the
google.api.resource_reference and google.api.resource annotations of its protos, or a
project_id field), wherever they sit in the message: parent and read_session.table of
CreateReadSession, secret.name of UpdateSecret, every entry of resource_names. A
field that only holds data, such as an object name, is not read, and neither is a
reference to another API's resource, such as the KMS key of an object or the Pub/Sub
topic of a Scheduler job. Every request message of a stream is checked, so a routing
header or an earlier message does not admit a project it does not name. Requests that
name no project at all are checked against floci-gcp.default-project-id. A project
number of a known project shares the state of its project ID, for the check and for
services.enable and services.disable alike. The consumer metadata and the message carry
the project as the request names it.
Some requests act on a project they do not name, and are checked against that project:
| Request | Project checked |
|---|---|
Cloud Storage requests that name a bucket (/storage/v1/b/{bucket}/..., /{bucket}/{object}, projects/_/buckets/{bucket} on gRPC) |
The project that owns the bucket, whichever project the resource name carries. A copy or rewrite checks the source and the destination. |
BigQuery Storage CreateReadSession and CreateWriteStream |
The project of the table (read_session.table, parent), as well as the session's parent. |
Cloud Storage writes resumed by upload_id (gRPC WriteObject, BidiWriteObject, QueryWriteStatus; resumable chunks on /upload/storage/v1/b/{bucket}/o, a retry of a finished upload included) |
The project that owns the bucket the upload was started for, as well as the bucket in the path. |
Cloud Storage /batch/storage/v1 |
Not checked itself; each request it carries is. |
Firestore requests that name documents (BatchGetDocuments, the writes of Commit, Write and BatchWrite, a Listen target) |
The project of every document named, as well as the database's. |
IAM projects/-/serviceAccounts/{EMAIL_ADDRESS\|UNIQUE_ID} |
The project that owns the service account. |
Cloud Logging entries:write and entries:list, and gRPC WriteLogEntries |
The projects named in the body: every entry's logName, and the resourceNames. |
Firebase Auth client endpoints (accounts:signUp, the secure token endpoint) |
floci-gcp.default-project-id. |
The rejection uses the format of the route: Datastore's HTTP transport answers a
serialized google.rpc.Status (application/x-protobuf), and the Cloud Storage XML API
answers an AccessDenied XML error.
Default-enabled services
A real new project starts with a set of APIs already enabled. With enforcement on,
the APIs in floci-gcp.services.serviceusage.default-enabled count as ENABLED in every
project until they are disabled, and get/list report them that way. The default list
is GCP's documented default set: analyticshub, apptopology, bigquery,
bigqueryconnection, bigquerydatapolicy, bigquerydatatransfer, bigquerymigration,
bigqueryreservation, bigquerystorage, cloudapis, cloudtrace, dataform,
dataplex, datastore, logging, monitoring, servicemanagement, serviceusage,
sql-component, storage-api, storage-component, storage, telemetry
(all .googleapis.com). So Cloud Storage, BigQuery, Datastore, Logging and Monitoring
work out of the box, and everything else must be enabled first:
Which APIs are gated
| Emulated service | API checked |
|---|---|
| Pub/Sub (gRPC + REST) | pubsub.googleapis.com |
| Secret Manager (gRPC + REST) | secretmanager.googleapis.com |
| Cloud Storage (JSON, XML, gRPC) | storage.googleapis.com |
| Firestore (gRPC) | firestore.googleapis.com |
| Datastore (gRPC + REST) | datastore.googleapis.com |
| Cloud Tasks (gRPC) | cloudtasks.googleapis.com |
| Cloud Scheduler (gRPC + REST) | cloudscheduler.googleapis.com |
| Cloud KMS (gRPC + REST) | cloudkms.googleapis.com |
| Cloud Logging (gRPC + REST) | logging.googleapis.com |
| Cloud Monitoring (gRPC + REST) | monitoring.googleapis.com |
| IAM (REST) | iam.googleapis.com |
| Cloud Functions | cloudfunctions.googleapis.com |
| Cloud Run (admin API and invocation proxy) | run.googleapis.com |
| BigQuery | bigquery.googleapis.com |
| BigQuery Storage Read and Write (gRPC) | bigquerystorage.googleapis.com |
| Firebase Auth (Identity Toolkit, Secure Token) | identitytoolkit.googleapis.com |
| GKE | container.googleapis.com |
| Compute Engine | compute.googleapis.com |
| Managed Kafka | managedkafka.googleapis.com |
| Eventarc | eventarc.googleapis.com |
| Cloud SQL | sqladmin.googleapis.com |
Never gated: Service Usage itself, Cloud Resource Manager, IAM Credentials, STS, the
OAuth token endpoint, the shared google.iam.v1.IAMPolicy gRPC mixin (its caller's API
depends on the resource, so it is left open), the shared long-running operations
endpoints, CORS preflight (OPTIONS) requests, and emulator-only endpoints
(/_floci-gcp/..., /emulator/...).
Cloud Resource Manager companion
The Terraform/Pulumi Google providers verify a project exists via
cloudresourcemanager.v1.Projects.GetProject before reading google_project_service.
floci-gcp serves the Cloud Resource Manager v1 projects API for this; see
Resource Manager for the endpoints, the project registry and
strict mode.
Quick Start
provider "google" {
project = "my-project"
service_usage_custom_endpoint = "http://localhost:4588/v1/"
resource_manager_custom_endpoint = "http://localhost:4588/v1/"
}
resource "google_project_service" "run" {
service = "run.googleapis.com"
disable_on_destroy = true
}
Export a fake token first: export GOOGLE_OAUTH_ACCESS_TOKEN=fake-token.
export CLOUDSDK_AUTH_DISABLE_CREDENTIALS=true
export CLOUDSDK_API_ENDPOINT_OVERRIDES_SERVICEUSAGE=http://localhost:4588/
gcloud services enable run.googleapis.com pubsub.googleapis.com --project=my-project
gcloud services list --enabled --project=my-project
gcloud services disable run.googleapis.com --project=my-project --force
ServiceUsageClient client = ServiceUsageClient.create(
ServiceUsageSettings.newHttpJsonBuilder()
.setEndpoint("http://localhost:4588")
.setCredentialsProvider(NoCredentialsProvider.create())
.build());
client.enableServiceAsync(EnableServiceRequest.newBuilder()
.setName("projects/my-project/services/run.googleapis.com")
.build())
.get();
Service service = client.getService(GetServiceRequest.newBuilder()
.setName("projects/my-project/services/run.googleapis.com")
.build());
// service.getState() == State.ENABLED
Scope and deviations
ListServicesreturns only services whose state has been tracked (enabled or later disabled) for the project, plus the default-enabled set when enforcement is on. Real GCP also lists every public API in theDISABLEDstate; the emulator does not ship a catalog of Google APIs.Service.configcarries only the servicename; real GCP includes title, quota, auth, and endpoint configuration.disableDependentServicesandcheckIfServiceHasUsageare accepted and ignored: there is no dependency graph or usage tracking.- Batch limits match real GCP: 20 services per
batchEnable, 30 names perbatchGet, page size capped at 200.