Skip to content

Commit

Permalink
docs: improve vcluster page
Browse files Browse the repository at this point in the history
  • Loading branch information
Lukas Gentele committed Jul 22, 2020
1 parent fb56969 commit 5d5878d
Showing 1 changed file with 78 additions and 2 deletions.
80 changes: 78 additions & 2 deletions docs/pages/vclusters/basics.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Virtual clusters:
- allow to test different Kubernetes versions inside a single host cluster which may have a different version than the virtual clusters
- more powerful than simple namespace (virtual clusters allow users to use CRDs etc.)
- allow users to install apps which require cluster-wide permissions while being limited to actually just one namespace within the host cluster
- provide strict isolation while still allowing you to share certain services of the underlying host cluster (e.g. [using the host's ingress-controller and cert-manager](#networking))


## Workflows
Expand All @@ -37,6 +38,13 @@ Run this command to create a virtual cluster:
loft create vcluster [VCLUSTER_NAME] # optional flag: --cluster=[CLUSTER_NAME]
```

Creating a virtual cluster using the CLI will automatically configure a kube-context on your local machine for this vCluster.

With the kube-context of the vCluster, you can run any kubectl command within the virtual cluster:
```bash
kubectl get namespaces
```

</TabItem>
<TabItem value="kubectl">

Expand Down Expand Up @@ -91,9 +99,10 @@ kubectl apply -f vcluster.yaml
</Tabs>

### Use vCluster
Run this command to add a kube-context for the virtual cluster to your local kube-config file:
Run this command to add a kube-context for the virtual cluster to your local kube-config file or to switch to an existing kube-context of a virtual cluster:
```bash
kubectl use vcluster [VCLUSTER_NAME] # optional flags: --cluster=[CLUSTER_NAME] --space [VCLUSTER_NAMESPACE]
kubectl use vcluster # shows a list of all available vclusters
kubectl use vcluster [VCLUSTER_NAME] # optional flags: --cluster=[CLUSTER_NAME] --space [VCLUSTER_NAMESPACE]
```

Then, run any kubectl command within the virtual cluster:
Expand Down Expand Up @@ -128,6 +137,73 @@ kubectl delete virtualcluster [VCLUSTER_NAME] --namespace [VCLUSTER_NAMESPACE]
</TabItem>
</Tabs>

<br/>

---


## Configuration
You can configure virtual clusters using the VirtualCluster CRD or using the loft UI. Virtual clusters are deployed using a Helm chart (see the [virtual-cluster project on GitHub](https://github.com/loft-sh/virtual-cluster)).

### Networking
By default, Services and Ingresses are syned from the virtual cluster to the host cluster in order to enable correct network functionality for the virtual cluster.

That means that you can create ingresses in your virtual cluster to make services available via domains using the ingress-controller that is running in the host cluster. This helps to share resources across different virtual clusters and is easier for users of virtual clusters because otherwise, they would need to install an ingress-controller and configure DNS for each virtual cluster.

Because the syncer keeps annotations for ingresses, you may also set the cert-manager ingress annotations to use the cert-manager in your host cluster to automatically provision SSL certificates from Let's Encrypt.

If you do **not** want ingresses to be syned and instead use a separate ingress controller within a virtual cluster, set the following syncer configuration:
```yaml
syncer:
extraArgs: ["--disable-sync-resources=ingresses"]
```

### Syncer
By default, certain Kubernetes objects such as Services or Ingresses are synced from the virtual cluster to the host cluster. The syncer removes unnecessary fields (such as labels) and also transforms certain fields of these objects before sending them to the host cluster.

You can configure the syncer using the following options:
```yaml
syncer:
extraArgs:
- --disable-sync-resources=ingresses # any k8s resources not to sync to the host cluster
env: []
volumeMounts:
- mountPath: /data
name: data
resources: {}
```

### Control Plane (k3s)
You can configure the control plane (API server, controller-manager, etcd) using the following options:
```yaml
virtualCluster:
image: rancher/k3s:v1.18.4-k3s1
command:
- /bin/k3s
baseArgs:
- server
- --write-kubeconfig=/k3s-config/kube-config.yaml
- --data-dir=/data
- --disable=traefik,servicelb,metrics-server,local-storage
- --disable-network-policy
- --disable-agent
- --disable-scheduler
- --disable-cloud-controller
- --flannel-backend=none
- --kube-controller-manager-arg=controllers=*,-nodeipam,-nodelifecycle,-persistentvolume-binder,-attachdetach,-persistentvolume-expander,-cloud-node-lifecycle
extraArgs:
- --service-cidr=10.96.0.0/12
volumeMounts:
- mountPath: /data
name: data
env: []
resources: {}
```
Note that you can use any k3s version and all arguments/flags that the k3s binary of this specific version provides. See [k3s](https://k3s.io/) for more information.

<br/>

---


## How does it work?
Expand Down

0 comments on commit 5d5878d

Please sign in to comment.