docs: add getting started guide for bootstrapping a managemenet cluster with clusterctl #308
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: andrewsykim The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
k8s-ci-robot
added
the
size/L
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
from
b83327e
to
7b342f7
Compare
There was a problem hiding this comment.
Hi @andrewsykim,
This. is. AMAZING. Thank you!!!
The only nits I have to pick are:
- Please be consistent with spacing between text and blocks of pre-formatted text. A single, empty line is usually what I've seen in k/k markdown.
- Please use
shellorbashwhen pre-formatting shell output with triple ticks. I noticed that missing in a few places.
Other than that, looks perfect!
There was a problem hiding this comment.
Hi @andrewsykim,
Sorry for the double-review, but something caught my eye and then I started looking more closely. One thing I didn't note in any comments (since it was prevalent everywhere) is that your IDE appears to line break in the middle of sentences. The k/k docs I've seen seem to use soft word wrapping from the IDE and prefer no line breaks except for when starting a new paragraph. Unless you object, I think we should stick with that. Thoughts?
docs/getting_started.md
Outdated
| Assuming you have a Go installed on your machine, run the following to install Kind: | ||
|
|
||
| ```bash | ||
| $ GO111MODULE="on" go get sigs.k8s.io/kind@v0.3.0 |
There was a problem hiding this comment.
Hi @andrewsykim,
Please change this to:
$ GO111MODULE="on" go get -mod readonly sigs.k8s.io/kind@v0.3.0This ensures that installing Kind won't modify a project's Go module files.
docs/getting_started.md
Outdated
| $ brew install gettext | ||
| ``` | ||
|
|
||
| NOTE: brew may install envsubst in a path that is not in your PATH environment variable. Ensure |
There was a problem hiding this comment.
Hi @andrewsykim,
There's a trailing Ensure that begins a second sentence I think you meant to finish.
docs/getting_started.md
Outdated
|
|
||
| #### clusterctl | ||
|
|
||
| A version of `clusterctl` that is built from **this** respository must be installed. If you have a workin Go environment, |
docs/getting_started.md
Outdated
| The `clusterctl` make target installs `clusterctls` in `bin/clusterctl`. Temporarily add this folder to your PATH to use it | ||
| for the rest of this guide: | ||
| ``` | ||
| $ export PATH=$PATH:$(pwd)/bin |
There was a problem hiding this comment.
Hi @andrewsykim,
Perhaps consider quoting it export PATH="${PATH}:$(pwd)/bin"
| ### Generating YAML for the Bootstrap Cluster | ||
|
|
||
| The bootstrapping process in `clusterctl` requires a few configuration files: | ||
| * **cluster.yaml**: a yaml file defining the cluster resource for your management cluster |
There was a problem hiding this comment.
Hi @andrewsykim,
Please consider a table here and pre-formatting the file names.
docs/getting_started.md
Outdated
|
|
||
| ### Managing Workload Clusters using the Management Cluster | ||
|
|
||
| With your management cluster bootstrapped, this is when you can reap the benefits of Cluster API. From this point forward, |
There was a problem hiding this comment.
s/this is when you can/it's time to/
docs/getting_started.md
Outdated
| kubelet: 1.13.6 | ||
| ``` | ||
|
|
||
| `kubectl apply -f` the above files on your management cluster and it should start provisioning the new cluster. |
There was a problem hiding this comment.
Hi @andrewsykim,
Instead of starting the sentence with the command, how about?
Run kubectl apply -f to apply the above files...
docs/getting_started.md
Outdated
| `kubectl apply -f` the above files on your management cluster and it should start provisioning the new cluster. | ||
| Clusters that are provisioned by the management cluster that run your application workloads are called [Workload Clusters](https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/book/GLOSSARY.md#workload-cluster). | ||
|
|
||
| The `kubeconfig` file to access workload clusters should be accessible as Secrets on the management cluster. As of today, the |
There was a problem hiding this comment.
Secret to reference Kubernetes Secret resources. But updating to as a Secret resource
There was a problem hiding this comment.
Ah. How about "as a Kubernetes Secret"? Maybe that isn't clear to those who don't use K8s as often as we do.
docs/getting_started.md
Outdated
| Clusters that are provisioned by the management cluster that run your application workloads are called [Workload Clusters](https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/book/GLOSSARY.md#workload-cluster). | ||
|
|
||
| The `kubeconfig` file to access workload clusters should be accessible as Secrets on the management cluster. As of today, the | ||
| secret is named `<cluster-resource-uuid>-kubeconfig` in the same namespace as the cluster resource it belongs to. For example, |
There was a problem hiding this comment.
s/in the same namespace as the cluster resource it belongs to/in the same namespace as the cluster to which the secret belongs/
| $ kubectl -n default get secrets 3644a115-88ae-11e9-952c-005056b08e9e-kubeconfig -o yaml | ||
| ``` | ||
|
|
||
| Now that you have the `kubeconfig` for your Workload Cluster, you can start deploying your applications there. |
There was a problem hiding this comment.
Hi @andrewsykim,
It may be valuable to actually add a Terms and Phrases section at the top of this document to define things like "Workload Cluster" there. I personally would find that valuable. Thoughts?
There was a problem hiding this comment.
I've noticed the terminology trips a lot of people up so this would be helpful. A graphic showing the relations may also be helpful.
There was a problem hiding this comment.
The doc links out in many places to the glossary page in the cluster-api docs but might be helpful to be more explicit in the beginning that the glossary page exists.
If we feel the glossary page there (https://cluster-api.sigs.k8s.io/glossary.html) is not enough we can add the definitions here again.
docs/getting_started.md
Outdated
| export VSPHERE_NETWORK="vm-network-1" # the VM network to deploy the management cluster on | ||
| export VSPHERE_RESOURCE_POOL="*/Resources/Compute-ResourcePool/CAPV" # the vSphere resource pool for your VMs | ||
| export VSPHERE_FOLDER="Workloads" # the VM folder for your VMs, this can be "" if not applicable to your environment | ||
| export VSPHERE_TEMPLATE="ubuntu-16.04-server-cloudimg-amd64" # the VM template to use for your management cluster |
There was a problem hiding this comment.
Hi @andrewsykim,
The template should be a template a user deployed from one of the OVAs in the GCS bucket gs://capv-images/release. For example, in our VMC test environment the template name is ubuntu-1804-kube-v1.13.6. A user can learn more about the machine images in the image documentation or list the available machine images with gsutil:
$ gsutil ls gs://capv-images/release/*
gs://capv-images/release/v1.13.6/:
gs://capv-images/release/v1.13.6/centos-7-kube-v1.13.6.ova
gs://capv-images/release/v1.13.6/centos-7-kube-v1.13.6.ova.sha256
gs://capv-images/release/v1.13.6/ubuntu-1804-kube-v1.13.6.ova
gs://capv-images/release/v1.13.6/ubuntu-1804-kube-v1.13.6.ova.sha256
gs://capv-images/release/v1.13.7/:
gs://capv-images/release/v1.13.7/centos-7-kube-v1.13.7.ova
gs://capv-images/release/v1.13.7/centos-7-kube-v1.13.7.ova.sha256
gs://capv-images/release/v1.13.7/ubuntu-1804-kube-v1.13.7.ova
gs://capv-images/release/v1.13.7/ubuntu-1804-kube-v1.13.7.ova.sha256
gs://capv-images/release/v1.14.0/:
gs://capv-images/release/v1.14.0/centos-7-kube-v1.14.0.ova
gs://capv-images/release/v1.14.0/centos-7-kube-v1.14.0.ova.sha256
gs://capv-images/release/v1.14.0/ubuntu-1804-kube-v1.14.0.ova
gs://capv-images/release/v1.14.0/ubuntu-1804-kube-v1.14.0.ova.sha256
gs://capv-images/release/v1.14.1/:
gs://capv-images/release/v1.14.1/centos-7-kube-v1.14.1.ova
gs://capv-images/release/v1.14.1/centos-7-kube-v1.14.1.ova.sha256
gs://capv-images/release/v1.14.1/ubuntu-1804-kube-v1.14.1.ova
gs://capv-images/release/v1.14.1/ubuntu-1804-kube-v1.14.1.ova.sha256
gs://capv-images/release/v1.14.2/:
gs://capv-images/release/v1.14.2/centos-7-kube-v1.14.2.ova
gs://capv-images/release/v1.14.2/centos-7-kube-v1.14.2.ova.sha256
gs://capv-images/release/v1.14.2/ubuntu-1804-kube-v1.14.2.ova
gs://capv-images/release/v1.14.2/ubuntu-1804-kube-v1.14.2.ova.sha256
gs://capv-images/release/v1.14.3/:
gs://capv-images/release/v1.14.3/centos-7-kube-v1.14.3.ova
gs://capv-images/release/v1.14.3/centos-7-kube-v1.14.3.ova.sha256
gs://capv-images/release/v1.14.3/ubuntu-1804-kube-v1.14.3.ova
gs://capv-images/release/v1.14.3/ubuntu-1804-kube-v1.14.3.ova.sha256There was a problem hiding this comment.
Going to put to a separate doc for "How to install the CAPV OVA in vSphere" that will be a pre-req for this, thoughts? Different from the one you linked since it will just be instructions for OVA download from google storage.
There was a problem hiding this comment.
Hi @andrewsykim,
I think a doc that is top-to-bottom from how to download Kind, get CAPV machine images, install as templates, run CAPV, etc. is needed. A single walk through.
Also, please say "CAPV machine image" instead of of OVA. I am going to open a PR to completely remove the installer directory so there's no longer any confusion about we mean when OVA is used. Still, since they're technically "machine images" that happen to be delivered as OVAs, let's be very clear.
There was a problem hiding this comment.
Sounds good to me, I'll add a section on how to upload the CAPV machine images to vSphere.
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
from
7b342f7
to
d2e81fc
Compare
This is mainly to make reviewing the PR easier. |
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
from
d2e81fc
to
eb65f24
Compare
It doesn't. You can see the line breaks in GH, and they don't break in a way that makes sense. GitHub and IDEs are able to soft-break, so let's maintain the standard in the community of no hard breaks except when beginning new paragraphs. Thanks. |
|
Good to know, thanks |
|
Going to continue writing docs assuming we are going to use #330 since it removes the need to install kustomize and envsubst locally. |
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
2 times, most recently
from
7a8e5bc
to
ff9f6c2
Compare
|
Comments addressed, PTAL |
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
9 times, most recently
from
88f0a28
to
6bb8d01
Compare
|
/lgtm Not sure why e2e is failing. No logs as far as I can tell. I wonder if the Prow cluster is having issues. |
k8s-ci-robot
added
the
lgtm
|
/retest |
2 similar comments
|
/retest |
|
/retest |
Signed-off-by: Andrew Sy Kim <kiman@vmware.com>
andrewsykim
force-pushed
the
bootstrap-cluster-docs
branch
from
6bb8d01
to
928a634
Compare
k8s-ci-robot
removed
the
lgtm
|
/lgtm |
k8s-ci-robot
added
the
lgtm
* [clusterawsadm] enable sharedconfig on the session * Updates for getting started guide * Update default manager image * Fix issue with machine create and LB assignment
Signed-off-by: Andrew Sy Kim kiman@vmware.com
/assign @akutz