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.
  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. A setting can’t be removed or emptied, only set to a value: to undo a change, set it to its default. null or an empty value answers 422, so an enterprise setting whose default is empty (the LDAP ones) can’t be emptied again once set.
• 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, replication and cluster wiring, announced addresses, logfile, 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.

​

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