Moorhold docs

Moorhold keeps what should exist as resources in its store, and the reconciler makes the tools match. This page lists every kind you can write, with its fields. It describes the latest release (2026.11.4).

Every resource has the same outer shape:

apiVersion: moorhold/v1alpha1
kind: <Kind>
metadata:
name: <name>
labels: {}
annotations: {}
spec: {}
Field Who sets it What it is
apiVersion you Always moorhold/v1alpha1.
kind you One of the kinds below.
metadata.name you A DNS label: lower-case letters, digits and hyphens, starting and ending with a letter or digit, up to 63 characters. Unique within its kind.
metadata.labels, metadata.annotations you Strings. Some annotations tell Moorhold to do something once, such as moorhold.adopt.
metadata.generation Moorhold Goes up by one each time spec changes.
metadata.resourceVersion Moorhold Changes on every write, so two writers can't overwrite each other.
metadata.finalizers, metadata.deletionTimestamp Moorhold Set while a resource is being torn down.
status Moorhold What the reconciler last saw and did.

status.observedGeneration is the generation the reconciler last acted on. status.conditions is a list of conditions, each with a type, a status (True, False or Unknown), a reason, a message and a lastTransitionTime:

Condition True means
Ready Every tool has what the resource asks for. False with reason Asleep means a tool that sleeps while idle is asleep.
Drifted Something in a tool collides with what Moorhold would create, and Moorhold won't take it over without the moorhold.adopt annotation.
Degraded A tool the resource needs isn't healthy, so Moorhold didn't change it or the tools after it.
BlockedByDependents A delete is waiting, because other objects depend on what it would remove.
Kind What it declares
Stack The server: its tools, sign-in, who proposes and approves, backups and how it's reached. See the Stack resource reference.
Component One tool.
RoleProjection Which role each group has in each tool.
ServiceAccount A login Moorhold uses in a tool.
Source A Postgres database as a source.
RestSource A web service as a source.
IcebergCatalog An Iceberg catalog in the lake.
Proposal A change waiting for approval.
Field Required What it is
role yes The role the tool fills, such as query or bi.
adapter yes The adapter that manages it, such as trino.
version yes The tool's version, from the release's manifest.
digest no The image digest from the manifest. Images are pulled by digest.
endpoint no The URL Moorhold uses for the tool's API.
overrides no Settings for this adapter only. See the Stack resource reference.

status.health is Healthy, Degraded or Unknown.

spec:
groups:
<group>: { <tool>: <role> }

For each Keycloak group, the role it has in each tool. A list means every role the group holds in that tool, base role first. A group with no entry gets least privilege. The installed server's projection:

Group Superset Trino DataHub Airflow
shipboard-admins Admin all Admin Admin
data-engineers Alpha, sql_lab all Editor Viewer
analysts Gamma read-only Reader Viewer
Field Required What it is
component yes The Component it's a login for.
username yes The login's name in that tool.
passwordRef yes A secret reference to its password, such as file:///run/secrets/<name>. Never a value.
usedBy no What uses it, such as reconciler.

A Postgres database, read by the tools named in consumers.

Field Default What it is
type postgres.
connection host, port (default 5432) and database.
consumers all four Which of query, orchestrator, bi and catalog use it.
credentials A login for each consumer: a username and passwordRef. query and catalog may take a lease from a secrets store in its place. Required for each consumer named.
datasets The tables to use, as schema.table.
checks, baselines [] Checks run on the tables, and the frozen baselines some checks compare against.
orchestration.flow A flow file name, for the orchestrator.
catalog.ingestion.schedule 0 * * * * When the catalog reads the source again, as a five-field cron line.

On an installed server, a new Source is refused with: This server can't use a Postgres database as a source. Add a web service instead.

A web service, loaded on a schedule into a schema in the warehouse.

Field Default What it is
baseUrl The service's base URL.
auth How Moorhold signs in. style: header sends a header name whose value is secretRef. style: session posts to loginPath with username and passwordRef, and renews every renewalSeconds. style: clientCredentials gets a token from tokenUrl with clientId and clientSecretRef.
extractor Your extractor, as module:function. The module must sit under one of the Stack's entrypointPrefixes.
resources What to load. Each has a key (also the table's name), a primaryKey, a cursor column, a writeMode (append, merge or replace) and, if the service reports totals, reportedTotal.
rateBudget Required: at most requests in windowSeconds.
backoff 1, 2, 60 initialSeconds, multiplier and maxSeconds between retries.
strain 429, 503 statusCodes that mean the service is under strain, and an optional latencyMultiple of its usual response time. Moorhold stops loading on either.
destination The catalog and schema the tables are written to.
consumers all four Which of query, orchestrator, bi and catalog use it.
schedule 0 6 * * * When the load runs, as a five-field cron line.
checks, baselines [] Checks after each load, before the marts, and their baselines.
marts [] Tables built from the loaded ones once the checks pass.
accessMarts [] Tables mapping a person to the rows they may see.
metrics [] Named measures over the marts, run as the signed-in person.
analyticsTasks [] Your scheduled code that reads marts and writes results. See below.
catalog.ingestion.schedule 0 * * * * When the catalog reads the source again.

An analytics task has a name, an entrypoint (module:function, under the Stack's entrypointPrefixes), the marts it reads, the table it writes, a schedule and a grain: group or person. A task at person grain needs an approved proposal, recorded with the task's hash, and runs only while its code still matches that hash.

Field Default What it is
bucket The lake bucket in the stack's own object store: lake- then lower-case letters, digits and hyphens, up to 63 characters. Leave it out when the Stack has an externalObjectStore.
consumers [query] Only query.

The catalog's name in Trino is the resource's name with - changed to _.

A change to another resource that waits for a person's approval. Agents and proposers create proposals through the portal and its MCP server.

Field What it is
spec.operation create, update or delete.
spec.target The resource it changes: its kind, name and, for create and update, its spec.
spec.proposedBy The user and client that proposed it.
spec.reason Why, up to 2000 characters.
spec.decision Who approved or rejected it, through which client, when, and the outcome.
spec.withdrawal Who withdrew it, and when.
status.phase pending_approval, approved, applied, rejected, withdrawing, withdrawn or removed.
status.plan What applying it would do, per adapter: an adapter, an action and a description.
status.appliedAt, status.removedAt When it was applied, or its change removed again.

See the concept page on proposals and four eyes for who may decide.

HostRequest is a request for the server to do something as root, such as giving an app more memory (memory-resize), setting a secret (set-secret) or adding the sample data (add-sample-data). The portal creates it and the server acts on it. You can't write one with moorhold apply.

Field What it is
spec.action, spec.target What to do, and to what.
spec.approval.route asker or fresh-sign-in. One admin is enough: the admin who asks approves the request by asking. set-secret is approved with fresh-sign-in: the admin signed in again moments before. two-person and sole-approver appear only on requests made before 2026.11.2.
status.phase pending_approval, approved, running, done, refused, failed or cancelled.

An approved request must start within 24 hours of the time it's set for, or it has to be approved again. A request can be set for at most 14 days ahead. A request that has started can't be cancelled. When the server acts on a request, it refuses one approved by someone who's no longer an admin.

Moorhold also stores its own records of first-run setup, updates, mail settings and the server's plan. They aren't kinds you write.