Skip to main content

kaniop_radius/reconcile/
image.rs

1//! Conservative image selection for the independently deployed Kanidm RADIUS.
2//!
3//! A Kanidm server image digest is NOT a RADIUS image digest. The only safe
4//! automatic derivation is the same pinned release tag from a Docker Hub
5//! kanidm/server image. For nonstandard registries, moving tags and digest-only
6//! references, the user must pin an explicit RADIUS image.
7
8use thiserror::Error;
9
10/// Numeric user of the `radiusd` account in the verified image. Kubelet cannot
11/// verify `runAsNonRoot` for a named image `USER`, so the pod sets it explicitly.
12pub const RADIUS_UID: i64 = 497;
13/// Numeric group of the `radiusd` account in the verified image; also the pod
14/// `fsGroup` so projected Secret files are group-readable.
15pub const RADIUS_GID: i64 = 496;
16
17/// The only upstream release whose published image is known to run as
18/// 497:496 (see [`RADIUS_UID`] and [`RADIUS_GID`]) and to bootstrap in the
19/// e2e tests, which use the image tagged with the `kanidm_client` version.
20/// Bump it together with that dependency.
21const VERIFIED_RADIUS_RELEASE: &str = "1.11.2";
22
23#[derive(Debug, Error, PartialEq, Eq)]
24pub enum RadiusImageError {
25    #[error("RADIUS image must not be empty")]
26    EmptyImage,
27    #[error("explicit RADIUS image is required for an unrecognized or unpinned Kanidm image")]
28    ExplicitImageRequired,
29}
30
31/// Return the image reference used by the dedicated RADIUS Deployment.
32///
33/// An override is a complete user-provided image reference and is never
34/// rewritten. An explicit digest therefore refers to the RADIUS artifact,
35/// rather than inheriting the (incompatible) server image digest.
36pub fn resolve_radius_image(
37    kanidm_image: &str,
38    override_image: Option<&str>,
39) -> Result<String, RadiusImageError> {
40    if let Some(image) = override_image {
41        if image.trim().is_empty() {
42            return Err(RadiusImageError::EmptyImage);
43        }
44        return Ok(image.to_string());
45    }
46
47    // Infer only the verified Docker Hub release: other upstream releases can
48    // change the non-root UID/GID or the bootstrap contract.
49    let mut parts = kanidm_image.rsplitn(2, ':');
50    let tag = parts
51        .next()
52        .ok_or(RadiusImageError::ExplicitImageRequired)?;
53    let name = parts
54        .next()
55        .ok_or(RadiusImageError::ExplicitImageRequired)?;
56    if !matches!(
57        name,
58        "kanidm/server" | "docker.io/kanidm/server" | "index.docker.io/kanidm/server"
59    ) || tag != VERIFIED_RADIUS_RELEASE
60    {
61        return Err(RadiusImageError::ExplicitImageRequired);
62    }
63
64    Ok(format!("kanidm/radius:{tag}"))
65}
66
67#[cfg(test)]
68mod tests {
69    use super::*;
70
71    #[test]
72    fn maps_official_dockerhub_release_tag_only() {
73        for image in [
74            "kanidm/server:1.11.2",
75            "docker.io/kanidm/server:1.11.2",
76            "index.docker.io/kanidm/server:1.11.2",
77        ] {
78            assert_eq!(
79                resolve_radius_image(image, None),
80                Ok("kanidm/radius:1.11.2".into())
81            );
82        }
83    }
84
85    #[test]
86    fn does_not_copy_digest_or_guess_nonofficial_registry() {
87        for image in [
88            "kanidm/server@sha256:deadbeef",
89            "docker.io/kanidm/server:latest",
90            "ghcr.io/kanidm/server:1.11.2",
91            "example.com/my/server:1.11.2",
92            "kanidm/server:devel",
93            "kanidm/server:1.11.3",
94            "kanidm/server:1.12.0",
95            "kanidm/server:1.11",
96            "kanidm/server",
97        ] {
98            assert_eq!(
99                resolve_radius_image(image, None),
100                Err(RadiusImageError::ExplicitImageRequired)
101            );
102        }
103    }
104
105    #[test]
106    fn overrides_are_passed_through_unmodified() {
107        assert_eq!(
108            resolve_radius_image(
109                "kanidm/server@sha256:deadbeef",
110                Some("mirror.example/radius@sha256:abcdef")
111            ),
112            Ok("mirror.example/radius@sha256:abcdef".into())
113        );
114    }
115
116    #[test]
117    fn explicitly_blank_override_fails_closed() {
118        assert_eq!(
119            resolve_radius_image("kanidm/server:1.11.2", Some("  ")),
120            Err(RadiusImageError::EmptyImage)
121        );
122    }
123}