From 86ed2d5343c0afd561e700e5ca7463fe73b308be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20Mass=C3=A9?= Date: Thu, 22 Jun 2017 09:17:21 +0200 Subject: [PATCH] finally, add some doc --- README.md | 130 +++++++++---------------------------- doc/ANSIBLE_WRAPPER.md | 52 +++++++++++++++ doc/BASTION.md | 99 ++++++++++++++++++++++++++++ doc/CUSTOMIZATION.md | 1 + doc/MACHINE_PREPARATION.md | 36 ++++++++++ doc/PLAYBOOKS.md | 50 ++++++++++++++ doc/ROLES.md | 20 ++++++ 7 files changed, 290 insertions(+), 98 deletions(-) create mode 100644 doc/ANSIBLE_WRAPPER.md create mode 100644 doc/BASTION.md create mode 100644 doc/CUSTOMIZATION.md create mode 100644 doc/MACHINE_PREPARATION.md create mode 100644 doc/PLAYBOOKS.md create mode 100644 doc/ROLES.md diff --git a/README.md b/README.md index 907ed6c..8bb4351 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,53 @@ -# OpenShift-Lab +# An "easy to use" OpenShift Lab This project is an Ansible Playbook to install OpenShift in a Lab Environment. -## Preparation work +Its goal is to help people install easily OpenShift in a lab environment, +for a test drive or a PoC. So, this project focuses mostly on ease of use instead +of security, availability, etc. **DO NOT USE THIS PROJECT IN PRODUCTION**. +You have been warned. -1. Pull the "openshift-ansible" sub-project using : -``` -git submodule init -git submodule update -``` -2. Review \*.hosts and change hostnames to target your environment - -## Example - -``` -./ansible bootstrap vm.openshift.test -./ansible play allinone -``` - - -## Connection through a bastion host - -Sometimes, your target machines are on a restricted network where access is -done through a "bastion host" (also called "jump host"). - -This section explains how to configure this project to work with such a -configuration. - -Two variants of this configuration are possible : - 1. The jump host holds the SSH keys to connect to the target host - 2. The jump host has no SSH key, the SSH Keys remains on your machine - -In the second configuration, you will have to setup your SSH Agent (if not -already done) and forward it. - -### Step 1: Setup your SSH Agent (optional) +It features multiple architecture choices : + - All-in-one: master, etcd, infra node, app node on the same machines (**DONE**) + - Small Cluster: 1 master with etcd, 1 infra node, 2 app nodes (**TODO**) + - Big Cluster: 3 masters with etcd, 2 infra nodes, 2 app nodes, 1 load balancer (**TODO**) -Run the SSH Agent : -``` -eval "$(ssh-agent -s)" -``` +By default, it deploys the following software in addition to OpenShift : + - Red Hat SSO + - 3scale + - the [OpenShift-Hostpath-Provisioner](https://github.com/nmasse-itix/OpenShift-HostPath-Provisioner) -And add your SSH key to your agent : -``` -ssh-add ~/.ssh/id_rsa -``` +This project is different from existing "demo" OpenShift playbooks in the sense that : + - It features a common inventory file for both the OpenShift playbooks and the complimentary playbooks. (it's easier to maintain) + - The underlying openshift-ansible playbooks are included directly (as opposed to other approaches that run an `ansible-playbook` command from inside the main playbook). -Source : https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ +By default, this project comes with a git submodule reference to the `openshift-ansible` repository for convenience. +But you could replace this reference with a symlink to your `openshift-ansible` installation, for instance if you installed the supported package from Red Hat. -### Step 2: Create the ssh.cfg +## Setup -Create a file named `ssh.cfg` with the following content : +1. First of all, clone this repo : ``` -Host jump.host - Hostname jump.host - User john-adm - ForwardAgent yes - ControlMaster auto - ControlPath ~/.ssh/ansible-%r@%h:%p - ControlPersist 5m - -Host 10.0.0.* - ProxyCommand ssh -q -W %h:%p jump.host - User john +git clone https://github.com/nmasse-itix/OpenShift-Lab.git ``` -You will have to replace `jump.host` (three occurrences) with the hostname of your jump host. -Also make sure to that the two usernames match your environment : -- The first `User` stanza is the username you will use to connect to your jump host -- The second `User` stanza is the username you will use to connect to your target host - -You will also have to replace `10.0.0.*` by the subnet of your target machines. -If you reference your machines by DNS names instead of IP address, you could use -the DNS suffix common to your target machines, like `*.compute.internal`. - -Note: the `ForwardAgent` stanza is only required if your jump host does not hold -the SSH keys to connect to your target machines. - -Now you can test your ssh.cfg by issuing the following command : +2. Pull the "openshift-ansible" sub-project using : ``` -ssh -F ssh.cfg your.target.host +git submodule init +git submodule update ``` -If your configuration is correct, you will be directly connected to your target -host. - -### Step 3: Edit the Ansible configuration file +3. Review allinone.hosts and change hostnames to target your environment -Edit the `ansible.cfg` file and add : +4. If needed, bootstrap your machines (optional) : ``` -# Connection through a jump host -[ssh_connection] -ssh_args = -F ./ssh.cfg -o ControlMaster=auto -o ControlPersist=30m -control_path = ~/.ssh/ansible-%%r@%%h:%%p +./ansible bootstrap vm.openshift.test ``` -You can test that your setup is correct by using the `ping` module of Ansible : +5. Run the playbook that installs everything on one machine : ``` -ansible -i your-inventory-file all -m ping +./ansible play allinone ``` -If your setup is correct, you should see something like : -``` -machine1.internal | SUCCESS => { - "changed": false, - "ping": "pong" -} -machine2.internal | SUCCESS => { - "changed": false, - "ping": "pong" -} -``` +## Further readings -Note: sometime your lab has no DNS server and you have to connect to your target -machines using IP addresses. If you still want to name your machines in Ansible -with a nice name, you can declare the target machines in the inventory file like this : -``` -machine1.internal ansible_host=10.0.0.1 -machine2.internal ansible_host=10.0.0.2 -``` +If you plan to use this project regularly, you might have a look at the [Ansible roles description](doc/ROLES.md). +And if you need to customize this project to suit your own needs, have a look at the [Customization Guide](doc/CUSTOMIZATION.md). diff --git a/doc/ANSIBLE_WRAPPER.md b/doc/ANSIBLE_WRAPPER.md new file mode 100644 index 0000000..7392d31 --- /dev/null +++ b/doc/ANSIBLE_WRAPPER.md @@ -0,0 +1,52 @@ +# Ansible Wrapper presentation + +The Ansible Wrapper is a small shell script (`./ansible`) that does two things : + - It calls the bootstrap playbook with the right environment variables + - It calls the target playbooks (`allinone.yml` for instance) with the right inventory file + +## Bootstrap + +Usually, when machines are provisioned, they are not ready to be used in Ansible. +For example : + - There is no regular user account, `root` is the only available user + - You SSH Keys are not yet installed, so a Password Authentication is required + - Sudo might no be configured + - etc. + +The ansible wrapper will : + - Make sure the SSH Host Key of the target machine is trusted (otherwise Ansible would complain...) + - Do a password authentication for the first time (thanks to `sshpass`) + - Add your SSH Keys to the `authorized_keys` + - Create a regular user (by default: `redhat`) + - Install and configure sudo + - Register the machine with the Red Hat Network (RHN) + - Attach a subscription pool + +To use the wrapper, you need to make sure you have `sshpass` installed : +``` +sshpass -V +``` + +If not installed, setup sshpass as explained here : https://gist.github.com/arunoda/7790979 + +To bootstrap a machine, just use : +``` +./ansible bootstrap machine1.compute.internal +``` + +__Tip :__ You can pass multiple machine on the command line to bootstrap them all at the same time. + +The wrapper, will then ask you a few questions : + - The root password. If you have already setup SSK Key Authentication, you can just hit enter. + - Your RHN login + - Your RHN password + - The Pool ID that you would like to use. If you do not provide a Pool ID, no pool will be attached and you will have to do it later manually. + +## Daily usage + +Once your machines are bootstrapped, you can launch the target playbook (`allinone` for instance) with : +``` +./ansible play allinone +``` + +__Note :__ the `play` command is just a shortcut to `ansible-playbook -i .host .yml` diff --git a/doc/BASTION.md b/doc/BASTION.md new file mode 100644 index 0000000..cefb9d6 --- /dev/null +++ b/doc/BASTION.md @@ -0,0 +1,99 @@ +## Connection through a bastion host + +Sometimes, your target machines are on a restricted network where access is +done through a "bastion host" (also called "jump host"). + +This section explains how to configure this project to work with such a +configuration. + +Two variants of this configuration are possible : + 1. The jump host holds the SSH keys to connect to the target host + 2. The jump host has no SSH key, the SSH Keys remains on your machine + +In the second configuration, you will have to setup your SSH Agent (if not +already done) and forward it. + +### Step 1: Setup your SSH Agent (optional) + +Run the SSH Agent : +``` +eval "$(ssh-agent -s)" +``` + +And add your SSH key to your agent : +``` +ssh-add ~/.ssh/id_rsa +``` + +Source : https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ + +### Step 2: Create the ssh.cfg + +Create a file named `ssh.cfg` with the following content : +``` +Host jump.host + Hostname jump.host + User john-adm + ForwardAgent yes + ControlMaster auto + ControlPath ~/.ssh/ansible-%r@%h:%p + ControlPersist 5m + +Host 10.0.0.* + ProxyCommand ssh -q -W %h:%p jump.host + User john +``` + +You will have to replace `jump.host` (three occurrences) with the hostname of your jump host. +Also make sure to that the two usernames match your environment : +- The first `User` stanza is the username you will use to connect to your jump host +- The second `User` stanza is the username you will use to connect to your target host + +You will also have to replace `10.0.0.*` by the subnet of your target machines. +If you reference your machines by DNS names instead of IP address, you could use +the DNS suffix common to your target machines, like `*.compute.internal`. + +Note: the `ForwardAgent` stanza is only required if your jump host does not hold +the SSH keys to connect to your target machines. + +Now you can test your ssh.cfg by issuing the following command : +``` +ssh -F ssh.cfg your.target.host +``` +If your configuration is correct, you will be directly connected to your target +host. + +### Step 3: Edit the Ansible configuration file + +Edit the `ansible.cfg` file and add : +``` +# Connection through a jump host +[ssh_connection] +ssh_args = -F ./ssh.cfg -o ControlMaster=auto -o ControlPersist=30m +control_path = ~/.ssh/ansible-%%r@%%h:%%p +``` + +You can test that your setup is correct by using the `ping` module of Ansible : +``` +ansible -i your-inventory-file all -m ping +``` + +If your setup is correct, you should see something like : +``` +machine1.internal | SUCCESS => { + "changed": false, + "ping": "pong" +} +machine2.internal | SUCCESS => { + "changed": false, + "ping": "pong" +} +``` + +Note: sometime your lab has no DNS server and you have to connect to your target +machines using IP addresses. If you still want to name your machines in Ansible +with a nice name, you can declare the target machines in the inventory file like this : +``` +machine1.internal ansible_host=10.0.0.1 +machine2.internal ansible_host=10.0.0.2 +``` diff --git a/doc/CUSTOMIZATION.md b/doc/CUSTOMIZATION.md new file mode 100644 index 0000000..4640904 --- /dev/null +++ b/doc/CUSTOMIZATION.md @@ -0,0 +1 @@ +# TODO diff --git a/doc/MACHINE_PREPARATION.md b/doc/MACHINE_PREPARATION.md new file mode 100644 index 0000000..01ff1de --- /dev/null +++ b/doc/MACHINE_PREPARATION.md @@ -0,0 +1,36 @@ +# Preparation of target machines + +Currently, the machines needs to have at least 2 disk partitions : + - 1 partition for the Operating System (**REQUIRED**) + - 1 LVM partition for the Docker Storage (**REQUIRED**) + +A third partition is recommended but not required : + - 1 partition for the OpenShift Persistent Volumes (**OPTIONAL**) + +If your machine has only one disk, you can create partitions (that may use LVM underneath or not, free choice). +An alternative when using Virtual Machines is to add 3 disks to the VM, the setup is a bit easier. + +The OS partition is created by the RHEL installer so you do not have to care much about it. + +The Docker Storage partition **has to be LVM** and **has to be in a separate Volume Group**. +Namely, if your Docker Storage partition is `/dev/sda2`, you can create a separate Volume Group by using : +``` +vgcreate docker /dev/sda2 +``` + +The OpenShift Persistent Volumes partition, if not required is still highly recommended. +By a having a dedicated partition, if the Persistent Volumes start to grow it will not +fill up the OS partition. + +If your OpenShift PV partition is `/dev/sda3`, you can set it up by using : +``` +mkfs.xfs /dev/sda3 +echo "/dev/sda3 /var/openshift xfs defaults 0 0" >> /etc/fstab +``` + +If you kept the default values (`docker` for the Volume Group name and +`/var/openshift` for the OpenShift PV mount point), no further setup is required. + +Otherwise, you might have to set the following variables in your inventory file : + - `docker_storage_vg` + - `hostpath_provisioner_options` diff --git a/doc/PLAYBOOKS.md b/doc/PLAYBOOKS.md new file mode 100644 index 0000000..f7c0dce --- /dev/null +++ b/doc/PLAYBOOKS.md @@ -0,0 +1,50 @@ +# Playbooks description + +## Bootstrap (`bootstrap.yml`) + +The bootstrap playbook is used to prepare a machine to be managed by Ansible. +Namely, it will : + - Create a regular user account (named `redhat`) + - Add your SSH Public Key to the `authorized_keys` of `root` and `redhat` + - Install and configure `sudo` so that the `redhat` user can launch commands as `root` without password + - Register the machine on the RHN (Red Hat Network) + +To work, this playbook will require a few environment variables : + +| Environment Variable | Description | +| --- | --- | +| RHN_LOGIN | Your Red Hat Network login | +| RHN_PASSWORD | Your Red Hat Network password | +| RHN_POOLID | The subscription pool you want to use | + +__Tip :__ You can get the PoolID by querying : +``` +sudo subscription-manager list --available --matches '*OpenShift*' +``` + +This playbook is best used with the [Ansible Wrapper](ANSIBLE_WRAPPER.md). + +## All-in-one cluster (`allinone.yml`) + +The All-in-one cluster playbook will deploy everyting on one machine. It is very +convenient for development or PoC where the focus is on the features rather than on the infrastructure. + +Minimal requirements for the target machine are : + - 2 Cores + - 4 GB of RAM + - 30 GB Hard Disk, partitioned as explained in the [Machine Preparation Guide](MACHINE_PREPARATION.md) + +Recommended config : + - 4 Cores + - 10 GB of RAM + - 60 GB Hard Disk, partitioned as explained in the [Machine Preparation Guide](MACHINE_PREPARATION.md) + +See [Machine Preparation Guide](MACHINE_PREPARATION.md) for more details about partitioning. + +## Small cluster (TODO) + +TODO + +## Big cluster (TODO) + +TODO diff --git a/doc/ROLES.md b/doc/ROLES.md new file mode 100644 index 0000000..bd09798 --- /dev/null +++ b/doc/ROLES.md @@ -0,0 +1,20 @@ +# Roles description + +## Bootstrap roles + +| Role | Description | +| --- | --- | +| [bootstrap](../roles/bootstrap/) | adds your SSH key to `authorized_keys`, creates users, configures sudo | +| [register-rhn](../roles/register-rhn/) | registers the target machine on RHN (Red Hat Network) and attaches a subscription pool | + +## Regular roles + +| Role | Description | +| --- | --- | +| [base](../roles/base/) | configures SSH to forbid password authentication, installs basic software and sets the hostname | +| [name-resolution](../roles/name-resolution/) | ensures name resolution through the whole cluster | +| [docker](../roles/docker/) | installs docker and configures docker storage | +| [openshift-prereq](../roles/openshift-prereq/) | ensures the system meet the pre-requisites for the OpenShift installation | +| [openshift-postinstall](../roles/openshift-postinstall/) | installs the latest JBoss ImageStreams | +| [3scale](../roles/3scale/) | deploys 3scale | +| [sso](../roles/sso/) | deploys Red Hat SSO |