Periscope (Headlamp clone)

Every backend has its own type system, and they vary wildly in size. A CSV gets by with one — everything is text. Vantage's SQLite type system has seven variants, Postgres fourteen, SurrealDB twenty-four. Vantage is strict about type boundaries and safety, so this first step defines that type system: the variants, the conversions to and from native Rust types, and clean round-tripping through CBOR / Serde. You declare it with a single macro:

vantage_type_system! {
    type_trait: KubeType,
    value_type: serde_json::Value,
    type_variants: [Null, Bool, Integer, Number, Quantity, Text, Time],
}

Kubernetes brings its own oddities — a Quantity and a Time — and the Vantage type system takes them in stride. The agent reads the guide and builds the right variants, so "16331752Ki" becomes a real number you can sort and chart, and "250m" a quarter of a CPU — not text.

Read furtherarrow_forward

Here the earlier pieces come together. The agent implements one trait, TableSource, and on it declares the backend's types — its value type, its condition (comparison) type, its select/source type, and several more. The same trait spans everything from a flat CSV to SurrealDB, one of the most feature-rich database servers; each backend simply names the types it actually has.

impl TableSource for PostgresDB {
    type Value = AnyPostgresType;
    type Condition = PostgresCondition;
    type Source = SelectSource<PostgresSelect>;
    // + Column, Id, AnyType …
}

impl TableSource for KubernetesCluster {
    type Value = CborValue;
    type Condition = KubeCondition;
    type Source = String;
    // no query language — just the kind
}

Postgres declares a full Select-based source; Kubernetes, with no query language, declares its source as a plain String — the resource kind. That single line is exactly why the three query steps above were skipped.

Implementing TableSource unlocks a Table: a typed Table<DB, Entity> with ActiveRecord-style records, CRUD, aggregates, ordering and pagination — none of which you write. Table is Rust-only and highly typed; in a Rust application it's what you reach for most of the time.

Reading it back is exactly what you'd expect — load the pods table and iterate its rows:

// load the pods table, then read every row
let pods = pods::pods_table(cluster);

for (_, pod) in pods.list_values().await? {
    let name  = pod.get("name");
    let ready = pod.get("ready");   // "1/1", "2/2", …
}

Read furtherarrow_forward

Now Vantage's relationship engine comes on. You declare how records relate — with_one for a belongs-to, with_many for a has-many — and the UI picks them up on its own, turning every reference into a link you can follow, with no per-screen wiring.

Table::new("replicasets", cluster)
    .with_many("pods", "owner_uid", Pod::table);  // a ReplicaSet → the pods it owns

How much a relationship can do depends on the backend. Vantage supports three levels — and since pushing work to the server is always cheaper, it prefers the higher ones. Pick a level:

.with_many("orders", "client_id", Order::table)
.with_expression("order_count", |t| {
    let orders = t.get_subquery_as::<Order>("orders").unwrap();
    orders.get_count_query()
})

Read furtherarrow_forward

By now the data source has the whole stack — types, expressions, conditions, queries, a typed Table and relations. The guide's checkpoint is to build a small CLI, the fastest way to exercise all of it against a real cluster. Because the backend type is erased, the same generic CLI code runs over any Vantage model: it fetches, filters with conditions and traverses relations, and vantage-cli-util renders each result as a table.

Fetch a resource and filter it by namespace — vantage-cli-util renders the result straight into the terminal:

Then traverse a relation — a deployment down to the pods it owns:

Exactly the three pods that deployment owns — fetched, filtered and drilled, with no Kubernetes-specific code in the CLI at all. The checkpoint passes.

Read furtherarrow_forward

So far everything has been type-rich Rust resources — ideal for Rust code, and invisible to everything else. To use that Table — the DataSource you just built — outside of Rust, or in Vantage UI, those types have to be sealed behind one uniform boundary. That boundary is Vista: a typed Table goes in, and out comes a schema-bearing handle the UI, scripts and agents read over a plain serialization boundary — no Rust struct needed on the other side.

As the table enters Vista it also declares the backend's capabilities. Queries? No. Conditions? Yes. Pagination? Yes. Consuming code reads these flags and adapts, so the same UI drives a SQL Vista, a Mongo Vista or this Kubernetes one without caring how it was built. Here is what the Kubernetes driver advertises:

Some of the right-hand column are real limits — the API has no query language, so server-side queries will never appear. But others the Kubernetes API does support; the v1 driver just doesn't use them yet — a live watch, server-side field selectors. They can be added later to make the driver more powerful, and swapped in without touching a line of code that uses Vantage — Vantage UI included.

Read furtherarrow_forward

Vantage UI ships as one precompiled binary — you can't drop new Rust into it. So tables are declared in YAML or Rhai instead, both read at runtime. Here's the same deployments table, three ways:

# table/deployments.yaml
datasource: cluster
title: Deployments
table: apis/apps/v1/deployments
columns:
  - { name: name, flags: [title] }
  - { name: namespace, references: namespaces }
  - { name: replicas, type: int }
  - { name: ready, type: int }
references:
  pods: { table: pods, kind: has_many, foreign_key: ownerDeployment }

# the pods relation, narrowed by a Rhai script
references:
  pods:
    table: pods
    kind: has_many
    rhai: |
      table("pods")
          .add_condition_eq("ownerDeployment", row.name)
          .add_order("name", "asc")

Table::new("deployments", cluster)
    .with_title_column_of::<String>("name")
    .with_column_of::<String>("namespace")
    .with_column_of::<i64>("replicas")
    .with_column_of::<i64>("ready")
    .with_many("pods", "ownerDeployment", pods_table);

Two of those need no recompile — which is the real unlock: you can mix and match custom manifest types, pointing a table at a CRD to add it to Vantage UI without touching the binary.

The Kubernetes driver itself shipped in Vantage 0.20 and stays a built-in capability — so a cluster works out of the box, and YAML or Rhai is for the custom types you layer on top.

Read furtherarrow_forward