Module deployment

Available on crate feature deployment only.

Expand description

Deployment contract validation and generation for Kubernetes/Helm/Docker.

Apps provide ~20% customisation via DeploymentContract; this module generates ~80% boilerplate (Dockerfile, Helm chart, Compose fragment) and validates existing artifacts against the contract.

§Architecture

App Config::default()  →  DeploymentContract  →  generate_chart("chart/")
                                               →  generate_dockerfile()
                                               →  generate_compose_fragment()
                                               →  validate_helm_values("chart/")
                                               →  validate_dockerfile("Dockerfile")

The config cascade (figment) is the SSoT for app defaults. The contract captures the deployment-facing subset. Generation creates artifacts from scratch; validation asserts that existing artifacts match.

§Example

use hyperi_rustlib::deployment::{
    DeploymentContract, HealthContract, ImageProfile, KedaContract, NativeDepsContract,
    generate_dockerfile, generate_chart, generate_compose_fragment,
};

let contract = DeploymentContract {
    app_name: "dfe-loader".into(),
    binary_name: "dfe-loader".into(),
    description: "High-performance data loader".into(),
    metrics_port: 9090,
    health: HealthContract::default(),
    env_prefix: "DFE_LOADER".into(),
    metric_prefix: "loader".into(),
    config_mount_path: "/etc/dfe/loader.yaml".into(),
    image_registry: "ghcr.io/hyperi-io".into(),
    extra_ports: vec![],
    entrypoint_args: vec!["--config".into(), "/etc/dfe/loader.yaml".into()],
    secrets: vec![],
    default_config: None,
    depends_on: vec!["kafka".into(), "clickhouse".into()],
    keda: Some(KedaContract::default()),
    base_image: "ubuntu:24.04".into(),
    native_deps: NativeDepsContract::for_rustlib_features(
        &["transport-kafka", "spool", "tiered-sink"],
        "ubuntu:24.04",
    ),
    image_profile: ImageProfile::Production,
    oci_labels: Default::default(),
    schema_version: 1,
};

// Generate production Dockerfile (without identity annotations -- Phase 1
// backwards-compat. New callers should pass `Some(&identity)`; see
// `ContractIdentity::new` and `ContractIdentity::detect`.)
let dockerfile = generate_dockerfile(&contract, None);

// Generate development Dockerfile (same binary, adds debug tools)
let dev_dockerfile = generate_dockerfile(&contract.with_dev_profile(), None);

// Generate Helm chart directory
// generate_chart(&contract, "chart/").unwrap();

// Generate Docker Compose service fragment
let compose = generate_compose_fragment(&contract);

Re-exports§

pub use app_project::AppProjectContract;
pub use app_project::AppProjectDestination;
pub use app_project::generate_argocd_app_project;
pub use contract_identity::ContractIdentity;
pub use contract_identity::IdentityError;
pub use contract_identity::KEY_PREFIX;
pub use contract_identity::VERSION;
pub use generate::ArgocdConfig;
pub use generate::generate_argocd_application;
pub use generate::generate_chart;
pub use generate::generate_compose_fragment;
pub use generate::generate_container_manifest;
pub use generate::generate_dockerfile;
pub use generate::generate_runtime_stage;
pub use waves::WAVE_APPS;
pub use waves::WAVE_CRDS;
pub use waves::WAVE_OPERATORS;
pub use waves::WAVE_POST;
pub use waves::WAVE_TOPICS;

Modules§

app_project: ArgoCD AppProject generator.
contract_identity: Contract Identity Annotation Scheme v1.
generate: Generate deployment artifacts (Dockerfile, Helm chart, Compose fragment, container manifest, ArgoCD Application) from a DeploymentContract.
waves: ArgoCD sync-wave constants.

Structs§

AptRepoContract: A custom APT repository (e.g., Confluent for librdkafka).
ContractMismatch: A single contract mismatch between app defaults and deployment artifact.
DeploymentContract: Deployment-facing contract points derived from the app config cascade.
HealthContract: Health probe endpoint paths.
KedaConfig: KEDA autoscaling configuration for the app config cascade.
KedaContract: KEDA contract points validated against Helm values.yaml.
NativeDepsContract: Runtime native dependencies for a container image.
OciLabels: OCI image labels for the container.
PortContract: Additional container port beyond the metrics port.
SecretEnvContract: A single environment variable sourced from a K8s Secret.
SecretGroupContract: A group of secrets from the same K8s Secret (e.g., “kafka”, “clickhouse”).

Enums§

DeploymentError: Errors from deployment validation and generation.
ImageProfile: Container image profile – controls what goes into the generated Dockerfile.

Constants§

DEFAULT_BASE_IMAGE: Default base image for the runtime stage.
DEFAULT_IMAGE_REGISTRY: Default publish-target registry for HyperI org.

Functions§

argocd_repo_url_from_cascade: Read the git repo URL for ArgoCD generation from the config cascade.
base_image_from_cascade: Read the runtime base image from the config cascade.
image_registry_from_cascade: Read the publish-target image registry from the config cascade.
validate_dockerfile: Validate a Dockerfile against the deployment contract.
validate_helm_values: Validate a Helm chart directory against the deployment contract.