XTesting/kubespray/docs/equinix-metal.md

   1 # Equinix Metal
   2
   3 Kubespray provides support for bare metal deployments using the [Equinix Metal](http://metal.equinix.com).
   4 Deploying upon bare metal allows Kubernetes to run at locations where an existing public or private cloud might not exist such
   5 as cell tower, edge collocated installations. The deployment mechanism used by Kubespray for Equinix Metal is similar to that used for
   6 AWS and OpenStack clouds (notably using Terraform to deploy the infrastructure). Terraform uses the Equinix Metal provider plugin
   7 to provision and configure hosts which are then used by the Kubespray Ansible playbooks. The Ansible inventory is generated
   8 dynamically from the Terraform state file.
   9
  10 ## Local Host Configuration
  11
  12 To perform this installation, you will need a localhost to run Terraform/Ansible (laptop, VM, etc) and an account with Equinix Metal.
  13 In this example, we're using an m1.large CentOS 7 OpenStack VM as the localhost to kickoff the Kubernetes installation.
  14 You'll need Ansible, Git, and PIP.
  15
  16 ```bash
  17 sudo yum install epel-release
  18 sudo yum install ansible
  19 sudo yum install git
  20 sudo yum install python-pip
  21 ```
  22
  23 ## Playbook SSH Key
  24
  25 An SSH key is needed by Kubespray/Ansible to run the playbooks.
  26 This key is installed into the bare metal hosts during the Terraform deployment.
  27 You can generate a key new key or use an existing one.
  28
  29 ```bash
  30 ssh-keygen -f ~/.ssh/id_rsa
  31 ```
  32
  33 ## Install Terraform
  34
  35 Terraform is required to deploy the bare metal infrastructure. The steps below are for installing on CentOS 7.
  36 [More terraform installation options are available.](https://learn.hashicorp.com/terraform/getting-started/install.html)
  37
  38 Grab the latest version of Terraform and install it.
  39
  40 ```bash
  41 echo "https://releases.hashicorp.com/terraform/$(curl -s https://checkpoint-api.hashicorp.com/v1/check/terraform | jq -r -M '.current_version')/terraform_$(curl -s https://checkpoint-api.hashicorp.com/v1/check/terraform | jq -r -M '.current_version')_linux_amd64.zip"
  42 sudo yum install unzip
  43 sudo unzip terraform_0.14.10_linux_amd64.zip -d /usr/local/bin/
  44 ```
  45
  46 ## Download Kubespray
  47
  48 Pull over Kubespray and setup any required libraries.
  49
  50 ```bash
  51 git clone https://github.com/kubernetes-sigs/kubespray
  52 cd kubespray
  53 ```
  54
  55 ## Install Ansible
  56
  57 Install Ansible according to [Ansible installation guide](/docs/ansible.md#installing-ansible)
  58
  59 ## Cluster Definition
  60
  61 In this example, a new cluster called "alpha" will be created.
  62
  63 ```bash
  64 cp -LRp contrib/terraform/packet/sample-inventory inventory/alpha
  65 cd inventory/alpha/
  66 ln -s ../../contrib/terraform/packet/hosts
  67 ```
  68
  69 Details about the cluster, such as the name, as well as the authentication tokens and project ID
  70 for Equinix Metal need to be defined. To find these values see [Equinix Metal API Accounts](https://metal.equinix.com/developers/docs/accounts/).
  71
  72 ```bash
  73 vi cluster.tfvars
  74 ```
  75
  76 * cluster_name = alpha
  77 * packet_project_id = ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
  78 * public_key_path = 12345678-90AB-CDEF-GHIJ-KLMNOPQRSTUV
  79
  80 ## Deploy Bare Metal Hosts
  81
  82 Initializing Terraform will pull down any necessary plugins/providers.
  83
  84 ```bash
  85 terraform init ../../contrib/terraform/packet/
  86 ```
  87
  88 Run Terraform to deploy the hardware.
  89
  90 ```bash
  91 terraform apply -var-file=cluster.tfvars ../../contrib/terraform/packet
  92 ```
  93
  94 ## Run Kubespray Playbooks
  95
  96 With the bare metal infrastructure deployed, Kubespray can now install Kubernetes and setup the cluster.
  97
  98 ```bash
  99 ansible-playbook --become -i inventory/alpha/hosts cluster.yml
 100 ```