Skip to content

Commit e12141f

Browse files
dtantsurdtantsur
committed
User guide: document database support for IrSO
Signed-off-by: Dmitry Tantsur <[email protected]>
1 parent fb88cf0 commit e12141f

File tree

3 files changed

+172
-0
lines changed

3 files changed

+172
-0
lines changed

‎docs/user-guide/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
- [Ironic container images](ironic/ironic-container-images.md)
3636
- [Ironic Standalone Operator](irso/introduction.md)
3737
- [Install Ironic with IrSO](irso/install-basics.md)
38+
- [External Database for Ironic](irso/database.md)
3839
- [Cluster-api-provider-metal3](capm3/introduction.md)
3940
- [Install Metal³ provider](capm3/installation_guide.md)
4041
- [Features](capm3/features.md)

‎docs/user-guide/src/irso/database.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# External database for Ironic
2+
3+
By default, Ironic uses a local [SQLite](https://sqlite.org/) database, which
4+
is not persisted anywhere. In this mode of operation, all data is lost on a pod
5+
restart. If you want the Ironic database to be persisted, you need to configure
6+
an external [MariaDB](https://mariadb.org/) database.
7+
8+
## Linking to an external database
9+
10+
You can request persistence by providing a link to an external database in the
11+
`database` field:
12+
13+
```yaml
14+
apiVersion: ironic.metal3.io/v1alpha1
15+
kind: Ironic
16+
metadata:
17+
name: ironic
18+
namespace: test-ironic
19+
spec:
20+
database:
21+
credentialsName: secret-with-user-password
22+
host: mariadb.hostname.example.com
23+
name: database-name
24+
version: "27.0"
25+
```
26+
27+
If your database uses TLS, provide the name of the secret with the CA
28+
certificate in the `tlsCertificateName` field.
29+
30+
## Using mariadb-operator
31+
32+
One of the supported ways to install MariaDB for Ironic is
33+
[mariadb-operator](https://github.com/mariadb-operator/mariadb-operator).
34+
Please refer to [its
35+
examples](https://github.com/mariadb-operator/mariadb-operator/tree/main/examples/manifests)
36+
for information on how to use it in your case. Generally, the process is as
37+
follows:
38+
39+
1. Create a database server (if not already):
40+
41+
```yaml
42+
---
43+
apiVersion: v1
44+
kind: Namespace
45+
metadata:
46+
name: mariadb
47+
---
48+
apiVersion: v1
49+
kind: Secret
50+
metadata:
51+
name: root-credentials
52+
namespace: mariadb
53+
type: Opaque
54+
data:
55+
username: aXJvbmlj
56+
password: # your password here
57+
---
58+
apiVersion: k8s.mariadb.com/v1alpha1
59+
kind: MariaDB
60+
metadata:
61+
name: database-server
62+
namespace: mariadb
63+
spec:
64+
rootPasswordSecretKeyRef:
65+
name: root-credentials
66+
key: password
67+
storage:
68+
# configure database storage here
69+
```
70+
71+
**Note:** a lot of parameters can be tuned here - see official examples.
72+
73+
2. Create the database for Ironic:
74+
75+
```yaml
76+
apiVersion: k8s.mariadb.com/v1alpha1
77+
kind: Database
78+
metadata:
79+
name: ironic-database
80+
namespace: test-ironic
81+
spec:
82+
mariaDbRef:
83+
name: database-server # matches the server created above
84+
namespace: mariadb # matches the namespace of the server (not Ironic)
85+
waitForIt: true
86+
characterSet: utf8
87+
cleanupPolicy: Delete
88+
collate: utf8_general_ci
89+
```
90+
91+
3. Create a user and grant it all privileges to the new database:
92+
93+
```yaml
94+
---
95+
apiVersion: v1
96+
kind: Secret
97+
metadata:
98+
name: ironic-user
99+
namespace: test-ironic
100+
type: Opaque
101+
data:
102+
username: aXJvbmljLXVzZXI= # this MUST match the name of the User
103+
password: # your password here
104+
---
105+
apiVersion: k8s.mariadb.com/v1alpha1
106+
kind: User
107+
metadata:
108+
name: ironic-user # this MUST match the username field in the secret
109+
namespace: test-ironic
110+
spec:
111+
mariaDbRef:
112+
name: database-server # matches the server created above
113+
namespace: mariadb # matches the namespace of the server (not Ironic)
114+
waitForIt: true
115+
cleanupPolicy: Delete
116+
host: '%'
117+
maxUserConnections: 100
118+
passwordSecretKeyRef:
119+
key: password
120+
name: ironic-user
121+
---
122+
apiVersion: k8s.mariadb.com/v1alpha1
123+
kind: Grant
124+
metadata:
125+
name: ironic-user-grant
126+
namespace: test-ironic
127+
spec:
128+
mariaDbRef:
129+
name: database-server # matches the server created above
130+
namespace: mariadb # matches the namespace of the server (not Ironic)
131+
waitForIt: true
132+
cleanupPolicy: Delete
133+
database: ironic-database # matches the name of the Database object
134+
host: '%'
135+
privileges:
136+
- ALL PRIVILEGES
137+
table: '*'
138+
username: ironic-user # matches the name of the User object
139+
```
140+
141+
**Warning:** mariadb-operator gets the user name from the name of the User
142+
object, while Ironic uses the `username` field of the secret. If these do
143+
not match, authentication will fail.
144+
145+
**Note:** the default `maxUserConnections` of 10 is not enough for a normal
146+
operation of Ironic. The exact value depends on your environment, 100 is the
147+
value used in the CI.
148+
149+
4. After making sure that all objects are created and in `Ready` state, you can
150+
link to the database via its service endpoint:
151+
152+
```yaml
153+
apiVersion: ironic.metal3.io/v1alpha1
154+
kind: Ironic
155+
metadata:
156+
name: ironic
157+
namespace: test-ironic
158+
spec:
159+
database:
160+
credentialsName: ironic-user
161+
host: database-server.mariadb.svc
162+
name: ironic-database
163+
version: "27.0"
164+
```

‎docs/user-guide/src/irso/install-basics.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ answer a few questions before you can pick the one that suits you:
2020
without TLS. To enable it, you need to manage the TLS secret. [Cert
2121
Manager](https://cert-manager.io/) is the recommended service for it.
2222

23+
- Do you need persistence for the Ironic's internal database? The examples in
24+
this guide assume no persistence, i.e. that **all data is lost on the pod
25+
restart**! This ephemeral mode of operation suits Metal3 well, since BMO
26+
treats BareMetalHost resources as the primary source of truth. However, for
27+
use cases outside of Metal3, you need to configure an [external
28+
database](./database.md).
29+
2330
## Using Ironic
2431

2532
Regardless of the scenario you choose, you will need to create at least an

0 commit comments

Comments
 (0)