diff --git a/README.rst b/README.rst index c8555f751..c49e80608 100644 --- a/README.rst +++ b/README.rst @@ -7,6 +7,7 @@ Team and repository tags .. Change things from this point on +======= Bifrost ======= @@ -24,8 +25,8 @@ Use Cases a batch operation. * Testing and development of ironic in a standalone use case. -Use -=== +How to Use +========== Installation and use of bifrost is split into roughly three steps: @@ -47,6 +48,10 @@ Supported operating systems: * Fedora 22 * openSUSE Leap 42.1, 42.2 +============ +Installation +============ + Pre-install steps ================= @@ -94,8 +99,8 @@ To enable EPEL on CentOS, run:: sudo yum install epel-release -Installation -============ +Bifrost Installation +==================== The installation is split into two parts. @@ -215,322 +220,7 @@ If you would like to install the ironic staging drivers, simply pass ansible-playbook -K -vvvv -i inventory/target install.yaml -e staging_drivers_include=true -Manual CLI use --------------- - -If you wish to utilize ironic's CLI in no-auth mode, you must set two -environment variables: - -- ``IRONIC_URL`` - A URL to the ironic API, such as http://localhost:6385/ -- ``OS_AUTH_TOKEN`` - Any value except empty space, such as 'fake-token', - is required to cause the client library to send requests directly to the API. - -For your ease of use, ``env-vars`` can be sourced to allow the CLI to connect -to a local ironic installation operating in noauth mode. Run e.g.:: - - source env-vars - ironic node-list - +------+------+---------------+-------------+--------------------+-------------+ - | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | - +------+------+---------------+-------------+--------------------+-------------+ - +------+------+---------------+-------------+--------------------+-------------+ - -which should print an empty table if connection to Ironic works as expected. - -Hardware enrollment -=================== - -The following requirements are installed during the `Installation`_ step -above: - -- openstack-infra/shade library -- openstack-infra/os-client-config - -In order to enroll hardware, you will naturally need an inventory of -your hardware. When utilizing the dynamic inventory module and -accompanying roles the inventory can be supplied in one of three ways, -all of which ultimately translate to JSON data that Ansible parses. - -The original method is to utilize a CSV file. This format is covered below in -the `Legacy CSV File Format`_ section. This has a number of limitations, but -does allow a user to bulk load hardware from an inventory list with minimal -data transformations. - -The newer method is to utilize a JSON or YAML document which the inventory -parser will convert and provide to Ansible. - -In order to use, you will need to define the environment variable -``BIFROST_INVENTORY_SOURCE`` to equal a file, which then allows you to -execute Ansible utilizing the ``bifrost_inventory.py`` file as the data -source. - -Conversion from CSV to JSON formats ------------------------------------ - -The ``inventory/bifrost_inventory.py`` program additionally features a -mode that allows a user to convert a CSV file to the JSON data format -utilizing a ``--convertcsv`` command line setting when directly invoked. - -Example:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.csv - inventory/bifrost_inventory.py --convertcsv >/tmp/baremetal.json - -JSON file format ----------------- - -The JSON format closely resembles the data structure that ironic -utilizes internally. The ``name``, ``driver_info``, ``nics``, -``driver``, and ``properties`` fields are directly mapped through to -ironic. This means that the data contained within can vary from host -to host, such as drivers and their parameters thus allowing a mixed -hardware environment to be defined in a single file. - -Example:: - - { - "testvm1": { - "uuid": "00000000-0000-0000-0000-000000000001", - "driver_info": { - "power": { - "ssh_port": 22, - "ssh_username": "ironic", - "ssh_virt_type": "virsh", - "ssh_address": "192.168.122.1", - "ssh_key_filename": "/home/ironic/.ssh/id_rsa" - } - }, - "nics": [ - { - "mac": "52:54:00:f9:32:f6" - } - ], - "driver": "agent_ssh", - "ansible_ssh_host": "192.168.122.2", - "ipv4_address": "192.168.122.2", - "provisioning_ipv4_address": "10.0.0.9", - "properties": { - "cpu_arch": "x86_64", - "ram": "3072", - "disk_size": "10", - "cpus": "1" - }, - "name": "testvm1" - } - } - -The additional power of this format is easy configuration parameter injection, -which could potentially allow a user to provision different operating system -images onto different hardware chassis by defining the appropriate settings -in an ``instance_info`` variable. - -Examples utilizing JSON and YAML formatting, along host specific variable -injection can be found in the ``playbooks/inventory/`` folder. - -Legacy CSV file format ----------------------- - -The CSV file has the following columns: - -0. MAC Address -1. Management username -2. Management password -3. Management Address -4. CPU Count -5. Memory size in MB -6. Disk Storage in GB -7. Flavor (Not Used) -8. Type (Not Used) -9. Host UUID -10. Host or Node name -11. Host IP Address to be set -12. ``ipmi_target_channel`` - Requires: ``ipmi_bridging`` set to single -13. ``ipmi_target_address`` - Requires: ``ipmi_bridging`` set to single -14. ``ipmi_transit_channel`` - Requires: ``ipmi_bridging`` set to dual -15. ``ipmi_transit_address`` - Requires: ``ipmi_bridging`` set to dual -16. ironic driver -17. Host provisioning IP Address - -Example definition:: - - 00:11:22:33:44:55,root,undefined,192.168.122.1,1,8192,512,NA,NA,aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,hostname_100,192.168.2.100,,,,agent_ipmitool,10.0.0.9 - -This file format is fairly flexible and can be easily modified -although the enrollment and deployment playbooks utilize the model -of a host per line model in order to process through the entire -list, as well as reference the specific field items. - -An example file can be found at: ``playbooks/inventory/baremetal.csv.example`` - -How this works? ---------------- - -Utilizing the dynamic inventory module, enrollment is as simple as setting -the ``BIFROST_INVENTORY_SOURCE`` environment variable to your inventory data -source, and then executing the enrollment playbook.:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - ansible-playbook -vvvv -i inventory/bifrost_inventory.py enroll-dynamic.yaml - -When ironic is installed on remote server, a regular ansible inventory -with a target server should be added to ansible. This can be achieved by -specifying a directory with files, each file in that directory will be part of -the ansible inventory. Refer to ansible documentation -http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources - -:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ enroll-dynamic.yaml - -Note that enrollment is a one-time operation. The Ansible module *does not* -synchronize data for existing nodes. You should use the ironic CLI to do this -manually at the moment. - -Additionally, it is important to note that the playbooks for enrollment are -split into three separate playbooks based on the ``ipmi_bridging`` setting. - -Hardware deployment -=================== - -How this works? ---------------- - -After the nodes are enrolled, they can be deployed upon. Bifrost is geared to -utilize configuration drives to convey basic configuration information to the -each host. This configuration information includes an SSH key to allow a user -to login to the system. - -To utilize the newer dynamic inventory based deployment:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - ansible-playbook -vvvv -i inventory/bifrost_inventory.py deploy-dynamic.yaml - -When ironic is installed on remote server, a regular ansible inventory -with a target server should be added to ansible. This can be achieved by -specifying a directory with files, each file in that directory will be part of -the ansible inventory. Refer to ansible documentation -http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources - -:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ deploy-dynamic.yaml - -Note:: - - Before running the above command, ensure that the value for `ssh_public_key_path` in - ``./playbooks/inventory/group_vars/baremetal`` refers to a valid public key file, - or set the ssh_public_key_path option on the ansible-playbook command line by - setting the variable. Example: "-e ssh_public_key_path=~/.ssh/id_rsa.pub" - -If the hosts need to be re-deployed, the dynamic redeploy playbook may be used:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - ansible-playbook -vvvv -i inventory/bifrost_inventory.py redeploy-dynamic.yaml - -This playbook will undeploy the hosts, followed by a deployment, allowing -a configurable timeout for the hosts to transition in each step. - -Testing with a single command -============================= - -A simple ``scripts/test-bifrost.sh`` script can be utilized to install -pre-requisite software packages, Ansible, and then execute the -``test-bifrost-create-vm.yaml`` and ``test-bifrost.yaml`` playbooks in order -to provide a single step testing mechanism. - -``playbooks/test-bifrost-create-vm.yaml`` creates one or more VMs for -testing and saves out a baremetal.csv file which is used by -``playbooks/test-bifrost.yaml`` to execute the remaining roles. Two -additional roles are invoked by this playbook which enables Ansible to -connect to the new nodes by adding them to the inventory, and then -logging into the remote machine via the user's ssh host key. Once -that has successfully occurred, additional roles will unprovision the -host(s) and delete them from ironic. - -Command:: - - scripts/test-bifrost.sh - -Note: - -- Cleaning mode is explicitly disabled in the ``test-bifrost.yaml`` - playbook due to the fact that is an IO-intensive operation that can - take a great deal of time. - -Legacy - testing with virtual machines -====================================== - -Bifrost supports using virtual machines to emulate the hardware. All of the -steps mentioned above are mostly the same. - -It is assumed you have an SSH server running on the host machine. The -``agent_ssh`` driver, used by ironic with VM testing, will need to use -SSH to control the virtual machines. - -An SSH key is generated for the ``ironic`` user when testing. The -ironic conductor will use this key to connect to the host machine and -run virsh commands. - -#. Set ``testing`` to *true* in the - ``playbooks/inventory/group_vars/target`` file. -#. You may need to adjust the value for ``ssh_public_key_path``. -#. Run the install step, as documented above, however adding ``-e - testing=true`` to the Ansible command line. -#. Execute the ``ansible-playbook -vvvv -i inventory/target - test-bifrost-create-vm.yaml`` command to create a test virtual - machine. -#. Set the environment variable of ``BIFROST_INVENTORY_SOURCE`` to the - path to the csv file, which by default has been written to - /tmp/baremetal.csv. -#. Run the enrollment step, as documented above, using the CSV file - you created in the previous step. -#. Run the deployment step, as documented above. - -Deployment and configuration of operating systems -================================================= - -By default, Bifrost deploys a configuration drive which includes the user SSH -public key, hostname, and the network configuration in the form of -network_data.json that can be read/parsed by the -`glean `_ utility. This allows for -the deployment of Ubuntu, CentOS, or Fedora "tenants" on baremetal. This file -format is not yet supported by Cloud-Init, however it is on track for -inclusion in cloud-init 2.0. - -By default, Bifrost utilizes a utility called simple-init which leverages -the previously noted glean utility to apply network configuration. This -means that by default, root file systems may not be automatically expanded -to consume the entire disk, which may, or may not be desirable depending -upon operational needs. This is dependent upon what base OS image you -utilize, and if the support is included in that image or not. At present, -the standard Ubuntu cloud image includes cloud-init which will grow the -root partition, however the ubuntu-minimal image does not include cloud-init -and thus will not automatically grow the root partition. - -Due to the nature of the design, it would be relatively easy for a user to -import automatic growth or reconfiguration steps either in the image to be -deployed, or in post-deployment steps via custom Ansible playbooks. - -Custom IPA images -================= - -Bifrost supports the ability for a user to build a custom IPA ramdisk -utilizing the diskimage-builder element "ironic-agent". In order to utilize -this feature, the ``download_ipa`` setting must be set to ``false`` and the -create_ipa_image must be set to "true". By default, the install playbook will -build a Debian jessie based IPA image, if a pre-existing IPA image is not -present on disk. If you wish to explicitly set a specific release to be -passed to diskimage-create, then the setting ``dib_os_release`` can be set in -addition to ``dib_os_element``. - -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. - +============== Driver Support ============== @@ -564,21 +254,3 @@ for mass node deployment. The OneView documentation can be found `here `_. - -Virtualenv installation support (EXPERIMENTAL) -============================================== - -Bifrost can be used with a python virtual environment. At present, -this feature is experimental, so it's disabled by default. If you -would like to use a virtual environment, you'll need to modify the -install steps slightly. To set up the virtual environment and install -ansible into it, run ``env-setup.sh`` as follows:: - - export VENV=/opt/stack/bifrost - ./scripts/env-setup.sh - -Then run the install playbook with the following arguments:: - - ansible-playbook -vvvv -i inventory/target install.yaml - -This will install ironic and its dependencies into the virtual environment. diff --git a/doc/source/deploy/dhcp.rst b/doc/source/deploy/dhcp.rst index d8bfd5519..b597cc8f4 100644 --- a/doc/source/deploy/dhcp.rst +++ b/doc/source/deploy/dhcp.rst @@ -1,7 +1,3 @@ -======================================= -Using Bifrost with your own DHCP server -======================================= - The possibility exists that a user may already have a Dynamic Host Configuration Protocol (DHCP) server on their network. @@ -58,18 +54,16 @@ in a trusted environment. |Ironic Server| | Server | +-------------+ +-----------+ -=============================================================== Setting static DHCP assignments with the integrated DHCP server -=============================================================== +--------------------------------------------------------------- You can set up a static DHCP reservation using the ``ipv4_address`` parameter and setting the ``inventory_dhcp`` setting to a value of ``true``. This will result in the first MAC address defined in the list of hardware MAC addresses to receive a static address assignment in dnsmasq. -====================================== Forcing DNS to resolve to ipv4_address -====================================== +-------------------------------------- dnsmasq will resolve all entries to the IP assigned to each server in the leases file. However, this IP will not always be the desired one, if you diff --git a/doc/source/deploy/keystone.rst b/doc/source/deploy/keystone.rst index 802bbe856..595ad5533 100644 --- a/doc/source/deploy/keystone.rst +++ b/doc/source/deploy/keystone.rst @@ -1,9 +1,5 @@ .. _keystone: -********************* -Bifrost with Keystone -********************* - .. NOTE:: Use of keystone with bifrost is a very new feature and should be considered an advanced topic. Please feel free to reach out to the bifrost contributors and the ironic community as a whole in the project's @@ -11,9 +7,8 @@ Bifrost with Keystone .. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC -########################## Installation with Keystone -########################## +-------------------------- Bifrost can now install and make use of keystone. In order to enable this as part of the installation, the ``enable_keystone`` variable @@ -49,8 +44,8 @@ the installation. That file can be located at ``~/.config/openstack/clouds.yaml``. The cloud that is written to that file is named ``bifrost``. -Use of bifrost with Keystone -============================ +Bifrost execution with Keystone +=============================== Ultimately, as bifrost was designed for relatively short-lived installations for rapid hardware deployment, the default operating @@ -69,9 +64,8 @@ following steps need to take place. #. Set the global defaults for tagret (``master/playbooks/inventory/group_vars/target``). - -OpenStack Client ----------------- +OpenStack Client use with bifrost installed Keystone +---------------------------------------------------- A user wishing to invoke OSC commands against the bifrost installation, should set the ``OS_CLOUD`` environment variable. @@ -94,9 +88,8 @@ guide`_. .. _`install guide`: http://docs.openstack.org/project-install-guide/baremetal/draft/configure-integration.html#configure-the-identity-service-for-the-bare-metal-service -############################## -Use of playbooks with Keystone -############################## +Individual playbook use with os-client-config +============================================= The OpenStack Ansible modules utilize os-client-config to obtain authentication details to connect to determine details. diff --git a/doc/source/howto.rst b/doc/source/howto.rst new file mode 100644 index 000000000..93df0ff53 --- /dev/null +++ b/doc/source/howto.rst @@ -0,0 +1,348 @@ +====== +How-To +====== + +Use the Ironic CLI +================== + +If you wish to utilize ironic's CLI in no-auth mode, you must set two +environment variables: + +- ``IRONIC_URL`` - A URL to the ironic API, such as http://localhost:6385/ +- ``OS_AUTH_TOKEN`` - Any value except empty space, such as 'fake-token', + is required to cause the client library to send requests directly to the API. + +For your ease of use, ``env-vars`` can be sourced to allow the CLI to connect +to a local ironic installation operating in noauth mode. Run e.g.:: + + source env-vars + ironic node-list + +------+------+---------------+-------------+--------------------+-------------+ + | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | + +------+------+---------------+-------------+--------------------+-------------+ + +------+------+---------------+-------------+--------------------+-------------+ + +which should print an empty table if connection to Ironic works as expected. + +Enroll Hardware +=============== + +The following requirements are installed during the `Installation`_ step +above: + +- openstack-infra/shade library +- openstack-infra/os-client-config + +In order to enroll hardware, you will naturally need an inventory of +your hardware. When utilizing the dynamic inventory module and +accompanying roles the inventory can be supplied in one of three ways, +all of which ultimately translate to JSON data that Ansible parses. + +The original method is to utilize a CSV file. This format is covered below in +the `Legacy CSV File Format`_ section. This has a number of limitations, but +does allow a user to bulk load hardware from an inventory list with minimal +data transformations. + +The newer method is to utilize a JSON or YAML document which the inventory +parser will convert and provide to Ansible. + +In order to use, you will need to define the environment variable +``BIFROST_INVENTORY_SOURCE`` to equal a file, which then allows you to +execute Ansible utilizing the ``bifrost_inventory.py`` file as the data +source. + +Conversion from CSV to JSON formats +----------------------------------- + +The ``inventory/bifrost_inventory.py`` program additionally features a +mode that allows a user to convert a CSV file to the JSON data format +utilizing a ``--convertcsv`` command line setting when directly invoked. + +Example:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.csv + inventory/bifrost_inventory.py --convertcsv >/tmp/baremetal.json + +JSON file format +---------------- + +The JSON format closely resembles the data structure that ironic +utilizes internally. The ``name``, ``driver_info``, ``nics``, +``driver``, and ``properties`` fields are directly mapped through to +ironic. This means that the data contained within can vary from host +to host, such as drivers and their parameters thus allowing a mixed +hardware environment to be defined in a single file. + +Example:: + + { + "testvm1": { + "uuid": "00000000-0000-0000-0000-000000000001", + "driver_info": { + "power": { + "ssh_port": 22, + "ssh_username": "ironic", + "ssh_virt_type": "virsh", + "ssh_address": "192.168.122.1", + "ssh_key_filename": "/home/ironic/.ssh/id_rsa" + } + }, + "nics": [ + { + "mac": "52:54:00:f9:32:f6" + } + ], + "driver": "agent_ssh", + "ansible_ssh_host": "192.168.122.2", + "ipv4_address": "192.168.122.2", + "provisioning_ipv4_address": "10.0.0.9", + "properties": { + "cpu_arch": "x86_64", + "ram": "3072", + "disk_size": "10", + "cpus": "1" + }, + "name": "testvm1" + } + } + +The additional power of this format is easy configuration parameter injection, +which could potentially allow a user to provision different operating system +images onto different hardware chassis by defining the appropriate settings +in an ``instance_info`` variable. + +Examples utilizing JSON and YAML formatting, along host specific variable +injection can be found in the ``playbooks/inventory/`` folder. + +Legacy CSV file format +---------------------- + +The CSV file has the following columns: + +0. MAC Address +1. Management username +2. Management password +3. Management Address +4. CPU Count +5. Memory size in MB +6. Disk Storage in GB +7. Flavor (Not Used) +8. Type (Not Used) +9. Host UUID +10. Host or Node name +11. Host IP Address to be set +12. ``ipmi_target_channel`` - Requires: ``ipmi_bridging`` set to single +13. ``ipmi_target_address`` - Requires: ``ipmi_bridging`` set to single +14. ``ipmi_transit_channel`` - Requires: ``ipmi_bridging`` set to dual +15. ``ipmi_transit_address`` - Requires: ``ipmi_bridging`` set to dual +16. ironic driver +17. Host provisioning IP Address + +Example definition:: + + 00:11:22:33:44:55,root,undefined,192.168.122.1,1,8192,512,NA,NA,aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,hostname_100,192.168.2.100,,,,agent_ipmitool,10.0.0.9 + +This file format is fairly flexible and can be easily modified +although the enrollment and deployment playbooks utilize the model +of a host per line model in order to process through the entire +list, as well as reference the specific field items. + +An example file can be found at: ``playbooks/inventory/baremetal.csv.example`` + +How this works? +--------------- + +Utilizing the dynamic inventory module, enrollment is as simple as setting +the ``BIFROST_INVENTORY_SOURCE`` environment variable to your inventory data +source, and then executing the enrollment playbook.:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + ansible-playbook -vvvv -i inventory/bifrost_inventory.py enroll-dynamic.yaml + +When ironic is installed on remote server, a regular ansible inventory +with a target server should be added to ansible. This can be achieved by +specifying a directory with files, each file in that directory will be part of +the ansible inventory. Refer to ansible documentation +http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources + +:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + rm inventory/*.example + ansible-playbook -vvvv -i inventory/ enroll-dynamic.yaml + +Note that enrollment is a one-time operation. The Ansible module *does not* +synchronize data for existing nodes. You should use the ironic CLI to do this +manually at the moment. + +Additionally, it is important to note that the playbooks for enrollment are +split into three separate playbooks based on the ``ipmi_bridging`` setting. + +Deploy Hardware +=============== + +How this works? +--------------- + +After the nodes are enrolled, they can be deployed upon. Bifrost is geared to +utilize configuration drives to convey basic configuration information to the +each host. This configuration information includes an SSH key to allow a user +to login to the system. + +To utilize the newer dynamic inventory based deployment:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + ansible-playbook -vvvv -i inventory/bifrost_inventory.py deploy-dynamic.yaml + +When ironic is installed on remote server, a regular ansible inventory +with a target server should be added to ansible. This can be achieved by +specifying a directory with files, each file in that directory will be part of +the ansible inventory. Refer to ansible documentation +http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources + +:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + rm inventory/*.example + ansible-playbook -vvvv -i inventory/ deploy-dynamic.yaml + +Note:: + + Before running the above command, ensure that the value for `ssh_public_key_path` in + ``./playbooks/inventory/group_vars/baremetal`` refers to a valid public key file, + or set the ssh_public_key_path option on the ansible-playbook command line by + setting the variable. Example: "-e ssh_public_key_path=~/.ssh/id_rsa.pub" + +If the hosts need to be re-deployed, the dynamic redeploy playbook may be used:: + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + ansible-playbook -vvvv -i inventory/bifrost_inventory.py redeploy-dynamic.yaml + +This playbook will undeploy the hosts, followed by a deployment, allowing +a configurable timeout for the hosts to transition in each step. + +Execute local testing +===================== + +A simple ``scripts/test-bifrost.sh`` script can be utilized to install +pre-requisite software packages, Ansible, and then execute the +``test-bifrost-create-vm.yaml`` and ``test-bifrost.yaml`` playbooks in order +to provide a single step testing mechanism. + +``playbooks/test-bifrost-create-vm.yaml`` creates one or more VMs for +testing and saves out a baremetal.csv file which is used by +``playbooks/test-bifrost.yaml`` to execute the remaining roles. Two +additional roles are invoked by this playbook which enables Ansible to +connect to the new nodes by adding them to the inventory, and then +logging into the remote machine via the user's ssh host key. Once +that has successfully occurred, additional roles will unprovision the +host(s) and delete them from ironic. + +Command:: + + scripts/test-bifrost.sh + +Note: + +- Cleaning mode is explicitly disabled in the ``test-bifrost.yaml`` + playbook due to the fact that is an IO-intensive operation that can + take a great deal of time. + +Manually test with Virtual Machines +=================================== + +Bifrost supports using virtual machines to emulate the hardware. + +It is assumed you have an SSH server running on the host machine. The +``agent_ssh`` driver, used by ironic with VM testing, will need to use +SSH to control the virtual machines. + +An SSH key is generated for the ``ironic`` user when testing. The +ironic conductor will use this key to connect to the host machine and +run virsh commands. + +#. Set ``testing`` to *true* in the + ``playbooks/inventory/group_vars/target`` file. +#. You may need to adjust the value for ``ssh_public_key_path``. +#. Run the install step, as documented above, however adding ``-e + testing=true`` to the Ansible command line. +#. Execute the ``ansible-playbook -vvvv -i inventory/target + test-bifrost-create-vm.yaml`` command to create a test virtual + machine. +#. Set the environment variable of ``BIFROST_INVENTORY_SOURCE`` to the + path to the csv file, which by default has been written to + /tmp/baremetal.csv. +#. Run the enrollment step, as documented above, using the CSV file + you created in the previous step. +#. Run the deployment step, as documented above. + +Deployment and configuration of operating systems +================================================= + +By default, Bifrost deploys a configuration drive which includes the user SSH +public key, hostname, and the network configuration in the form of +network_data.json that can be read/parsed by the +`glean `_ utility. This allows for +the deployment of Ubuntu, CentOS, or Fedora "tenants" on baremetal. This file +format is not yet supported by Cloud-Init, however it is on track for +inclusion in cloud-init 2.0. + +By default, Bifrost utilizes a utility called simple-init which leverages +the previously noted glean utility to apply network configuration. This +means that by default, root file systems may not be automatically expanded +to consume the entire disk, which may, or may not be desirable depending +upon operational needs. This is dependent upon what base OS image you +utilize, and if the support is included in that image or not. At present, +the standard Ubuntu cloud image includes cloud-init which will grow the +root partition, however the ubuntu-minimal image does not include cloud-init +and thus will not automatically grow the root partition. + +Due to the nature of the design, it would be relatively easy for a user to +import automatic growth or reconfiguration steps either in the image to be +deployed, or in post-deployment steps via custom Ansible playbooks. + +Build Custom Ironic Python Agent (IPA) images +============================================= + +Bifrost supports the ability for a user to build a custom IPA ramdisk +utilizing the diskimage-builder element "ironic-agent". In order to utilize +this feature, the ``download_ipa`` setting must be set to ``false`` and the +create_ipa_image must be set to "true". By default, the install playbook will +build a Debian jessie based IPA image, if a pre-existing IPA image is not +present on disk. If you wish to explicitly set a specific release to be +passed to diskimage-create, then the setting ``dib_os_release`` can be set in +addition to ``dib_os_element``. + +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. + +Use Bifrost with your own DHCP server +===================================== +.. include:: deploy/dhcp.rst + +Use Bifrost with Keystone +========================= +.. include:: deploy/keystone.rst + +Virtualenv installation support (EXPERIMENTAL) +============================================== + +Bifrost can be used with a python virtual environment. At present, +this feature is experimental, so it's disabled by default. If you +would like to use a virtual environment, you'll need to modify the +install steps slightly. To set up the virtual environment and install +ansible into it, run ``env-setup.sh`` as follows:: + + export VENV=/opt/stack/bifrost + ./scripts/env-setup.sh + +Then run the install playbook with the following arguments:: + + ansible-playbook -vvvv -i inventory/target install.yaml + +This will install ironic and its dependencies into the virtual environment. + +Offline Installation +==================== +.. include:: offline-install.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index e1deb0e58..c6cc3fdbb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,12 +7,10 @@ Contents: :maxdepth: 2 readme + howto contributing troubleshooting vagrant - deploy/dhcp - deploy/keystone - offline-install Indices and tables ================== diff --git a/doc/source/offline-install.rst b/doc/source/offline-install.rst index 8488a7777..78d61e5a6 100644 --- a/doc/source/offline-install.rst +++ b/doc/source/offline-install.rst @@ -1,7 +1,3 @@ -======================= -Bifrost Offline Install -======================= - The ansible scripts that compose Bifrost download and install software via a number of means, which generally assumes connectivity to the internet.