Skip to content

Commit 9ac7069

Browse files
ArnobKumarSahaArnobKumarSaha
committed
docs(platform): add API-based database creation guide (using-api)
Signed-off-by: Arnob kumar saha <arnob@appscode.com>
1 parent 9e80d93 commit 9ac7069

4 files changed

Lines changed: 403 additions & 0 deletions

File tree

‎docs/platform/guides/database-management/create-database/_index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ The overall flow is the same for every engine and is documented once in
2121
and a handful of engine-specific settings — pick your engine below for a guide tailored to
2222
it, then follow the common steps for everything else.
2323

24+
Prefer to automate this instead of using the UI? See
25+
[**Using the API**](using-api/_index.md) for the equivalent flow driven entirely by API calls.
26+
2427
---
2528

2629
## Supported Engines

‎docs/platform/guides/database-management/create-database/using-api/_index.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
layout: docs
3+
menu:
4+
docsplatform_{{.version}}:
5+
identifier: database-management-create-api
6+
name: Using the API
7+
parent: database-management-create
8+
weight: 6
9+
menu_name: docsplatform_{{.version}}
10+
section_menu_id: guides
11+
---
12+
13+
# Creating a Database via API
14+
15+
Everything the **Create Database** wizard does (see [Common Steps](../../common-steps.md)) can
16+
also be done directly against the platform API — useful for scripting, CI/CD pipelines, or
17+
automating database provisioning without the UI.
18+
19+
The flow is the same for every database engine: fetch the engine's default form values,
20+
render them into a full values model (dry-run), then submit to create the database. Only the
21+
`spec` fields you customize (mode, version, replicas, resources, storage) differ per engine.
22+
23+
## Before You Start
24+
25+
- **Base URL**: `https://<your-host>/api/v1/clusters/<org>/<cluster>`
26+
- **Auth**: every call needs your session cookie and CSRF token:
27+
```
28+
-H "Cookie: <your-session-cookie>"
29+
-H "x-csrf-token: <your-csrf-token>"
30+
-H "content-type: application/json"
31+
```
32+
33+
## The 3-Call Flow
34+
35+
| # | Call | Purpose |
36+
|---|------|---------|
37+
| 1 | `GET /helm/packageview/values` | Get the default form values for the engine |
38+
| 2 | `PUT /helm/options/model` | Render your inputs into a full values model (dry-run) |
39+
| 3 | `PUT /helm/editor` | **Submit — this creates the database** |
40+
41+
Call 1 returns the default config for the engine (all the fields the UI shows, with their
42+
defaults). Note the shape: `form`, `metadata`, and `spec` are **top-level siblings** — the
43+
editable database config lives under the top-level `spec`, not under `form`. Fields like the
44+
available versions and storage classes usually come back empty — set your preferred values
45+
before moving to call 2.
46+
47+
Call 2 takes the `form` object from call 1 with your choices filled in (name, namespace,
48+
version, mode, replicas, resources, storage, etc.) and renders it into the full set of
49+
Kubernetes manifests that would be applied — without creating anything. The response's
50+
`resources` map (e.g. `resources.kubedbCom<Engine>`) is exactly what call 3 will apply, so
51+
this is the point to verify your configuration before submitting.
52+
53+
Call 3 takes the same `form`/`metadata` plus the rendered `resources` map from call 2 and
54+
submits it via `?response-id=<uuid>` (any client-generated UUID, used only to correlate the
55+
request with a progress stream). A `200` response means the database — and its
56+
autoscaler/binding/backup config — has been created.
57+
58+
## Supported Engines
59+
60+
- [MongoDB](../mongodb.md)
61+
- [PostgreSQL](../postgres.md)
62+
63+
> More engines will be documented here as their API flows are captured. Until then, follow
64+
> the pattern above against `GET /helm/packageview/values` with your engine's `kind` (e.g.
65+
> `Redis`, `MySQL`) to discover its fields.

‎docs/platform/guides/database-management/create-database/using-api/mongodb.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
layout: docs
3+
menu:
4+
docsplatform_{{.version}}:
5+
identifier: database-management-create-api-mongodb
6+
name: MongoDB
7+
parent: database-management-create-api
8+
weight: 10
9+
menu_name: docsplatform_{{.version}}
10+
section_menu_id: guides
11+
---
12+
13+
# Creating a MongoDB Database via API
14+
15+
This page walks through the API calls needed to provision a MongoDB database, equivalent
16+
to using the **Create Database** wizard in the UI at
17+
`/db/<org>/<cluster>/kubedb.com/v1/mongodbs/create`. See
18+
[Using the API](../_index.md) for the general 3-call flow and
19+
[MongoDB](../../mongodb.md) for the Database Mode options this flow configures.
20+
21+
**Example values used throughout**: namespace `demo`, database name `mgc`, MongoDB version
22+
`8.0.17`, 3-replica replica set, `900m` CPU / `1Gi` memory per node, `2Gi` storage on
23+
`local-path` storage class. Swap these for your own.
24+
25+
---
26+
27+
## 1. Get Default Form Values
28+
29+
```bash
30+
curl -sk "$BASE_URL/helm/packageview/values" \
31+
-H "Cookie: $COOKIE" -H "x-csrf-token: $CSRF" \
32+
--get \
33+
--data-urlencode "name=kubedbcom-mongodb-editor-options" \
34+
--data-urlencode "sourceApiGroup=source.toolkit.fluxcd.io" \
35+
--data-urlencode "sourceKind=HelmRepository" \
36+
--data-urlencode "sourceNamespace=kubeops" \
37+
--data-urlencode "sourceName=appscode-wizards-oci" \
38+
--data-urlencode "version=v0.35.0" \
39+
--data-urlencode "group=kubedb.com" \
40+
--data-urlencode "kind=MongoDB" \
41+
--data-urlencode "variant=default" \
42+
--data-urlencode "namespace=demo" \
43+
--data-urlencode "format=json"
44+
```
45+
46+
> The `version` query param (`v0.35.0` above) is the wizard chart version — it gets bumped
47+
> by 1 with each kubedb-platform release.
48+
49+
**Example response** (trimmed):
50+
51+
```json
52+
{
53+
"form": {
54+
"alert": { "enabled": "critical", "groups": { "...": "..." } }
55+
},
56+
"metadata": {
57+
"release": { "name": "", "namespace": "demo" },
58+
"resource": { "group": "kubedb.com", "kind": "MongoDB", "version": "v1alpha2" }
59+
},
60+
"spec": {
61+
"admin": { "databases": { "MongoDB": { "versions": { "default": "", "available": [] } } } },
62+
"mode": "Replicaset",
63+
"podResources": { "machine": "", "resources": { "requests": { "cpu": "900m", "memory": "1Gi" } } },
64+
"persistence": { "size": "2Gi" },
65+
"storageClasses": null,
66+
"replicaSet": { "name": "rs0", "replicas": 3 }
67+
}
68+
}
69+
```
70+
71+
Fields like `spec.admin.databases.MongoDB.versions.default` and `spec.storageClasses` come
72+
back empty/null — the defaults don't pick a version or storage class for you. Set your
73+
preferred values in these fields (version, storage class, mode, replicas, resources,
74+
storage size) before passing the config to call 2.
75+
76+
> `spec.mode` also accepts `Standalone` and `Sharded` — see
77+
> [MongoDB Database Mode](../../mongodb/#database-mode) for the fields each mode adds
78+
> (e.g. `Sharded` needs shard/config-server/mongos sections instead of `replicaSet`).
79+
80+
---
81+
82+
## 2. Render the Values Model (Dry-Run)
83+
84+
Take the `form` object from call 1, fill in your choices, and submit it here. No database
85+
is created yet — this only validates and renders the config.
86+
87+
```bash
88+
curl -sk -X PUT "$BASE_URL/helm/options/model" \
89+
-H "Cookie: $COOKIE" -H "x-csrf-token: $CSRF" -H "content-type: application/json" \
90+
--data-binary @request-model.json
91+
```
92+
93+
Key fields to change per deployment, in the request body:
94+
95+
```json
96+
{
97+
"metadata": {
98+
"release": { "name": "mgc", "namespace": "demo" }
99+
},
100+
"spec": {
101+
"mode": "Replicaset",
102+
"replicaSet": { "name": "rs0", "replicas": 3 },
103+
"podResources": {
104+
"resources": { "requests": { "cpu": "900m", "memory": "1Gi" }, "limits": { "cpu": "900m", "memory": "1Gi" } }
105+
},
106+
"persistence": { "size": "2Gi" }
107+
}
108+
}
109+
```
110+
111+
`spec.admin.databases.MongoDB.versions.default` in the same body controls the version
112+
(e.g. `"8.0.17"`).
113+
114+
**Example response** (trimmed):
115+
116+
```json
117+
{
118+
"form": { "...": "echoes back your form, resolved" },
119+
"resources": {
120+
"kubedbComMongoDB": {
121+
"apiVersion": "kubedb.com/v1",
122+
"kind": "MongoDB",
123+
"spec": {
124+
"replicas": 3,
125+
"replicaSet": { "name": "rs0" },
126+
"storage": { "storageClassName": "local-path", "resources": { "requests": { "storage": "2Gi" } } },
127+
"version": "8.0.17"
128+
}
129+
},
130+
"autoscalingKubedbComMongoDBAutoscaler": { "...": "rendered autoscaler CR" },
131+
"catalogAppscodeComMongoDBBinding": { "...": "rendered binding CR" },
132+
"coreKubestashComBackupConfiguration": { "...": "rendered backup config CR" }
133+
}
134+
}
135+
```
136+
137+
This is the key thing to check before submitting: `resources.kubedbComMongoDB` is exactly
138+
what call 3 will apply.
139+
140+
---
141+
142+
## 3. Submit — Creates the Database
143+
144+
```bash
145+
RESPONSE_ID=$(uuidgen)
146+
curl -sk -X PUT "$BASE_URL/helm/editor?response-id=$RESPONSE_ID" \
147+
-H "Cookie: $COOKIE" -H "x-csrf-token: $CSRF" -H "content-type: application/json" \
148+
--data-binary @request-editor.json
149+
```
150+
151+
`response-id` is any UUID you generate client-side — the server doesn't validate it against
152+
earlier calls, it's only used to correlate this request with a response/progress stream.
153+
154+
The body is the same `form`/`metadata` as call 2, plus the `resources` map from call 2's
155+
response — the fully rendered manifests that get applied via Helm:
156+
157+
- `kubedbComMongoDB` — the MongoDB custom resource itself
158+
- `autoscalingKubedbComMongoDBAutoscaler` — autoscaler config
159+
- `catalogAppscodeComMongoDBBinding` — service binding for the UI
160+
- `coreKubestashComBackupConfiguration` — backup schedule/config
161+
162+
A `200` response means the database (and its autoscaler/binding/backup config) has been
163+
created. Confirm with:
164+
165+
```bash
166+
curl -sk "$BASE_URL/proxy/kubedb.com/v1alpha2/namespaces/demo/mongodbs/mgc" \
167+
-H "Cookie: $COOKIE" -H "x-csrf-token: $CSRF"
168+
```

0 commit comments

Comments
 (0)