Stackable operator-rs

https://github.com/stackabletech/operator-rs
Admin
A simple Rust library providing helper methods, structs, and enums for writing Kubernetes...
Tokens:88,654
Snippets:689
Trust Score:9.2
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example usage of WebhookServer

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-webhook.md

Shows how to construct WebhookServerOptions and create a WebhookServer instance.

```rust
use stackable_webhook::{WebhookServer, WebhookServerOptions};

let webhook_options = WebhookServerOptions {
    socket_addr: WebhookServer::DEFAULT_SOCKET_ADDRESS,
    webhook_namespace: "my-namespace".to_owned(),
    webhook_service_name: "my-operator".to_owned(),
};
let server = WebhookServer::new(webhooks, webhook_options).await.unwrap();
server.run(shutdown_signal).await.unwrap();

```

--------------------------------

### Example: using condition builders with compute_conditions

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/status-logging.md

Complete example showing how to implement `HasStatusCondition` for a custom status struct, build DaemonSet and StatefulSet condition builders, and call `compute_conditions` to compute new conditions.

```rust
use stackable_operator::status::condition::{
    ClusterCondition, compute_conditions,
    daemonset::DaemonSetConditionBuilder,
    statefulset::StatefulSetConditionBuilder,
};

struct ClusterStatus { conditions: Vec<ClusterCondition> }

impl HasStatusCondition for ClusterStatus {
    fn conditions(&self) -> Vec<ClusterCondition> { self.conditions.clone() }
}

let mut ds_builder = DaemonSetConditionBuilder::default();
ds_builder.add(my_daemonset);
let mut ss_builder = StatefulSetConditionBuilder::default();
ss_builder.add(my_statefulset);

let new_status = compute_conditions(
    &old_status,
    &[&ds_builder as &dyn ConditionBuilder, &ss_builder as &dyn ConditionBuilder],
);

```

--------------------------------

### Example JSON dump from containerdebug --output

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/containerdebug/README.md

Example output of the containerdebug tool when using the --output=/path/to/dump.json flag. The format is JSON and is intended for querying with tools like jq, but is not stable and may change over time.

```json
{
  "resources": {
    "cpu_count": 8,
    "physical_core_count": 8,
    "total_memory": 24604889088,
    "free_memory": 17228574720,
    "available_memory": 22974619648,
    "used_memory": 1630269440,
    "total_swap": 0,
    "free_swap": 0,
    "used_swap": 0,
    "total_memory_cgroup": null,
    "free_memory_cgroup": null,
    "free_swap_cgroup": null
  },
  "os": {
    "name": "NixOS",
    "kernel_version": "6.6.46",
    "version": "Linux 24.11 NixOS",
    "host_name": "nixos2",
    "cpu_arch": "x86_64"
  },
  "current_user": {
    "name": "nat",
    "uid": "1000",
    "gid": "100"
  },
  "disks": [
    {
      "name": "/dev/sda2",
      "mount_point": "/",
      "total_space": 106298343424,
      "available_space": 72267354112
    },
    {
      "name": "/dev/sda2",
      "mount_point": "/nix/store",
      "total_space": 106298343424,
      "available_space": 72267354112
    },
    {
      "name": "/dev/sda1",
      "mount_point": "/boot",
      "total_space": 1071624192,
      "available_space": 1022820352
    }
  ],
  "network": {
    "interfaces": {
      "enp1s0": [
        "192.168.122.138",
        "fe80::5054:ff:fe91:5652"
      ],
      "lo": [
        "127.0.0.1",
        "::1"
      ],
      "br-82bbc663b8a3": [
        "172.18.0.1",
        "fc00:f853:ccd:e793::1"
      ],
      "docker0": [
        "172.17.0.1"
      ]
    },
    "reverse_lookups": {
      "fe80::5054:ff:fe91:5652": [
        "nixos2."
      ],
      "127.0.0.1": [
        "localhost."
      ],
      "192.168.122.138": [
        "nixos2.kvm."
      ],
      "::1": [
        "localhost."
      ],
      "172.17.0.1": [
        "nixos2.",
        "nixos2.local."
      ],
      "172.18.0.1": [
        "nixos2.",
        "nixos2.local."
      ]
    },
    "forward_lookups": {
      "nixos2.kvm.": [
        "127.0.0.2"
      ],
      "nixos2.": [
        "127.0.0.2"
      ],
      "nixos2.local.": [
        "192.168.122.138",
        "172.18.0.1",
        "172.17.0.1"
      ],
      "localhost.": [
        "127.0.0.1"
      ]
    }
  }
}
```

--------------------------------

### Usage example for parsing, constructing, and ordering versions

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/k8s-version.md

Shows usage of the k8s-version crate: parsing API versions from strings, constructing them programmatically, and comparing versions. Note that `Group::from_str("extension")` is used even though the parsed example uses "extensions".

```rust
use std::str::FromStr;
use k8s_version::{ApiVersion, Group, Level, Version};

// Parsing
let api_version = ApiVersion::from_str("extensions/v1beta1").unwrap();
let parsed: ApiVersion = "extensions/v1alpha1".parse().unwrap();

// Constructing
let version = Version::new(1, Some(Level::Beta(1)));
let group = Group::from_str("extension").unwrap();
let api_version = ApiVersion::new(Some(group), version);
assert_eq!(api_version.to_string(), "extension/v1beta1");

// Ordering
assert!(Version::new(1, Some(Level::Alpha(1))) < Version::new(1, Some(Level::Beta(1))));
assert!(Version::new(1, None) > Version::new(1, Some(Level::Beta(99))));
```

--------------------------------

### Example CLI invocation for template subcommand

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/config-utils.md

Shows how to run the template subcommand with a file, file type, and escape flag.

```sh
config-utils template --file /stackable/conf/hive.properties --file-type properties --escape
```

--------------------------------

### Usage example for memory helpers

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/memory-cpu.md

Shows how to use `to_java_heap` and `MemoryQuantity` to convert a quantity to a Java heap string and format a memory value for Java.

```rust
use stackable_operator::memory::{BinaryMultiple, MemoryQuantity, to_java_heap};

let heap = to_java_heap(&Quantity("1Gi".to_owned()), 0.75)
    .expect("valid quantity");
let mem = MemoryQuantity::from_mebi(512.0)
    .scale_to(BinaryMultiple::Mebi)
    .format_for_java()
    .expect("valid java unit");
```

--------------------------------

### Example: get_enabled_feature_gates usage

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Example usage of `get_enabled_feature_gates` to iterate over enabled feature gates and check for a specific name. This requires the `client-feature-gates` crate feature.

```rust
// Only available with the `client-feature-gates` crate feature
let enabled = client.get_enabled_feature_gates().await?;
for gate in enabled {
    if gate.name == "AllowDNSOnlyNodeCSR" { /* ... */ }
}
```

--------------------------------

### containerdebug command-line usage examples

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/containerdebug.md

Shows three common invocations: print once, loop every 5 minutes, and write JSON output to a file.

```sh
containerdebug                       # print environment info once
containerdebug --loop=5m             # collect every 5 minutes
containerdebug -o /tmp/debug.json    # write JSON output
```

--------------------------------

### Condition builder usage example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/status-logging.md

Shows how to instantiate a `StatefulSetConditionBuilder` and add a `StatefulSet` to it. Similar builders exist for DaemonSet, Deployment, and operations.

```rust
let mut builder = StatefulSetConditionBuilder::default();
builder.add(StatefulSet::default());
// or DaemonSetConditionBuilder / DeploymentConditionBuilder / operation builders

```

--------------------------------

### Usage exemplar for product_logging

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/product-logging.md

Shows how to use the product_logging module: get a default container log config, convert a log level to a logback literal, and calculate a log volume size limit from memory quantities.

```rust
use stackable_operator::product_logging::{
    framework::calculate_log_volume_size_limit,
    spec::{LogLevel, default_container_log_config},
};

let log_config = default_container_log_config();
let level = LogLevel::Info.to_logback_literal(); // "INFO"
let size_limit = calculate_log_volume_size_limit(&[MemoryQuantity::from_mebi(64.0)]);
```

--------------------------------

### Build an HTTP GET probe

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Builds an HTTP GET probe with a period of 10 seconds and an initial delay of 5 seconds. The with_period call switches the builder into the Period state, and build returns a Result that is unwrapped with expect.

```rust
let probe = ProbeBuilder::http_get(
    HTTPGetAction::new(8080, "/health")
).with_period(Duration::from_secs(10))  // switches into Period state
 .with_initial_delay(Duration::from_secs(5))
 .build().expect("probe built");
```

--------------------------------

### Basic usage: initialize client and use get/apply_patch

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Basic usage: initialize the operator client and perform a get and an apply_patch operation.

```rust
use stackable_operator::client::{Client, initialize_operator};
use stackable_operator::utils::cluster_info::KubernetesClusterInfoOptions;

let cluster_info_options = KubernetesClusterInfoOptions::parse();
let client = initialize_operator(Some("my-operator"), &cluster_info_options)
    .await
    .expect("Unable to construct client.");

let pod = client.get::<Pod>("my-pod", &client.default_namespace).await?;
let updated = client
    .apply_patch("controller", &pod, serde_json::json!({ ... }))
    .await?;
```

--------------------------------

### Usage example (OPA): OpaConfig and document_url

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/commons.md

Constructs an OpaConfig with a config map name and optional package, then calls document_url with a cluster reference, an optional read action, and the newest OPA API version to obtain a URL.

```rust
use stackable_operator::commons::opa::{OpaApiVersion, OpaConfig};

let opa = OpaConfig {
    config_map_name: "opa",
    package: Some("my-product"),
};
let url = opa.document_url(&cluster, Some("read"), &OpaApiVersion::newest());
```

--------------------------------

### Example output of containerdebug tool

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/containerdebug/README.md

Shows the log output produced by the containerdebug tool on a virtual machine, listing system information like CPU, memory, swap, cgroup status, OS details, user, disks, and network interfaces.

```text
2025-02-03T11:37:47.420479Z  INFO containerdebug: stackable_operator::utils::logging: Starting
2025-02-03T11:37:47.420521Z  INFO containerdebug: stackable_operator::utils::logging: This is version 0.1.1 (Git information: 0.1.1-1-gcf51ae1), built for x86_64-unknown-linux-gnu by rustc 1.84.1 (e71f9a9a9 2025-01-27) at Tue, 1 Jan 1980 00:00:00 +0000
2025-02-03T11:37:47.420544Z  INFO containerdebug:SystemInformation::init: containerdebug::system_information: initializing
2025-02-03T11:37:47.426065Z  INFO containerdebug:SystemInformation::init: containerdebug::system_information: init finished
2025-02-03T11:37:47.426135Z  INFO containerdebug:SystemInformation::collect: containerdebug::system_information: Starting data collection
2025-02-03T11:37:47.426693Z  INFO containerdebug:SystemInformation::collect:Resources::collect: containerdebug::system_information::resources: cpus cpus.physical=8 cpus.cores.physical=8
2025-02-03T11:37:47.426727Z  INFO containerdebug:SystemInformation::collect:Resources::collect: containerdebug::system_information::resources: memory memory.total=24604889088 memory.free=17235124224 memory.available=22974955520 memory.used=1629933568
2025-02-03T11:37:47.426746Z  INFO containerdebug:SystemInformation::collect:Resources::collect: containerdebug::system_information::resources: swap swap.total=0 swap.free=0 swap.used=0
2025-02-03T11:37:47.426857Z  INFO containerdebug:SystemInformation::collect:Resources::collect: containerdebug::system_information::resources: not in a cgroup
2025-02-03T11:37:47.426940Z  INFO containerdebug:SystemInformation::collect:OperatingSystem::collect: containerdebug::system_information::os: operating system os.name="NixOS" os.kernel.version="6.6.46" os.version="Linux 24.11 NixOS" os.host_name="nixos2" os.cpu_arch="x86_64"
2025-02-03T11:37:47.427031Z  INFO containerdebug:SystemInformation::collect:User::collect_current: containerdebug::system_information::user: current user user.name="nat" user.uid="Uid(1000)" user.gid="Uid(1000)"
2025-02-03T11:37:47.427436Z  INFO containerdebug:SystemInformation::collect:Disk::collect_all: containerdebug::system_information::disk: found disk disk.mount_point="/" disk.name="/dev/sda2" disk.space.total=106298343424 disk.space.available=72663478272
2025-02-03T11:37:47.427483Z  INFO containerdebug:SystemInformation::collect:Disk::collect_all: containerdebug::system_information::disk: found disk disk.mount_point="/nix/store" disk.name="/dev/sda2" disk.space.total=106298343424 disk.space.available=72663478272
2025-02-03T11:37:47.427499Z  INFO containerdebug:SystemInformation::collect:Disk::collect_all: containerdebug::system_information::disk: found disk disk.mount_point="/boot" disk.name="/dev/sda1" disk.space.total=1071624192 disk.space.available=1022820352
2025-02-03T11:37:47.428771Z  INFO containerdebug:SystemInformation::collect:SystemNetworkInfo::collect: containerdebug::system_information::network: found network interface network.interface.name="lo" network.interface.address=127.0.0.1
2025-02-03T11:37:47.428821Z  INFO containerdebug:SystemInformation::collect:SystemNetworkInfo::collect: containerdebug::system_information::network: found network interface network.interface.name="enp1s0" network.interface.address=192.168.122.138
2025-02-03T11:37:47.428836Z  INFO containerdebug:SystemInformation::collect:SystemNetworkInfo::collect: containerdebug::system_information::network: found network interface network.interface.name="br-82bbc663b8a3" network.interface.address=172.18.0.1
2025-02-03T11:37:47.428847Z  INFO containerdebug:SystemInformation::collect:SystemNetworkInfo::collect: containerdebug::system_information::network: found network interface network.interface.name="docker0" network.interface.address=172.17.0.1
2025-02-03T11:37:47.428861Z  INFO containerdebug:SystemInformation::collect:SystemNetworkInfo::collect: containerdebug::system_information::network: found network interface network.interface.name="lo" network.interface.address=::1
```

--------------------------------

### versioned attribute macro example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-versioned.md

Example of using the #[versioned] attribute macro to generate a versioned module (v1alpha1) with conversion machinery. The comment indicates the generated code.

```rust
use stackable_operator::versioned::versioned;

#[versioned(version(name = "v1alpha1"))]
mod versioned {
    struct Foo {
        bar: usize,
    }
}
// Generated: mod v1alpha1 { struct Foo { bar: usize } } and conversion machinery
```

--------------------------------

### get

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Retrieves a single resource instance by name. Returns the deserialized resource.

```APIDOC
## get

### Description
Retrieves a single resource instance by name. Returns the deserialized resource.

### Method
get

### Signature
```rust
pub async fn get<T>(&self, resource_name: &str, namespace: &T::Namespace) -> Result<T>
where
    T: Clone + Debug + DeserializeOwned + Resource + GetApi,
    <T as Resource>::DynamicType: Default,
```

### Parameters
- `resource_name` (str) - Required - The name of the resource to retrieve.
- `namespace` (T::Namespace) - Required - The namespace of the resource.

### Returns
- `Result<T>` - The deserialized resource.
```

--------------------------------

### S3 connection reference example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/crd.md

Shows how to create an S3 connection reference using InlineConnectionOrReference and ClusterRef. Use when configuring S3 connections in stackable-operator CRDs.

```rust
use stackable_operator::crd::s3::connection::InlineConnectionOrReference;
use stackable_operator::crd::ClusterRef;

let s3 = InlineConnectionOrReference::Reference(ClusterRef::to_named("my-s3", None));
```

--------------------------------

### WebhookServer run method signature

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-webhook.md

Signature for the async run method that starts the server and certificate rotation loop.

```rust
pub async fn run<F>(self, shutdown_signal: F) -> Result<()>
// where F: Future<Output = ()>

```

--------------------------------

### TlsClientDetailsWithSecureDefaults

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/commons.md

Provides methods to add TLS volumes and mounts to PodBuilder/ContainerBuilder, check TLS usage, and get the CA certificate mount path.

```APIDOC
## TlsClientDetailsWithSecureDefaults

### Description
Provides methods to add TLS volumes and mounts to PodBuilder/ContainerBuilder, check TLS usage, and get the CA certificate mount path.

### Methods
- `add_volumes_and_mounts(/* to PodBuilder/ContainerBuilder */) -> Result<()>` - Adds TLS volumes and mounts to the given builder.
- `volumes_and_mounts(/* ... */)` - Returns the TLS volumes and mounts.
- `const fn uses_tls(&self) -> bool` - Returns whether TLS is used.
- `fn uses_tls_verification(&self) -> bool` - Returns whether TLS verification is used.
- `fn tls_ca_cert_mount_path(&self) -> Option<String>` - Returns the mount path for the CA certificate, if any.
```

--------------------------------

### as_kube_client: Get unwrapped kube::Client

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Returns an unwrapped `kube::Client` that can be freely used without cloning first.

```rust
pub fn as_kube_client(&self) -> KubeClient
```

--------------------------------

### get_api, get_all_api, get_namespaced_api: Get kube::Api handles

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Return namespaced or cluster-scoped `kube::Api<T>` handles.

```rust
pub fn get_api<T>(&self, namespace: &T::Namespace) -> Api<T>
// T: Resource + GetApi
pub fn get_all_api<T>(&self) -> Api<T>
// T: Resource
#[deprecated(note = "Use Api::get_api instead", since = "0.26.0")]
pub fn get_namespaced_api<T>(&self, namespace: &str) -> Api<T>
```

--------------------------------

### Create labels with Label::try_from and Labels::try_from

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/kvp.md

Creates a single label and a set of labels from key-value pairs using `Label::try_from` and `Labels::try_from`. Both calls expect valid input; the example asserts the string representation of the single label and uses `.expect("valid labels")` to panic on invalid pairs.

```rust
use stackable_operator::kvp::{Label, Labels};

let label = Label::try_from(("stackable.tech/vendor", "Stackable"))
    .expect("valid pair");
assert_eq!(label.to_string(), "stackable.tech/vendor=Stackable");

let labels = Labels::try_from([
    ("app.kubernetes.io/name", "zookeeper"),
    ("app.kubernetes.io/instance", "test-01"),
])
.expect("valid labels");
```

--------------------------------

### Generate ECDSA leaf certificate example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-certs.md

Creates a CertificateAuthority with a fresh ECDSA key and generates a leaf certificate for a webhook service, with a 90-day validity.

```rust
use stackable_certs::ca::CertificateAuthority;

let mut ca = CertificateAuthority::new_ecdsa().expect("CA created");
let cert_pair = ca
    .generate_ecdsa_leaf_certificate(
        "webhook",
        "stackable-operators",
        ["webhook.stackable-operators.svc.cluster.local"],
        Duration::from_days_unchecked(90),
    )
    .expect("leaf certificate generated");
```

--------------------------------

### Usage of ClusterResources

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/cluster-resources.md

Usage example: creates ClusterResources for a Zookeeper operator, adds a ClusterRole and a ServiceAccount, then deletes orphaned resources. Requires the client to be in scope.

```rust
use stackable_operator::cluster_resources::{
    ClusterResource, ClusterResourceApplyStrategy, ClusterResources,
};

let resources = ClusterResources::new(
    "zookeeper", "zookeeper.stackable.tech", "zookeepercluster", /* cluster ref */,
);
resources.add::<ClusterRole>(my_cluster_role).await?;
resources.add::<ServiceAccount>(my_service_account).await?;
resources.delete_orphaned_resources(&client).await?;
```

--------------------------------

### Usage example with validate_config and estimated_replica_count

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/role-utils.md

Shows how to use RoleGroup::validate_config to validate a role group configuration and estimated_replica_count to compute the total replica count from all role groups in a cluster. The validate_config call expects the role group config to be valid.

```rust
use stackable_operator::role_utils::{Role, RoleGroup};

let validated = role_group
    .validate_config(&role, &default_config_fragment)
    .expect("role group config valid");
let replicas = estimated_replica_count(
    cluster.role_groups().values().map(|rg| rg.replicas),
);
```

--------------------------------

### ResourceRequirementsBuilder API and usage example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

The first block lists the public API of ResourceRequirementsBuilder, including state-machine generics and fluent methods for CPU and memory requests/limits. The second block shows a typical usage that sets a CPU limit and a memory range before building the ResourceRequirements.

```rust
pub struct ResourceRequirementsBuilder<CR, CL, MR, ML> { /* state-machine generics */ }
pub fn new() -> Self
pub fn with_cpu_request(&mut self, request: impl Into<Quantity>) -> ...
pub fn with_cpu_range(&mut self, request: impl Into<Quantity>, limit: impl Into<Quantity>) -> ...
pub fn with_cpu_limit(&mut self, limit: impl Into<Quantity>) -> ...
pub fn with_memory_request(&mut self, request: impl Into<Quantity>) -> ...
pub fn with_memory_range(&mut self, request: impl Into<Quantity>, limit: impl Into<Quantity>) -> ...
pub fn with_memory_limit(&mut self, limit: impl Into<Quantity>) -> ...
pub fn with_resource(&mut self, resource: impl Into<Quantity>) -> ...
pub fn build(&self) -> ResourceRequirements
```

```rust
let resources = ResourceRequirementsBuilder::new()
    .with_cpu_limit("1")
    .with_memory_range("1Gi", "2Gi")
    .build();
```

--------------------------------

### Parse an API version with k8s_version::ApiVersion

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/k8s-version/README.md

Parses a Kubernetes API version string using the from_str method. The example expects a valid version string such as "extensions/v1beta1".

```rust
use k8s_version::ApiVersion;

let api_version = ApiVersion::from_str("extensions/v1beta1")?;
```

--------------------------------

### Client methods for feature gates

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

These are the public methods on the client for retrieving feature gates. `get_feature_gates` performs a raw `GET /metrics` request to the API server and parses lines starting with the `kubernetes_feature_enabled` metric.

```rust
pub async fn get_feature_gates(&self) -> Result<Vec<FeatureGate>>
pub async fn get_enabled_feature_gates(&self) -> Result<Vec<FeatureGate>>
pub async fn get_disabled_feature_gates(&self) -> Result<Vec<FeatureGate>>
```

--------------------------------

### Create example.xml with placeholders

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/config-utils/README.md

Creates an XML file with placeholders for environment variable and file content. The ${env:EXAMPLE_USERNAME} placeholder is replaced with the value of the EXAMPLE_USERNAME environment variable, and ${file:UTF-8:example-password} is replaced with the contents of the example-password file.

```xml
cat > example.xml << 'EOF'
<credentials>
  <username>${env:EXAMPLE_USERNAME}</username>
  <password>${file:UTF-8:example-password}</password>
</credentials>
EOF
```

--------------------------------

### ClusterRef<K> struct and usage example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/crd.md

The struct definition and a usage example for the ClusterRef type. The struct is generic over the resource kind K, which is stored as a phantom type. The usage example shows constructing a reference with to_named and then resolving the namespace relative to an owner object.

```rust
#[derive(Deserialize, Serialize, JsonSchema, Educe)]
#[educe(
    Clone(bound()),
    Debug(bound()),
    Default(bound()),
    PartialEq(bound()),
    Eq(bound())
)]
pub struct ClusterRef<K> {
    /// The name of the cluster
    pub name: Option<String>,

    /// The namespace of the cluster
    ///
    /// This field is optional, and will default to the namespace of the referring object.
    #[serde(default)]
    pub namespace: Option<String>,

    #[serde(skip)]
    _kind: PhantomData<K>,
}
```

```rust
let ref = ClusterRef::<ZookeeperCluster>::to_named("my-zookeeper", None);
let ns = ref.namespace_relative_from(&self_ctx_owner); // defaults to owner namespace
```

--------------------------------

### Run config-utils template command

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/config-utils/README.md

Sets the EXAMPLE_USERNAME environment variable and runs the config-utils template command on example.xml. This replaces the placeholders with the environment variable value and the file contents, escaping them for XML.

```bash
export EXAMPLE_USERNAME=my-user

config-utils template example.xml
```

--------------------------------

### Create example-password file

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/config-utils/README.md

Creates a file named example-password containing the string 'example-password <123>!'. This file is referenced by the ${file:UTF-8:example-password} placeholder in the example.xml file.

```bash
echo 'example-password <123>!' > example-password
```

--------------------------------

### Use report_controller_reconciled in a reconciliation example

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/status-logging.md

Example usage of report_controller_reconciled within a futures::try_join! macro, passing the client, cluster, and reconcile error. This demonstrates how to report reconciliation outcomes in a controller.

```rust
use stackable_operator::logging::controller::report_controller_reconciled;

let reconcile_results = futures::try_join!(
    report_controller_reconciled::<MyCluster, _, _>(&client, &cluster, reconcile_error)
);

```

--------------------------------

### Marker traits HasInstance and HasApplication

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/crd.md

Defines two marker traits for custom resources: HasInstance provides a method to get the instance name, and HasApplication provides a static method to get the application name. These traits are used to standardize resource identification across operators.

```rust
/// Retrieve the custom resource name (e.g. simple-test-cluster).
pub trait HasInstance {
    fn get_instance_name(&self) -> &str;
}

/// Retrieve the application name (e.g. spark, zookeeper).
pub trait HasApplication {
    fn get_application_name() -> &'static str;
}
```

--------------------------------

### GetApi trait

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Trait for getting kube::Api instances for a Kubernetes resource's scope.

```APIDOC
## `GetApi` trait

### Description
Helper trait for getting `kube::Api` instances for a Kubernetes resource's scope.

### Method
Trait method

### Signature
```rust
pub trait GetApi: Resource + Sized {
    type Namespace: ?Sized;
    fn get_api(client: kube::Client, ns: &Self::Namespace) -> kube::Api<Self>
    where
        Self::DynamicType: Default;
    fn get_namespace(&self) -> &Self::Namespace;
}
```

### Parameters
- `client` (`kube::Client`) - Required - The Kubernetes client.
- `ns` (`&Self::Namespace`) - Required - The namespace for the resource's scope.

### Returns
- `kube::Api<Self>` - The API instance for the resource's scope.

### Notes
Blanket-implemented for all `Resource` types via the hidden `GetApiImpl` trait:
- `(K, NamespaceResourceScope)` → `Namespace = str`, namespaced API, namespace from `meta().namespace`
- `(K, ClusterResourceScope)` → `Namespace = ()`, cluster-scoped API (`Api::all`), namespace is `&()`
```

--------------------------------

### Initialize tracing with Tracing::pre_configured

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-telemetry.md

Initializes the tracing subsystem with pre-configured options. The returned guard must be kept alive for the process lifetime; dropping it flushes the telemetry.

```rust
use stackable_operator::telemetry::Tracing;

let tracing = Tracing::pre_configured("my-operator", telemetry_options).init()
    .expect("tracing initialized");
// tracing guard kept alive for the process lifetime; drop it to flush
```

--------------------------------

### Build a Pod with PodBuilder

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Builds a Pod using the PodBuilder fluent API, chaining metadata, container, volume, and termination grace period settings before calling build(). Requires the builder methods to return Result where noted, and uses expect() to handle errors.

```rust
let pod = PodBuilder::new()
    .metadata_builder(|b| b.name("test"))
    .add_container(ContainerBuilder::new("main").expect("name")
        .image("my/image:1.0").build())
    .add_empty_dir_volume("data", Some(Quantity("1Gi")))
    .expect("volume added")
    .termination_grace_period(&Duration::from_secs(42))
    .expect("grace period ok")
    .build()
    .expect("pod built");
```

--------------------------------

### Constructing ProductName and ClusterName

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/v2.md

Shows how to construct ProductName and ClusterName from strings. ProductName uses FromStr and expects a valid product name; ClusterName uses TryFrom and may fail if the cluster name is too long.

```rust
use stackable_operator::v2::types::operator::{ClusterName, ProductName, RoleName};

let product = ProductName::from_str("opensearch").expect("valid product name");
let cluster = ClusterName::try_from("my-cluster").expect("cluster too long?");
```

--------------------------------

### get: Retrieve resource by name

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Retrieves a single resource instance by name. Returns `Result<T>` — the deserialized resource.

```rust
pub async fn get<T>(&self, resource_name: &str, namespace: &T::Namespace) -> Result<T>
where
    T: Clone + Debug + DeserializeOwned + Resource + GetApi,
    <T as Resource>::DynamicType: Default,
```

--------------------------------

### create: Create a new resource

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Creates a new resource.

```rust
pub async fn create<T>(&self, resource: &T) -> Result<T>
// T: Clone + Debug + DeserializeOwned + Resource + Serialize + GetApi
```

--------------------------------

### get_opt: Retrieve resource if it exists

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Retrieves a resource if it exists. Returns `Result<Option<T>>`.

```rust
pub async fn get_opt<T>(
    &self,
    resource_name: &str,
    namespace: &T::Namespace,
) -> Result<Option<T>>
where
    T: Clone + Debug + DeserializeOwned + Resource + GetApi,
    <T as Resource>::DynamicType: Default,
```

--------------------------------

### ContainerBuilder::startup_probe

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Sets the startup probe for the container.

```APIDOC
## ContainerBuilder::startup_probe

### Description
Sets the startup probe for the container.

### Method
`pub fn startup_probe(&mut self, probe: Probe) -> &mut Self`

### Parameters
- **probe** (`Probe`) - Required - The startup probe configuration.

### Returns
- `&mut Self` - Returns a mutable reference to the builder for chaining.

### Example
```rust
builder.startup_probe(probe);
```
```

--------------------------------

### create

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Creates a new resource.

```APIDOC
## create

### Description
Creates a new resource.

### Method
create

### Signature
```rust
pub async fn create<T>(&self, resource: &T) -> Result<T>
// T: Clone + Debug + DeserializeOwned + Resource + Serialize + GetApi
```

### Parameters
- `resource` (T) - Required - The resource to create.

### Returns
- `Result<T>` - The created resource.
```

--------------------------------

### Generate snapshot files with `cargo insta test -p stackable-versioned-macros --all-features`

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/stackable-versioned-macros/tests/README.md

Generates new snapshot files (with a `.new` extension) in the `snapshots` folder. These files must not appear on `main` but can be shared on branches; review them with `cargo insta review` and accept or fix them.

```shell
cargo insta test -p stackable-versioned-macros --all-features
```

--------------------------------

### Build a container with ContainerBuilder

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Builds a container with a required name, an image, an environment variable, and a volume mount. The name must be a valid RFC 1123 label (≤63 characters); invalid names or volume mount failures cause the expect calls to panic.

```rust
let container = ContainerBuilder::new("main")
    .expect("container name invalid")
    .image("busybox:latest")
    .add_env_var("FOO", "bar")
    .add_volume_mount("data", "/data", true)
    .expect("volume mount failed")
    .build();
```

--------------------------------

### OpaConfig

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/commons.md

Configuration for OPA (Open Policy Agent) integration, including the config map name and package. Provides a method to get the document URL.

```APIDOC
## OpaConfig

### Description
Configuration for OPA (Open Policy Agent) integration, including the config map name and package. Provides a method to get the document URL.

### Fields
- `config_map_name` (String) - The name of the ConfigMap containing the OPA policy.
- `package` (Option<String>) - The OPA package name.

### Methods
- `document_url(&self, cluster: &Cluster, path: Option<&str>, api_version: &OpaApiVersion) -> String` - Returns the URL to the OPA document for the given cluster, path, and API version.
```

--------------------------------

### database_connections helper functions

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/misc.md

Helper functions for generating environment variable names and URL query parameters for database connections. The second function takes a unique database name and returns a tuple of username and password environment variable names.

```rust
pub fn username_and_password_envs(/* ... */) -> Vec<(String, String)>
pub fn username_and_password_env_names(unique_database_name: &str) -> (String, String)
pub fn connection_parameters_as_url_query_parameters(/* ... */) -> String
```

--------------------------------

### Using CustomResourceExt to write YAML schema

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-shared.md

Example usage of the CustomResourceExt trait to write a YAML schema for a custom resource, using the operator version '1.2.0'.

```rust
use stackable_operator::CustomResourceExt;
MyCluster::write_yaml_schema("/tmp/my-cluster.yaml", "1.2.0").expect("schema written");
```

--------------------------------

### CLI options struct (Opts) with clap attributes

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/containerdebug.md

Defines the command-line options for containerdebug using clap. Includes --loop for repeated collection, -o/--output for JSON output, and flattened telemetry arguments.

```rust
/// Collects and prints helpful debugging information about the environment that it is running in.
#[derive(clap::Parser)]
struct Opts {
    /// Loop every DURATION, instead of shutting down once completed (default DURATION: 30m)
    #[clap(
        long = "loop",
        value_name = "INTERVAL",
        default_missing_value = "30m",
        num_args = 0..=1,
        require_equals = true,
    )]
    loop_interval: Option<stackable_shared::time::Duration>,

    /// Write collected information to OUTPUT as JSON
    #[clap(long, short = 'o')]
    output: Option<PathBuf>,

    #[clap(flatten)]
    pub telemetry_arguments: TelemetryOptions,
}
```

--------------------------------

### list

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Lists all instances of a resource type in a namespace, with optional list parameters.

```APIDOC
## list

### Description
Lists all instances of a resource type in a namespace, with optional list parameters.

### Method
list

### Signature
```rust
pub async fn list<T>(
    &self,
    namespace: &T::Namespace,
    list_params: &ListParams,
) -> Result<Vec<T>>
```

### Parameters
- `namespace` (T::Namespace) - Required - The namespace to list resources from.
- `list_params` (ListParams) - Required - Parameters for listing, may carry `label_selector` / `field_selector`.

### Returns
- `Result<Vec<T>>` - A vector of resources.
```

--------------------------------

### Validate role name with is_lowercase_rfc_1123_label

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/utils.md

Example usage of the validation function. It checks if a role name is a valid lowercase RFC 1123 label and logs an error if not.

```rust
if !is_lowercase_rfc_1123_label(role_name).is_ok() {
    tracing::error!("invalid role name");
}
```

--------------------------------

### GenericRoleConfig and EmptyRoleConfig structures

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/role-utils.md

Default configuration structures for roles.

```rust
pub struct GenericRoleConfig {
    // resources: Option<Resources<Quantity>>
    #[serde(default)]
    // + further defaulted fields
}
pub struct EmptyRoleConfig {}
```

--------------------------------

### Pattern constants for env and file substitution

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/config-utils.md

Defines start and end patterns for environment variable and file-based substitutions, including escaped variants where the colon is escaped.

```rust
// It could be the case that the colon (:) in the start pattern has been escaped
pub const ENV_VAR_START_PATTERNS: [&str; 2] = ["${env:", "${env\\:"];
pub const ENV_VAR_END_PATTERN: &str = "}";

pub const FILE_START_PATTERNS: [&str; 2] = ["${file:UTF-8:", "${file\\:UTF-8\\:"];
pub const FILE_END_PATTERN: &str = "}";
```

--------------------------------

### tracing module declaration with Error enum

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-telemetry.md

Declares the tracing module's settings submodule and an Error enum for initialization errors (logger/tracer provider setup).

```rust
pub mod settings;

pub enum Error {
    // initialization errors (logger/tracer provider setup); see errors.md
}
```

--------------------------------

### BinaryMultiple enum and methods

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/memory-cpu.md

Defines the `BinaryMultiple` enum with variants for KiB, MiB, GiB, TiB, and methods to convert to Java memory unit strings and get the smallest unit.

```rust
pub enum BinaryMultiple {
    // KiB, MiB, GiB, TiB (variants)
}
impl BinaryMultiple {
    pub fn to_java_memory_unit(&self) -> String
    pub const fn get_smallest() -> Self
}
```

--------------------------------

### Usage of config_overrides

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/config-overrides-deep-merge.md

Shows how to create KeyValueConfigOverrides and JsonConfigOverrides from CLI/JSON overrides and apply them to a base JSON value.

```rust
use stackable_operator::config_overrides::{JsonConfigOverrides, KeyValueConfigOverrides};

let kv = KeyValueConfigOverrides::try_from(cli_overrides).expect("valid overrides");
let json = JsonConfigOverrides::try_from(json_overrides).expect("valid JSON overrides");
let merged = json.apply(&base_json).expect("overrides applied");
```

--------------------------------

### Basic no-op handler for MutatingWebhook

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-webhook.md

Shows the expected handler signature for MutatingWebhook. The handler receives an Arc<S> and an AdmissionRequest<R> and returns an AdmissionResponse. This example is a no-op that returns a response from the request.

```rust
// Basic no-op handler signature expected by MutatingWebhook
pub async fn my_handler(
    ctx: Arc<()>,
    request: AdmissionRequest<StatefulSet>,
) -> AdmissionResponse {
    AdmissionResponse::from(&request)
}
```

--------------------------------

### ContainerBuilder::lifecycle_post_start / lifecycle_pre_stop

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Sets the post-start or pre-stop lifecycle handlers.

```APIDOC
## ContainerBuilder::lifecycle_post_start / lifecycle_pre_stop

### Description
Sets the post-start or pre-stop lifecycle handlers.

### Method
These are setter methods that accept a `LifecycleHandler`.

### Parameters
- **handler** (`LifecycleHandler`) - Required - The lifecycle handler to set.

### Returns
- `&mut Self` - Returns a mutable reference to the builder for chaining.

### Example
```rust
builder.lifecycle_post_start(handler);
// or
builder.lifecycle_pre_stop(handler);
```
```

--------------------------------

### constant! macro usage: DATA_VOLUME_NAME and CONFIG_VOLUME_NAME

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/v2.md

Example usage of the constant! macro, which defines a LazyLock constant from a string via FromStr::from_str. The first defines a private constant, the second a public one.

```rust
constant!(DATA_VOLUME_NAME: VolumeName = "data");
constant!(pub CONFIG_VOLUME_NAME: VolumeName = "config");
```

--------------------------------

### Input file structure with `// ---` delimiters for `#[versioned]` snapshot tests

Source: https://github.com/stackabletech/operator-rs/blob/main/crates/stackable-versioned-macros/tests/README.md

Shows the required input file structure for snapshot tests: three `// ---` delimiters split the file into imports, the attribute macro, the item, and the rest of the code. The delimiter is `// ---\n` and doc comments on the container must be placed after the delimiter.

```rust
use stackable_versioned::versioned;
// --- <- See here!
#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    version(name = "v1")
)]
// --- <- See here!
pub(crate) struct Foo {
    #[versioned(
        changed(since = "v1beta1", from_name = "jjj", from_type = "u8"),
        changed(since = "v1", from_type = "u16"),
    )]
    bar: usize,
    baz: bool,
}
// --- <- See here!
fn main() {}

// Rest of code ...
```

--------------------------------

### Using the versioned! macro

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/stackable-versioned-macros.md

Example of using the versioned! macro to define a versioned struct. The macro must be placed before other derive macros and attributes. It declares a version v1alpha1 and defines a struct Foo with a field bar.

```rust
use stackable_versioned::versioned;
#[versioned(version(name = "v1alpha1"))]
mod versioned {
    struct Foo {
        bar: usize,
    }
}
```

--------------------------------

### tls_verification module: TlsClientDetails, TlsVerification, CaCert types

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/commons.md

Public API types for TLS client details and verification. Use these to configure TLS settings, including a secure-defaults variant that provides methods for adding volumes and mounts to PodBuilder/ContainerBuilder, checking TLS usage, and retrieving the CA certificate mount path.

```rust
pub enum TlsClientDetailsError { /* ... */ }
pub struct TlsClientDetails { /* ... */ }
pub struct TlsClientDetailsWithSecureDefaults { /* ... */ } // secure defaults variant

impl TlsClientDetailsWithSecureDefaults {
    pub fn add_volumes_and_mounts(/* to PodBuilder/ContainerBuilder */) -> Result<()>
    pub fn volumes_and_mounts(/* ... */)
    pub const fn uses_tls(&self) -> bool
    pub fn uses_tls_verification(&self) -> bool
    pub fn tls_ca_cert_mount_path(&self) -> Option<String>
}

pub struct Tls { /* enabled flag + details */ }
pub enum TlsVerification { /* ... */ }
pub struct TlsServerVerification { /* ... */ }
pub enum CaCert { /* ... */ }
```

--------------------------------

### Client::new constructor

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Constructor for `Client` that takes the underlying kube-rs client, an optional field manager name for server-side apply patches, the default namespace from the kubeconfig, and cluster information.

```rust
pub fn new(
    client: KubeClient,
    field_manager: Option<String>,
    default_namespace: String,
    kubernetes_cluster_info: KubernetesClusterInfo,
) -> Self
```

--------------------------------

### wait_created: Wait until resources exist

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Waits indefinitely (using a kube watcher) until resources matching `watcher_config` exist.

```rust
pub async fn wait_created<T>(&self, namespace: &T::Namespace, watcher_config: watcher::Config)
// T: Resource + GetApi + Clone + Debug + DeserializeOwned + Send + 'static
```

--------------------------------

### list: List resources with ListParams

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Lists all instances of a resource type; `list_params` may carry `label_selector` / `field_selector`.

```rust
pub async fn list<T>(
    &self,
    namespace: &T::Namespace,
    list_params: &ListParams,
) -> Result<Vec<T>>
```

--------------------------------

### create_if_missing: Create resource only if missing

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Creates the resource only if it does not exist yet (lookup by `ResourceExt::name_any()`). Returns either the existing or the newly created resource.

```rust
pub async fn create_if_missing<T>(&self, resource: &T) -> Result<T>
```

--------------------------------

### Free functions to_java_heap and to_java_heap_value

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/memory-cpu.md

Free functions that convert a Kubernetes quantity into a Java heap size string or a u32 count in a specified binary multiple, applying a factor.

```rust
pub fn to_java_heap(q: &Quantity, factor: f32) -> Result<String>
pub fn to_java_heap_value(q: &Quantity, factor: f32, target_unit: BinaryMultiple) -> Result<u32>
```

--------------------------------

### ContainerBuilder::args

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/builder.md

Sets the arguments for the container command.

```APIDOC
## ContainerBuilder::args

### Description
Sets the arguments for the container command.

### Method
`pub fn args(&mut self, args: Vec<String>) -> &mut Self`

### Parameters
- **args** (`Vec<String>`) - Required - The arguments to pass to the command.

### Returns
- `&mut Self` - Returns a mutable reference to the builder for chaining.

### Example
```rust
builder.args(vec!["-c".to_string(), "echo hello".to_string()]);
```
```

--------------------------------

### as_kube_client

Source: https://github.com/stackabletech/operator-rs/blob/main/_autodocs/api-reference/client.md

Returns an unwrapped kube::Client that can be freely used without cloning first.

```APIDOC
## as_kube_client

### Description
Returns an unwrapped `kube::Client` that can be freely used without cloning first.

### Method
as_kube_client

### Signature
```rust
pub fn as_kube_client(&self) -> KubeClient
```

### Returns
- `KubeClient` - The underlying kube client.
```
Tokens:
Raw