diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c271f1eec45..24ee0b39fc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ Due to their public nature, GitHub and mailing lists are not appropriate places ## Getting Started - Fork the repository on GitHub +- Install [build dependencies](docs/dev/dependencies.md). - Read the [README](README.md) for build and test instructions - Play with the project, submit bugs, submit patches! diff --git a/README.md b/README.md index 271287a4663..ec6b4334d2c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ## Quick Start +First, install all [build dependencies](docs/dev/dependencies.md). + After cloning this repository, the installer binary will need to be built by running the following: ```sh diff --git a/docs/dev/dependencies.md b/docs/dev/dependencies.md index 05be7a3f593..3e5e05c209f 100644 --- a/docs/dev/dependencies.md +++ b/docs/dev/dependencies.md @@ -1,5 +1,21 @@ # Managing Dependencies +## Build Dependencies + +The following dependencies must be installed on your system before you can build the installer. + +### Fedora + +```sh +sudo dnf install golang-bin gcc-c++ +``` + +### CentOS, RHEL + +```sh +sudo yum install golang-bin gcc-c++ +``` + ## Go We follow a hard flattening approach; i.e. direct and inherited dependencies are installed in the base `vendor/`. diff --git a/docs/dev/libvirt-howto.md b/docs/dev/libvirt-howto.md index 18eb83e7016..d92dadb2d9b 100644 --- a/docs/dev/libvirt-howto.md +++ b/docs/dev/libvirt-howto.md @@ -6,16 +6,38 @@ for operator development. ## 1. One-time setup It's expected that you will create and destroy clusters often in the course of development. These steps only need to be run once (or once per RHCOS update). -### 1.1 Pick a name and ip range +Before you begin, install the [build dependencies](dependencies.md). + +### 1.1 Install and Enable Libvirt +On Fedora: + +```sh +sudo dnf install libvirt-daemon +``` + +or on CentOS / RHEL: + +```sh +sudo yum install libvirt-daemon +``` + +Then start libvirtd: + +```sh +sudo systemctl start libvirtd +sudo systemctl enable libvirtd +``` + +### 1.2 Pick a name and ip range In this example, we'll set the baseDomain to `tt.testing`, the name to `test1` and the ipRange to `192.168.124.0/24` -### 1.2 Clone the repo +### 1.3 Clone the repo ```sh git clone https://github.com/openshift/installer.git cd installer ``` -### 1.3 (Optional) Download and prepare the operating system image +### 1.4 (Optional) Download and prepare the operating system image *By default, the installer will download the latest RHCOS image every time it is invoked. This may be problematic for users who create a large number of clusters or who have limited network bandwidth. The installer allows a local image to be used instead.* @@ -25,10 +47,10 @@ Download the latest RHCOS image (you will need access to the Red Hat internal bu curl http://aos-ostree.rhev-ci-vms.eng.rdu2.redhat.com/rhcos/images/cloud/latest/rhcos-qemu.qcow2.gz | gunzip > rhcos-qemu.qcow2 ``` -### 1.4 Get a pull secret +### 1.5 Get a pull secret Go to https://account.coreos.com/ and obtain a Tectonic *pull secret*. -### 1.5 Make sure you have permissions for `qemu:///system` +### 1.6 Make sure you have permissions for `qemu:///system` You may want to grant yourself permissions to use libvirt as a non-root user. You could allow all users in the wheel group by doing the following: ```sh cat <> /etc/polkit-1/rules.d/80-libvirt.rules @@ -40,7 +62,7 @@ polkit.addRule(function(action, subject) { EOF ``` -### 1.6 Configure libvirt to accept TCP connections +### 1.7 Configure libvirt to accept TCP connections The Kubernetes [cluster-api](https://github.com/kubernetes-sigs/cluster-api) components drive deployment of worker machines. The libvirt cluster-api @@ -118,9 +140,29 @@ sudo firewall-cmd --zone=FedoraWorkstation --list-sources NOTE: When the firewall rules are no longer needed, `sudo firewalld-cmd --reload` will remove the changes made as they were not permanently added. For persistence, -include the `--permanent` to the commands that add-source and add-port. +add `--permanent` to the `firewall-cmd` commands and run them a second time. + +### 1.8 Configure default libvirt storage pool + +Check to see if a default storage pool has been defined in Libvirt by running +`virsh --connect qemu:///system pool-list`. If it does not exist, create it: + +```sh +sudo virsh pool-define /dev/stdin < + default + + /var/lib/libvirt/images + + +EOF + +sudo virsh pool-start default +sudo virsh pool-autostart default +``` + -### 1.7 Prepare the installer configuration file +### 1.9 Prepare the installer configuration file 1. `cp examples/libvirt.yaml ./` 2. Edit the configuration file: 1. Set an email and password in the `admin` section @@ -132,9 +174,9 @@ include the `--permanent` to the commands that add-source and add-port. 7. Ensure the `libvirt.uri` IP address matches your virbr0 interface IP address which belongs to the libvirt *default* network. If you're uncertain about the libvirt *default* subnet you should be able to see its address using the command `ip -4 a show dev virbr0` or by inspecting `virsh --connect qemu:///system net-dumpxml default`. 8. Ensure the `libvirt.network.ipRange` does not overlap your virbr0 IP address - 9. (Optional) Change the `image` to the file URL of the operating system image you downloaded (e.g. `file:///home/user/Downloads/rhcos.qcow`). This will allow the installer to re-use that image instead of having to download it every time. + 9. (Optional) Change the `image` to the file URL of the operating system image you downloaded (e.g. `file:///home/user/Downloads/rhcos-qemu.qcow2`). This will allow the installer to re-use that image instead of having to download it every time. -### 1.8 Set up NetworkManager DNS overlay +### 1.10 Set up NetworkManager DNS overlay This step is optional, but useful for being able to resolve cluster-internal hostnames from your host. 1. Edit `/etc/NetworkManager/NetworkManager.conf` and set `dns=dnsmasq` in section `[main]` 2. Tell dnsmasq to use your cluster. The syntax is `server=//`. @@ -146,14 +188,14 @@ This step is optional, but useful for being able to resolve cluster-internal hos ``` 3. `systemctl restart NetworkManager` -### 1.9 Install the terraform provider +### 1.11 Install the terraform provider 1. Make sure you have the `virsh` binary installed: `sudo dnf install libvirt-client libvirt-devel` 2. Install the libvirt terraform provider: ```sh GOBIN=~/.terraform.d/plugins go get -u github.com/dmacvicar/terraform-provider-libvirt ``` -### 1.10 Cache terrafrom plugins (optional, but makes subsequent runs a bit faster) +### 1.12 Cache terrafrom plugins (optional, but makes subsequent runs a bit faster) ```sh cat < $HOME/.terraformrc plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" @@ -175,7 +217,7 @@ alias tectonic="${PWD}/tectonic-dev/installer/tectonic" Initialize (the environment variables are a convenience): ```sh -tectonic init --config=../libvirt.yaml +tectonic init --config=libvirt.yaml export CLUSTER_NAME= export BASE_DOMAIN= ```