Seed data

LocalCloud accepts YAML fixture data at root operator endpoints. Seeding covers the service registrars listed below; it is not a migration, backup, or production-data tool.

Load and reload

curl -fsS -X POST http://localhost:5380/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 5380 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, sheets, firestore, and kms.

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 a seed registrar and is disabled by default. Enable it explicitly and consult its operation contract. A registrar or successful fixture import does not establish complete query, listener, or recovery fidelity.

Volatile restart mode

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

The current VOLATILE_SEED_SERVICES set is empty, so volatile mode selects no services. Pub/Sub now uses PostgreSQL persistence. Use normal explicit seeding for test-owned fixtures; retaining a volume is not a production durability guarantee.

Startup file

Container startup and the Console own automatic samples. The CLI does not discover, mount, or apply seed files; host.seed is accepted but ignored. Set server.auto_seed: false to disable bootstrap samples. 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:5380-5405:5380-5405 \
  -m 4g \
  -v "$PWD/seed.yaml:/opt/localcloud/seed.yaml:ro" \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest

The latest image tag is mutable. Prefer localcloud start, and pin an image 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.