Metalnetes

Tools for managing multiple Kubernetes 1.14 clusters on KVM (3 CentOS 7 VMs) running on a bare metal Fedora 29 server (also tested on Ubuntu 18.04 until 1.13). Use this repo if you want to create, destroy and manage native Kubernetes clusters. It is a full installer for taking a brand new server up to speed using just bash and environment variables.

.. image:: https://i.imgur.com/awLwim1.png

Getting Started

This repo <https://github.com/jay-johnson/metalnetes>__ automates:

• installing many rpms, systems and tools to prepare a bare metal server (on Fedora 29) to host multiple Kubernetes clusters
• deploying Kubernetes clusters on 3 CentOS 7 VMs
• each VM has 100 GB, 4 cpu cores, 16 GB ram, and auto-configured for static IP assignment from env vars
• hosting VMs using KVM which requires access to the server's hypervisor (running this in a vm will not work)
• deploying a Rook Ceph storage cluster for Kubernetes persistent volumes
• installs a local dns server (named) with working example for mapping VM static ips to urls that a browser can use with any Kubernetes nginx ingress endpoint
• ssh access for manually fixing a VM after deployment
• optional - deploy the Stock Analysis Engine <https://stock-analysis-engine.readthedocs.io/en/latest/>__ which includes helm charts for running: Minio (on-premise s3), Redis cluster, Jupyter, Grafana + Prometheus for monitoring (required for ceph cluster monitoring)

Fedora Bare Metal Install Guide

Server Resource Requirements

Minimum hardware specs to run 1 cluster:

• 50 GB RAM
• 12 cpu cores
• 500 GB hdd space for each cluster (400 GB if you do not want to use base images and slow down each cluster deployment)

Clone

::

git clone https://github.com/jay-johnson/metalnetes.git
cd metalnetes

Edit Cluster Configuration

Please edit the default Cluster Config k8.env <https://github.com/jay-johnson/metalnetes/blob/master/k8.env>__ as needed

Launch Checklist

Uninstalling and reinstalling clusters is not a slow process, and it helps to take a moment to review the VM's networking, Kubernetes cluster deployment, and KVM configuration before starting or testing a new idea for your next cluster deployment:

#. Set a name for the cluster <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L4-L8>__ #. KVM

#.  `K8_VMS <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L100>`__ - short VM names for showing in ``virsh list`` and must be unique
#.  `K8_DOMAIN <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L101>`__ - search domain for cluster ``example.com`` and must work with the dns server records and VM ip addresses
#.  `K8_INITIAL_MASTER <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L102>`__ - initial fqdn to set ``m10.example.com``
#.  `K8_SECONDARY_MASTERS <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L103>`__ - additional fqdns to set ``m11.example.com m12.example.com`` and space separated

#. Networking

#.  `Confirm VM IP Addresses <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L105-L108>`__
#.  `Confirm VM MAC Addresses <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L109-L111>`__
#.  `Confirm DNS <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L104>`__

#. Confirm User For Private Docker Registry <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L35-L39>__ #. Confirm User For SSH Access to VMs <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L118-L119>__ #. Confirm CPU Per VM (4 cores) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L116>__ #. Confirm Memory Per VM (16 GB ram) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L117>__ #. Confirm Storage Per VM (100 GB harddrives and qemu raw image format) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L114>__ #. Confirm Cluster Storage (rook-ceph by default) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L57-L60>__ #. Confirm Ingress (nginx by default) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L91-L94>__ #. Confirm Bridge (br0 by default) <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L115>__ #. Confirm Base VM IP and Mac Address <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L208-L209>__ #. Confirm Base VM Allow Query DNS CIDR <https://github.com/jay-johnson/metalnetes/blob/master/k8.env#L205>__

Start Install

Change to root and start the Fedora bare metal server installer:

::

sudo su
./fedora/server-install.sh

Install Bridge

This will install a bridge network device called br0 from a network device eno1. This br0 bridge is used by KVM as a shared networking device for all VMs in all Kubernetes clusters.

::

./fedora/install-bridge.sh

I am not sure this is required, but I reboot the server at this point. This ensures the OS reboots correctly before creating any VMs, and I can confirm the br0 bridge shows up after a clean restart using ifconfig -a | grep br0 or nmcli dev | grep br0.

Start the Kubernetes Cluster

Boot your cluster as your user (which should have KVM access). The boot.sh <https://github.com/jay-johnson/metalnetes/blob/master/boot.sh>__ uses a base VM to bootstrap and speed up future deployments. Once the base VM is built, it will copy and launch 3 VMs (from the base) and install the latest Kubernetes build in all VMs. Once installed and running the 2nd and 3rd nodes join the 1st node to initialize the cluster. After initializing the cluster, helm and tiller will install and a rook-ceph storage layer will be deployed for persisting your data in volumes:

.. note:: Initial benchmarks take around 30 minutes to build all VMs and bring a new cluster online. Cleaning and restarting the cluster does not take nearly as long as creating VMs for a new cluster. Also the first time running ./boot.sh will take the longest because it builds a shared base VM image to decrease future cluster deploy time.

::

# go to the base of the repo
source k8.env
./boot.sh

For help with issues please refer to the FAQ <https://github.com/jay-johnson/metalnetes#faq>__

View Kubernetes Nodes

Once it finishes you can view your new cluster nodes with:

::

./tools/show-nodes.sh

Changing Between Kubernetes Clusters

If you create a new k8.env file for each cluster, like dev_k8.env and prod_k8.env then you can then quickly toggle between clusters using:

#. Load dev Cluster Config file

::

    source dev_k8.env

#. Use the metal bash function to sync the KUBECONFIG through the dev cluster and local host

::

    metal

#. Load prod Cluster Config file

::

    source prod_k8.env

#. Use the metal bash function to sync the KUBECONFIG through the prod cluster and local host

::

    metal

Customizing the Kubernetes Cluster

If you are looking to swap out parts of the deployment, please ensure the hosting server has a replacement in place for these bare minimum components:

• a dns server that can host the example.com zone
• access to a docker-ce daemon (latest stable)
• a private docker registry
• KVM (requires hypervisor access)
• a network device that supports static bridging for KVM (please review the centos/install-network-device.sh for examples)
• default static network ip assignment from a router or switch that can map a VM's MAC address to a static ip address that the dns server can map to for helping browsers access nginx ingress endpoints
• access to arp-scan tool for detecting when each VM is ready for ssh scripting using dns name resolution

Before starting a second cluster there are some deployment sections to change from the default k8.env Cluster Config file.

Please review these sections to prevent debugging collision-related issues:

VM and Kubernetes Node Configuration

• VM names, Cluster Nodes, Node Labels, Cluster Tools section <https://github.com/jay-johnson/metalnetes/blob/34c0eabf5f7007056a4823f5c4ea760aea7c8e6e/k8.env#L96-L194>__

Considerations and Deployment Constraints

• K8_ENV must be a unique name for the cluster (dev vs prod for example)
• VM names need to be unique (and on the dns server with fqdn: VM_NAME.example.com as the default naming convention
• IPs must be unique (or the dns server will have problems)
• MAC addressess must be unique

Helm and Tiller Configuration

• Helm and Tiller <https://github.com/jay-johnson/metalnetes/blob/34c0eabf5f7007056a4823f5c4ea760aea7c8e6e/k8.env#L48-L55>__

Cluster Storage Configuation

Considerations and Deployment Constraints

• Operator redundancy

• Storage (rook-ceph by default) <https://github.com/jay-johnson/metalnetes/blob/34c0eabf5f7007056a4823f5c4ea760aea7c8e6e/k8.env#L57-L65>__

• Additional Block Devices per VM <https://github.com/jay-johnson/metalnetes/blob/34c0eabf5f7007056a4823f5c4ea760aea7c8e6e/k8.env#L178-L188>__

Private Docker Registry

Please export the address to your private docker registy before deploying with format:

::

export DOCKER_REGISTRY_FQDN=REGISTRY_HOST:PORT

• Registry <https://github.com/jay-johnson/metalnetes/blob/34c0eabf5f7007056a4823f5c4ea760aea7c8e6e/k8.env#L35-L46>__

Managing a Running Kubernetes Cluster

Run these steps to manage a running kubernetes cluster.

Load the CLUSTER_CONFIG environment

::

# from within the re