The document describes the installation process for DBaaS Aggregator.
The following PaaS versions are supported:
| PaaS type | Versions | Support type |
|---|---|---|
| kubernetes | 1.21.x-1.32.x | Full support |
| Openshift OCP (enterprise) | 4.11-4.18 | Full support |
The following software should be installed before DBaaS installation:
| Dependency | Version |
|---|---|
| PostgreSQL | PostgreSQL 14-17 |
Note that despite DBaaS is used to manage various DBs (Cassandra, MongoDB, etc.) - these DBs could be installed after DBaaS installation. This table contains minimal supported versions:
| Database type | Database version |
|---|---|
| PostgreSQL | 1.28.0-4 |
| MongoDB | 1.21.3 |
| OpenSearch | 0.3.1 |
| Cassandra | 1.35.0 |
| Clickhouse | 0.13.0-3 |
| ArangoDB | 0.20.0-3 |
| Redis | 2.10.3 |
-
If you update from 3.17.0 or older version then migration procedure to v3 classifier will be performed. If there is incorrect classifier, update won't be performed. So, it's highly recommended to check microservices' classifiers and update to correct classifier by procedure: Classifier v3 migration process.
By incorrect classifier we mean a classifier which does contains such necessary fields as 'microserviceName', 'isService' or 'isServiceDb', 'tenantId' in case of tenant database. -
If you upgrade from version 3.x.x to 4.x.x, then it's strongly recommended doing via 4.2.0 version as it allows to avoid some problems in case if there are databases with incorrect classifiers.
-
If you're upgrading from DBaaS 4.4.0 or earlier versions in OpenShift environments, there are important notes to consider:
- Maintenance Window Requirement: Installation on OpenShift necessitates a maintenance window.
- Changes in Supported Entities: OpenShift-specific entities like DeploymentConfig and Router are no longer supported. After installation, it's essential to carry out housekeeping procedures.
Depending on installation mode (Development, Production) - different HW resources should be available for installation:
| CPU request | CPU limit | RAM request | RAM limit | |
|---|---|---|---|---|
| Dev profile | 100 | 2000 | 526 | 526 |
| Prod profile | 100 | 4000 | 710 | 710 |
CPU is in millicores, RAM is in Mb.
For Development environments with many namespaces you should set the sufficient -Xmx value in dbaas-aggregator Deployment.
Refer to Heap memory for H2 cache for details.
- PostgreSQL user with CREATEDB and public schema privilege is required. This user credentials should be either provided to DBaaS installation scripts or used to manually create registry database.
- User for DBaaS deployment should have
administratorrole andport-forwardgrants in all namespaces where databases managed by DBaaS will be deployed (PostgreSQL, MongoDb, Cassandra. Redis, etc.) and project-admin grants to the project where dbaas-aggregator will be deployed. - DBaaS installation procedure requires specific label with key 'region' to be set up on nodes before deploy job execution. Default value of the label is 'database'. For example: 'region=database'. The label name and value can be customized with NODE_SELECTOR_DBAAS_KEY and REGION_DBAAS envs.
This section describes both initial DBaaS installation and update. Some steps are optional - see note in every section.
Note: this step is required only for initial installation. Should be skipped for update installation.
The suggested namespace name for DBaaS Aggregator is dbaas.
If you have several physical databases of the same type (for example you have two PostgreSQL clusters you want to use with one DBaaS instance), then before DBaaS Aggregator installation you need to scale to 0 all DBaaS adapters of that type, except one, which will be the default adapter of that type. (The logical databases will be created through there by default). If you do not do this, then the default adapter will be the one which will be registered first.
Remember to scale all DBaaS adapters' pods back after DBaaS Aggregator installation has finished and the default adapter is registered.
Important information: You should create DBaaS-specific user manually with CREATEDB optional or pass PostgreSQL DBA
user credentials.
If you do not do it and default POSTGRES_DBA_USER/POSTGRES_DBA_PASSWORD do not match then you will get an installation
fail.
All, except POSTGRES_DBAAS_USER/POSTGRES_DBAAS_PASSWORD, parameters are optional, so if you do not specify your own
values then the default values will be applied.
| Parameter name | Description | Default |
|---|---|---|
| POSTGRES_HOST | Name of host to connect to PostgreSQL physical database. | pg-patroni.postgresql |
| POSTGRES_PORT | Port number to connect to the PostgreSQL physical database. | 5432 |
| PRODUCTION_MODE | If PRODUCTION_MODE is set to true, dropping databases in dbaas is not allowed. | true |
| NODE_SELECTOR_DBAAS_KEY | It indicates a node region key where pods will be located | region |
| REGION_DBAAS | It indicates a node region where pods will be located | database |
| priorityClassName | Defines priority of the pod. | None |
| CLOUD_TOPOLOGY_KEY | Nodes' label to match for inner pod anti-affinity soft rule | kubernetes.io/hostname |
| DBAAS_DEFAULT_PHYSICAL_DATABASES_DISABLED | Disable default physical databases. Default physical database is used when dedicated rules for microservice and namespace are not found. | false |
| READONLY_CONTAINER_FILE_SYSTEM_ENABLED | If READONLY_CONTAINER_FILE_SYSTEM_ENABLED is set to true, dbaas-aggregator will be deployed with read-only file system in its container. | false |
| MONITORING_ENABLED | Flag to install podmonitor custom resource and grafana dashboard for DBaaS | true |
| DBAAS_OWN_PG_DB_CREATED_MANUALLY | Setting this parameter to true disables automatic database creation. Allows to use user's own database. |
false |
| USE_POSTGRES_PORT_FORWARD | Enable or disable PostgreSQL port-forward during DBaaS Aggregator installation. It is needed if Deployer does not have direct access to PostgreSQL database | true |
| POSTGRES_DBA_USER/POSTGRES_DBA_PASSWORD | PostgreSQL user with privileged rights (SUPERUSER). You should pass it if you do not specify POSTGRES_DBAAS_USER |
postgres/password |
| POSTGRES_DBAAS_USER/POSTGRES_DBAAS_PASSWORD | PostgreSQL DBaaS-specific user. Should be created manually with CREATEDB optional or you can use POSTGRES_DBA_USER for creating such user automatically. In this case PG DBaaS user will have dbaas_user_<namespace> username and random password |
None |
| POSTGRES_DBAAS_DATABASE_NAME | PostgreSQL logical database where DBaaS will store its own data. If database does not exist, DBaaS Aggregator creates it automatically | <NAMESPACE> |
| DBAAS_RECREATE_DEPLOYMENT_STRATEGY | Use recreate deployment strategy instead of rolling. It Ensure a more reliable migration process | false |
| DBAAS_PREMATURE_REGISTRATION_ADAPTER_ADDRESSES | Addresses of the adapters, that have to be registered as soon as DBaaS Aggregator starts. Addresses must be separated by comma. Example: http://dbaas-postgres-adapter.postgresql-dbaas:8080,http://dbaas-mongo-adapter.mongo-cluster:8080 |
None |
| DBAAS_DB_EDITOR_CREDENTIALS_USERNAME | Username for role "dbaas-db-editor". This role can edit logical database registration in DBaaS store database, e.g. it is needed for API: update existing classifier. | dbaas-db-editor |
| DBAAS_DB_EDITOR_CREDENTIALS_PASSWORD | Password for role "dbaas-db-editor". This role can edit logical database registration in DBaaS store database, e.g. it is needed for API: update existing classifier. | None |
| DBAAS_CLUSTER_DBA_CREDENTIALS_USERNAME | Username for user "cluster-dba" used to authorize access to databases administration API by deployer and functional projects. Also "cluster-dba" is used by DBaaS adapters for registration. Same credentials should be used during installation of functional Cloud-Core-based and DBaaS adapters. | cluster-dba |
| DBAAS_CLUSTER_DBA_CREDENTIALS_PASSWORD | Password for user "cluster-dba" used to authorize access to databases administration API by deployer and functional projects. Also "cluster-dba" is used by DBaaS adapters for registration. Same credentials should be used during installation of functional Cloud-Core-based and DBaaS adapters. | None |
| BACKUP_DAEMON_DBAAS_ACCESS_USERNAME | Username for "dbaas-backup" user used to authorize access to backup collection and restoration by project backup daemon, should be generated on DBaaS installation or should be equal to the same value used during cloud-project-backup installation. | backup-daemon |
| BACKUP_DAEMON_DBAAS_ACCESS_PASSWORD | Password for "dbaas-backup" user used to authorize access to backup collection and restoration by project backup daemon, should be generated on DBaaS installation or should be equal to the same value used during cloud-project-backup installation. | None |
| DBAAS_TENANT_USERNAME | Username for "dbaas-tenant" user used by tenant-manager to clean sandbox tenant. Same credentials should be used during installation of functional projects where tenant-manager is included. | dbaas-tenant |
| DBAAS_TENANT_PASSWORD | Password for "dbaas-tenant" user used by tenant-manager to clean sandbox tenant. Same credentials should be used during installation of functional projects where tenant-manager is included. | None |
| DBAAS_BACKUP_RESTORE_CHECK_LOCK_TIMEOUT | Specifies the amount of time the lock should be kept in case the executing node dies. | |
| DBAAS_BACKUP_RESTORE_CHECK_INTERVAL | Specifies the interval between requests to adapters for backup or restore status during an asynchronous process. | |
| DBAAS_BACKUP_RESTORE_CHECK_ATTEMPTS | Specifies the max number of attempts to request adapters for backup or restore status during an asynchronous process. | |
| DBAAS_BACKUP_RESTORE_RETRY_DELAY_SECONDS | Specifies the delay between retries of requesting adapter in seconds if the previous attempt failed. | |
| DBAAS_BACKUP_RESTORE_RETRY_ATTEMPTS | Specifies the max number of retries to request adapter for backup or restore if the previous attempt failed. | |
| DBAAS_SECURITY_NAMESPACE_ISOLATION_ENABLED | If DBAAS_SECURITY_NAMESPACE_ISOLATION_ENABLED is set to true, dbaas-aggregator will reject requests with invalid namespace. | true |
| KUBERNETES_JWT_ENABLED | If KUBERNETES_JWT_ENABLED is set to true, dbaas-aggregator will accept requests with Kubernetes service account tokens for M2M authentication. | true |
| KUBERNETES_JWT_AUDIENCE | KUBERNETES_JWT_AUDIENCE specifies the expected audience from Kubernetes tokens. Tokens with a different audience are rejected. | dbaas |
You can find more info about existing and removed parameters in parameters.md
You should prepare values.yaml file with all required deployment parameters and perform usual helm installation to the desired namespace.
Upgrading procedure to DBaaS 4.5 and higher on OpenShift 4.14+ environment requires maintenance windows.
Since DeploymentConfig is being deprecated with OpenShift 4.14, instead of Openshift specific entities ( DeploymentConfig, Route) DBaaS will use Kubernetes ones (Deployment, Ingress). Therefore, if you are going to update DBaaS to 4.5 or higher version, you must do the following steps:
- Before updating OpenShift and DBaaS to a new version, scale down all DBaaS Aggregator pods in the namespace where you intend to update DBaaS.
oc scale deploymentconfig dbaas-aggregator --replicas=0 -n "<namespace>"-
Update DBaaS Aggregator to 4.5+ version. After updating, DBaaS should have both DeploymentConfig and Route entities along with the new Deployment and Ingress entities. Ensure that the
DeploymentConfig entity should have 0 replicas, and all pods must be generated from DeploymentConfig -
After updating DBaaS, perform the housekeeping procedure, which involves the removal of OpenShift-specific entities, such as DeploymentConfig and Route (see command below):
oc delete deploymentconfig --namespace="<namespace>" dbaas-aggregator
oc delete route --namespace="<namespace>" aggregator * Instead of <namespace> provide namespace name where dbaas was updated.
* Instead of oc you may use kubectl
- The final step is to update OpenShift to version 4.14 and above.