diff --git a/_data/guides.yml b/_data/guides.yml index fdade5b1ec..f66d0706ee 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -8,6 +8,7 @@ toc: - docs/whatisk8s.md - docs/getting-started-guides/kubeadm.md - docs/getting-started-guides/kops.md + - docs/getting-started-guides/kargo.md - docs/hellonode.md - docs/getting-started-guides/kubectl.md - docs/getting-started-guides/binary_release.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 13315bf5ed..231a583524 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -1,5 +1,5 @@ bigheader: "Tasks" -abstract: "Step-by-step instructions for performing operations with Kuberentes." +abstract: "Step-by-step instructions for performing operations with Kubernetes." toc: - docs/tasks/index.md diff --git a/docs/getting-started-guides/kargo.md b/docs/getting-started-guides/kargo.md new file mode 100644 index 0000000000..93f1373c75 --- /dev/null +++ b/docs/getting-started-guides/kargo.md @@ -0,0 +1,104 @@ +--- +title: Installing Kubernetes On-premise/Cloud Providers with Kargo +--- + + + +## Overview + +This quickstart helps to install a Kubernetes cluster hosted +on GCE, Azure, OpenStack, AWS or Baremetal with +[`Kargo`](https://github.com/kubernetes-incubator/kargo) tool. + +Kargo is a composition of [Ansible](http://docs.ansible.com/) playbooks, +[inventory](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ansible.md) +generation CLI tools and domain knowledge for generic OS/Kubernetes +clusters configuration management tasks. It provides: + +* [High available cluster](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ha-mode.md) +* [Composable](https://github.com/kubernetes-incubator/kargo/blob/master/docs/vars.md) + (Choice of the network plugin, for instance) +* Support most popular Linux + [distributions](https://github.com/kubernetes-incubator/kargo#supported-linux-distributions) +* Continuous integration tests + +To choose a tool which fits your use case the best, you may want to read this +[comparison](https://github.com/kubernetes-incubator/kargo/blob/master/docs/comparisons.md) +to [kubeadm](../kubeadm) and [kops](../kops). + +## Creating a cluster + +### (1/4) Ensure the underlay [requirements](https://github.com/kubernetes-incubator/kargo#requirements) are met + +#### Checklist + +* You must have cloud instances or baremetal nodes running for your future Kubernetes cluster. + A way to achieve that is to use the + [kargo-cli tool](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md). +* Or provision baremetal hosts with a tool-of-your-choice or launch cloud instances, + then create an inventory file for Ansible with this [tool](https://github.com/kubernetes-incubator/kargo/blob/master/contrib/inventory_generator/inventory_generator.py). + +### (2/4) Compose the deployment + +#### Checklist + +* Customize your deployment by usual Ansible meanings, which is + [generating inventory](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md#building-your-own-inventory) + and overriding default data [variables](https://github.com/kubernetes-incubator/kargo/blob/master/docs/vars.md). + Or just stick with default values (Kargo will choose Flannel networking plugin for you + then). This includes steps like deciding on the: + * DNS [configuration options](https://github.com/kubernetes-incubator/kargo/blob/master/docs/dns-stack.md) + * [Networking plugin](https://github.com/kubernetes-incubator/kargo#network-plugins) to use + * [Versions](https://github.com/kubernetes-incubator/kargo#versions-of-supported-components) + of components. + * Additional node groups like [bastion hosts](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ansible.md#bastion-host) or + [Calico BGP route reflectors](https://github.com/kubernetes-incubator/kargo/blob/master/docs/calico.md#optional--bgp-peering-with-border-routers). +* Plan custom deployment steps, if any, or use the default composition layer in the + [cluster definition file](https://github.com/kubernetes-incubator/kargo/blob/master/cluster.yml). + Taking the best from Ansible world, Kargo allows users to execute arbitrary steps via the + ``ansible-playbook`` with given inventory, playbooks, data overrides and tags, limits, batches + of nodes to deploy and so on. +* For large deployments (100+ nodes), you may want to + [tweak things](https://github.com/kubernetes-incubator/kargo/blob/master/docs/large-deployments.md) + for best results. + +### (3/4) Run the deployment + +#### Checklist + +* Apply deployment with + [kargo-cli tool](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md) + or ``ansible-playbook`` + [manual commands](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md#starting-custom-deployment). + +### (4/4) (Optional) verify inter-pods connectivity and DNS resolve with [Netchecker](https://github.com/kubernetes-incubator/kargo/blob/master/docs/netcheck.md) + +#### Checklist + +* Enusre the netchecker-agent's pods can resolve DNS requests and ping each over within the default namespace. + Those pods mimic similar behavior of the rest of the workloads and serve as cluster health indicators. + +## Explore contributed add-ons + +See the [list of contributed playbooks](https://github.com/kubernetes-incubator/kargo/tree/master/contrib) +to explore other deployment options. + +## What's next + +Kargo has quite a few [marks on the radar](https://github.com/kubernetes-incubator/kargo/blob/master/docs/roadmap.md). + +## Cleanup + +To delete your scratch cluster, you can apply the +[reset role](https://github.com/kubernetes-incubator/kargo/blob/master/roles/reset/tasks/main.yml) +with the manual ``ansible-playbook`` command. + +Note, that it is highly unrecommended to delete production clusters with the reset playbook! + +## Feedback + +* Slack Channel: [#kargo](https://kubernetes.slack.com/messages/kargo/) +* [GitHub Issues](https://github.com/kubernetes-incubator/kargo/issues) + diff --git a/docs/index.md b/docs/index.md index 24814e55ae..1201403936 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,6 +20,7 @@ title: Kubernetes Documentation
  • Minikube: Install a single-node Kubernetes cluster on your local machine for development and testing.
  • Installing Kubernetes on AWS with kops: Bring up a complete Kubernetes cluster on Amazon Web Services, using a tool called kops.
  • Installing Kubernetes on Linux with kubeadm (Alpha): Install a secure Kubernetes cluster on any pre-existing machines running Linux, using the built-in kubeadm tool.
    • +
  • Installing Kubernetes On-premise/Cloud Providers with Kargo: Deploy a Kubernetes cluster on-premise baremetal or hosted on cloud providers, with Ansible and kargo tools.

    • Guides, Tutorials, Tasks, and Concepts