envtest 0.0.1

A lightweight, type‑safe wrapper around the Kubernetes `envtest` Go package that lets you spin up a temporary control plane from Rust.
docs.rs failed to build envtest-0.0.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: envtest-0.1.2

envtest

A lightweight, type‑safe wrapper around the Kubernetes envtest Go package that lets you spin up a temporary control plane from Rust.

envtest aims to make integration testing with real Kubernetes components straightforward. This project is based on the envtest Go package, but provides a Rust interface for the library usage.

Table of Contents

Features

  • Create an isolated test environment with a fully‑working control plane.
  • Destroy the environment automatically when the Server instance is dropped.
  • Retrieve the kubeconfig as a strongly‑typed kube::config::Kubeconfig.
  • Pre‑install provide user CRDs, either from files or in‑memory definitions.

Getting Started

Installation

Add envtest to your Cargo.toml:

[dependencies]
envtest = "0.1"
kube = { version = "1" }

Note: rust2go requires a working Go toolchain and clang for the bindgen step.
Make sure that Go (GO111MODULE=on) is available on your PATH.

Basic Usage

use envtest::Environment;
use kube::{Client, config::Kubeconfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the default environment (latest envtest binaries)
    let env = Environment::default();

    // 2. Spin up a temporary control plane
    let server = env.create()?;

    // 3. Retrieve a strongly‑typed kubeconfig
    let kubeconfig: Kubeconfig = server.kubeconfig()?;

    // 4. Create a `kube` client
    let client = Client::try_from(kubeconfig)?;

    // 5. `server` is dropped at the end of scope, cleaning up the control plane
    Ok(())
}

Customizing the Environment

Environment exposes two nested structs:

Field Purpose
crd_install_options.paths Paths to directories or files with CRDs.
crd_install_options.crds In‑memory CRDs to install.
crd_install_options.error_if_path_missing Fail if a a CRD path is missing.
binary_assets_settings.download_binary_assets false → use binaries from $KUBEBUILDER_ASSETS.
binary_assets_settings.binary_assets_directory Cache directory for downloaded binaries.
binary_assets_settings.download_binary_assets_version Specific envtest version to download.
binary_assets_settings.download_binary_assets_index_url URL pointing to the envtest release index.

Using with_crds

use envtest::{Environment, BinaryAssetsSettings};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let env = Environment::default()
        .with_crds(vec![CustomResourceDefinition::default()])?;

    let server = env.create()?;
    Ok(())
}

Explicit Cleanup

The Server implements Drop, but you can destroy it manually:

let server = env.create()?;
server.destroy()?;

Building the Bindings

envtest generates Go bindings at compile time via rust2go. The build process relies on:

  • rust2go (which uses bindgen under the hood)
  • A working Go toolchain (GO111MODULE=on)
  • clang (for bindgen)

Refer to the bindgen requirements for more details.

License

MIT license – see the LICENSE file for details.