Centralize user documentation

Change-Id: Icf1643f3d6c87a596e6a6b5cdb73dced42ea0797
This commit is contained in:
Julia Kreger 2017-08-07 22:41:16 +00:00 committed by Dmitry Tantsur
parent bc0a12dfff
commit aad9617163
10 changed files with 72 additions and 45 deletions

View File

@ -11,7 +11,5 @@ Contents:
:maxdepth: 1
install/index
howto
user/index
contributing
troubleshooting
vagrant

View File

@ -1 +0,0 @@
.. include:: ../../troubleshooting.rst

View File

@ -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

15
doc/source/user/index.rst Normal file
View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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 <<provisioning_ip_address>>/<<mask>> dev <<interface>>
ip link set <<interface>> up
ip addr add <<provisioning_ip_address>>/<<mask>> dev <<interface>>
ip link set <<interface>> 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 <http://docs.openstack.org/image-guide/obtain-images.html>`_
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>`_.
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.

View File

@ -1 +0,0 @@
.. include:: ../../README.vagrant.rst