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
• Getting Started
  • Installation
  • Basic Usage
  • Customizing the Environment
    • Using with_crds
  • Explicit Cleanup
  • Usage in testing
• Building the Bindings
• License

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 user CRDs from in‑memory definitions.

Getting Started

Installation

Add envtest to your Cargo.toml:

[dependencies]
envtest = "0.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;

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

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

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

    // 4. Create a `kube` client
    let client = server.client()?;

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

Customizing the Environment

You can tweak binary download behavior through binary_assets_settings:

use envtest::Environment;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut env = Environment::default();
    env.binary_assets_settings.download_binary_assets_version = Some("1.32.0".to_string());
    env.binary_assets_settings.binary_assets_directory = Some(".cache/envtest".to_string());
    let server = env.create()?;
    Ok(())
}

Using with_crds

use envtest::Environment;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let crd = MyCustomResource::crd();

    let env = Environment::default()
        .with_crds(crd)?;

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

Explicit Cleanup

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

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

Usage in testing

envtest is most useful in combination with the kube feature (enabled by default), which provides a strongly typed API client for interacting with the Kubernetes API.

use envtest::Environment;
use kube::{Api, api::{DeleteParams, PostParams}};
use k8s_openapi::api::core::v1::Namespace;

#[tokio::test]
async fn work_with_namespace_with_kube_client() -> Result<(), Box<dyn std::error::Error>> {
    let server = Environment::default().create()?;
    let namespaces: Api<Namespace> = Api::all(server.client()?);
    namespaces
        .create(
            &PostParams::default(),
            &Namespace {
                metadata: kube::core::ObjectMeta {
                    name: Some("envtest-e2e".to_string()),
                    ..Default::default()
                },
                ..Default::default()
            },
        )
        .await?;

    namespaces
        .delete("envtest-e2e", &DeleteParams::default())
        .await?;

    Ok(())
}

For test suites, prefer one Environment per test to avoid shared state between cases.

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.