Alpha · Apache 2.0 · Self-hosted

KubeVirt Shepherd

VM requests, approvals and audit for KubeVirt teams

KubeVirt Shepherd (kv-shepherd) gives teams a shared place to request and manage virtual machines, apply access policies and review platform actions.

For platform teams offering KubeVirt VMs to internal users.

Explore the demo Deployment options

Browser demo · No account · Simulated data

KubeVirt Shepherd dashboard with platform and VM information
A view of the Shepherd dashboard. The browser demo uses simulated data.
How it works

Follow a VM request from submission to result

An example of a VM creation request that requires approval. The requester, reviewer and background workers each have a distinct role.

  1. Requester

    Describe the VM you need

    Choose a service, template and instance size, then submit the VM request with its intended environment.

  2. Approver

    Review the request and placement

    Review the requested resources and select an eligible target cluster before approving or rejecting the request.

  3. Background workers

    Execute and report progress

    Approved work is queued for execution. Workers apply the change to the target cluster and report its status or failure.

  4. Your team

    Follow the outcome

    Check the request and VM state, then review audit records for the actor, action and affected resource.

Approval requirements are configurable by operation and environment. A submitted request is not a guarantee that a VM can be scheduled.

Capabilities

The tools around day-to-day VM work

Manage the resources, permissions and operational context needed to offer KubeVirt VMs as a shared service.

Resource catalog

Manage namespaces, templates and instance sizes, and organize VM ownership through Systems and Services.

Scoped access

Combine platform roles with System, Service and VM membership, including environment-scoped role bindings.

Multiple clusters

Register Kubernetes/KubeVirt clusters and manage request placement and resource visibility from one interface.

Lifecycle operations

Request creation, modification, power actions and deletion, with review governed by the configured policies.

Console entrypoints

Open VNC or serial console sessions through platform access controls in your self-hosted installation.

Operational visibility

Inspect audit history and administrator metrics. API tracing uses an OpenTelemetry backend when configured.

The product includes Chinese and English interfaces, plus an authentication provider SDK for LDAP, OIDC and custom integrations.

Scope and maturity

Evaluate it against your environment

KubeVirt remains the virtualization layer. Shepherd manages the requests, permissions and operational records around your VMs.

The public GitHub organization for KubeVirt Shepherd is kv-shepherd.

Application source (main)
Development of the Go backend and product web UI.
Helm chart
Chart source and configuration for installation on Kubernetes.
Deployment guide (main)
Setup requirements and installation options documented on the main branch.

Main-branch code and documentation can be ahead of published releases. Check the release notes and use documentation for your chosen version.

  • Bring your clusters

    A real installation needs reachable Kubernetes/KubeVirt clusters and suitable storage, networking and cluster credentials.

  • Start with an Alpha evaluation

    Review the release notes and test compatibility, upgrades, authentication and permissions before using it with shared workloads.

  • Keep the demo boundary clear

    The public demo runs in your browser with simulated data. It does not provision VMs or connect to real consoles.

Architecture

Where Shepherd fits

The web UI talks to the Go API. PostgreSQL holds application data and queued work; KubeVirt runs the virtual machines.

The default Shepherd application stack uses PostgreSQL without Redis or a separate message broker. Cluster services and optional observability backends are configured separately.

Explore the architecture and API

Web UI

React · Next.js

Go API and workers

Gin · River Queue

PostgreSQL 18

Application data · audit · jobs

Your KubeVirt clusters

VM workloads

Deploy

Choose a way to evaluate Shepherd

Explore the workflow first, or install the real platform on infrastructure you control.

See the interface

Browser demo

Try requests, approvals and role switching with simulated data. No account or cluster setup.

Open the demo
Install in a cluster

Helm on Kubernetes

Use the maintained Helm chart. Review chart values, database persistence, TLS and permissions for managed clusters.

Read the Helm guide
Install on a host

Docker Compose

Run published server and web images with Docker Compose. Use bundled PostgreSQL or configure an external database.

Read the Compose guide

Real VM operations require a configured KubeVirt environment. Source-build and local development instructions are included in the deployment documentation.

Full deployment guide
Task guides

Go deeper into the workflow you need

Read the focused guides for UI, VM operations, access control and multi-cluster management.

VM requests

Request a VM

Choose the service, namespace, template and size, then follow the request through review and delivery.

Read guide Product walkthrough

Navigate the UI

Find ownership, request and review views, resource state and administrator observability.

Read guide VM operations

Change a VM

Review capacity changes, power policy and live errors without confusing approval with completion.

Read guide Built-in approval

Review a request

Inspect request context and placement, record a decision and follow the execution outcome.

Read guide Access design

Scope team access

Combine capabilities, inherited resource access and environment scope, then test separate accounts.

Read guide Cluster placement

Plan cluster placement

Match workload requirements, namespace environment and cluster policy before confirming placement.

Read guide Interactive access

Open a VM console

Check permissions and policy, open an available console and review its access event.

Read guide Installation planning

Plan an installation

Choose deployment and recovery responsibilities, then validate a workflow on a real test cluster.

Read guide
Questions

Before you try it

The essentials about KubeVirt, approval policies, the demo and Alpha evaluation.

Are kv-shepherd and KubeVirt Shepherd the same project?

Yes. KubeVirt Shepherd is the full project name; kv-shepherd is its short name and public GitHub organization. The shepherd repository in that organization contains the application source. This website introduces the project and links to its documentation, releases and simulated demo.

Does Shepherd replace KubeVirt?

KubeVirt runs virtual machines on Kubernetes. KubeVirt Shepherd adds a shared application for VM requests, review, scoped access and audit records. A self-hosted installation connects to Kubernetes clusters with KubeVirt already installed.

Is approval required for every action?

Approval requirements depend on the operation and environment policy. A request that needs review goes to an approver before execution. Role and resource permissions still apply to actions that do not require approval.

Does the online demo create real virtual machines?

The browser demo uses simulated data and operations. You can switch roles, try requests and approvals, and reset your session without an account. Live clusters, VNC, serial consoles and external authentication require a self-hosted installation.

What should I evaluate while the project is in Alpha?

Check the release notes and test your KubeVirt version, storage, networking and authentication setup. Configure cluster permissions, TLS, secrets and database backups for your environment before connecting shared workloads.

How can I deploy or contribute?

Use the maintained Helm chart to install on Kubernetes, or Docker Compose with published images for a host-based installation. The project is Apache 2.0 licensed. Deployment instructions, source code and contribution guidance are public on GitHub.

Read the documentationRead release notes
Open development

Help shape the next release

Shepherd is an Alpha project developed in public under Apache License 2.0. Source, changes and release notes are available on GitHub.

Feedback from an actual environment is useful: describe the workflow, KubeVirt version and steps needed to reproduce a problem.

Report an issue Ask a question Contribute
Source and releases