Deployment bodies

​

The body

{
  "schemaVersion": 1,
  "metadata": { "name": "graph-prod", "namespace": "team-a", "labels": { "team": "search" } },
  "spec": {
    "version": "4.22.0",
    "topology": { "mode": "replication", "replicas": 3 },
    "nodes": {
      "resources": { "requests": { "cpu": "1", "memory": "4Gi" }, "limits": { "memory": "4Gi" } },
      "storage": { "size": "50Gi", "storageClass": "gp3" }
    },
    "sentinels": { "replicas": 3 },
    "config": {
      "graph": { "THREAD_COUNT": "8" },
      "enterprise": { "falkordbe.idle-threshold-ms": "60000" },
      "server": { "maxmemory-policy": "noeviction" }
    },
    "networking": {
      "externalDomain": "db.example.com",
      "services": [{ "name": "public", "target": "nodes", "type": "LoadBalancer" }]
    },
    "security": { "tls": { "issuer": "Enterprise" }, "auth": { "password": "…" } },
    "backup": { "schedule": "0 2 * * *" },
    "observability": { "exporter": true },
    "lifecycle": { "state": "Running", "deletionPolicy": "DoNotTerminate" }
  }
}

​

Create, read and change

curl -sS -b cookies.txt -X POST https://admin.example.com/api/clusters \
  -H 'Content-Type: application/json' -d @graph-prod.json

curl -sS -b cookies.txt \
  'https://admin.example.com/api/clusters/graph-prod?namespace=team-a&schemaVersion=1'

curl -sS -b cookies.txt -X PATCH \
  'https://admin.example.com/api/clusters/graph-prod?namespace=team-a' \
  -H 'Content-Type: application/merge-patch+json' -H 'If-Match: "7"' \
  -d '{"schemaVersion":1,"spec":{"topology":{"replicas":5}}}'

• GET /api/clusters?schemaVersion=1 lists deployments as { "schemaVersion": 1, "deployments": [...], "total": N }.
• PATCH takes a JSON Merge Patch: send only what changes. Objects merge, lists are replaced whole, and null removes a field.
• PUT takes a whole body. Fields it leaves out are removed, with these exceptions:
  • config.enterprise and config.server: only the settings it names change.
  • version, componentDefinition, and lifecycle’s state and deletionPolicy: these keep their current values, so leaving them out doesn’t upgrade, start a stopped deployment, or drop DoNotTerminate.
  • Labels and annotations that other tools manage. These keep their current values when the body leaves them out. Their key prefix is one of:
    • kubeblocks.io/ or falkordb.cloud/, or a subdomain of one, such as apps.kubeblocks.io/ or keel.falkordb.cloud/.
    • app.kubernetes.io/, exactly.
    • A domain in the Admin Server’s ADMIN_SERVER_PRESERVED_LABEL_PREFIXES, or a subdomain of one.
    Legacy falkordb.io/ and falkordb.com/ keys are moved to falkordb.cloud/ with the same name, and kept there.
  To remove a tool-managed label or annotation, PATCH it to null by name, for example {"schemaVersion": 1, "metadata": {"labels": {"keel.falkordb.cloud/cell": null}}}. Setting the whole map to null ("labels": null) removes only the other labels; the tool-managed ones stay. Reserved annotations can’t be removed at all, even by name: those under kubeblocks.io/ or apps.kubeblocks.io/, and the Admin Server’s own TLS and pending-settings annotations. A null for one of them is ignored. A PUT of what a read returns changes nothing. That includes a Sentinel left on an older addon release: to bring it to the data nodes’ definition, PATCH spec.componentDefinition. Don’t send backup or an inline password again: both are set at create time only.
• If-Match takes the metadata.generation you read. When the deployment changed since, the update is refused with 412 instead of overwriting the other change.
• ?dryRun=true returns what the update would do without doing it.

​

Rules an update follows

• Volumes only grow, and their storage class can’t change.
• A deployment can’t move between sharded and not sharded, or gain or lose sentinels. A primary with replicas and no sentinels can become a single node and back.
• The FalkorDB version can’t go back.
• config.enterprise and config.server change only while the deployment is running. See how settings are applied for which ones restart the pods, and how to reset or empty one.
• Settings and volume growth are applied after the write, and only while the deployment is running: otherwise they answer 409.
• While earlier settings or volume growth still wait to be applied, another update that queues some answers 409. Retry once they are applied.
• While a Reconfiguring operation runs, an update that sets one of its settings to another value answers 409; the same value is taken as already on its way.
• A request that stops the deployment can’t also change settings or grow volumes: that answers 422.
• config.server can’t set the directives the FalkorDB addon manages: the listening port and TLS, accounts (requirepass, user, …), modules, the data directory and file names, replication and cluster wiring, announced addresses, logfile, pidfile, and the switches that open MODULE and DEBUG.
• GET /api/clusters/{name}/config shows credentials set as enterprise settings only to users who may read the deployment’s credentials (clusters:update). Anyone else sees (redacted).
• A field set outside this API is not overwritten: the update answers 422 naming it. Add ?overwriteUnmanaged=true to replace it.

​

How settings are applied

• An enterprise setting set to null goes back to its default. When the default is empty, as with the LDAP settings, null or "" empties it, so setting falkordbe.ldap_servers to null turns LDAP authentication off. An empty value for any other enterprise setting answers 422.
• A config.graph setting set to null is removed, and the server uses its default.
• A config.server directive has no default the API knows, so null answers 422: set the value you want. "" empties a directive that is applied on the fly. A directive that needs a restart can’t be emptied, because a bad empty value could keep the pods from starting.
• A whole section (config.server: null) can’t be removed.

​

Errors

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Invalid deployment: spec.topology.replicas: required for mode 'replication'",
  "issues": [{ "path": "spec.topology.replicas", "message": "required for mode 'replication'" }]
}

​

Deprecated requests