Using CockroachDB single node storage
The deployment of Keycloak can use a CockroachDB instance when using the new map storage.
As an alternative CockroachDB setup, there is also Using CockroachDB with an Operator which has more features and uses more resources.
Enabling CockroachDB storage
Using a CockroachDB single node installation is available in Keycloak’s new JPA map storage.
It can be enabled via the following settings in the .env file in the provision/kubernetes folder:
KC_DATABASE=cockroach-single
KC_STORAGE=jpaSee Customizing the deployment for a list of all configuration options.
After every change, re-run the task command to apply the changes to the minikube instance.
Task will trigger the necessary scripts and will use the minimal steps to update the minikube.
Running rebuild.sh is not required: It will destroy the complete instance and will take a lot longer to complete.
The deployment adds a new CockroachDB pod to the minikube setup and removes all other storage pods that are no longer necessary. Every time the pod is restarted, the database is cleared.
Keycloak connects to the CockroachDB database pod inside minikube and populates the DB schema. The SQL Pad allows accessing the database via the browser.
Verifying the setup
The automated script verifies that Keycloak starts up, which requires that CockroachDB start up first. A user can test the setup by accessing CockroachDB’s console.
Accessing the CockroachDB console
Assuming the command minikube ip returned 192.168.39.39, the console is available on http://cockroach.192.168.39.39.nip.io.
The username is keycloak, password is pass.
| minikube’s IP address changes every time the minikube instance is re-created. |
Connecting a local application to CockroachDB
CockroachDB’s database port is also available as a node port so that it can be accessed from a local application.
Assuming the command minikube ip returned 192.168.39.39, the JDBC URL is jdbc:postgres://192.168.39.39:30010/keycloak?sslmode=disable.
| minikube’s IP address changes every time the minikube instance is re-created. |
It can be used, for example, to connect the developer’s IDE to the database.
The connection details: Port is always 30010, username is keycloak, password is pass, database name is keycloak.
All ports are specified without the port offset.
If you are using the configuration option KC_PORT_OFFSET you need to add the offset to port numbers.
For the port offset XX (00-26) and the port number 300YY the resulting port will be 3XXYY.
|
Metrics and Dashboards for CockroachDB
Metrics from the CockroachDB are available in Prometheus, and dashboards are available in Grafana. They are named “CDRB Console: SQL”, “CDRB Console: Runtime” and “CDRB Console: Storage”. The dashboards have been taken from the CockroachDB manual and adapted for the Job name.
To see all metrics, query Prometheus for {job="keycloak/cockroach-metrics"}.
Known issues for the CockroachDB setup
Users of this setup should be aware of the following known issues.
Transactions are rolled back with the message RETRY_SERIALIZABLE
As the database will always run in isolation level serializable, there are situations where this can’t be avoided. On the other hand, the system could be optimized to retry those failures, or to use better query paths.
See the docs about this error message on how to collect more information on the Keycloak message RETRY_SERIALIZABLE.