koprs_admission/lib.rs
1//! # koprs-admission
2//!
3//! Validating admission webhook server for Kubernetes operators, designed as
4//! a companion to [`koprs`](https://docs.rs/koprs).
5//!
6//! Kubernetes admission webhooks intercept API requests before they are
7//! persisted and let operators enforce policy: reject resources that violate
8//! naming conventions, block dangerous container configurations, or require
9//! labels that your operator depends on. Writing the HTTP server, TLS wiring,
10//! request parsing, and response serialisation for every webhook is
11//! repetitive and error-prone. `koprs-admission` handles all of that.
12//!
13//! ## Core model
14//!
15//! Implement [`Validator`] for your resource type —
16//! inspect the [`AdmissionRequest`] and return a [`ValidationResponse`].
17//! Pass the validator to [`WebhookBuilder`] and call
18//! `.run()`. The framework handles the rest.
19//!
20//! ## Quick start
21//!
22//! ```no_run
23//! use std::fs;
24//! use koprs_admission::{AdmissionRequest, ValidationResponse};
25//! use koprs_admission::webhook::{Validator, WebhookBuilder};
26//! use serde::Deserialize;
27//!
28//! #[derive(Deserialize)]
29//! struct MyResource { replicas: u32 }
30//!
31//! struct ReplicaLimit;
32//!
33//! impl Validator<MyResource> for ReplicaLimit {
34//! type Error = std::convert::Infallible;
35//!
36//! async fn validate(
37//! &self,
38//! request: &AdmissionRequest<MyResource>,
39//! ) -> Result<ValidationResponse, Self::Error> {
40//! if request.object.as_ref().map_or(true, |r| r.replicas <= 10) {
41//! Ok(ValidationResponse::allow())
42//! } else {
43//! Ok(ValidationResponse::deny("replicas must not exceed 10"))
44//! }
45//! }
46//! }
47//!
48//! # async fn example() -> Result<(), koprs_admission::AdmissionError> {
49//! let cert_pem = fs::read("/tls/tls.crt")?;
50//! let key_pem = fs::read("/tls/tls.key")?;
51//!
52//! WebhookBuilder::new()
53//! .port(8443)
54//! .tls_from_pem(&cert_pem, &key_pem)?
55//! .health_port(8080)
56//! .graceful_shutdown()
57//! .validate("/validate/myresource", ReplicaLimit)
58//! .run()
59//! .await?;
60//! # Ok(())
61//! # }
62//! ```
63
64pub mod error;
65pub mod review;
66pub mod webhook;
67
68pub use error::AdmissionError;
69pub use review::{AdmissionRequest, Operation, ValidationResponse};
70pub use webhook::{Validator, WebhookBuilder};
71
72#[cfg(test)]
73mod tests;