From aad96171635a8f0bf7f7f6cecbfa0ec73fa35fa8 Mon Sep 17 00:00:00 2001 From: Julia Kreger Date: Mon, 7 Aug 2017 22:41:16 +0000 Subject: [PATCH] Centralize user documentation Change-Id: Icf1643f3d6c87a596e6a6b5cdb73dced42ea0797 --- doc/source/index.rst | 4 +- doc/source/troubleshooting.rst | 1 - doc/source/{deploy => user}/dhcp.rst | 0 doc/source/{ => user}/howto.rst | 4 +- doc/source/user/index.rst | 15 ++++++ doc/source/{deploy => user}/keystone.rst | 8 +-- .../source/user/troubleshooting.rst | 0 .../source/user/vagrant.rst | 32 ++++++++---- .../README.md => doc/source/user/virsh.rst | 52 ++++++++++--------- doc/source/vagrant.rst | 1 - 10 files changed, 72 insertions(+), 45 deletions(-) delete mode 100644 doc/source/troubleshooting.rst rename doc/source/{deploy => user}/dhcp.rst (100%) rename doc/source/{ => user}/howto.rst (99%) create mode 100644 doc/source/user/index.rst rename doc/source/{deploy => user}/keystone.rst (91%) rename troubleshooting.rst => doc/source/user/troubleshooting.rst (100%) rename README.vagrant.rst => doc/source/user/vagrant.rst (64%) rename tools/virsh_dev_env/README.md => doc/source/user/virsh.rst (52%) delete mode 100644 doc/source/vagrant.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index c80710490..77cd9687d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,7 +11,5 @@ Contents: :maxdepth: 1 install/index - howto + user/index contributing - troubleshooting - vagrant diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst deleted file mode 100644 index 666938c4a..000000000 --- a/doc/source/troubleshooting.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../troubleshooting.rst diff --git a/doc/source/deploy/dhcp.rst b/doc/source/user/dhcp.rst similarity index 100% rename from doc/source/deploy/dhcp.rst rename to doc/source/user/dhcp.rst diff --git a/doc/source/howto.rst b/doc/source/user/howto.rst similarity index 99% rename from doc/source/howto.rst rename to doc/source/user/howto.rst index 6d1f45910..233750dde 100644 --- a/doc/source/howto.rst +++ b/doc/source/user/howto.rst @@ -322,10 +322,10 @@ If you wish to include an extra element into the IPA disk image, such as a custom hardware manager, you can pass the variable ``ipa_extra_dib_elements`` as a space-separated list of elements. This defaults to an empty string. -.. include:: deploy/dhcp.rst +.. include:: dhcp.rst Use Bifrost with Keystone ========================= -.. include:: deploy/keystone.rst +.. include:: keystone.rst diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..69e969d20 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,15 @@ +################## +Bifrost User Guide +################## + +As bifrost is primarilly intended to be a tool for use by administrators, +this documentation serves as a blend of both Admin and User documentation. + +.. toctree:: + :maxdepth: 1 + + vagrant + virsh + howto + troubleshooting + diff --git a/doc/source/deploy/keystone.rst b/doc/source/user/keystone.rst similarity index 91% rename from doc/source/deploy/keystone.rst rename to doc/source/user/keystone.rst index ca457aa90..a56216920 100644 --- a/doc/source/deploy/keystone.rst +++ b/doc/source/user/keystone.rst @@ -11,10 +11,10 @@ Bifrost execution with Keystone =============================== Ultimately, as bifrost was designed for relatively short-lived -installations for rapid hardware deployment, the default operating -mode is referred to as ``noauth`` mode. With that, in order to -leverage keystone authentication for the roles, one of the -following steps need to take place. +installations to facilitate rapid hardware deployment, the default +operating mode is referred to as ``noauth`` mode. With that, +in order to leverage keystone authentication for the roles, +one of the following steps need to take place. #. Update the role defaults for each role you plan to make use. This may not make much sense for most users, unless they are diff --git a/troubleshooting.rst b/doc/source/user/troubleshooting.rst similarity index 100% rename from troubleshooting.rst rename to doc/source/user/troubleshooting.rst diff --git a/README.vagrant.rst b/doc/source/user/vagrant.rst similarity index 64% rename from README.vagrant.rst rename to doc/source/user/vagrant.rst index 773b5e005..d8a4f5bf7 100644 --- a/README.vagrant.rst +++ b/doc/source/user/vagrant.rst @@ -1,19 +1,34 @@ -============================== -Vagrant support for developers -============================== +.. _vagrant: -Bifrost vagrant file for developers can be found in the -``tools/vagrant_dev_env`` directory. Running ``vagrant up`` from -within this folder will bring up an Ubuntu Trusty box with Bifrost +Bifrost via Vagrant +=================== + +One of the main user audiences that we've found is for users to utilize +vagrant in order to build quick development environments, or for their +environments to facilitate deployments, as the intent is for relatively +short lived installations. + +As such, a virtual machine can be started with vagrant executing the +following commands:: + + cd tools/vagrant_dev_env + vagrant up + +This will bring up an Ubuntu based virtual machine, with bifrost installed. +.. note:: Virtual machine images, as well as all of the software + used in bifrost can take some time to install. Typically + expect ``vagrant up`` to take at least fifteen minutes if + you do not already have the virtual machine image on your + machine. + By default, the VM will have three interfaces: - **eth0** - connected to a NAT network - **eth1** - connected to Host-only network named: vboxnet1 - **eth2** - bridged - adapter must be set in Vagrantfile -------------------------- Walkthrough done on OS X ------------------------- Setup vagrant by: @@ -25,7 +40,7 @@ Setup vagrant by: Configure Vagrant with the correct box:: - vagrant box add ubuntu/trusty64 + vagrant box add ubuntu/xenial64 Clone bifrost repo:: @@ -47,7 +62,6 @@ Boot the VM with:: vagrant up --------------------- Installation Options -------------------- Ansible is installed within the VM directly from `source diff --git a/tools/virsh_dev_env/README.md b/doc/source/user/virsh.rst similarity index 52% rename from tools/virsh_dev_env/README.md rename to doc/source/user/virsh.rst index 7667d35a3..4ed31072b 100644 --- a/tools/virsh_dev_env/README.md +++ b/doc/source/user/virsh.rst @@ -1,10 +1,12 @@ Deploying with libvirt ====================== -In order to deploy bifrost with libvirt, but managing baremetal servers, a special -network config needs to be setup. +In order to deploy bifrost with libvirt, in order to support managing +baremetal servers from with-in that libvirt VM, a special network +configuration is required. Two networks need to be created: + - default network, that will be a standard virtual network, using NAT. - provisioning network, that will be used for PXE boot. As we need to setup a dhcp server on bifrost guest, creating a virtual network will give @@ -14,52 +16,52 @@ Two networks need to be created: Please note that you will need to have macvlan enabled on your kernel. When creating the guest, a minimum of 8GB of memory is needed in order to -build disk images properly. Also when defining the interfaces for the guest, the two -networks that have been created need to be attached. +build disk images along with run the services to support bifrost. -These sample commands will spin up a bifrost vm based on centos: +When defining the interfaces for the guest, the two networks that have been +created need to be attached. -virsh net-define --file network/default.xml -virsh net-start default -virsh net-define --file network/br_direct.xml -virsh net-start br_direct -virsh define --file vm/baremetal.xml -virsh start baremetal -virsh console baremetal +These sample commands will spin up a bifrost vm based on centos:: + + virsh net-define --file tools/virsh_dev_env/network/default.xml + virsh net-start default + virsh net-define --file tools/virsh_dev_env/network/br_direct.xml + virsh net-start br_direct + virsh define --file tools/virsh_dev_env/vm/baremetal.xml + virsh start baremetal + virsh console baremetal When you login into baremetal, the interface for the provisioning -network will be down. You may need to add an IP manually: +network will be down. You may need to add an IP manually:: -ip addr add <>/<> dev <> -ip link set <> up + ip addr add <>/<> dev <> + ip link set <> up Where to get guest images -========================= +------------------------- In order to create the guest VMs, you will need a cloud image for the distro you want to deploy. You will need to download the guest image on a directory on the host, and then in the template for the VM, you can specify it on the disk section, as shown in the example template. -Please follow the information on this link to get the images: - -http://docs.openstack.org/image-guide/obtain-images.html +Please see the `OpenStack Image Guide `_ +for options and locations for obtaining guest images. Add credentials to guest image -============================== +------------------------------ Normally guest images come without user and password, they rely on ssh to allow access. In this case, it can be useful to enable ssh access to some user from host to guest. A way to do that, is creating a config drive and reference it on the template for the guest VM. -A useful script to generate config drives can be found at: +A useful script to generate config drives can be found +`here `_. -https://github.com/larsks/virt-utils/blob/master/create-config-drive +Relying on this script, a config drive can be created with:: -Relying on this script, a config drive can be created with: - -create-config-drive -k ~/.ssh/id_rsa.pub config.iso + create-config-drive -k ~/.ssh/id_rsa.pub config.iso And then this ISO can be referenced on the guest VM template. diff --git a/doc/source/vagrant.rst b/doc/source/vagrant.rst deleted file mode 100644 index 3b3c48063..000000000 --- a/doc/source/vagrant.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.vagrant.rst