Seed data

LocalCloud accepts YAML fixture data at root operator endpoints. Seeding is partial and service-specific; it is not a migration, backup, or production-data tool.

Load and reload

curl -fsS -X POST http://localhost:24080/seed \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml

The canonical gateway URL applies to manual Docker. With the host CLI, derive the actual gateway URL from localcloud start, localcloud status, or localcloud env because port 24080 can be remapped.

Other routes:

Accepted envelopes

Flat service keys

# docs-example: seed-flat

gcs:
  buckets:
    - name: localcloud-docs-bucket
      objects:
        - key: fixtures/hello.txt
          content: Hello from LocalCloud

pubsub:
  topics:
    - name: docs-events
      subscriptions:
        - name: docs-events-sub

One-project services mapping

# docs-example: seed-services

services:
  gcs:
    buckets:
      - name: localcloud-docs-bucket
  secretmanager:
    secrets:
      - name: docs-api-key
        versions:
          - data: fake-local-value
  bigquery:
    datasets:
      - name: analytics
        location: US
    tables:
      - dataset: analytics
        name: events
        schema:
          fields:
            - name: event_id
              type: STRING
              mode: REQUIRED
        rows:
          - event_id: event-001

BigQuery tables are top-level entries under bigquery.tables; every table names its dataset. Secret Manager records belong under secretmanager.secrets.

Multi-project mapping

# docs-example: seed-projects

projects:
  local-gcp-project:
    services:
      gcs:
        buckets:
          - name: localcloud-main-project
  second-local-project:
    services:
      pubsub:
        topics:
          - name: second-project-events

Supported seed registrars

The reviewed SeedService implementation registers gcs, pubsub, bigquery, spanner, secretmanager, cloudtasks, memorystore, workflows, cloudscheduler (alias scheduler), cloudfunctions (alias functions), alloydb, dataproc, cloudiam (alias iam), cloudsql, bigtable, and sheets.

A registrar can still be unavailable if its service is disabled, its tier is unavailable, or its implementation was not registered in the assembled runtime. Firestore has no enabled seed registrar and is rejected; create Firestore test data through the SDK instead.

Volatile restart mode

curl -fsS -X POST 'http://localhost:24080/seed?mode=volatile' \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml

Volatile mode seeds only Pub/Sub and Bigtable from the current implementation. Firestore is listed internally as volatile but has no implemented registrar, so it remains unavailable. Persistent services are skipped because their service stores are expected to retain data on the volume; this is not a production durability guarantee.

Startup file

Manual Docker users can mount the seed and persistent data together:

docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:24080-24092:24080-24092 \
  -m 4g \
  -v "$PWD/seed.yaml:/etc/localcloud/seed.yaml:ro" \
  -v localcloud-data:/var/lib/localcloud \
  jaysen2apache/localcloud:latest

The mutable image tag remains release-unverified. Prefer localcloud start and pin a qualified digest for release workflows.

Terraform interaction

LOCALCLOUD_TERRAFORM_MODE=true causes seed requests to return a skipped result so Terraform-managed resources are not duplicated. Do not combine a Terraform resource-creation test with implicit startup seed data.

Fixture safety

• Use stable IDs, deterministic values, and small datasets.
• Use fake secret payloads only; never copy production credentials or customer data.
• Assert the data through the same SDK/API path the application uses.
• Reset only the intended project and verify the response before continuing.
• Validate production migrations, backup/recovery, and secret handling separately against real Google Cloud.