adding_hosts_to_existing_cluster.adoc

Adding Hosts to an Existing Cluster

• Overview
• Adding Hosts Using the Quick Installer Tool
• Adding Hosts Using the Advanced Install
• Adding etcd Hosts to existing Cluster

Overview

Depending on how your {product-title} cluster was installed, you can add new hosts (either nodes or masters) to your installation by using the install tool for quick installations, or by using the scaleup.yml playbook for advanced installations.

Adding Hosts Using the Quick Installer Tool

If you used the quick install tool to install your {product-title} cluster, you can use the quick install tool to add a new node host to your existing cluster.

Note	Currently, you can not use the quick installer tool to add new master hosts. You must use the advanced installation method to do so.

If you used the installer in either interactive or unattended mode, you can re-run the installation as long as you have an installation configuration file at ~/.config/openshift/installer.cfg.yml (or specify a different location with the -c option).

Important

The recommended maximum number of nodes is 300.

To add nodes to your installation:

1. Ensure you have the latest installer and playbooks by updating the atomic-openshift-utils package:

   # yum update atomic-openshift-utils

2. Run the installer with the scaleup subcommand in interactive or unattended mode:

   # atomic-openshift-installer [-u] [-c </path/to/file>] scaleup

3. The installer detects your current environment and allows you to add additional nodes:

   *** Installation Summary ***
   
   Hosts:
   - 100.100.1.1
     - OpenShift master
     - OpenShift node
     - Etcd (Embedded)
     - Storage
   
   Total OpenShift masters: 1
   Total OpenShift nodes: 1
   
   
   ---
   
   We have detected this previously installed OpenShift environment.
   
   This tool will guide you through the process of adding additional
   nodes to your cluster.
   
   Are you ready to continue? [y/N]:

   Choose (y) and follow the on-screen instructions to complete your desired task.

Adding Hosts Using the Advanced Install

If you installed using the advanced install, you can add new hosts to your cluster by running the scaleup.yml playbook. This playbook queries the master, generates and distributes new certificates for the new hosts, then runs the configuration playbooks on the new hosts only. Before running the scaleup.yml playbook, complete all prerequisite host preparation steps.

You must have an existing inventory file (for example, /etc/ansible/hosts) that is representative of your current cluster configuration in order to run the scaleup.yml playbook.

Important

The recommended maximum number of nodes is 300.

To add a host to an existing cluster:

1. Ensure you have the latest playbooks by updating the atomic-openshift-utils package:

   # yum update atomic-openshift-utils

2. Edit your /etc/ansible/hosts file and add new_<host_type> to the [OSEv3:children] section:

   For example, to add a new node host, add new_nodes:

   [OSEv3:children]
   masters
   nodes
   new_nodes

   To add new master hosts, add new_masters.

3. Create a [new_<host_type>] section much like an existing section, specifying host information for any new hosts you want to add. For example, when adding a new node:

   [nodes]
   master[1:3].example.com
   node1.example.com openshift_node_labels="{'region': 'primary', 'zone': 'east'}"
   node2.example.com openshift_node_labels="{'region': 'primary', 'zone': 'west'}"
   infra-node1.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   infra-node2.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   
   [new_nodes]
   node3.example.com openshift_node_labels="{'region': 'primary', 'zone': 'west'}"

   See Configuring Host Variables for more options.

   When adding new masters, hosts added to the [new_masters] section must also be added to the [new_nodes] section. This ensures the new master host is part of the OpenShift SDN.

   [masters]
   master[1:2].example.com
   
   [new_masters]
   master3.example.com
   
   [nodes]
   master[1:2].example.com
   node1.example.com openshift_node_labels="{'region': 'primary', 'zone': 'east'}"
   node2.example.com openshift_node_labels="{'region': 'primary', 'zone': 'west'}"
   infra-node1.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   infra-node2.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   
   [new_nodes]
   master3.example.com

   Masters are also automatically marked as unschedulable for pod placement by the installer.

   Important

   If you label a master host with the region=infra label and have no other dedicated infrastructure nodes, you must also explicitly mark the host as schedulable by adding openshift_schedulable=true to the entry. Otherwise, the registry and router pods cannot be placed anywhere.

4. Run the scaleup.yml playbook. If your inventory file is located somewhere other than the default of /etc/ansible/hosts, specify the location with the -i option.

   For additional nodes:

   # ansible-playbook [-i /path/to/file] \
       /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-node/scaleup.yml

   For additional masters:

   # ansible-playbook [-i /path/to/file] \
       /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-master/scaleup.yml

5. After the playbook completes successfully, verify the installation.

6. Finally, move any hosts you had defined in the [new_<host_type>] section into their appropriate section (but leave the [new_<host_type>] section definition itself in place) so that subsequent runs using this inventory file are aware of the nodes but do not handle them as new nodes. For example, when adding new nodes:

   [nodes]
   master[1:3].example.com
   node1.example.com openshift_node_labels="{'region': 'primary', 'zone': 'east'}"
   node2.example.com openshift_node_labels="{'region': 'primary', 'zone': 'west'}"
   node3.example.com openshift_node_labels="{'region': 'primary', 'zone': 'west'}"
   infra-node1.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   infra-node2.example.com openshift_node_labels="{'region': 'infra', 'zone': 'default'}"
   
   [new_nodes]

Adding etcd Hosts to existing Cluster

You can add new etcd hosts to your cluster by running the etcd scaleup playbook. This playbook queries the master, generates and distributes new certificates for the new hosts, and then runs the configuration playbooks on the new hosts only. Before running the etcd scaleup.yml playbook, complete all prerequisite host preparation steps.

To add an etcd host to an existing cluster:

1. Ensure you have the latest playbooks by updating the atomic-openshift-utils package:

   $ yum update atomic-openshift-utils

2. Edit your /etc/ansible/hosts file, add new_<host_type> to the [OSEv3:children] group and add hosts under the new_<host_type> group:

   For example, to add a new etcd, add new_etcd:

   [OSEv3:children]
   masters
   nodes
   etcd
   new_etcd
   
   [etcd]
   etcd1.example.com
   etcd2.example.com
   
   [new_etcd]
   etcd3.example.com

3. Run the etcd scaleup.yml playbook. If your inventory file is located somewhere other than the default of /etc/ansible/hosts, specify the location with the -i option.

   $ ansible-playbook [-i /path/to/file] \
     /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-etcd/scaleup.yml

4. After the playbook completes successfully, verify the installation.