Operations

LiveVerification Required

ObjectDB operator runbooks.

ObjectDB operator runbooks for local startup, health, platform capabilities, S3 Core smoke, data-directory checks, common errors, unsupported S3 behavior, and support evidence handoff.

Current availability

Private Beta. Public beta is scheduled for September 7, 2026.

Runbook Snapshot

Runbooks: 6
Smoke steps: 9
Error entries: 10
Review state: Pending

Runbook Summary

ObjectDB operator runbook coverage
Runbook	Severity	Scope	First check	Evidence
Startup and health smoke	P2 to P4	Local service process and /health route	Confirm OBJECTDB_BIND_ADDRESS, service terminal, and GET /health response.	ODB-EVID-007, DOCS-029
Platform capability check	P2 to P4	/v1/platform/capabilities and startup probe output	Confirm data directory, flush behavior, atomic rename, free space, device, and direct I/O fields.	ODB-EVID-008, DOCS-030
Data-directory check	P2 to P4	OBJECTDB_DATA_DIR and temporary local state	Confirm the path is disposable, writable, and matches the capability response.	ODB-EVID-008, DOCS-030
S3 Core smoke	P2 to P4	Bucket create, object put/get, list, cleanup	Run path-style bucket/object smoke commands against the local endpoint.	ODB-EVID-006, ODB-EVID-007
Unsupported S3 behavior triage	P3 to P4	Versioning, Object Lock, lifecycle, replication, inventory, notifications, SelectObjectContent, ACLs, website hosting	Confirm unsupported families return S3-shaped NotImplemented and stay out of operator promises.	ODB-EVID-009, ODB-EVID-010
Support evidence handoff	P2 to P4	Redacted command output, response headers, platform JSON, and logs	Capture evidence before mutation and redact sensitive data before sharing.	DOCS-049, DOCS-050

Service Startup

Run service startup in one terminal, then run the smoke checks in a second terminal.

export OBJECTDB_SOURCE=/path/to/Service.ObjectDB
export OBJECTDB_BIND_ADDRESS=127.0.0.1:18080
export OBJECTDB_DATA_DIR="${TMPDIR:-/tmp}/objectdb-docs-050"
cd "$OBJECTDB_SOURCE"
cargo run --package objectdb

Local Smoke Test

Configure check terminal

Smoke step

export OBJECTDB_ENDPOINT=http://127.0.0.1:18080
export OBJECTDB_BUCKET=ops-docs-050
export OBJECTDB_KEY=smoke/object.txt
export OBJECTDB_BODY_FILE=/tmp/objectdb-docs-050-body.txt
printf 'objectdb-operator-smoke' > "$OBJECTDB_BODY_FILE"

Expected signal

Endpoint, bucket, key, and a small body file are ready.

Capture: Endpoint value, bucket name, object key, and body byte count.

Health

Smoke step

curl -i "$OBJECTDB_ENDPOINT/health"

Expected signal

200 OK with JSON string "Healthy".

Capture: Status, headers, endpoint value, and service terminal state.

Platform capabilities

Smoke step

curl -s "$OBJECTDB_ENDPOINT/v1/platform/capabilities"

Expected signal

JSON includes dataDirectory.path, flushBehavior, atomicRename, freeSpace, device, and directIo.

Capture: Redacted JSON response and configured OBJECTDB_DATA_DIR.

Create bucket

Smoke step

curl -i -X PUT "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET"

Expected signal

200 OK with x-objectdb-s3-profile: s3-core-v1 and x-objectdb-s3-operation: CreateBucket.

Capture: Status, operation header, request ID, and bucket name.

Put object

Smoke step

curl -i -X PUT \
  -H "x-amz-content-sha256: UNSIGNED-PAYLOAD" \
  --data-binary @"$OBJECTDB_BODY_FILE" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"

Expected signal

200 OK with x-objectdb-s3-operation: PutObject and local body size headers.

Capture: Status, operation header, object key, payload size, and body path.

Get object

Smoke step

curl -i "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"

Expected signal

200 OK with x-objectdb-s3-operation: GetObject and the uploaded payload.

Capture: Status, operation header, content length, and redacted payload.

List objects

Smoke step

curl -i "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET?list-type=2&prefix=smoke/"

Expected signal

200 OK with x-objectdb-s3-operation: ListObjectsV2 and the smoke key in XML.

Capture: Status, operation header, prefix, and key count.

Unsupported behavior

Smoke step

curl -i "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET?versioning"

Expected signal

501 Not Implemented with x-objectdb-s3-operation: GetBucketVersioning and NotImplemented XML.

Capture: Status, operation header, error code, and query shape.

Cleanup

Smoke step

curl -i -X DELETE "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"
curl -i -X DELETE "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET"
rm -f "$OBJECTDB_BODY_FILE"
rm -rf "${TMPDIR:-/tmp}/objectdb-docs-050"

Expected signal

Object and bucket cleanup completes, then only the disposable smoke files are removed.

Capture: Delete statuses and the exact data directory cleanup target.

Data-Directory Checks

ObjectDB data-directory checks
Check	Command	Expected signal	Evidence to capture
Confirm configured path	`printf '%s\n' "$OBJECTDB_DATA_DIR"`	Path is disposable for local smoke checks or explicitly approved for the environment.	Configured value and operator note.
Compare platform response	`curl -s "$OBJECTDB_ENDPOINT/v1/platform/capabilities"`	dataDirectory.path matches the expected ObjectDB data directory.	Redacted capability JSON and timestamp.
Confirm writable path before startup	`mkdir -p "$OBJECTDB_DATA_DIR" test -w "$OBJECTDB_DATA_DIR"`	Command exits successfully.	Path, owner, permission mode, and filesystem context.
Avoid shared-state cleanup	`test "$OBJECTDB_DATA_DIR" != "/"`	Cleanup target is not root, a home directory, or a shared product directory.	Cleanup command and reviewer note before deletion.

Common Errors

ObjectDB operator triage entries
Symptom	Likely cause	First check	Remediation
Health check cannot connect	Service is not running, still compiling, or bound to a different address.	Compare OBJECTDB_BIND_ADDRESS with OBJECTDB_ENDPOINT and check the service terminal.	Start the service on an unprivileged loopback port and retry /health.
Startup platform probe fails	Data directory cannot be created, written, flushed, renamed, or inspected.	Read service stderr and verify OBJECTDB_DATA_DIR.	Choose a writable local path; capture stderr and capability context before retrying.
BucketAlreadyOwnedByYou	The smoke bucket already exists in local service state.	Check bucket name and data directory reuse.	Reuse the bucket intentionally, clean it up, or choose a unique smoke bucket.
NoSuchBucket or NoSuchKey	Bucket or key was not created in the current data directory.	Confirm bucket/key values and list current objects.	Create the bucket/object again or point at the intended data directory.
BucketNotEmpty	Visible current objects remain in the bucket.	Run ListObjectsV2 with the smoke prefix.	Delete current smoke objects before deleting the bucket.
BadDigest	Supplied checksum header does not match the uploaded payload.	Check checksum headers and body file contents.	Use UNSIGNED-PAYLOAD for local smoke or regenerate checksums for the exact payload.
EntityTooLarge	Body chunk or temporary local adapter body exceeds current caps.	Check body size and response headers.	Use a smaller payload or a supported multipart path; do not present this as a broad object-size limit.
InvalidURI	Request target, host, query, or virtual-host base-domain shape is invalid.	Compare path-style request with OBJECTDB_S3_BASE_DOMAINS.	Use path-style addressing or correct base-domain configuration.
SlowDown or RequestTimeout	S3 ingress concurrency is saturated or the body stream stalled.	Capture response headers such as Retry-After.	Retry after the indicated delay or fix the client connection.
NotImplemented	Request is outside the active s3-core-v1 profile.	Check the compatibility matrix and known limits.	Use a supported S3 Core route or record an unsupported-behavior follow-up.

Unsupported S3 Behavior

Unsupported S3 families include versioning, Object Lock, lifecycle, replication, inventory, notifications, SelectObjectContent, ACLs, and website hosting. Treat those requests as known limits, not as incidents by themselves.

Capture The ResponseRecord status, operation header, error code, request path, query string, and redacted request ID.
Link The LimitLink the compatibility or known-limits row that explains the unsupported S3 family.
Find A Supported PathConfirm whether bucket and object operations in the active S3 Core profile satisfy the application need.
Avoid False EscalationEscalate only when a supported route is failing or the unsupported behavior was documented incorrectly.

Support Evidence

ObjectDB support evidence package
Include	Source	Redact or exclude
Health response status and headers	GET /health	External tokens and unrelated headers.
Platform capability JSON	GET /v1/platform/capabilities	Absolute paths only when they reveal private user names or customer identifiers.
S3 response headers and XML errors	Smoke commands and affected request	Bearer tokens, access keys, payload contents, tenant identifiers, and customer object keys when sensitive.
Data-directory context	OBJECTDB_DATA_DIR, startup stderr, filesystem check result	Customer payloads, unrelated directory listings, and secrets in shell history.
Compatibility and limits links	DOCS-038, DOCS-042, ODB-EVID-009, ODB-EVID-010	Unreviewed claims or roadmap promises.

Safety Rules

Capture Before Mutation

Record health, platform, response headers, XML errors, request IDs, and data-directory context before cleanup or retry steps change the signal.

Protect Local State

Only remove the disposable DOCS-050 smoke directory. Shared ObjectDB data directories need owner review before cleanup.

Do Not Promote Claims

Passing local smoke checks does not approve stronger durability, support, security, scale, customer credential, or broad S3 wording.

Evidence

DOCS-050 evidence map
Runbook area	Evidence	Status
Health and platform routes	DOCS-029, DOCS-030, ODB-EVID-007, ODB-EVID-008	pending
Local smoke commands	DOCS-022, ODB-EVID-006, Validate-S3HttpGateway.sh	pending
S3 Core compatibility and unsupported behavior	DOCS-038, DOCS-042, ODB-EVID-009, ODB-EVID-010	pending
ObjectDB operator runbook artifact	DOCS-050 and /products/objectdb/operations/operator-runbooks/	pending

Internal review records track this ObjectDB runbook page and its evidence handoff requirements.

Safe Next Steps

Available: DOCS-029
Read S3 and HTTP reference
Use route shapes, headers, errors, limits, and local adapter details when triaging ObjectDB requests.
Available: DOCS-030
Read configuration reference
Check bind address, data directory, S3 base domains, fixed ingress limits, and platform capability requirements.
Available: DOCS-042
Review known limits
Separate unsupported S3 requests from incidents on supported S3 Core routes.
Available
Review ObjectDB evidence
Use ODB evidence records before strengthening runbook or support wording.