github.com/weaveworks/common@v0.0.0-20230728070032-dd9e68f319d5/tools/config_management/README.md (about)

     1  # Weaveworks configuration management
     2  
     3  ## Introduction
     4  
     5  This project allows you to configure a machine with:
     6  
     7  * Docker and Weave Net for development: `setup_weave-net_dev.yml`
     8  * Docker and Weave Net for testing: `setup_weave-net_test.yml`
     9  * Docker, Kubernetes and Weave Kube (CNI plugin): `setup_weave-kube.yml`
    10  
    11  You can then use these environments for development, testing and debugging.
    12  
    13  ## Set up
    14  
    15  You will need [Python](https://www.python.org/downloads/) and [Ansible 2.+](http://docs.ansible.com/ansible/intro_installation.html) installed on your machine and added to your `PATH` in order to be able to configure environments automatically.
    16  
    17  * On any platform, if you have Python installed: `pip install ansible`
    18  * On macOS: `brew install ansible`
    19  * On Linux (via Aptitude): `sudo apt install ansible`
    20  * On Linux (via YUM): `sudo yum install ansible`
    21  * For other platforms or more details, see [here](http://docs.ansible.com/ansible/intro_installation.html)
    22  
    23  Frequent errors during installation are:
    24  
    25  * `fatal error: Python.h: No such file or directory`: install `python-dev`
    26  * `fatal error: ffi.h: No such file or directory`: install `libffi-dev`
    27  * `fatal error: openssl/opensslv.h: No such file or directory`: install `libssl-dev`
    28  
    29  Full steps for a blank Ubuntu/Debian Linux machine:
    30  
    31      sudo apt-get install -qq -y python-pip python-dev libffi-dev libssl-dev
    32      sudo pip install -U cffi
    33      sudo pip install ansible
    34  
    35  ## Tags
    36  
    37  These can be used to selectively run (`--tags "tag1,tag2"`) or skip (`--skip-tags "tag1,tag2"`) tasks.
    38  
    39    * `output`: print potentially useful output from hosts (e.g. output of `kubectl get pods --all-namespaces`)
    40  
    41  ## Usage
    42  
    43  ### Local machine
    44  
    45  ```
    46  ansible-playbook -u <username> -i "localhost", -c local setup_weave-kube.yml
    47  ```
    48  
    49  ### Vagrant
    50  
    51  Provision your local VM using Vagrant:
    52  
    53  ```
    54  cd $(mktemp -d -t XXX)
    55  vagrant init ubuntu/xenial64  # or, e.g. centos/7
    56  vagrant up
    57  ```
    58  
    59  then set the following environment variables by extracting the output of `vagrant ssh-config`:
    60  
    61  ```
    62  eval $(vagrant ssh-config | sed \
    63  -ne 's/\ *HostName /vagrant_ssh_host=/p' \
    64  -ne 's/\ *User /vagrant_ssh_user=/p' \
    65  -ne 's/\ *Port /vagrant_ssh_port=/p' \
    66  -ne 's/\ *IdentityFile /vagrant_ssh_id_file=/p')
    67  ```
    68  
    69  and finally run:
    70  
    71  ```
    72  ansible-playbook --private-key=$vagrant_ssh_id_file -u $vagrant_ssh_user \
    73  --ssh-extra-args="-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" \
    74  -i "$vagrant_ssh_host:$vagrant_ssh_port," setup_weave-kube.yml
    75  ```
    76  
    77  or, for specific versions of Kubernetes and Docker:
    78  
    79  ```
    80  ansible-playbook --private-key=$vagrant_ssh_id_file -u $vagrant_ssh_user \
    81  --ssh-extra-args="-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" \
    82  -i "$vagrant_ssh_host:$vagrant_ssh_port," setup_weave-kube.yml \
    83  --extra-vars "docker_version=1.12.3 kubernetes_version=1.4.4"
    84  ```
    85  
    86  NOTE: Kubernetes APT repo includes only the latest version, so currently
    87  retrieving an older version will fail.
    88  
    89  ### Terraform
    90  
    91  Provision your machine using the Terraform scripts from `../provisioning`, then run:
    92  
    93  ```
    94  terraform output ansible_inventory > /tmp/ansible_inventory
    95  ```
    96  
    97  and
    98  
    99  ```
   100  ansible-playbook \
   101      --private-key="$(terraform output private_key_path)" \
   102      -u "$(terraform output username)" \
   103      -i /tmp/ansible_inventory \
   104      --ssh-extra-args="-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" \
   105      ../../config_management/setup_weave-kube.yml
   106  
   107  ```
   108  
   109  To specify versions of Kubernetes and Docker see Vagrant examples above.
   110  
   111  N.B.: `--ssh-extra-args` is used to provide:
   112  
   113  * `StrictHostKeyChecking=no`: as VMs come and go, the same IP can be used by a different machine, so checking the host's SSH key may fail. Note that this introduces a risk of a man-in-the-middle attack.
   114  * `UserKnownHostsFile=/dev/null`: if you previously connected a VM with the same IP but a different public key, and added it to `~/.ssh/known_hosts`, SSH may still fail to connect, hence we use `/dev/null` instead of `~/.ssh/known_hosts`.
   115  
   116  
   117  ### Docker installation role
   118  
   119  Various ways to install Docker are provided:
   120  
   121  - `docker-from-docker-ce-repo`
   122  - `docker-from-docker-repo`
   123  - `docker-from-get.docker.com`
   124  - `docker-from-tarball`
   125  
   126  each producing a slightly different outcome, which can be useful for testing various setup scenarios.
   127  
   128  The `docker-install` role selects one of the above ways to install Docker based on the `docker_install_role` variable.
   129  The default value for this variable is configured in `group_vars/all`.
   130  You can however override it with whichever role you would want to run by passing the name of the role as a key-value pair in `extra-vars`, e.g.:
   131  
   132  ```
   133  ansible-playbook <playbook>.yml \
   134      --extra-vars "docker_install_role=docker-from-docker-ce-repo"
   135  ```
   136  
   137  
   138  ## Resources
   139  
   140  * [https://www.vagrantup.com/docs/provisioning/ansible.html](https://www.vagrantup.com/docs/provisioning/ansible.html)
   141  * [http://docs.ansible.com/ansible/guide_vagrant.html](http://docs.ansible.com/ansible/guide_vagrant.html)