From caab0cdf27b2d9949b3b025c72a7a2b11431aeaf Mon Sep 17 00:00:00 2001 From: Bogdan Dobrelya Date: Wed, 11 Jan 2017 12:46:44 +0100 Subject: [PATCH] Docs updates Fix mismatching inventory examples. Add command examples. Clarify groups use cases. Signed-off-by: Bogdan Dobrelya --- docs/ansible.md | 34 ++++++++++++++++++++++++++-------- docs/getting-started.md | 32 +++++++++++++++++++++++++++++--- inventory/inventory.example | 2 +- 3 files changed, 56 insertions(+), 12 deletions(-) diff --git a/docs/ansible.md b/docs/ansible.md index 0ecb8c3ee..fc74aa707 100644 --- a/docs/ansible.md +++ b/docs/ansible.md @@ -8,20 +8,39 @@ The inventory is composed of 3 groups: * **kube-node** : list of kubernetes nodes where the pods will run. * **kube-master** : list of servers where kubernetes master components (apiserver, scheduler, controller) will run. - Note: if you want the server to act both as master and node the server must be defined on both groups _kube-master_ and _kube-node_ * **etcd**: list of server to compose the etcd server. you should have at least 3 servers for failover purposes. +Note: do not modify the children of _k8s-cluster_, like putting +the _etcd_ group into the _k8s-cluster_, unless you are certain +to do that and you have it fully contained in the latter: + +``` +k8s-cluster ⊂ etcd => kube-node ∩ etcd = etcd +``` + +When _kube-node_ contains _etcd_, you define your etcd cluster to be as well schedulable for Kubernetes workloads. +If you want it a standalone, make sure those groups do not intersect. +If you want the server to act both as master and node, the server must be defined +on both groups _kube-master_ and _kube-node_. If you want a standalone and +unschedulable master, the server must be defined only in the _kube-master_ and +not _kube-node_. + +There are also two special groups: + +* **calico-rr** : explained for [advanced Calico networking cases](docs/calico.md) +* **bastion** : configure a bastion host if your nodes are not directly reachable + Below is a complete inventory example: ``` ## Configure 'ip' variable to bind kubernetes services on a ## different ip than the default iface -node1 ansible_ssh_host=95.54.0.12 # ip=10.3.0.1 -node2 ansible_ssh_host=95.54.0.13 # ip=10.3.0.2 -node3 ansible_ssh_host=95.54.0.14 # ip=10.3.0.3 -node4 ansible_ssh_host=95.54.0.15 # ip=10.3.0.4 -node5 ansible_ssh_host=95.54.0.16 # ip=10.3.0.5 -node6 ansible_ssh_host=95.54.0.17 # ip=10.3.0.6 +node1 ansible_ssh_host=95.54.0.12 ip=10.3.0.1 +node2 ansible_ssh_host=95.54.0.13 ip=10.3.0.2 +node3 ansible_ssh_host=95.54.0.14 ip=10.3.0.3 +node4 ansible_ssh_host=95.54.0.15 ip=10.3.0.4 +node5 ansible_ssh_host=95.54.0.16 ip=10.3.0.5 +node6 ansible_ssh_host=95.54.0.17 ip=10.3.0.6 [kube-master] node1 @@ -42,7 +61,6 @@ node6 [k8s-cluster:children] kube-node kube-master -etcd ``` Group vars and overriding variables precedence diff --git a/docs/getting-started.md b/docs/getting-started.md index c15ed2975..906f78c07 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -23,10 +23,36 @@ Building your own inventory Ansible inventory can be stored in 3 formats: YAML, JSON, or inifile. There is an example inventory located -[here](https://github.com/kubernetes-incubator/kargo/blob/master/inventory/inventory.example). +[here](https://github.com/kubernetes-incubator/kargo/blob/master/inventory/inventory.example): -You can use an +``` +cp -r inventory my_inventory +cp my_inventory/inventory.example my_inventory/inventory.cfg +# edit the inventory file as needed +``` + +Or you can use an [inventory generator](https://github.com/kubernetes-incubator/kargo/blob/master/contrib/inventory_builder/inventory.py) to create or modify an Ansible inventory. Currently, it is limited in functionality and is only use for making a basic Kargo cluster, but it does -support creating large clusters. +support creating large clusters. For example: + +``` +cp -r inventory my_inventory +declare -a IPS=(10.10.1.3 10.10.1.4 10.10.1.5) +CONFIG_FILE=my_inventory/inventory.cfg python3 contrib/inventory_builder/inventory.py ${IPS} +``` + +Starting custom deployment +-------------------------- + +Once you have an inventory, you may want to customize deployment data vars +and start the deployment: + +``` +# Edit my_inventory/groups_vars/*.yaml to override data vars +ansible-playbook -i my_inventory/inventory.cfg cluster.yaml -b -v \ + --private-key=~/.ssh/private_key +``` + +See more details in the [ansible guide](ansible.md). diff --git a/inventory/inventory.example b/inventory/inventory.example index 1d10cdce0..13cc3612e 100644 --- a/inventory/inventory.example +++ b/inventory/inventory.example @@ -7,7 +7,7 @@ # node5 ansible_ssh_host=95.54.0.16 # ip=10.3.0.5 # node6 ansible_ssh_host=95.54.0.17 # ip=10.3.0.6 -# ## configure a bastion host if your nodes are not publicly reachable +# ## configure a bastion host if your nodes are not directly reachable # bastion ansible_ssh_host=x.x.x.x # [kube-master]