mirror of
https://github.com/mariadb-operator/mariadb-operator.git
synced 2025-07-25 01:28:31 +00:00
228 lines
7.1 KiB
Markdown
228 lines
7.1 KiB
Markdown
# SQL resources
|
|
|
|
`mariadb-operator` enables you to manage SQL resources declaratively through CRs. By SQL resources, we refer to users, grants, and databases that are typically created using SQL statements.
|
|
|
|
The key advantage of this approach is that, unlike executing SQL statements, which is a one-time operation, declaring a SQL resource via a CR ensures that the resource is periodically reconciled by the operator. This provides a guarantee that the resource will be recreated if it gets manually deleted. Additionally, it prevents state drifts, as the operator will regularly update the resource according to the CR specification.
|
|
|
|
## Table of contents
|
|
<!-- toc -->
|
|
- [`User` CR](#user-cr)
|
|
- [`Grant` CR](#grant-cr)
|
|
- [`Database` CR](#database-cr)
|
|
- [Initial `User`, `Grant` and `Database`](#initial-user-grant-and-database)
|
|
- [Authentication plugins](#authentication-plugins)
|
|
- [Configure reconciliation](#configure-reconciliation)
|
|
- [Cleanup policy](#cleanup-policy)
|
|
- [Reference](#reference)
|
|
<!-- /toc -->
|
|
|
|
## `User` CR
|
|
|
|
By creating this resource, you are declaring an intent to create an user in the referred `MariaDB` instance, just like a [`CREATE USER`](https://mariadb.com/kb/en/create-user/) statement would do:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: bob
|
|
spec:
|
|
mariaDbRef:
|
|
name: mariadb
|
|
passwordSecretKeyRef:
|
|
name: bob-password
|
|
key: password
|
|
maxUserConnections: 20
|
|
host: "%"
|
|
cleanupPolicy: Delete
|
|
```
|
|
|
|
In the example above, a user named `bob` identified by the password available in the `bob-password` `Secret` will be created in the `mariadb` instance.
|
|
|
|
Refer to the [reference section](#reference) for more detailed information about every field.
|
|
|
|
#### Custom name
|
|
|
|
By default, the CR name is used to create the user in the database, but you can specify a different one providing the `name` field under spec:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: user
|
|
spec:
|
|
name: user-custom
|
|
```
|
|
|
|
## `Grant` CR
|
|
|
|
By creating this resource, you are declaring an intent to grant permissions to a given user in the referred `MariaDB` instance, just like a [`GRANT`](https://mariadb.com/kb/en/grant/) statement would do.
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: Grant
|
|
metadata:
|
|
name: grant-bob
|
|
spec:
|
|
mariaDbRef:
|
|
name: mariadb
|
|
privileges:
|
|
- "SELECT"
|
|
- "INSERT"
|
|
- "UPDATE"
|
|
database: "*"
|
|
table: "*"
|
|
username: bob
|
|
grantOption: true
|
|
host: "%"
|
|
```
|
|
You may provide any set of [privileges supported by MariaDB](https://mariadb.com/kb/en/grant/#privilege-levels).
|
|
|
|
Refer to the [reference section](#reference) for more detailed information about every field.
|
|
|
|
## `Database` CR
|
|
|
|
By creating this resource, you are declaring an intent to create a logical database in the referred `MariaDB` instance, just like a [`CREATE DATABASE`](https://mariadb.com/kb/en/create-database/) statement would do:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: Database
|
|
metadata:
|
|
name: wordpress
|
|
spec:
|
|
mariaDbRef:
|
|
name: mariadb
|
|
characterSet: utf8
|
|
collate: utf8_general_ci
|
|
```
|
|
Refer to the [reference section](#reference) for more detailed information about every field.
|
|
|
|
#### Custom name
|
|
|
|
By default, the CR name is used to create the user in the database, but you can specify a different one providing the `name` field under spec:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: Database
|
|
metadata:
|
|
name: database
|
|
spec:
|
|
name: database-custom
|
|
```
|
|
|
|
## Initial `User`, `Grant` and `Database`
|
|
|
|
If you only need one user to interact with a single logical database, you can use of the `MariaDB` resource to configure it, instead of creating the `User`, `Grant` and `Database` resources separately:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: MariaDB
|
|
metadata:
|
|
name: mariadb
|
|
spec:
|
|
username: bob
|
|
passwordSecretKeyRef:
|
|
name: bob-password
|
|
key: password
|
|
database: wordpress
|
|
```
|
|
|
|
Behind the scenes, the operator will be creating an `User` resource with `ALL PRIVILEGES` in the initial `Database`.
|
|
|
|
## Authentication plugins
|
|
|
|
Passwords can be supplied using the `passwordSecretKeyRef` field in the `User` CR. This is a reference to a `Secret` that contains a password in plain text.
|
|
|
|
Alternatively, you can use [MariaDB authentication plugins](https://mariadb.com/kb/en/authentication-plugins/) to avoid passing passwords in plain text and provide the password in a hashed format instead. This doesn't affect the end user experience, as they will still need to provide the password in plain text to authenticate.
|
|
|
|
#### Password hash
|
|
|
|
Provide the password hashed using the [MariaDB `PASSWORD` ](https://mariadb.com/kb/en/password/)function:
|
|
|
|
```yaml
|
|
kind: Secret
|
|
metadata:
|
|
name: mariadb-auth
|
|
stringData:
|
|
passwordHash: "*57685B4F0FF9D049082E296E2C39354B7A98774E"
|
|
---
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: user-password-hash
|
|
spec:
|
|
mariaDbRef:
|
|
name: mariadb
|
|
passwordHashSecretKeyRef:
|
|
name: mariadb-auth
|
|
key: passwordHash
|
|
host: "%"
|
|
```
|
|
|
|
The password hash can be obtained by executing `SELECT PASSWORD('<password>');` in an existing MariaDB installation.
|
|
|
|
#### Password plugin
|
|
|
|
Provide the password hashed using any of the available [MariaDB authentication plugins](https://mariadb.com/kb/en/authentication-plugins/), for example `mysql_native_password`:
|
|
|
|
```yaml
|
|
kind: Secret
|
|
metadata:
|
|
name: mariadb-auth
|
|
stringData:
|
|
passwordHash: "*57685B4F0FF9D049082E296E2C39354B7A98774E"
|
|
nativePasswordPlugin: mysql_native_password
|
|
---
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: user-password-plugin
|
|
spec:
|
|
mariaDbRef:
|
|
name: mariadb
|
|
passwordPlugin:
|
|
pluginNameSecretKeyRef:
|
|
name: mariadb-auth
|
|
key: nativePasswordPlugin
|
|
pluginArgSecretKeyRef:
|
|
name: mariadb-auth
|
|
key: passwordHash
|
|
host: "%"
|
|
```
|
|
|
|
The plugin name should be available in a `Secret` referenced by `pluginNameSecretKeyRef` and the argument passed to it in `pluginArgSecretKeyRef`. The argument is the hashed password in most cases, refer to the [MariaDB docs](https://mariadb.com/kb/en/authentication-plugins/) for further detail.
|
|
|
|
## Configure reconciliation
|
|
|
|
As we previously mentioned, SQL resources are periodically reconciled by the operator into SQL statements. You are able to configure the reconciliation interval using the following fields:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: user
|
|
spec:
|
|
requeueInterval: 30s
|
|
retryInterval: 5s
|
|
```
|
|
|
|
If the SQL statement executed by the operator is successful, it will schedule the next reconciliation cycle using the `requeueInterval`. If the statement encounters an error, the operator will use the `retryInterval` instead.
|
|
|
|
## Cleanup policy
|
|
|
|
Whenever you delete a SQL resource, the operator will also delete the associated resource in the database. This is the default behaviour, that can also be achieved by setting `cleanupPolicy=Delete`:
|
|
|
|
```yaml
|
|
apiVersion: k8s.mariadb.com/v1alpha1
|
|
kind: User
|
|
metadata:
|
|
name: user
|
|
spec:
|
|
cleanupPolicy: Delete
|
|
```
|
|
|
|
You can opt-out from this cleanup process using `cleanupPolicy=Skip`. Note that this resources will remain in the database.
|
|
|
|
## Reference
|
|
- [API reference](./API_REFERENCE.md)
|
|
- [Example suite](../examples/)
|