diff --git a/docs/devel/writing-a-getting-started-guide.md b/docs/devel/writing-a-getting-started-guide.md index 348faf9be7e..d7463a4c6bf 100644 --- a/docs/devel/writing-a-getting-started-guide.md +++ b/docs/devel/writing-a-getting-started-guide.md @@ -20,10 +20,11 @@ certainly want the docs that go with that version. + # Writing a Getting Started Guide This page gives some advice for anyone planning to write or update a Getting Started Guide for Kubernetes. It also gives some guidelines which reviewers should follow when reviewing a pull request for a -guide. +guide. A Getting Started Guide is instructions on how to create a Kubernetes cluster on top of a particular type(s) of infrastructure. Infrastructure includes: the IaaS provider for VMs; @@ -36,11 +37,12 @@ the combination of all these things needed to run on a particular type of infras which is similar to the one you have planned, consider improving that one. -Distros fall into two categories: +Distros fall into two categories: - **versioned distros** are tested to work with a particular binary release of Kubernetes. These come in a wide variety, reflecting a wide range of ideas and preferences in how to run a cluster. - **development distros** are tested work with the latest Kubernetes source code. But, there are - relatively few of these and the bar is much higher for creating one. + relatively few of these and the bar is much higher for creating one. They must support + fully automated cluster creation, deletion, and upgrade. There are different guidelines for each. @@ -51,17 +53,14 @@ These guidelines say *what* to do. See the Rationale section for *why*. search for uses of flags by guides. - We may ask that you host binary assets or large amounts of code in our `contrib` directory or on your own repo. + - Add or update a row in [The Matrix](../../docs/getting-started-guides/README.md). + - State the binary version of kubernetes that you tested clearly in your Guide doc. - Setup a cluster and run the [conformance test](development.md#conformance-testing) against it, and report the results in your PR. - - Add or update a row in [The Matrix](../../docs/getting-started-guides/README.md). - - State the binary version of kubernetes that you tested clearly in your Guide doc and in The Matrix. - - Even if you are just updating the binary version used, please still do a conformance test. - - If it worked before and now fails, you can ask on IRC, - check the release notes since your last tested version, or look at git -logs for files in other distros - that are updated to the new version. - Versioned distros should typically not modify or add code in `cluster/`. That is just scripts for developer distros. - - If a versioned distro has not been updated for many binary releases, it may be dropped from the Matrix. + - When a new major or minor release of Kubernetes comes out, we may also release a new + conformance test, and require a new conformance test run to earn a conformance checkmark. If you have a cluster partially working, but doing all the above steps seems like too much work, we still want to hear from you. We suggest you write a blog post or a Gist, and we will link to it on our wiki page. @@ -93,11 +92,6 @@ These guidelines say *what* to do. See the Rationale section for *why*. - We want users to have a uniform experience with Kubernetes whenever they follow instructions anywhere in our Github repository. So, we ask that versioned distros pass a **conformance test** to make sure really work. - - We ask versioned distros to **clearly state a version**. People pulling from Github may - expect any instructions there to work at Head, so stuff that has not been tested at Head needs - to be called out. We are still changing things really fast, and, while the REST API is versioned, - it is not practical at this point to version or limit changes that affect distros. We still change - flags at the Kubernetes/Infrastructure interface. - We want to **limit the number of development distros** for several reasons. Developers should only have to change a limited number of places to add a new feature. Also, since we will gate commits on passing CI for all distros, and since end-to-end tests are typically somewhat diff --git a/docs/getting-started-guides/README.md b/docs/getting-started-guides/README.md index 9a88b7803e7..4ce621a6a8f 100644 --- a/docs/getting-started-guides/README.md +++ b/docs/getting-started-guides/README.md @@ -28,38 +28,38 @@ For the easiest "kick the tires" experience, please try the [local docker](docke If you are considering contributing a new guide, please read the [guidelines](../../docs/devel/writing-a-getting-started-guide.md). -IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level | Notes --------------------- | ------------ | ------ | ---------- | ------------------------------------------------------------------------------ | ----------- | ---------------------------- | ----- -GKE | | | GCE | [docs](https://cloud.google.com/container-engine) | [✓][1](#references) | Commercial | Uses latest via https://get.k8s.io -Vagrant | Saltstack | Fedora | OVS | [docs](vagrant.md) | | Project | Uses latest via https://get.k8s.io/ -GCE | Saltstack | Debian | GCE | [docs](gce.md) | | Project | Uses latest via https://get.k8s.io -Azure | CoreOS | CoreOS | Weave | [docs](coreos/azure/README.md) | | Community ([@errordeveloper](https://github.com/errordeveloper), [@squillace](https://github.com/squillace), [@chanezon](https://github.com/chanezon), [@crossorigin](https://github.com/crossorigin)) | Uses K8s version 0.17.0 -Docker Single Node | custom | N/A | local | [docs](docker.md) | | Project (@brendandburns) | Tested @ 0.14.1 | -Docker Multi Node | Flannel | N/A | local | [docs](docker-multinode.md) | | Project (@brendandburns) | Tested @ 0.14.1 | -Bare-metal | Ansible | Fedora | flannel | [docs](fedora/fedora_ansible_config.md) | | Project | Uses K8s v0.13.2 -Bare-metal | custom | Fedora | _none_ | [docs](fedora/fedora_manual_config.md) | | Project | Uses K8s v0.13.2 -Bare-metal | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))| Tested with 0.15.0 -libvirt | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))| Tested with 0.15.0 -KVM | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))| Tested with 0.15.0 -Mesos/GCE | | | | [docs](mesos.md) | | [Community](https://github.com/mesosphere/kubernetes-mesos) ([@jdef](https://github.com/jdef)) | Uses K8s v0.11.2 -AWS | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community | Uses K8s version 0.19.3 -GCE | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community [@pires](https://github.com/pires) | Uses K8s version 0.19.3 -Vagrant | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community ( [@pires](https://github.com/pires), [@AntonioMeireles](https://github.com/AntonioMeireles) ) | Uses K8s version 0.19.3 -Bare-metal (Offline) | CoreOS | CoreOS | flannel | [docs](coreos/bare_metal_offline.md) | | Community([@jeffbean](https://github.com/jeffbean)) | Uses K8s version 0.15.0 -CloudStack | Ansible | CoreOS | flannel | [docs](cloudstack.md) | | Community (@runseb) | Uses K8s version 0.9.1 -Vmware | | Debian | OVS | [docs](vsphere.md) | | Community (@pietern) | Uses K8s version 0.9.1 -Bare-metal | custom | CentOS | _none_ | [docs](centos/centos_manual_config.md) | | Community(@coolsvap) | Uses K8s v0.9.1 -AWS | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) | [Tested](http://reports.vapour.ws/charm-tests-by-charm/kubernetes) K8s v0.8.1 -OpenStack/HPCloud | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) | [Tested](http://reports.vapour.ws/charm-tests-by-charm/kubernetes) K8s v0.8.1 -Joyent | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) | [Tested](http://reports.vapour.ws/charm-tests-by-charm/kubernetes) K8s v0.8.1 -AWS | Saltstack | Ubuntu | OVS | [docs](aws.md) | | Community (@justinsb) | Uses K8s version 0.5.0 -Vmware | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community (@kelseyhightower) | Uses K8s version 0.15.0 -Azure | Saltstack | Ubuntu | OpenVPN | [docs](azure.md) | | Community | -Bare-metal | custom | Ubuntu | flannel | [docs](ubuntu.md) | | Community (@resouer @WIZARD-CXY) | use k8s version 0.19.3 -Local | | | _none_ | [docs](locally.md) | | Community (@preillyme) | -libvirt/KVM | CoreOS | CoreOS | libvirt/KVM | [docs](libvirt-coreos.md) | | Community (@lhuard1A) | -oVirt | | | | [docs](ovirt.md) | | Community (@simon3z) | -Rackspace | CoreOS | CoreOS | flannel | [docs](rackspace.md) | | Community (@doublerr) | use k8s version 0.18.0 +IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level +-------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ---------------------------- +GKE | | | GCE | [docs](https://cloud.google.com/container-engine) | | Commercial +Vagrant | Saltstack | Fedora | OVS | [docs](vagrant.md) | | Project +GCE | Saltstack | Debian | GCE | [docs](gce.md) | [✓][1] | Project +Azure | CoreOS | CoreOS | Weave | [docs](coreos/azure/README.md) | | Community ([@errordeveloper](https://github.com/errordeveloper), [@squillace](https://github.com/squillace), [@chanezon](https://github.com/chanezon), [@crossorigin](https://github.com/crossorigin)) +Docker Single Node | custom | N/A | local | [docs](docker.md) | | Project (@brendandburns) +Docker Multi Node | Flannel | N/A | local | [docs](docker-multinode.md) | | Project (@brendandburns) +Bare-metal | Ansible | Fedora | flannel | [docs](fedora/fedora_ansible_config.md) | | Project +Bare-metal | custom | Fedora | _none_ | [docs](fedora/fedora_manual_config.md) | | Project +Bare-metal | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal)) +libvirt | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal)) +KVM | custom | Fedora | flannel | [docs](fedora/flannel_multi_node_cluster.md) | | Community ([@aveshagarwal](https://github.com/aveshagarwal)) +Mesos/GCE | | | | [docs](mesos.md) | | [Community](https://github.com/mesosphere/kubernetes-mesos) ([@jdef](https://github.com/jdef)) +AWS | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community +GCE | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community [@pires](https://github.com/pires) +Vagrant | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community ( [@pires](https://github.com/pires), [@AntonioMeireles](https://github.com/AntonioMeireles) ) +Bare-metal (Offline) | CoreOS | CoreOS | flannel | [docs](coreos/bare_metal_offline.md) | | Community([@jeffbean](https://github.com/jeffbean)) +CloudStack | Ansible | CoreOS | flannel | [docs](cloudstack.md) | | Community (@runseb) +Vmware | | Debian | OVS | [docs](vsphere.md) | | Community (@pietern) +Bare-metal | custom | CentOS | _none_ | [docs](centos/centos_manual_config.md) | | Community(@coolsvap) +AWS | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) +OpenStack/HPCloud | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) +Joyent | Juju | Ubuntu | flannel | [docs](juju.md) | | [Community](https://github.com/whitmo/bundle-kubernetes) ( [@whit](https://github.com/whitmo), [@matt](https://github.com/mbruzek), [@chuck](https://github.com/chuckbutler) ) +AWS | Saltstack | Ubuntu | OVS | [docs](aws.md) | | Community (@justinsb) +Vmware | CoreOS | CoreOS | flannel | [docs](coreos.md) | | Community (@kelseyhightower) +Azure | Saltstack | Ubuntu | OpenVPN | [docs](azure.md) | | Community +Bare-metal | custom | Ubuntu | flannel | [docs](ubuntu.md) | | Community (@resouer @WIZARD-CXY) +Local | | | _none_ | [docs](locally.md) | | Community (@preillyme) +libvirt/KVM | CoreOS | CoreOS | libvirt/KVM | [docs](libvirt-coreos.md) | | Community (@lhuard1A) +oVirt | | | | [docs](ovirt.md) | | Community (@simon3z) +Rackspace | CoreOS | CoreOS | flannel | [docs](rackspace.md) | | Community (@doublerr) Don't see anything above that meets your needs? See our [Getting Started from Scratch](scratch.md) guide. @@ -73,7 +73,7 @@ Definition of columns: - **Networking** is what implements the [networking model](../../docs/admin/networking.md). Those with networking type _none_ may not support more than one node, or may support multiple VM nodes only in the same physical node. - **Conformance** indicates whether a cluster created with this configuration has passed the project's conformance - tests for supporting the API and base features of Kubernetes v1.0.0. + tests for supporting the API and base features of Kubernetes v1.0.0. - Support Levels - **Project**: Kubernetes Committers regularly use this configuration, so it usually works with the latest release of Kubernetes. @@ -82,8 +82,9 @@ Definition of columns: - **Inactive**: No active maintainer. Not recommended for first-time K8s users, and may be deleted soon. - **Notes** is relevant information such as version k8s used. -#### References: -- [1] [GCE conformance test result](https://gist.github.com/erictune/4cabc010906afbcc5061) + + +[1]: https://gist.github.com/erictune/4cabc010906afbcc5061