Docs: Update getting started section #1551
Conversation
aimeeu
changed the title
docs/pages/fragments/install/cli.mdx
Outdated
| brew install loft-sh/tap/vcluster | ||
| brew install vcluster |
There was a problem hiding this comment.
We want to use the loft tap instead of the homebrew tap, so this needs to be reverted.
There was a problem hiding this comment.
Thanks for the clarification. I wondered why there were 2 tabs for Homebrew, so I picked the more common "brew install" and planned to follow up. I will update.
brew install vcluster does install the latest version. Can you tell me why you recommend brew install loft-sh/tap/vcluster instead?
There was a problem hiding this comment.
The loft-sh/tap/vcluster formula is part of our tap and is updated faster than the "official" homebrew tap, as it's part of our release pipelines in goreleaser.
Furthermore, our formula is only installing the statically compiled binaries from the GitHub release section instead of building the CLI from the source as the vcluster formula does.
This removes the build dependency of Go on a system and cuts down on install time, all while the installed binaries are cosign-signed, so that's a plus for anyone focused on security.
| ### Air-Gapped Clusters | ||
|
|
||
| If you want to deploy vCluster in an air-gapped environment, set the following option in the `values.yaml` used to deploy vCluster: | ||
|
|
||
| :::caution Air-gapped Clusters | ||
| If you want to deploy vClusters in an air-gapped environment, you can set the following option in the `values.yaml` used to deploy vCluster: | ||
| ``` | ||
| defaultImageRegistry: my-private-registry:5000/vcluster/ | ||
| ``` | ||
| This will tell vCluster to prepend the above image registry to all images used by vCluster, such as syncer, k3s, coredns etc. So for example `rancher/k3s:v1.22.2-k3s1` will become `my-private-registry:5000/vcluster/rancher/k3s:v1.22.2-k3s1` | ||
|
|
||
| This tells vCluster to prepend the image registry to all images used by vCluster, such as syncer, K3s, and CoreDNS. For example, `rancher/K3a:v1.22.2-k3s1` becomes `my-private-registry:5000/vcluster/rancher/k3s:v1.22.2-k3s1`. | ||
|
|
||
| You can find a list of all needed images by vCluster in the file `vcluster-images.txt` at the [releases page](https://github.com/loft-sh/vcluster/releases), as well as two scripts (download-images.sh & push-images.sh) to pull and push those to your private registry. | ||
|
|
||
| You can locate the Helm chart and values file for Kubernetes distro in the vCluster [repo](https://github.com/loft-sh/vcluster/tree/main/charts). Be sure to choose the tag that matches your vCluster version. |
There was a problem hiding this comment.
If we turn the air-gapped warning into a section, having it sit below the "Create Virtual Clusters" section might make sense, as the happy path is a non-air-gapped cluster.
docs/pages/getting-started/setup.mdx
Outdated
| @@ -6,17 +6,20 @@ sidebar_label: 1. Download CLI | |||
| import InstallCLIFragment from '../fragments/install/cli.mdx' | |||
|
|
|||
| :::note About This Guide | |||
There was a problem hiding this comment.
It's not necessarily part of this PR, but it might make sense to change this note into a heading so that the links render in blue, as in a note, it's hard to determine whether it's a link or not.
| :::note About This Guide | |
| ## About This Guide |
and then removing the ::: in line 15.
Screenshot showcasing link rendering in the note:
There was a problem hiding this comment.
I moved the content out of the note and into Learning objectives and Before you begin sections.
| Virtual clusters provide immense benefits for large-scale Kubernetes deployments and multi-tenancy: | ||
| - **Full Admin Access**: | ||
| - Deploy operators with CRDs, create namespaces and other cluster scoped resources that's usually not possible in namespaces. | ||
| - Taint and label nodes without any influence on the host cluster. |
There was a problem hiding this comment.
That depends on the configuration; enabling the scheduler in the vCluster will propagate those taints and labels if I recall correctly.
There was a problem hiding this comment.
@ThomasK33 I copied this section directly from connect.mdx, since I felt this content belonged on an intro page. Lukas Gentele created the original content, and I don't yet have the product knowledge to update "Benefits of Virtual Clusters". What do you think of my opening a new issue to update the "Benefits of Virtual Clusters" content in a separate PR?
| - Reuse and share services across multiple virtual clusters with ease. | ||
| - **Cost Savings:** | ||
| - You can create lightweight vClusters that share the underlying host cluster instead of creating separate "real" clusters. | ||
| - vClusters are just deployments, so they can be easily auto-scaled, purged, snapshotted and moved. |
There was a problem hiding this comment.
What do you mean by auto-scaled and snapshotted here?
| - vClusters are just deployments, so they can be easily auto-scaled, purged, snapshotted and moved. | ||
| - **Low Overhead:** | ||
| - vClusters are super lightweight and only reside in a single namespace. | ||
| - vClusters run with K3s, a super low-footprint K8s distribution, but they can also run with "real" K8s. |
There was a problem hiding this comment.
vClusters run by default with K3s, we also have other distros supported, such as K0s, vanilla K8s, and EKS.
| - **Low Overhead:** | ||
| - vClusters are super lightweight and only reside in a single namespace. | ||
| - vClusters run with K3s, a super low-footprint K8s distribution, but they can also run with "real" K8s. | ||
| - The control plane of a vCluster runs inside a single pod (+1 CoreDNS pod for vCluster-internal DNS capabilities). |
There was a problem hiding this comment.
The "+1 CoreDNS pod" is required in OSS.
In vCluster.Pro one can enable the integrated CoreDNS so that the additional pod isn't required.
One might want to remove that "+1 pod" mention here.
| - vClusters run with K3s, a super low-footprint K8s distribution, but they can also run with "real" K8s. | ||
| - The control plane of a vCluster runs inside a single pod (+1 CoreDNS pod for vCluster-internal DNS capabilities). | ||
| - **<u>No</u> Network Degradation:** | ||
| - Since the pods and services inside a vCluster are actually being synchronized down to the host cluster\*, they are effectively using the underlying cluster's pod and service networking and are therefore not a bit slower than any other pods in the underlying host cluster. |
There was a problem hiding this comment.
not a bit slower
I'd probably rewrite this as "as fast as other pods in the underlying host cluster.", as one can quickly glance over the not here and get an entirely wrong impression.
| - **<u>No</u> Network Degradation:** | ||
| - Since the pods and services inside a vCluster are actually being synchronized down to the host cluster\*, they are effectively using the underlying cluster's pod and service networking and are therefore not a bit slower than any other pods in the underlying host cluster. | ||
| - **API Server Compatibility:** | ||
| - vClusters run with the K3s API server which is certified K8s distro which ensures 100% Kubernetes API server compliance. |
There was a problem hiding this comment.
Same as above: vClusters run by default with K3s, we also have other distros supported, such as K0s, vanilla K8s, and EKS.
| - Since the pods and services inside a vCluster are actually being synchronized down to the host cluster\*, they are effectively using the underlying cluster's pod and service networking and are therefore not a bit slower than any other pods in the underlying host cluster. | ||
| - **API Server Compatibility:** | ||
| - vClusters run with the K3s API server which is certified K8s distro which ensures 100% Kubernetes API server compliance. | ||
| - vCluster have their own API server, controller-manager and a separate, isolated data store (sqlite for easiest option but this is configurable, you can also deploy a full-blown etcd if needed). |
There was a problem hiding this comment.
It could be more precise here. Does a vCluster run with the K3s API server or with its own?
Maybe something like "vCluster manages its API server" would be more explicit.
✅ Deploy Preview for vcluster-docs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
clarify a few points incorporate content from blog post address feedback
the relative links compile locally but not in Netlify
changed section name add links to internal and external docs fix grammar nits
Co-authored-by: Thomas Kosiewski <thoma471@googlemail.com>
Thanks for catching that (very embarrassing) typo! |
I am interviewing for the Technical Writer role at Loft Labs. This PR is the result of a question that David Bitton asked during the interview.
Deploy previews:
What issue type does this pull request address? (keep at least one, remove the others)
/kind documentation
What does this pull request do? Which issues does it resolve? (use
resolves #<issue_number>if possible)N/A
Please provide a short message that should be published in the vcluster release notes
N/A
What else do we need to know?
connect.mdxtowhat-are-virtual-clusters.mdx. I didn't write this content. I moved the content because it's a better fit for an explanatory page.fragments/deploy-clusterinto theget-started/deploymentfile and delete the fragment since no other file uses it.The docs don't have a defined style guide, but the style looks closest to the Kubernetes Documentation Style Guide, which is a subset of the Google developer documentation style guide. I've used both when contributing to other projects. For page title capitalization, I followed the Chicago Manual of Style (https://titlecaseconverter.com/).