Skip to content

Commit 3e391ff

Browse files
sbernauersbernauer
committed
Add lots of docs
1 parent 49f8ba0 commit 3e391ff

10 files changed

Lines changed: 333 additions & 32 deletions

File tree

‎crates/stackable-operator/crds/DummyCluster.yaml‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,208 @@ spec:
7272
and `stopped` will take no effect until `reconciliationPaused` is set to false or removed.
7373
type: boolean
7474
type: object
75+
databaseConnection:
76+
oneOf:
77+
- required:
78+
- postgresql
79+
- required:
80+
- mysql
81+
- required:
82+
- derby
83+
- required:
84+
- redis
85+
- required:
86+
- genericJDBC
87+
- required:
88+
- genericSQLAlchemy
89+
- required:
90+
- genericCelery
91+
properties:
92+
derby:
93+
description: |-
94+
Connection settings for an embedded [Apache Derby](https://db.apache.org/derby/) database.
95+
96+
Derby is an embedded, file-based Java database engine that requires no separate server process.
97+
It is typically used for development, testing, or as a lightweight metastore backend (e.g. for
98+
Apache Hive).
99+
properties:
100+
location:
101+
description: |-
102+
Path on the filesystem where Derby stores its database files.
103+
104+
If not specified, defaults to `/tmp/derby/{unique_database_name}/derby.db`.
105+
The `{unique_database_name}` part is automatically handled by the operator and is added to
106+
prevent clashing database files. The `create=true` flag is always appended to the JDBC URL,
107+
so the database is created automatically if it does not yet exist at this location.
108+
nullable: true
109+
type: string
110+
type: object
111+
genericCelery:
112+
description: |-
113+
A generic Celery database connection for broker or result backend types not covered by a
114+
dedicated variant.
115+
116+
Use this when you need a Celery-compatible connection that does not have a first-class
117+
connection type. The complete connection URI is read from a Secret, giving the user full
118+
control over the connection string.
119+
properties:
120+
uriSecret:
121+
description: The name of the Secret that contains an `uri` key with the complete SQLAlchemy URI.
122+
type: string
123+
required:
124+
- uriSecret
125+
type: object
126+
genericJDBC:
127+
description: |-
128+
A generic JDBC database connection for database types not covered by a dedicated variant.
129+
130+
Use this when you need to connect to a JDBC-compatible database that does not have a
131+
first-class connection type. You are responsible for providing the correct driver class name
132+
and a fully-formed JDBC URI as well as providing the needed classes on the Java classpath.
133+
properties:
134+
credentialsSecret:
135+
description: |-
136+
Name of a Secret containing the `username` and `password` keys used to authenticate
137+
against the database.
138+
type: string
139+
driver:
140+
description: |-
141+
Fully-qualified Java class name of the JDBC driver, e.g. `org.postgresql.Driver` or
142+
`com.mysql.jdbc.Driver`. The driver JAR must be provided by you on the classpath.
143+
type: string
144+
uri:
145+
description: |-
146+
The JDBC connection URI, e.g. `jdbc:postgresql://my-host:5432/mydb`. Credentials must
147+
not be embedded in this URI; they are instead injected via environment variables sourced
148+
from `credentials_secret`.
149+
format: uri
150+
type: string
151+
required:
152+
- credentialsSecret
153+
- driver
154+
- uri
155+
type: object
156+
genericSQLAlchemy:
157+
description: |-
158+
A generic SQLAlchemy database connection for database types not covered by a dedicated variant.
159+
160+
Use this when you need to connect to a SQLAlchemy-compatible database that does not have a
161+
first-class connection type. The complete connection URI is read from a Secret, giving the user
162+
full control over the connection string including any driver-specific options.
163+
properties:
164+
uriSecret:
165+
description: The name of the Secret that contains an `uri` key with the complete SQLAlchemy URI.
166+
type: string
167+
required:
168+
- uriSecret
169+
type: object
170+
mysql:
171+
description: Connection settings for a [MySQL](https://www.mysql.com/) database.
172+
properties:
173+
credentialsSecret:
174+
description: |-
175+
Name of a Secret containing the `username` and `password` keys used to authenticate
176+
against the MySQL server.
177+
type: string
178+
database:
179+
description: Name of the database (schema) to connect to.
180+
type: string
181+
host:
182+
description: Hostname or IP address of the MySQL server.
183+
type: string
184+
parameters:
185+
additionalProperties:
186+
type: string
187+
default: {}
188+
description: |-
189+
Additional map of JDBC connection parameters to append to the connection URL. The given
190+
`HashMap<String, String>` will be converted to query parameters in the form of
191+
`?param1=value1&param2=value2`.
192+
type: object
193+
port:
194+
default: 3306
195+
description: Port the MySQL server is listening on. Defaults to `3306`.
196+
format: uint16
197+
maximum: 65535.0
198+
minimum: 0.0
199+
type: integer
200+
required:
201+
- credentialsSecret
202+
- database
203+
- host
204+
type: object
205+
postgresql:
206+
description: Connection settings for a [PostgreSQL](https://www.postgresql.org/) database.
207+
properties:
208+
credentialsSecret:
209+
description: |-
210+
Name of a Secret containing the `username` and `password` keys used to authenticate
211+
against the PostgreSQL server.
212+
type: string
213+
database:
214+
description: Name of the database (schema) to connect to.
215+
type: string
216+
host:
217+
description: Hostname or IP address of the PostgreSQL server.
218+
type: string
219+
parameters:
220+
additionalProperties:
221+
type: string
222+
default: {}
223+
description: |-
224+
Additional map of JDBC connection parameters to append to the connection URL. The given
225+
`HashMap<String, String>` will be converted to query parameters in the form of
226+
`?param1=value1&param2=value2`.
227+
type: object
228+
port:
229+
default: 5432
230+
description: Port the PostgreSQL server is listening on. Defaults to `5432`.
231+
format: uint16
232+
maximum: 65535.0
233+
minimum: 0.0
234+
type: integer
235+
required:
236+
- credentialsSecret
237+
- database
238+
- host
239+
type: object
240+
redis:
241+
description: |-
242+
Connection settings for a [Redis](https://redis.io/) instance.
243+
244+
Redis is commonly used as a Celery message broker or result backend (e.g. for Apache Airflow).
245+
properties:
246+
credentialsSecret:
247+
description: |-
248+
Name of a Secret containing the `username` and `password` keys used to authenticate
249+
against the Redis server.
250+
type: string
251+
databaseId:
252+
default: 0
253+
description: |-
254+
Numeric index of the Redis logical database to use. Defaults to `0`.
255+
256+
Redis supports multiple logical databases within a single instance, identified by an
257+
integer index. Database `0` is the default.
258+
format: uint16
259+
maximum: 65535.0
260+
minimum: 0.0
261+
type: integer
262+
host:
263+
description: Hostname or IP address of the Redis server.
264+
type: string
265+
port:
266+
default: 6379
267+
description: Port the Redis server is listening on. Defaults to `6379`.
268+
format: uint16
269+
maximum: 65535.0
270+
minimum: 0.0
271+
type: integer
272+
required:
273+
- credentialsSecret
274+
- host
275+
type: object
276+
type: object
75277
domainName:
76278
description: A validated domain name type conforming to RFC 1123, so e.g. not an IP address
77279
type: string
@@ -2128,6 +2330,7 @@ spec:
21282330
required:
21292331
- clientAuthenticationDetails
21302332
- clusterOperation
2333+
- databaseConnection
21312334
- domainName
21322335
- gitSync
21332336
- hostName

‎crates/stackable-operator/src/client.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -590,7 +590,7 @@ impl Client {
590590
pub trait GetApi: Resource + Sized {
591591
/// The namespace type for `Self`'s scope.
592592
///
593-
/// This will be [`str`] for namespaced resource, and [`()`] for cluster-scoped resources.
593+
/// This will be [`str`] for namespaced resource, and `()` for cluster-scoped resources.
594594
type Namespace: ?Sized;
595595
/// Get a [`kube::Api`] for `Self`'s native scope..
596596
fn get_api(client: kube::Client, ns: &Self::Namespace) -> kube::Api<Self>

‎crates/stackable-operator/src/databases/databases/derby.rs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,20 @@ pub enum Error {
1313
ParseConnectionUrl { source: url::ParseError },
1414
}
1515

16-
/// TODO docs
16+
/// Connection settings for an embedded [Apache Derby](https://db.apache.org/derby/) database.
17+
///
18+
/// Derby is an embedded, file-based Java database engine that requires no separate server process.
19+
/// It is typically used for development, testing, or as a lightweight metastore backend (e.g. for
20+
/// Apache Hive).
1721
#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
1822
#[serde(rename_all = "camelCase")]
1923
pub struct DerbyConnection {
20-
/// TODO docs, especially on default
24+
/// Path on the filesystem where Derby stores its database files.
25+
///
26+
/// If not specified, defaults to `/tmp/derby/{unique_database_name}/derby.db`.
27+
/// The `{unique_database_name}` part is automatically handled by the operator and is added to
28+
/// prevent clashing database files. The `create=true` flag is always appended to the JDBC URL,
29+
/// so the database is created automatically if it does not yet exist at this location.
2130
pub location: Option<String>,
2231
}
2332

‎crates/stackable-operator/src/databases/databases/mysql.rs‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,24 +19,27 @@ pub enum Error {
1919
ParseConnectionUrl { source: url::ParseError },
2020
}
2121

22-
/// TODO docs
22+
/// Connection settings for a [MySQL](https://www.mysql.com/) database.
2323
#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
2424
#[serde(rename_all = "camelCase")]
2525
pub struct MysqlConnection {
26-
/// TODO docs
26+
/// Hostname or IP address of the MySQL server.
2727
pub host: HostName,
2828

29-
/// TODO docs
29+
/// Port the MySQL server is listening on. Defaults to `3306`.
3030
#[serde(default = "MysqlConnection::default_port")]
3131
pub port: u16,
3232

33-
/// TODO docs
33+
/// Name of the database (schema) to connect to.
3434
pub database: String,
3535

36-
/// TODO docs
36+
/// Name of a Secret containing the `username` and `password` keys used to authenticate
37+
/// against the MySQL server.
3738
pub credentials_secret: String,
3839

39-
/// TODO docs
40+
/// Additional map of JDBC connection parameters to append to the connection URL. The given
41+
/// `HashMap<String, String>` will be converted to query parameters in the form of
42+
/// `?param1=value1&param2=value2`.
4043
#[serde(default)]
4144
pub parameters: BTreeMap<String, String>,
4245
}

‎crates/stackable-operator/src/databases/databases/postgresql.rs‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,24 +23,27 @@ pub enum Error {
2323
ParseConnectionUrl { source: url::ParseError },
2424
}
2525

26-
/// TODO docs
26+
/// Connection settings for a [PostgreSQL](https://www.postgresql.org/) database.
2727
#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
2828
#[serde(rename_all = "camelCase")]
2929
pub struct PostgresqlConnection {
30-
/// TODO docs
30+
/// Hostname or IP address of the PostgreSQL server.
3131
pub host: HostName,
3232

33-
/// TODO docs
33+
/// Port the PostgreSQL server is listening on. Defaults to `5432`.
3434
#[serde(default = "PostgresqlConnection::default_port")]
3535
pub port: u16,
3636

37-
/// TODO docs
37+
/// Name of the database (schema) to connect to.
3838
pub database: String,
3939

40-
/// TODO docs
40+
/// Name of a Secret containing the `username` and `password` keys used to authenticate
41+
/// against the PostgreSQL server.
4142
pub credentials_secret: String,
4243

43-
/// TODO docs
44+
/// Additional map of JDBC connection parameters to append to the connection URL. The given
45+
/// `HashMap<String, String>` will be converted to query parameters in the form of
46+
/// `?param1=value1&param2=value2`.
4447
#[serde(default)]
4548
pub parameters: BTreeMap<String, String>,
4649
}

‎crates/stackable-operator/src/databases/databases/redis.rs‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,28 @@ use crate::{
1010
},
1111
};
1212

13-
/// TODO docs
13+
/// Connection settings for a [Redis](https://redis.io/) instance.
14+
///
15+
/// Redis is commonly used as a Celery message broker or result backend (e.g. for Apache Airflow).
1416
#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
1517
#[serde(rename_all = "camelCase")]
1618
pub struct RedisConnection {
17-
/// TODO docs
19+
/// Hostname or IP address of the Redis server.
1820
pub host: HostName,
1921

20-
/// TODO docs
22+
/// Port the Redis server is listening on. Defaults to `6379`.
2123
#[serde(default = "RedisConnection::default_port")]
2224
pub port: u16,
2325

24-
/// TODO docs
26+
/// Numeric index of the Redis logical database to use. Defaults to `0`.
27+
///
28+
/// Redis supports multiple logical databases within a single instance, identified by an
29+
/// integer index. Database `0` is the default.
2530
#[serde(default = "RedisConnection::default_database_id")]
2631
pub database_id: u16,
2732

28-
/// TODO docs
33+
/// Name of a Secret containing the `username` and `password` keys used to authenticate
34+
/// against the Redis server.
2935
pub credentials_secret: String,
3036
}
3137

‎crates/stackable-operator/src/databases/drivers/celery.rs‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,18 @@ use crate::{
77
databases::TemplatingMechanism,
88
};
99

10-
/// TODO docs
10+
/// Implemented by database connection types that can serve as a
11+
/// [Celery](https://docs.celeryq.dev/) broker or result backend.
12+
///
13+
/// Provides a standardized way to obtain a Celery connection URI template together with the
14+
/// necessary credential env vars, regardless of the concrete database or message broker type.
1115
pub trait CeleryDatabaseConnection {
12-
/// TODO docs, e.g. on what are valid characters for unique_database_name
16+
/// Returns the Celery connection details for the given `unique_database_name` using the
17+
/// default [`TemplatingMechanism`].
18+
///
19+
/// `unique_database_name` identifies this particular database connection within the operator
20+
/// and is used as a prefix when naming the injected environment variable. It must consist only
21+
/// of uppercase ASCII letters and underscores.
1322
fn celery_connection_details(
1423
&self,
1524
unique_database_name: &str,
@@ -20,6 +29,9 @@ pub trait CeleryDatabaseConnection {
2029
)
2130
}
2231

32+
/// Like [`Self::celery_connection_details`], but allows specifying a [`TemplatingMechanism`]
33+
/// explicitly. Use this when the calling context controls how configuration files are rendered,
34+
/// e.g. when using bash env substitution instead of config-utils.
2335
fn celery_connection_details_with_templating(
2436
&self,
2537
unique_database_name: &str,
@@ -60,7 +72,12 @@ impl CeleryDatabaseConnectionDetails {
6072
}
6173
}
6274

63-
/// TODO docs
75+
/// A generic Celery database connection for broker or result backend types not covered by a
76+
/// dedicated variant.
77+
///
78+
/// Use this when you need a Celery-compatible connection that does not have a first-class
79+
/// connection type. The complete connection URI is read from a Secret, giving the user full
80+
/// control over the connection string.
6481
#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
6582
#[serde(rename_all = "camelCase")]
6683
pub struct GenericCeleryDatabaseConnection {

0 commit comments

Comments
 (0)