Skip to main content

GCS

GCS is the GCP-native recording driver. The gcs driver field configures session recordings. It cannot be used for cluster state or audit events.

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

TL;DR​

  1. Use GCS when AlmaForge runs on GCP and you want recordings to stay inside the same cloud boundary.
  2. Write a StorageConfig with spec.gcs for name: recordings.
  3. Prefer Application Default Credentials on GCE or GKE, and use bucket-side location and lifecycle settings for durability.

Prerequisites​

Before you start, make sure you have:

  • A GCS bucket, or permission for AlmaForge to create it on startup.
  • A GCP service account with the required Cloud Storage permissions.
  • Network reachability from the Auth host to GCS.
  • A decision on whether you are using Application Default Credentials or an explicit JSON key file.

Configuration​

Step 1. Pick the bucket layout​

Use GCS when AlmaForge runs on GCP and you want the recording path to stay inside the same cloud boundary as the rest of the deployment.

There is exactly one recordings instance per cluster. Use a separate backup or replication process when you need another copy. Bucket lifecycle policies control retention and storage class.

Step 2. Write the recordings resource​

With an explicit credentials file:

recordings-credentials.yaml:

examples/storage/gcs/recordings-credentials.yaml
# GCS recording destination using a service-account credentials file.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  gcs:
    bucket: almaforge-recordings
    projectID: my-gcp-project
    credentialsPath: /etc/almaforge/gcp-creds.json

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

recordings-adc.yaml:

examples/storage/gcs/recordings-adc.yaml
# GCS recording destination using Application Default Credentials.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  gcs:
    bucket: almaforge-recordings
    projectID: my-gcp-project
FieldRequiredDefaultNotes
bucketyesnoneGCS bucket name.
projectIDyesnoneGCP project that owns the bucket.
credentialsPathnoADC chainPath to a JSON service account key file when not using ambient GCP credentials.
endpointnoGCS defaultCustom endpoint, usually for testing against the GCS emulator.
kmsKeyNamenounsetCloud KMS key name for customer-managed encryption.
pathnobucket rootPath prefix inside the bucket. Operators usually set this to records.

Step 3. Restart and verify​

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

Terminal
sudo systemctl restart almadalma get storageconfig/recordings -o yaml

Open and end a recorded terminal session, then replay it from the Web UI. Successful replay verifies the recording write and read paths, not just the configured bucket name.

URI form​

Equivalent URI string, suitable for an environment variable or a CLI flag. The URI host is the bucket. The URI path is the optional object prefix:

text
gs://almaforge-recordings/sessions?project_id=my-gcp-project&credentials_path=/etc/almaforge/gcp-sa.json&kms_key_name=projects/my-gcp-project/locations/us/keyRings/r/cryptoKeys/k

The gcs:// scheme is accepted as an alias for gs://. Canonical query keys are snake_case. The typed JSON-tag form (projectID, credentialsPath, kmsKeyName) is accepted as an alias, and the legacy keyName key is accepted for the KMS key. The path prefix may also be passed as ?path=<prefix> for backward compatibility.

Troubleshooting​

The Auth host cannot find credentials​

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

Production config sets endpoint​

That field is usually for the GCS emulator. Remove it from production configs.

You need extra copies of recordings​

Keep one recordings instance and arrange a separate backup or replication process for another copy. Lifecycle rules alone do not create an independent backup.

Operations​

Authentication​

The preferred path is Application Default Credentials. Run the Auth host on GCE or GKE with a service account that has Cloud Storage access, and omit credentialsPath.

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

Bucket policy and placement​

Latency and resilience depend on bucket location. Dual-Region or Multi-Region buckets with Standard storage are the usual production choice.

The required Cloud Storage permissions are storage.buckets.get, storage.objects.create, storage.objects.get, storage.objects.list, and storage.objects.update. storage.objects.delete is needed only to clean up multipart upload parts after they have been composed into the final object. storage.buckets.create is needed only if you want AlmaForge to create the bucket for you.

References​