-
Notifications
You must be signed in to change notification settings - Fork 431
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update README.md #1978
Merged
Merged
Update README.md #1978
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,34 +1,20 @@ | ||||||
<br> | ||||||
<a href="https://www.vcluster.com"><img src="docs/static/media/vcluster_horizontal_black.svg" width="500"></a> | ||||||
|
||||||
### **[Website](https://www.vcluster.com)** • **[Quickstart](https://www.vcluster.com/docs/getting-started/setup)** • **[Documentation](https://www.vcluster.com/docs/what-are-virtual-clusters)** • **[Blog](https://loft.sh/blog)** • **[Twitter](https://twitter.com/loft_sh)** • **[Slack](https://slack.loft.sh/)** | ||||||
### **[Website](https://www.vcluster.com)** • **[Quickstart](https://www.vcluster.com/docs/get-started/)** • **[Documentation](https://www.vcluster.com/docs/what-are-virtual-clusters)** • **[Blog](https://loft.sh/blog)** • **[Twitter](https://twitter.com/loft_sh)** • **[Slack](https://slack.loft.sh/)** | ||||||
|
||||||
![Latest Release](https://img.shields.io/github/v/release/loft-sh/vcluster?style=for-the-badge&label=Latest%20Release&color=%23007ec6) | ||||||
![License: Apache-2.0](https://img.shields.io/github/license/loft-sh/vcluster?style=for-the-badge&color=%23007ec6) | ||||||
|
||||||
[![Join us on Slack!](docs/static/media/slack.svg)](https://slack.loft.sh/) [![Open in DevPod!](https://devpod.sh/assets/open-in-devpod.svg)](https://devpod.sh/open#https://github.com/loft-sh/vcluster) | ||||||
|
||||||
Create fully functional virtual Kubernetes clusters - Each vcluster runs inside a namespace of the underlying k8s cluster. It's cheaper than creating separate full-blown clusters and it offers better multi-tenancy and isolation than regular namespaces. | ||||||
|
||||||
### Why Virtual Kubernetes Clusters? | ||||||
|
||||||
- **Cluster Scoped Resources**: much more powerful than simple namespaces (virtual clusters allow users to use CRDs, namespaces, cluster roles etc.) | ||||||
- **Ease of Use**: usable in any Kubernetes cluster and created in seconds either via a single command or [cluster-api](https://github.com/loft-sh/cluster-api-provider-vcluster) | ||||||
- **Cost Efficient**: much cheaper and efficient than "real" clusters (single pod and shared resources just like for namespaces) | ||||||
- **Lightweight**: built upon the ultra-fast k3s distribution with minimal overhead per virtual cluster (other distributions work as well) | ||||||
- **Strict isolation**: complete separate Kubernetes control plane and access point for each vcluster while still being able to share certain services of the underlying host cluster | ||||||
- **Cluster Wide Permissions**: allow users to install apps which require cluster-wide permissions while being limited to actually just one namespace within the host cluster | ||||||
- **Great for Testing**: allow you to test different Kubernetes versions inside a single host cluster which may have a different version than the virtual clusters | ||||||
Virtual clusters are fully functional Kubernetes clusters nested inside a physical host cluster providing better isolation and flexibility to support multi-tenancy. Multiple teams can operate independently within the same physical infrastructure while minimizing conflicts, maximizing autonomy, and reducing costs. | ||||||
|
||||||
Learn more on [www.vcluster.com](https://vcluster.com). | ||||||
Virtual clusters run inside host cluster namespaces but function as separate Kubernetes clusters, with their own API server, control plane, syncer, and set of resources. While virtual clusters share the physical resources of the host cluster (such as CPU, memory, and storage), they manage their resources independently, allowing for efficient utilization and scaling. | ||||||
|
||||||
<br> | ||||||
|
||||||
![vcluster Intro](docs/static/media/vcluster-comparison.png) | ||||||
|
||||||
![vcluster Compatibility](docs/static/media/cluster-compatibility.png) | ||||||
|
||||||
Learn more in the [documentation](https://vcluster.com/docs/what-are-virtual-clusters). | ||||||
Virtual clusters interact with the host cluster for resource scheduling and networking but maintain a level of abstraction to ensure operations within a virtual cluster don't directly affect the host cluster's global state. | ||||||
|
||||||
<br> | ||||||
|
||||||
|
@@ -38,132 +24,59 @@ Learn more in the [documentation](https://vcluster.com/docs/what-are-virtual-clu | |||||
|
||||||
<br> | ||||||
|
||||||
### Features | ||||||
|
||||||
- **Certified Kubernetes Distribution** - vcluster itself is a [certified Kubernetes distribution](https://www.cncf.io/certification/software-conformance/) and is 100% Kubernetes API conform. Everything that works in a regular Kubernetes cluster works in vcluster | ||||||
- **Lightweight & Low-Overhead** - Based on k3s, bundled in a single pod and with super-low resource consumption. Other distributions such as k0s or vanilla k8s are also supported | ||||||
- **No Performance Degradation** - Pods are scheduled in the underlying host cluster, so they get no performance hit at all while running | ||||||
- **Reduced Overhead On Host Cluster** - Split up large multi-tenant clusters into smaller vclusters to reduce complexity and increase scalability. Since most vcluster api requests and objects will not reach the host cluster at all, vcluster can greatly decrease pressure on the underlying Kubernetes cluster | ||||||
- **Easy Provisioning** - Create via vcluster CLI, helm, kubectl, [cluster api](https://github.com/loft-sh/cluster-api-provider-vcluster), Argo CD or any of your favorite tools (it is basically just a StatefulSet) | ||||||
- **No Admin Privileges Required** - If you can deploy a web app to a Kubernetes namespace, you will be able to deploy a vcluster as well | ||||||
- **Single Namespace Encapsulation** - Every vcluster and all of its workloads are inside a single namespace of the underlying host cluster | ||||||
- **Easy Cleanup** - Delete the host namespace and the vcluster plus all of its workloads will be gone immediately | ||||||
- **Flexible & Versatile** - vcluster supports different storage backends (such as sqlite, mysql, postgresql & etcd), plugins, customizable sync behaviour, vcluster within vcluster setups and has many more additional configuration options to fit a multitude of different use cases | ||||||
|
||||||
<br> | ||||||
|
||||||
## Quick Start (~ 1 minute) | ||||||
|
||||||
To learn more about vcluster, [**open the full getting started guide**](https://www.vcluster.com/docs/getting-started/setup). | ||||||
|
||||||
### 1. Download vcluster CLI | ||||||
## Benefits | ||||||
Virtual clusters provide immense benefits for large-scale Kubernetes deployments and multi-tenancy. | ||||||
|
||||||
VCluster has a hard dependency on `helm` (v3.10.0+), if it is not installed on your machine, you can [install it](https://helm.sh/docs/intro/install/) beforehand or let vCluster install it for you. | ||||||
<img src="docs/static/media//diagrams/vcluster-comparison.png" width="500"> | ||||||
|
||||||
Use one of the following commands to download the vcluster CLI binary from GitHub: | ||||||
### Robust security and isolation | ||||||
- **Granular Permissions:** vCluster users operate with minimized permissions in the host cluster, significantly reducing the risk of privileged access misuse. Within their vCluster, users have admin-level control, enabling them to manage CRDs, RBAC, and other security policies independently. | ||||||
- **Isolated Control Plane:** Each vCluster comes with its own dedicated API server and control plane, creating a strong isolation boundary. | ||||||
- **Customizable Security Policies:** Tenants can implement additional vCluster-specific governance, including OPA policies, network policies, resource quotas, limit ranges, and admission control, in addition to the existing policies and security measures in the underlying physical host cluster. | ||||||
- **Enhanced Data Protection:** With options for separate backing stores, including embedded SQLite, etcd, or external databases, virtual clusters allow for isolated data management, reducing the risk of data leakage between tenants. | ||||||
|
||||||
<details> | ||||||
<summary>Mac (Intel/AMD)</summary> | ||||||
### Access for tenants | ||||||
- **Full Admin Access per Tenant:** Tenants can freely deploy CRDs, create namespaces, taint, and label nodes, and manage cluster-scoped resources typically restricted in standard Kubernetes namespaces. | ||||||
- **Isolated yet Integrated Networking:** While ensuring automatic isolation (for example, pods in different virtual clusters cannot communicate by default), vCluster allows for configurable network policies and service sharing, supporting both separation and sharing as needed. | ||||||
- **Node Management:** Assign static nodes to specific virtual clusters or share node pools among multiple virtual clusters, providing flexibility in resource allocation. | ||||||
|
||||||
```bash | ||||||
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin | ||||||
``` | ||||||
### Cost-effectiveness and reduced overhead | ||||||
- **Lightweight Infrastructure:** Virtual clusters are significantly more lightweight than physical clusters, able to spin up in seconds, which contrasts sharply with the lengthy provisioning times often seen in environments like EKS (~45 minutes). | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Take it or leave it, just an alternative.
Suggested change
|
||||||
- **Resource Efficiency:** By sharing the underlying host cluster's resources, virtual clusters minimize the need for additional physical infrastructure, reducing costs and environmental impact. | ||||||
- **Simplified Management:** The vCluster control plane, running inside a single pod, along with optional integrated CoreDNS, minimizes the operational overhead, making virtual clusters especially suitable for large-scale deployments and multi-tenancy scenarios. | ||||||
|
||||||
</details> | ||||||
### Enhanced flexibility and compatibility | ||||||
- **Diverse Kubernetes Environments:** vCluster supports different Kubernetes versions and distributions (including K8s, K3s, and K0s), allowing version skews. This makes it possible to tailor each virtual cluster to specific requirements without impacting others. | ||||||
- **Adaptable Backing Stores:** Choose from a range of data stores, from lightweight (SQLite) to enterprise-grade options (embedded etcd, external data stores like Global RDS), catering to various scalability and durability needs. | ||||||
- **Runs Anywhere:** Virtual clusters can run on EKS, GKE, AKS, OpenShift, RKE, K3s, cloud, edge, and on-prem. As long as it's a K8s cluster, you can run a virtual cluster on top of it. | ||||||
|
||||||
<details> | ||||||
<summary>Mac (Silicon/ARM)</summary> | ||||||
### Improved scalability | ||||||
- **Reduced API Server Load:** Virtual clusters, each with their own dedicated API server, significantly reduce the operational load on the host cluster's Kubernetes API server by isolating and handling requests internally. | ||||||
- **Conflict-Free CRD Management:** Independent management of CRDs within each virtual cluster eliminates the potential for CRD conflicts and version discrepancies, ensuring smoother operations and easier scaling as the user base expands. | ||||||
|
||||||
```bash | ||||||
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin | ||||||
``` | ||||||
## Common use cases | ||||||
### Pre-production | ||||||
- **Empower developers with self-service Kubernetes:** Simplify Kubernetes access for developers through self-service virtual clusters, reducing human error and enhancing developer autonomy without compromising security and compliance requirements. | ||||||
- **Accelerate CI/CD with ephemeral Kubernetes clusters:** Instantly create clean, new virtual Kubernetes clusters for each pull request, enabling fast, isolated testing and PR previews without wait times and the struggles of a shared test environment. | ||||||
|
||||||
</details> | ||||||
### Production | ||||||
- **Elevate your ISV offering with a dedicated cluster per customer:** Host each customer in a virtual cluster with strict tenant isolation and seamless scalability, while consolidating essential tools into a unified platform stack serving multiple tenants. | ||||||
- **Build a managed Kubernetes service with best-in-class COGS and high margins:** Enable direct customer access to dedicated virtual Kubernetes clusters, streamlining node and resource allocation for industry-leading efficiency and unparalleled scalability. | ||||||
|
||||||
<details> | ||||||
<summary>Linux (AMD)</summary> | ||||||
## Quick Start | ||||||
|
||||||
```bash | ||||||
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin | ||||||
``` | ||||||
|
||||||
</details> | ||||||
|
||||||
<details> | ||||||
<summary>Linux (ARM)</summary> | ||||||
|
||||||
```bash | ||||||
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin | ||||||
``` | ||||||
|
||||||
</details> | ||||||
|
||||||
<details> | ||||||
<summary>Windows (Powershell)</summary> | ||||||
|
||||||
```bash | ||||||
md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12'; | ||||||
Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe; | ||||||
$env:Path += ";" + $Env:APPDATA + "\vcluster"; | ||||||
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User); | ||||||
``` | ||||||
|
||||||
> If you get the error that Windows cannot find vcluster after installing it, you will need to restart your computer, so that the changes to the `PATH` variable will be applied. | ||||||
|
||||||
</details> | ||||||
|
||||||
<br> | ||||||
|
||||||
Alternatively, you can download the binary for your platform from the [GitHub Releases](https://github.com/loft-sh/vcluster/releases) page and add this binary to your PATH. | ||||||
|
||||||
<br> | ||||||
|
||||||
### 2. Create a vcluster | ||||||
|
||||||
```vash | ||||||
vcluster create my-vcluster | ||||||
|
||||||
# OR: Use --expose to create a vcluster with an externally accessible LoadBalancer | ||||||
vcluster create my-vcluster --expose | ||||||
|
||||||
# OR: Use --isolate to create an isolated environment for the vcluster workloads | ||||||
vcluster create my-vcluster --isolate | ||||||
``` | ||||||
|
||||||
Take a look at the [vcluster docs](https://www.vcluster.com/docs/getting-started/deployment) to see how to deploy a vcluster using Helm or Kubectl instead. | ||||||
|
||||||
### 3. Use the vcluster | ||||||
|
||||||
Run in a terminal: | ||||||
|
||||||
```bash | ||||||
# Run any kubectl, helm, etc. command in your vcluster | ||||||
kubectl get namespace | ||||||
kubectl get pods -n kube-system | ||||||
kubectl create namespace demo-nginx | ||||||
kubectl create deployment nginx-deployment -n demo-nginx --image=nginx | ||||||
kubectl get pods -n demo-nginx | ||||||
``` | ||||||
|
||||||
### 4. Cleanup | ||||||
|
||||||
```bash | ||||||
vcluster delete my-vcluster | ||||||
``` | ||||||
|
||||||
Alternatively, you could also delete the host-namespace using kubectl. | ||||||
|
||||||
## Architecture | ||||||
|
||||||
[![vcluster Intro](docs/static/media/diagrams/vcluster-architecture.svg)](https://www.vcluster.com) | ||||||
Refer to our [quick start guide](https://www.vcluster.com/docs/vcluster/) to deploy your first vCluster! | ||||||
|
||||||
## Contributing | ||||||
|
||||||
Thank you for your interest in contributing! Please refer to | ||||||
[CONTRIBUTING.md](https://github.com/loft-sh/vcluster/blob/main/CONTRIBUTING.md) for guidance. | ||||||
|
||||||
<br> | ||||||
|
||||||
--- | ||||||
## License | ||||||
|
||||||
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at | ||||||
|
||||||
http://www.apache.org/licenses/LICENSE-2.0 | ||||||
|
||||||
This project is open-source and licensed under Apache 2.0, so you can use it in any private or commercial projects. | ||||||
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Less a suggestion of I think you should do this. I'm just personally more likely to halt a quick scroll for a short bulleted list.