XTesting/kubespray/docs/getting-started.md

   1 # Getting started
   2
   3 ## Building your own inventory
   4
   5 Ansible inventory can be stored in 3 formats: YAML, JSON, or INI-like. There is
   6 an example inventory located
   7 [here](https://github.com/kubernetes-sigs/kubespray/blob/master/inventory/sample/inventory.ini).
   8
   9 You can use an
  10 [inventory generator](https://github.com/kubernetes-sigs/kubespray/blob/master/contrib/inventory_builder/inventory.py)
  11 to create or modify an Ansible inventory. Currently, it is limited in
  12 functionality and is only used for configuring a basic Kubespray cluster inventory, but it does
  13 support creating inventory file for large clusters as well. It now supports
  14 separated ETCD and Kubernetes control plane roles from node role if the size exceeds a
  15 certain threshold. Run `python3 contrib/inventory_builder/inventory.py help` for more information.
  16
  17 Example inventory generator usage:
  18
  19 ```ShellSession
  20 cp -r inventory/sample inventory/mycluster
  21 declare -a IPS=(10.10.1.3 10.10.1.4 10.10.1.5)
  22 CONFIG_FILE=inventory/mycluster/hosts.yml python3 contrib/inventory_builder/inventory.py ${IPS[@]}
  23 ```
  24
  25 Then use `inventory/mycluster/hosts.yml` as inventory file.
  26
  27 ## Starting custom deployment
  28
  29 Once you have an inventory, you may want to customize deployment data vars
  30 and start the deployment:
  31
  32 **IMPORTANT**: Edit my\_inventory/groups\_vars/\*.yaml to override data vars:
  33
  34 ```ShellSession
  35 ansible-playbook -i inventory/mycluster/hosts.yml cluster.yml -b -v \
  36   --private-key=~/.ssh/private_key
  37 ```
  38
  39 See more details in the [ansible guide](/docs/ansible.md).
  40
  41 ### Adding nodes
  42
  43 You may want to add worker, control plane or etcd nodes to your existing cluster. This can be done by re-running the `cluster.yml` playbook, or you can target the bare minimum needed to get kubelet installed on the worker and talking to your control planes. This is especially helpful when doing something like autoscaling your clusters.
  44
  45 - Add the new worker node to your inventory in the appropriate group (or utilize a [dynamic inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html)).
  46 - Run the ansible-playbook command, substituting `cluster.yml` for `scale.yml`:
  47
  48 ```ShellSession
  49 ansible-playbook -i inventory/mycluster/hosts.yml scale.yml -b -v \
  50   --private-key=~/.ssh/private_key
  51 ```
  52
  53 ### Remove nodes
  54
  55 You may want to remove **control plane**, **worker**, or **etcd** nodes from your
  56 existing cluster. This can be done by re-running the `remove-node.yml`
  57 playbook. First, all specified nodes will be drained, then stop some
  58 kubernetes services and delete some certificates,
  59 and finally execute the kubectl command to delete these nodes.
  60 This can be combined with the add node function. This is generally helpful
  61 when doing something like autoscaling your clusters. Of course, if a node
  62 is not working, you can remove the node and install it again.
  63
  64 Use `--extra-vars "node=<nodename>,<nodename2>"` to select the node(s) you want to delete.
  65
  66 ```ShellSession
  67 ansible-playbook -i inventory/mycluster/hosts.yml remove-node.yml -b -v \
  68 --private-key=~/.ssh/private_key \
  69 --extra-vars "node=nodename,nodename2"
  70 ```
  71
  72 If a node is completely unreachable by ssh, add `--extra-vars reset_nodes=false`
  73 to skip the node reset step. If one node is unavailable, but others you wish
  74 to remove are able to connect via SSH, you could set `reset_nodes=false` as a host
  75 var in inventory.
  76
  77 ## Connecting to Kubernetes
  78
  79 By default, Kubespray configures kube_control_plane hosts with insecure access to
  80 kube-apiserver via port 8080. A kubeconfig file is not necessary in this case,
  81 because kubectl will use <http://localhost:8080> to connect. The kubeconfig files
  82 generated will point to localhost (on kube_control_planes) and kube_node hosts will
  83 connect either to a localhost nginx proxy or to a loadbalancer if configured.
  84 More details on this process are in the [HA guide](/docs/ha-mode.md).
  85
  86 Kubespray permits connecting to the cluster remotely on any IP of any
  87 kube_control_plane host on port 6443 by default. However, this requires
  88 authentication. One can get a kubeconfig from kube_control_plane hosts
  89 (see [below](#accessing-kubernetes-api)).
  90
  91 For more information on kubeconfig and accessing a Kubernetes cluster, refer to
  92 the Kubernetes [documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
  93
  94 ## Accessing Kubernetes Dashboard
  95
  96 Supported version is kubernetes-dashboard v2.0.x :
  97
  98 - Login option : token/kubeconfig by default
  99 - Deployed by default in "kube-system" namespace, can be overridden with `dashboard_namespace: kubernetes-dashboard` in inventory,
 100 - Only serves over https
 101
 102 Access is described in [dashboard docs](https://github.com/kubernetes/dashboard/tree/master/docs/user/accessing-dashboard). With kubespray's default deployment in kube-system namespace, instead of kubernetes-dashboard :
 103
 104 - Proxy URL is <http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#/login>
 105 - kubectl commands must be run with "-n kube-system"
 106
 107 Accessing through Ingress is highly recommended. For proxy access, please note that proxy must listen to [localhost](https://github.com/kubernetes/dashboard/issues/692#issuecomment-220492484) (`proxy  --address="x.x.x.x"` will not work)
 108
 109 For token authentication, guide to create Service Account is provided in [dashboard sample user](https://github.com/kubernetes/dashboard/blob/master/docs/user/access-control/creating-sample-user.md) doc. Still take care of default namespace.
 110
 111 Access can also by achieved via ssh tunnel on a control plane :
 112
 113 ```bash
 114 # localhost:8081 will be sent to control-plane-1's own localhost:8081
 115 ssh -L8001:localhost:8001 user@control-plane-1
 116 sudo -i
 117 kubectl proxy
 118 ```
 119
 120 ## Accessing Kubernetes API
 121
 122 The main client of Kubernetes is `kubectl`. It is installed on each kube_control_plane
 123 host and can optionally be configured on your ansible host by setting
 124 `kubectl_localhost: true` and `kubeconfig_localhost: true` in the configuration:
 125
 126 - If `kubectl_localhost` enabled, `kubectl` will download onto `/usr/local/bin/` and setup with bash completion. A helper script `inventory/mycluster/artifacts/kubectl.sh` also created for setup with below `admin.conf`.
 127 - If `kubeconfig_localhost` enabled `admin.conf` will appear in the `inventory/mycluster/artifacts/` directory after deployment.
 128 - The location where these files are downloaded to can be configured via the `artifacts_dir` variable.
 129
 130 NOTE: The controller host name in the admin.conf file might be a private IP. If so, change it to use the controller's public IP or the cluster's load balancer.
 131
 132 You can see a list of nodes by running the following commands:
 133
 134 ```ShellSession
 135 cd inventory/mycluster/artifacts
 136 ./kubectl.sh get nodes
 137 ```
 138
 139 If desired, copy admin.conf to ~/.kube/config.
 140
 141 ## Setting up your first cluster
 142
 143 [Setting up your first cluster](/docs/setting-up-your-first-cluster.md) is an
 144  applied step-by-step guide for setting up your first cluster with Kubespray.