github-personal/kamaji
1
0
Fork 0
mirror of https://github.com/outbackdingo/kamaji.git synced 2026-01-27 10:19:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: documenting datastore feature

Browse Source
This commit is contained in:
Dario Tranchitella
2022-08-25 21:21:15 +02:00
parent a23fcc502f
commit b23cbe3976
8 changed files with 30 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
deploy/kine/README.md
View File

@@ -7,41 +7,20 @@ This can help in overcoming the `etcd` limitation regarding scalability and clus
## Kamaji additional CLI flags
Once a compatible database is running, we need to provide information about it to Kamaji by using the following flags:
Kamaji read the data store configuration from a cluster-scoped resource named `DataStore`, containing all tha required details to secure a connection using a specific driver.
- [Example of a `etcd` DataStore](./../../config/samples/kamaji_v1alpha1_datastore_etcd.yaml)
- [Example of a `MySQL` DataStore](./../../config/samples/kamaji_v1alpha1_datastore_mysql.yaml)
- [Example of a `PostgreSQL` DataStore](./../../config/samples/kamaji_v1alpha1_datastore_postgresql.yaml)
Once the datastore is running, and the `DataStore` has been created with the required details, we need to provide information about it to Kamaji by using the following flag and pointing to the resource name:
```
--etcd-storage-type={kine-mysql,kine-postgresql}
--kine-host=<database host>
--kine-port=<database port>
--kine-secret-name=<secret name>
--kine-secret-namespace=<secret namespace>
--datastore={.metadata.name}
```
## Kine Secret
The Kine Secret must be configured as follows:
```yaml
apiVersion: v1
data:
ca.crt: "content of the Certificate Authority for SSL connection"
password: "password of the super user"
server.crt: "content of the certificate for SSL connection"
server.key: "content of the private key for SSL connection"
username: "username of the super user"
kind: Secret
metadata:
name: kine-secret
namespace: kamaji-system
type: kamaji.clastix.io/kine
```
> Please, pay attention to the type `kamaji.clastix.io/kine`: this check is enforced at the code level to ensure the required data is provided.
> Actually, the `kine` integration expects a secured connection to the database since the sensitivity data of the Tenant.
## Drivers
Further details on the setup for each driver are available here:
- [MySQL/MariaDB](../deploy/kine/mysql/README.md)
- [PostgreSQL](../deploy/kine/postgresql/README.md)
- [PostgreSQL](../deploy/kine/postgresql/README.md)

11
deploy/kine/mysql/Makefile
View File

@@ -1,6 +1,6 @@
ROOT_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
mariadb: mariadb-certificates mariadb-secret mariadb-kine-secret mariadb-deployment
mariadb: mariadb-certificates mariadb-secret mariadb-deployment
mariadb-certificates:
rm -rf $(ROOT_DIR)/certs && mkdir $(ROOT_DIR)/certs
@@ -22,15 +22,6 @@ mariadb-secret:
--from-literal=MYSQL_ROOT_PASSWORD=root \
--dry-run=client -o yaml | kubectl apply -f -
mariadb-kine-secret:
@\
CA=$$(cat $(ROOT_DIR)/certs/ca.crt | base64 | tr -d '\n') \
CRT=$$(cat $(ROOT_DIR)/certs/server.crt | base64 | tr -d '\n') \
KEY=$$(cat $(ROOT_DIR)/certs/server.key | base64 | tr -d '\n') \
ROOT_USERNAME=$$(echo -n root | base64) \
ROOT_PASSWORD=$$(kubectl -n kamaji-system get secret mysql-config -o jsonpath='{.data.MYSQL_ROOT_PASSWORD}') \
envsubst < $(ROOT_DIR)/../secret.yaml | kubectl -n kamaji-system apply -f -
mariadb-deployment:
@kubectl -n kamaji-system apply -f $(ROOT_DIR)/mariadb.yaml

8
deploy/kine/mysql/README.md
View File

@@ -59,14 +59,6 @@ $ make mariadb-secrets
Previous certificates and MySQL configuration have to be available in order to be used.
They will be under the secret `kamaji-system:mysql-config`, used by the MySQL/MariaDB instance.
## Kine Secret
```bash
$ make mariadb-kine-secret
```
Organize the required Kine data such as username, password, CA, certificate, and private key to be stored in the Kamaji desired format.
## Deployment
```bash

11
deploy/kine/postgresql/Makefile
View File

@@ -1,6 +1,6 @@
ROOT_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
postgresql: cnpg-setup cnpg-deploy postgresql-secret postgresql-kine-secret
postgresql: cnpg-setup cnpg-deploy postgresql-secret
cnpg-setup:
@kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.16.0.yaml
@@ -21,15 +21,6 @@ postgresql-secret: cnpg
--cnpg-cluster postgresql \
--cnpg-user $$(kubectl -n kamaji-system get secret postgresql-superuser -o jsonpath='{.data.username}' | base64 -d)
postgresql-kine-secret:
@\
CA=$$(kubectl -n kamaji-system get secret postgresql-ca -o jsonpath='{.data.ca\.crt}') \
CRT=$$(kubectl -n kamaji-system get secret postgres-root-cert -o jsonpath='{.data.tls\.crt}') \
KEY=$$(kubectl -n kamaji-system get secret postgres-root-cert -o jsonpath='{.data.tls\.key}') \
ROOT_USERNAME=$$(kubectl -n kamaji-system get secret postgresql-superuser -o jsonpath='{.data.username}' ) \
ROOT_PASSWORD=$$(kubectl -n kamaji-system get secret postgresql-superuser -o jsonpath='{.data.password}' ) \
envsubst < $(ROOT_DIR)/../secret.yaml | kubectl -n kamaji-system apply -f -
postgresql-destroy:
@kubectl delete -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.16.0.yaml --ignore-not-found && \
kubectl delete secret postgres-root-cert --ignore-not-found && \

12
deploy/kine/postgresql/README.md
View File

@@ -1,6 +1,7 @@
# PostgreSQL as Kubernetes Storage
Kamaji offers the possibility of having a different storage system than `etcd` thanks to [kine](https://github.com/k3s-io/kine). One of the implementations is [PostgreSQL](https://www.postgresql.org/).
Kamaji offers the possibility of having a different storage system than `etcd` thanks to [kine](https://github.com/k3s-io/kine).
One of the implementations is [PostgreSQL](https://www.postgresql.org/).
Kamaji project is developed using [kind](https://kind.sigs.k8s.io), therefore, a PostgreSQL instance must be deployed in advance into the local kubernetes cluster in order to be used as storage for the tenants.
For the sake of simplicity, the [cloudnative-pg](https://cloudnative-pg.io/) Operator will be used to simplify the setup of it.
@@ -34,7 +35,6 @@ validatingwebhookconfiguration.admissionregistration.k8s.io/cnpg-validating-webh
deployment "cnpg-controller-manager" successfully rolled out
cluster.postgresql.cnpg.io/postgresql unchanged
secret/postgres-root-cert created
secret/kine-secret created
```
## Operator setup
@@ -55,15 +55,13 @@ $ make postgresql-secret
This target will download locally the `kubectl-cnpg` utility to generate an SSL certificate required to secure the connection to the PostgreSQL instance.
## Kine Secret generation
## Certificate generation
```bash
$ make postgresql-kine-secret
$ make postgresql-secret
```
Generate the Kine secret required for Kamaji.
> Requires the generation of the `postgresql-secret`
Generate the Certificate required to connect to the DataStore.
## Teardown

14
deploy/kine/secret.yaml
View File

@@ -1,14 +0,0 @@
# secret.yaml is the Secret object that Kamaji is expecting to user to connect to the Kine SQL datastore:
# certificates keys are required, username and password are optional.
apiVersion: v1
kind: Secret
data:
ca.crt: ${CA}
server.crt: ${CRT}
server.key: ${KEY}
username: ${ROOT_USERNAME}
password: ${ROOT_PASSWORD}
metadata:
creationTimestamp: null
name: kine-secret
type: kamaji.clastix.io/kine

4
docs/getting-started-with-kamaji.md
View File

@@ -57,9 +57,7 @@ Kamaji offers the possibility of using a different storage system than `ETCD` fo
Read it more in the provided [guide](../deploy/kine/README.md).
Assuming you adjusted the [Kamaji manifest](./config/install.yaml) to connect to Kine and compatible database using the proper driver, you can now install it.
Assuming you adjusted the [Kamaji manifest](../config/install.yaml) to connect to Kine and compatible database using the proper driver, you can now install it.
### Install Kamaji

44
docs/reference.md
View File

@@ -15,49 +15,30 @@ This is easily explained in this way:
Available flags are the following:
```
--config-file string Configuration file alternative. (default "./kamaji.yaml")
--etcd-ca-secret-name Name of the secret which contains CA's certificate and private key. (default: "etcd-certs")
--etcd-ca-secret-namespace Namespace of the secret which contains CA's certificate and private key. (default: "kamaji")
--etcd-client-secret-name Name of the secret which contains ETCD client certificates. (default: "root-client-certs")
--etcd-client-secret-namespace Name of the namespace where the secret which contains ETCD client certificates is. (default: "kamaji")
--etcd-compaction-interval ETCD Compaction interval (i.e. "5m0s"). (default: "0" (disabled))
--etcd-endpoints Comma-separated list with ETCD endpoints (i.e. https://etcd-0.etcd.kamaji.svc.cluster.local,https://etcd-1.etcd.kamaji.svc.cluster.local,https://etcd-2.etcd.kamaji.svc.cluster.local)
--etcd-storage-type ETCD Storage type (i.e. "etcd", "kine-mysql", "kine-postgresql"). (default: "etcd")
--config-file string Configuration file alternative. (default "kamaji.yaml")
--datastore string The default DataStore that should be used by Kamaji to setup the required storage (default "etcd")
--health-probe-bind-address string The address the probe endpoint binds to. (default ":8081")
--kine-port int Port where the DB used by Kine is listening to.
--kine-host string Host where the DB used by Kine is working.
--kine-secret-name Name of the secret which contains the Kine configuration. (default: "kine-secret")
--kine-secret-name Name of the namespace where the secret which contains the Kine configuration. (default: "kamaji-system")
--kine-image string Container image along with tag to use for the Kine sidecar container (used only if etcd-storage-type is set to one of kine strategies) (default "rancher/kine:v0.9.2-amd64")
--kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
--leader-elect Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager.
--metrics-bind-address string The address the metric endpoint binds to. (default ":8080")
--tmp-directory Directory which will be used to work with temporary files. (default "/tmp/kamaji")
--tmp-directory string Directory which will be used to work with temporary files. (default "/tmp/kamaji")
--zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) (default true)
--zap-encoder encoder Zap log encoding (one of 'json' or 'console')
--zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', or any integer value > 0 which corresponds to custom debug levels of increasing verbosity
--zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic').
--zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'.
```
Available environment variables are:
| Environment variable | Description |
| ---------------------------------- | ------------------------------------------------------------ |
| `KAMAJI_ETCD_CA_SECRET_NAME` | Name of the secret which contains CA's certificate and private key. (default: "etcd-certs") |
| `KAMAJI_ETCD_CA_SECRET_NAMESPACE` | Namespace of the secret which contains CA's certificate and private key. (default: "kamaji") |
| `KAMAJI_ETCD_CLIENT_SECRET_NAME` | Name of the secret which contains ETCD client certificates. (default: "root-client-certs") |
| `KAMAJI_ETCD_CLIENT_SECRET_NAMESPACE` | Name of the namespace where the secret which contains ETCD client certificates is. (default: "kamaji") |
| `KAMAJI_ETCD_COMPACTION_INTERVAL` | ETCD Compaction interval (i.e. "5m0s"). (default: "0" (disabled)) |
| `KAMAJI_ETCD_ENDPOINTS` | Comma-separated list with ETCD endpoints (i.e. etcd-server-1:2379,etcd-server-2:2379). (default: "etcd-server:2379") |
| `KAMAJI_ETCD_STORAGE_TYPE` | ETCD Storage type (i.e. "etcd", "kine-mysql"). (default: "etcd") |
| `KAMAJI_ETCD_SERVERS` | Comma-separated list with ETCD servers (i.e. etcd-0.etcd.kamaji.svc.cluster.local,etcd-1.etcd.kamaji.svc.cluster.local,etcd-2.etcd.kamaji.svc.cluster.local) |
| `KAMAJI_METRICS_BIND_ADDRESS` | The address the metric endpoint binds to. (default ":8080") |
| `KAMAJI_HEALTH_PROBE_BIND_ADDRESS` | The address the probe endpoint binds to. (default ":8081") |
| `KAMAJI_KINE_MYSQL_HOST` | Host where MySQL is running(default "localhost") |
| `KAMAJI_KINE_MYSQL_PORT` | Port where MySQL is running (default: 3306) |
| `KAMAJI_KINE_MYSQL_SECRET_NAME` | Name of the secret where the necessary configuration and certificates are. (default: "mysql-config") |
| `KAMAJI_KINE_MYSQL_SECRET_NAMESPACE` | Name of the namespace of the secret where the necessary configuration and certificates are. (default: "kamaji-system") |
| `KAMAJI_LEADER_ELECTION` | Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager. |
| `KAMAJI_TMP_DIRECTORY` | Directory which will be used to work with temporary files. (default "/tmp/kamaji") |
| Environment variable | Description |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `KAMAJI_DATASTORE` | Name of the DataStore resource with driver definition and settings. (default "etcd") |
| `KAMAJI_METRICS_BIND_ADDRESS` | The address the metric endpoint binds to. (default ":8080") |
| `KAMAJI_HEALTH_PROBE_BIND_ADDRESS` | The address the probe endpoint binds to. (default ":8081") |
| `KAMAJI_LEADER_ELECTION` | Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager. |
| `KAMAJI_TMP_DIRECTORY` | Directory which will be used to work with temporary files. (default "/tmp/kamaji") |
## Build and deploy
@@ -130,3 +111,4 @@ addons:
memory: 128Mi
serverImage: us.gcr.io/k8s-artifacts-prod/kas-network-proxy/proxy-server
agentImage: us.gcr.io/k8s-artifacts-prod/kas-network-proxy/proxy-agent
```