Skip to content

Commit 85cacd1

Browse files
sivanov-nuodbsivanov-nuodb
committed
Initial commit
1 parent 1187496 commit 85cacd1

File tree

8 files changed

+793
-0
lines changed

8 files changed

+793
-0
lines changed

‎DatabaseInjector.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Database Injector Guide
2+
3+
NuoDB Control Plane (CP) can be used to create NuoDB databases for applications that are running in the same [Kubernetes][1] cluster.
4+
This document describes how to use database injector to supply database connection information to sample YCSB application.
5+
6+
## Prerequisites
7+
8+
- A running [Kubernetes cluster][2]
9+
- [kubectl][3] installed and able to access the cluster.
10+
11+
## Installing NuoDB Control Plane
12+
13+
Install NuoDB CP as documented in [Installation](../README.md#installation) section.
14+
15+
### Enable Cluster-scoped Access
16+
17+
By default NuoDB operator will monitor only the local namespace for NuoDB [custom resources][4].
18+
If cluster-scoped access is required, set the `cpOperator.watchNamespace.enabled=false` Helm value during installation. E.g.:
19+
20+
```sh
21+
helm install nuodb-cp-operator nuodb-cp/nuodb-cp-operator \
22+
--namespace nuodb-cp-system \
23+
--set cpOperator.watchNamespace.enabled=false \
24+
--set nuodb.serviceAccount.create=false \
25+
--set nuodb.serviceAccount.name=default \
26+
...
27+
```
28+
29+
>**Note**
30+
> The `nuodb` service account (SA) creation is disabled in the above command for simplicity. To enable NuoDB Kubernetes Aware Admin (KAA) capabilities, the NuoDB processes should be given special permissions to access Kubernetes API server.
31+
For more information, please check [Automatic Management of NuoDB State](https://doc.nuodb.com/nuodb/latest/deployment-models/kubernetes-environments/kubernetes-aware-admin/). For cluster-scoped deployments, the NuoDB SA and RBAC should be provisioned before hand in each namespace where NuoDB databases are created.
32+
33+
## Database Injection
34+
35+
NuoDB operator can inject database information into ConfigMap's _data_ once the database is ready.
36+
This enables easy data source configuration in the application container and acts as a dependency mechanism without the need of additional _init_ containers.
37+
38+
Database connection details are populated _after_ the database is created and ready to accept SQL connections which blocks application container creation.
39+
All containers that have references to the target ConfigMap will fail with `CreateContainerConfigError` due to the ConfigMap key being absent.
40+
41+
### Injected Properties
42+
43+
| Property | Description |
44+
| ----- | ----------- |
45+
| `dbName` | NuoDB database name |
46+
| `dbHost` | The FQDN of the domain managing this database. If external access is enabled on the domain, the property will be populated with the external FQDN. |
47+
| `dbPort` | The database port for SQL clients. If external access is enabled on the domain, the property will be populated with the Ingress Controller's service port (by default _443_). |
48+
| `caPem` | The Certificate Authority (CA) certificate for the domain. Used by SQL clients that need to enable TLS encryption on the database connections. If TLS is not enabled on the domain, the property is not injected. |
49+
50+
### Creating Database
51+
52+
NuoDB domain and database resources can be created either via REST API or declaratively using [custom resources][4].
53+
This example creates NuoDB domain and database using custom resources.
54+
55+
```sh
56+
kubectl apply -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/domain.yaml
57+
kubectl apply -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/database.yaml
58+
```
59+
60+
## Creating Sample Application
61+
62+
Create a sample Yahoo! Cloud Serving Benchmark (YCSB) application and reference the database information into the _app_ container.
63+
64+
```sh
65+
kubectl apply -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/ycsb-demo-app.yaml
66+
```
67+
68+
Wait for the database to become ready.
69+
70+
```sh
71+
kubectl wait --for=condition=ready database acme-messaging-demo
72+
```
73+
74+
Verify that database information is injected into `acme-messaging-demo-info` ConfigMap's data and the YCSB Pod is _Running_.
75+
76+
```sh
77+
kubectl get cm acme-messaging-demo-info -o yaml
78+
kubectl get pods -l app=ycsb-load
79+
```
80+
81+
### Injector Configuration
82+
83+
Database injection is controlled by custom annotations specified on the target ConfigMap.
84+
85+
| Annotation | ConfigMap data key | Description | Example Value |
86+
| ----- | ----- | ----------- | ------ |
87+
| `cp.nuodb.com/inject-database` | `cp.inject-database` | Specifies that the object should be injected with database information. The annotation value is a reference to a database object in form of "name" or "namespace/name". If the namespace part is omitted, it is inferred from the target ConfigMap. | `acme-messaging-demo` |
88+
| `cp.nuodb.com/inject-database-properties` | `cp.inject-database-properties` | Specifies the database properties that should be injected into the target object. The value is a comma-delimited string of properties. By default, all connection information properties are injected. | `dbHost,dbName` |
89+
| `cp.nuodb.com/inject-database-<property>-field` | `cp.inject-database-<property>-field` | Specifies the database property to target field mapping. By default the field name will match the property name, e.g. "dbHost" property will be injected as "dbHost" field. See [Injected Properties](#injected-properties). | `"cp.nuodb.com/inject-database-dbHost-field": "host"` |
90+
| `cp.nuodb.com/inject-database-notready` | `cp.inject-database-notready` | Whether a non-ready database should be injected. Only the annotation existence is checked. Its value is currently not used. By default, the database is injected only after it becomes ready. | `true` |
91+
92+
There is an alternative way to configure database injection using the ConfigMap _data_ markers.
93+
Their values are treated the same way as the annotation value.
94+
This can be used in environments where custom annotations can't be specified.
95+
96+
## Cleanup
97+
98+
Delete all resources.
99+
100+
```sh
101+
kubectl delete -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/ycsb-demo-app.yaml
102+
kubectl delete -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/database.yaml
103+
kubectl delete -f https://raw.githubusercontent.com/nuodb/nuodb-cp-releases/main/docs/files/domain.yaml
104+
```
105+
106+
[1]: https://kubernetes.io/docs/home/
107+
[2]: https://kubernetes.io/docs/concepts/overview/components/
108+
[3]: https://kubernetes.io/docs/tasks/tools/
109+
[4]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#custom-resources

‎QuickStart.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# DBaaS Quick Start Guide
2+
3+
This document describes how to provision NuoDB databases in multi-tenancy model by using NuoDB Control Plane (CP).
4+
NuoDB Control Plane works with [Kubernetes][1] locally or in the cloud.
5+
The steps in this guide can be followed regardless of the selected Kubernetes platform provider.
6+
7+
## Prerequisites
8+
9+
- A running [Kubernetes cluster][2]
10+
- [kubectl][3] installed and able to access the cluster.
11+
- [Helm 3.x][4] installed.
12+
13+
## Installing Dependencies
14+
15+
### Install Cert Manager
16+
17+
To enable [admission webhooks][7] in the NuoDB operator, [cert-manager](https://github.com/cert-manager/cert-manager) must be installed to automatically generate certificates for the webhook server.
18+
19+
Add the official Helm repositories.
20+
21+
```sh
22+
helm repo add jetstack https://charts.jetstack.io
23+
helm repo update
24+
```
25+
26+
Install Cert Manager Helm chart.
27+
28+
```sh
29+
helm upgrade --install cert-manager jetstack/cert-manager \
30+
--namespace cert-manager \
31+
--set installCRDs=true \
32+
--create-namespace
33+
```
34+
35+
Wait for Cert Manager to become available.
36+
37+
```sh
38+
kubectl -n cert-manager wait pod --all --for=condition=Ready
39+
```
40+
41+
## Installing NuoDB Control Plane
42+
43+
The NuoDB Control Plane consists of [Custom Resource Definitions][5] and the following workloads:
44+
45+
- *NuoDB CP Operator*, which enforces the desired state of the NuoDB [custom resources][6].
46+
- *NuoDB CP REST service*, that exposes a REST API allowing users to manipulate and inspect DBaaS entities.
47+
48+
By default the NuoDB CP will operate in a single namespace only which will be used for NuoDB CP and all databases created by it.
49+
The databases are grouped into *projects*, which are themselves grouped into *organizations*.
50+
51+
Add the official Helm repositories.
52+
53+
```sh
54+
helm repo add nuodb-cp https://nuodb.github.io/nuodb-cp-releases/charts
55+
helm repo update
56+
```
57+
58+
Install NuoDB CP Helm charts.
59+
60+
```sh
61+
helm upgrade --install nuodb-cp-crd nuodb-cp/nuodb-cp-crd \
62+
--namespace nuodb-cp-system \
63+
--create-namespace
64+
65+
helm upgrade --install nuodb-cp-operator nuodb-cp/nuodb-cp-operator \
66+
--namespace nuodb-cp-system \
67+
--set cpOperator.webhooks.enabled=true \
68+
--set 'cpOperator.extraArgs[0]=--ingress-https-port=48006' # Enables connecting to databases with port-forwarding
69+
70+
helm upgrade --install nuodb-cp-rest nuodb-cp/nuodb-cp-rest \
71+
--namespace nuodb-cp-system \
72+
--set cpRest.authentication.enabled=true \
73+
--set cpRest.authentication.admin.create=true \
74+
--set cpRest.baseDomainName=dbaas.localtest.me # Enables connecting to databases with port-forwarding
75+
```
76+
77+
Wait for NuoDB Control Plane to become available.
78+
79+
```sh
80+
kubectl -n nuodb-cp-system -l app=nuodb-cp-operator wait pod --all --for=condition=Ready
81+
kubectl -n nuodb-cp-system -l app=nuodb-cp-rest wait pod --all --for=condition=Ready
82+
```
83+
84+
## Creating NuoDB Database
85+
86+
Once the Control Plane is deployed, projects and databases can now be created.
87+
88+
### Access and Authentication
89+
90+
This guide will use port forwarding and [cURL][9] to demonstrate how to create projects and databases through the REST service.
91+
92+
```sh
93+
kubectl port-forward -n nuodb-cp-system svc/nuodb-cp-rest 8080 2>&1 >/dev/null &
94+
```
95+
96+
To successfully authenticate with the REST API, get the *system/admin* user's password from the cluster:
97+
98+
```sh
99+
PASS=$(kubectl get secret dbaas-user-system-admin -n nuodb-cp-system -o jsonpath='{.data.password}' | base64 -d)
100+
BASE_URL="http://localhost:8080"
101+
```
102+
103+
### Create Project
104+
105+
Create a new project *messaging* in organization *acme*:
106+
107+
```sh
108+
curl -u "system/admin:$PASS" -X PUT -H 'Content-Type: application/json' \
109+
$BASE_URL/projects/acme/messaging \
110+
-d '{"sla": "dev", "tier": "n0.small"}'
111+
```
112+
113+
>**Note**
114+
> Creating project and database with `n0.small` service tier will require 3 vCPU and 5Gi RAM allocatable resources from your cluster. If your setup is resource constrained, consider using `n0.nano` service tier.
115+
116+
Wait for the project to become available.
117+
118+
```sh
119+
while [ "$(curl -s -u "system/admin:$PASS" $BASE_URL/projects/acme/messaging | jq '.status.ready')" != "true" ]; do echo "Waiting ..."; sleep 5; done; echo "Domain is available"
120+
```
121+
122+
### Create database
123+
124+
Create a new database *demo* in project *messaging*:
125+
126+
```sh
127+
curl -u "system/admin:$PASS" -X PUT -H 'Content-Type: application/json' \
128+
$BASE_URL/databases/acme/messaging/demo \
129+
-d '{"dbaPassword": "secret"}'
130+
```
131+
132+
Wait for the database to become available.
133+
134+
```sh
135+
while [ "$(curl -s -u "system/admin:$PASS" $BASE_URL/databases/acme/messaging/demo | jq '.status.ready')" != "true" ]; do echo "Waiting ..."; sleep 5; done; echo "Database is available"
136+
```
137+
138+
### Connect to Database
139+
140+
This guide will use port forwarding to connect to the NuoDB database.
141+
142+
```sh
143+
ADMIN_SVC=$(kubectl get svc -n nuodb-cp-system \
144+
-l 'cp.nuodb.com/organization=acme,cp.nuodb.com/project=messaging,!cp.nuodb.com/database' -oname | grep "clusterip")
145+
DB_SVC=$(kubectl get svc -n nuodb-cp-system \
146+
-l "cp.nuodb.com/organization=acme,cp.nuodb.com/project=messaging,cp.nuodb.com/database" -oname)
147+
kubectl port-forward -n nuodb-cp-system $ADMIN_SVC 48004 2>&1 >/dev/null &
148+
kubectl port-forward -n nuodb-cp-system $DB_SVC 48006 2>&1 >/dev/null &
149+
```
150+
151+
Connect to the NuoDB database via `nuosql` (requires [nuodb-client][8] package v20230228 or later).
152+
153+
```sh
154+
CA_CERT="$(curl -s -u "system/admin:$PASS" $BASE_URL/databases/acme/messaging/demo | jq -r '.status.caPem')"
155+
DB_URL="$(curl -s -u "system/admin:$PASS" $BASE_URL/databases/acme/messaging/demo | jq -r '.status.sqlEndpoint')"
156+
nuosql "demo@${DB_URL}" --user dba --password secret --connection-property trustedCertificates="$CA_CERT"
157+
```
158+
159+
### Cleanup
160+
161+
- Delete all custom resources that have been created in `nuodb-cp-system` namespace.
162+
163+
```sh
164+
kubectl config set-context --current --namespace=nuodb-cp-system
165+
kubectl get databases.cp.nuodb.com -o name | xargs kubectl delete
166+
kubectl get domains.cp.nuodb.com -o name | xargs kubectl delete
167+
kubectl get servicetiers.cp.nuodb.com -o name | xargs kubectl delete
168+
kubectl get helmfeatures.cp.nuodb.com -o name | xargs kubectl delete
169+
kubectl get databasequotas.cp.nuodb.com -o name | xargs -r kubectl delete
170+
kubectl get secrets -o name --selector=cp.nuodb.com/organization | xargs -r kubectl delete
171+
kubectl get pvc -o name --selector=group=nuodb | xargs -r kubectl delete
172+
```
173+
174+
- Cleanup the installed resources in the following order:
175+
176+
```sh
177+
helm uninstall nuodb-cp-rest --namespace nuodb-cp-system
178+
helm uninstall nuodb-cp-operator --namespace nuodb-cp-system
179+
helm uninstall nuodb-cp-crd --namespace nuodb-cp-system
180+
helm uninstall cert-manager --namespace cert-manager
181+
```
182+
183+
- Delete the provisioned namespace:
184+
185+
```sh
186+
kubectl delete namespace nuodb-cp-system
187+
kubectl delete namespace cert-manager
188+
```
189+
190+
[1]: https://kubernetes.io/docs/home/
191+
[2]: https://kubernetes.io/docs/concepts/overview/components/
192+
[3]: https://kubernetes.io/docs/tasks/tools/
193+
[4]: https://helm.sh/
194+
[5]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions
195+
[6]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#custom-resources
196+
[7]: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/
197+
[8]: https://github.com/nuodb/nuodb-client/releases
198+
[9]: https://curl.se/

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
# nuodb-cp-docs
22
Documentation for NuoDB DBaaS Control Plane
3+

0 commit comments

Comments
 (0)