Firestore

Firestore is the GCP-native shared driver. The same firestore driver field works for cluster state and audit events. It is the natural fit when the Auth Service runs on GCP and you want a managed control-plane store without running PostgreSQL or etcd yourself.

Storage concern	Supported
Cluster state (name: state)	yes
Audit events (name: audit-*)	yes
Session recordings (name: recordings)	no

TL;DR

1. Use Firestore when the cluster already lives on GCP and you want Google-managed storage and identity handling.
2. Write one spec.firestore StorageConfig for name: state and separate audit-* resources for audit events.
3. Pair Firestore with GCS for session recordings.

Prerequisites

Before you start, make sure you have:

• A GCP project with Firestore enabled.
• A service account with read, write, and admin permissions on the target Firestore collection.
• A planned collection name for state and a different one for audit events.
• A decision on whether you are using Application Default Credentials or an explicit JSON key file.

Application Default Credentials work when the Auth host runs on GCE or GKE with an attached service account. Otherwise, supply a JSON key file.

Configuration

Step 1. Pick the collection layout

Use Firestore when the Auth Service runs on GCP and you want a managed driver that fits the rest of the deployment.

Use a different collection for cluster state and audit events. The schemas differ, and reusing the state collection breaks the driver.

Step 2. Write the state backend resource

Every Auth Service instance points at the same state collection:

state-credentials.yaml:

examples/storage/firestore/state-credentials.yaml

# Firestore state backend using a service-account credentials file.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: state
spec:
  firestore:
    projectID: my-gcp-project
    collectionName: almaforge-state
    credentialsPath: /etc/almaforge/firestore-creds.json

If the Auth host runs on GCE or GKE with an attached service account, omit credentialsPath:

state-adc.yaml:

examples/storage/firestore/state-adc.yaml

# Firestore state backend using Application Default Credentials.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: state
spec:
  firestore:
    projectID: my-gcp-project
    collectionName: almaforge-state

Field	Required	Default	Notes
projectID	yes	none	GCP project that owns the Firestore collection.
collectionName	yes	none	Firestore collection used for cluster state.
credentialsPath	no	ADC chain	Path to a JSON service account key file when not using ambient GCP credentials.
endpoint	no	Firestore default endpoint	Useful for the Firestore emulator.
purgeExpiredDocumentsPollInterval	no	1m	Cleanup interval for expired state documents.
retryPeriod	no	10s	Retry interval for long-lived operations.
disableExpiredDocumentPurge	no	false	Disables built-in expired-document cleanup.
bufferSize	no	1024	Event watcher buffer capacity.

Step 3. Write any audit-events resources

The same firestore driver field works for audit-events instances:

audit-credentials.yaml:

examples/storage/firestore/audit-credentials.yaml

# Firestore audit destination using a service-account credentials file.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-primary
spec:
  firestore:
    projectID: my-gcp-project
    collectionName: almaforge-audit
    credentialsPath: /etc/almaforge/firestore-creds.json

You can fan out across multiple GCP projects by adding more audit-* instances:

audit-fanout.yaml:

examples/storage/firestore/audit-fanout.yaml

# Two Firestore destinations that each receive every audit event.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-primary
spec:
  firestore:
    projectID: my-gcp-project
    collectionName: almaforge-audit
---
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-secondary
spec:
  firestore:
    projectID: my-other-gcp-project
    collectionName: almaforge-audit

Both state and audit honor the same Application Default Credentials chain or explicit credentialsPath.

Retention lives on the driver block as auditRetentionPeriod. Firestore honors it via a background purge.

Step 4. Restart and verify

Restart the Auth Service after updating the bootstrap file, then verify the active resources:

Terminal

sudo systemctl restart almadalma get storageconfig/state -o yamlalma get storageconfig/audit-primary -o yaml

The configuration is loaded when the output names the intended project and collections. Sign in again and confirm that the login event appears in the audit log to check the write path.

URI form

Equivalent URI strings, suitable for an environment variable or a CLI flag. The URI host is the collection name. Other fields go in the query string.

State backend:

text

firestore://cluster-state?project_id=my-gcp-project&credentials_path=/etc/almaforge/gcp-sa.json

Audit backend with retention:

text

firestore://cluster-events?project_id=my-gcp-project&credentials_path=/etc/almaforge/gcp-sa.json&audit_retention_period=168h

Canonical query keys are snake_case (project_id, credentials_path, audit_retention_period). The camelCase form used in StorageConfig resources (projectID, credentialsPath, auditRetentionPeriod) is accepted as an alias. The earlier eventRetentionPeriod key also remains accepted for compatibility.

Troubleshooting

State and audit share one collection

Split them. The schemas differ, and audit writes fail against the state collection.

Production config sets endpoint

That field exists for the Firestore emulator. Leave it out of production configs.

The Auth host cannot find credentials

Either run on GCE or GKE with an attached service account so Application Default Credentials work, or set credentialsPath to a readable JSON key file.

Operations

Authentication

The preferred path is to run the Auth host on GCE or GKE with an attached service account that has Firestore access. Omit credentialsPath and AlmaForge uses the Application Default Credentials chain.

If you cannot rely on ambient GCP identity, point credentialsPath at a JSON service account key file. On Linux Auth hosts, keep the file owned by root:root with mode 0600. Mount credentials as a Secret when deploying on Kubernetes.

Driver limits

Session recordings do not live in Firestore. Pair this driver with GCS for the recordings instance.

Use separate collections for state and audit. They do not share a schema.

References

• Storage backends overview.
• High availability.
• Break-glass access.
• GCS.