Bug 1310270 - Director Install Guide catch-all BZ
Director Install Guide catch-all BZ
Status: ASSIGNED
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation (Show other bugs)
7.0 (Kilo)
All Linux
high Severity medium
: ga
: 9.0 (Mitaka)
Assigned To: Dan Macpherson
RHOS Documentation Team
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2016-02-19 18:37 EST by Dan Yocum
Modified: 2017-11-11 22:05 EST (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed:
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Dan Yocum 2016-02-19 18:37:43 EST
Description of problem:

This BZ should be used for current Director Install Guide documentation issues.

Version-Release number of selected component (if applicable):

7.3


Sections 3.1 -> 3.5 should be a script included in the appendix (and noted as such), but specifically 3.4 should include a script like this (to be run as root): 

$ sudo for repo in rhel-7-server-openstack-7.0-rpms rhel-7-server-rpms rhel-7-server-optional-rpms rhel-7-server-extras-rpms rhel-7-server-openstack-7.0-director-rpms; do sudo yum-config-manager --enable $repo --setopt="${repo}.priority=1"; done

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux_OpenStack_Platform/7/html-single/Director_Installation_and_Usage/index.html#sect-Registering_your_System

The script bit in Section 3.4 should fixed thusly (because a normal user can't 'reboot'):

$ sudo yum update -y
$ sudo reboot


Section 3.7

The code block shows:
[stack@host1 ~]$ ls /httpboot -l
total 151636
-rw-r--r--. 1 ironic ironic       269 Sep 19 02:43 boot.ipxe
-rw-r--r--. 1 root   root         252 Sep 10 15:35 discoverd.ipxe
-rwxr-xr-x. 1 root   root     5027584 Sep 10 16:32 discovery.kernel
-rw-r--r--. 1 root   root   150230861 Sep 10 16:32 discovery.ramdisk
drwxr-xr-x. 2 ironic ironic      4096 Sep 19 02:45 pxelinux.cfg

On a fresh install, this is what I see (and put the -l before the dir, please):

$ ls -l /httpboot
total 155544
-rw-r--r--. 1 ironic ironic       237 Feb 19 15:25 discoverd.ipxe
-rwxr-xr-x. 1 root   root     5153184 Feb 19 18:11 discovery.kernel
-rw-r--r--. 1 root   root   154114052 Feb 19 18:11 discovery.ramdisk
Comment 2 Dan Yocum 2016-02-20 08:24:27 EST
In section 6.3.3.2. ahc-match, the following text should be set to a bold heading type - it's hard to determine that it is a heading:

⁠Ready-State Files (Dell DRAC only)
Comment 3 Dan Yocum 2016-02-20 08:32:42 EST
The following needs to be summarized and added, probably as an appendix, but referred to in 6.3.5. Configuring Ceph Storage:

http://docs.openstack.org/developer/ironic/deploy/install-guide.html#specifying-the-disk-for-deployment

Dell doesn't necessarily put the install drives as the first devices in the RAID.
Comment 4 Dan Yocum 2016-02-20 08:46:56 EST
6.3.5. Configuring Ceph Storage

Why is this not part of the storage-environment.yaml file by default:

parameter_defaults:
  ExtraConfig:
    ceph::profile::params::osds:
Comment 5 Dan Yocum 2016-02-21 08:48:26 EST
(In reply to Dan Yocum from comment #2)
> In section 6.3.3.2. ahc-match, the following text should be set to a bold
> heading type - it's hard to determine that it is a heading:
> 
> ⁠Ready-State Files (Dell DRAC only)



It's hard to tell *all* sub-headings from normal text.
Comment 6 Dan Macpherson 2016-03-16 02:17:12 EDT
Hi Dan,

Responses below...

(In reply to Dan Yocum from comment #0)
> Sections 3.1 -> 3.5 should be a script included in the appendix (and noted
> as such), but specifically 3.4 should include a script like this (to be run
> as root):
> 
> $ sudo for repo in rhel-7-server-openstack-7.0-rpms rhel-7-server-rpms
> rhel-7-server-optional-rpms rhel-7-server-extras-rpms
> rhel-7-server-openstack-7.0-director-rpms; do sudo yum-config-manager
> --enable $repo --setopt="${repo}.priority=1"; done

This section has been removed in accordance with another BZ:
https://bugzilla.redhat.com/show_bug.cgi?id=1305475

> The script bit in Section 3.4 should fixed thusly (because a normal user
> can't 'reboot'):
> 
> $ sudo yum update -y
> $ sudo reboot

Push a commit for the missing sudo:

https://gitlab.cee.redhat.com/rhci-documentation/docs-Red_Hat_Enterprise_Linux_OpenStack_Platform/commit/0a83ba142e3788c46907f8d3f7930f3c55bedf43
 
> Section 3.7
> 
> The code block shows:
> [stack@host1 ~]$ ls /httpboot -l
> total 151636
> -rw-r--r--. 1 ironic ironic       269 Sep 19 02:43 boot.ipxe
> -rw-r--r--. 1 root   root         252 Sep 10 15:35 discoverd.ipxe
> -rwxr-xr-x. 1 root   root     5027584 Sep 10 16:32 discovery.kernel
> -rw-r--r--. 1 root   root   150230861 Sep 10 16:32 discovery.ramdisk
> drwxr-xr-x. 2 ironic ironic      4096 Sep 19 02:45 pxelinux.cfg
> 
> On a fresh install, this is what I see (and put the -l before the dir,
> please):
> 
> $ ls -l /httpboot
> total 155544
> -rw-r--r--. 1 ironic ironic       237 Feb 19 15:25 discoverd.ipxe
> -rwxr-xr-x. 1 root   root     5153184 Feb 19 18:11 discovery.kernel
> -rw-r--r--. 1 root   root   154114052 Feb 19 18:11 discovery.ramdisk
Comment 7 Dan Macpherson 2016-03-16 02:28:10 EDT
CONT

> Section 3.7
> 
> The code block shows:
> [stack@host1 ~]$ ls /httpboot -l
> total 151636
> -rw-r--r--. 1 ironic ironic       269 Sep 19 02:43 boot.ipxe
> -rw-r--r--. 1 root   root         252 Sep 10 15:35 discoverd.ipxe
> -rwxr-xr-x. 1 root   root     5027584 Sep 10 16:32 discovery.kernel
> -rw-r--r--. 1 root   root   150230861 Sep 10 16:32 discovery.ramdisk
> drwxr-xr-x. 2 ironic ironic      4096 Sep 19 02:45 pxelinux.cfg
> 
> On a fresh install, this is what I see (and put the -l before the dir,
> please):
> 
> $ ls -l /httpboot
> total 155544
> -rw-r--r--. 1 ironic ironic       237 Feb 19 15:25 discoverd.ipxe
> -rwxr-xr-x. 1 root   root     5153184 Feb 19 18:11 discovery.kernel
> -rw-r--r--. 1 root   root   154114052 Feb 19 18:11 discovery.ramdisk

This has been fixed in another BZ:
https://bugzilla.redhat.com/show_bug.cgi?id=1304941

> In section 6.3.3.2. ahc-match, the following text should be set to a bold
> heading type - it's hard to determine that it is a heading:
> 
> ⁠Ready-State Files (Dell DRAC only)

I won't be able to fix this directly because these headings are using a portal-wide stylesheet. I might see if I can restructure the sections for OSP8 so that the headings appear more prominent. 

(In reply to Dan Yocum from comment #3)
> The following needs to be summarized and added, probably as an appendix, but
> referred to in 6.3.5. Configuring Ceph Storage:
> 
> http://docs.openstack.org/developer/ironic/deploy/install-guide.
> html#specifying-the-disk-for-deployment
> 
> Dell doesn't necessarily put the install drives as the first devices in the
> RAID.

I've got this included in the new Ceph Storage guide:

http://file.bne.redhat.com/~dmacpher/OpenStack/8.0/Ceph_Storage/#defining_the_root_disk_for_ceph_storage_nodes

> Why is this not part of the storage-environment.yaml file by default:
> 
> parameter_defaults:
>   ExtraConfig:
>     ceph::profile::params::osds:

I'm not sure. You might need to ask the Engineering team about this. However, I've tried to document this as a part of the storage-environment.yaml file in the Ceph Storage Guide:

http://file.bne.redhat.com/~dmacpher/OpenStack/8.0/Ceph_Storage/#mapping_the_ceph_storage_node_disk_layout
Comment 9 Dan Yocum 2016-04-06 08:50:07 EDT
No where in the doc is there a complete 'openstack overcloud deploy ...' statement.  Not even in section 6.2.9, which is where an operator would expect to find one.  

I suggest the following:

openstack overcloud deploy \
-t 120 \
--templates \
--control-scale 3 \
--compute-scale 1 \
--ceph-storage-scale 4 \
--control-flavor control \
--compute-flavor compute \
--ceph-storage-flavor ceph-storage \
--ntp-server 10.5.26.10 \
--neutron-network-type vxlan \
--neutron-tunnel-types vxlan \
--validation-errors-fatal \
--validation-warnings-fatal \
-e /usr/share/openstack-tripleo-heat-templates/overcloud-resource-registry-puppet.yaml \
-e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
-e ~/templates/network-environment.yaml \
-e ~/templates/ceph-wipe-environment.yaml \
-e ~/templates/storage-environment.yaml \
-e ~/templates/enable-tls.yaml \
-e ~/templates/cloudname.yaml \
-e ~/templates/inject-trust-anchor.yaml \
-e ~/templates/rhel-registration/environment-rhel-registration.yaml \
-e ~/templates/rhel-registration/rhel-registration-resource-registry.yaml \
Comment 10 Dan Yocum 2016-04-08 16:28:56 EDT
A VERY LARGE WARNING MUST PUT IN SECTION 3.4!!!!

Something like "IF YOU USE THE EPEL REPOSITORY IT MUST BE DISABLED UNTIL THE OVERCLOUD IS DEPLOYED!!  Set enabled=0 in the /etc/yum.repos.d/epel.repo file!"
Comment 11 Dan Yocum 2016-04-08 16:29:28 EDT
Setting to priority high because of Comment 10.
Comment 12 Dan Yocum 2016-04-24 10:42:29 EDT
https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/red-hat-ceph-storage-for-the-overcloud/

In the code block exists text that should be in the normal page format, not code format:

````

This Heat template makes reference to a Bash script called `wipe-disk.sh`. This script contains your procedure to wipe the non-root disks. The following script is an example of `wipe-disk.sh` that wipes all disks except for the root disk:
````
Comment 13 Dan Yocum 2016-04-25 13:18:08 EDT
In OSP-d v7, the 'extra' field looked something like this:

| extra       | {u'newly_discovered': u'true', u'block_devices':      |
|             | {u'serials': [u'100000000', u'100000001',             |
|             | u'100000002', u'100000003', u'100000004',             |
|             | u'100000005', u'100000006', u'100000007',             |


In OSP-d v8, the 'extra' field looks like this:

| extra       | {u'hardware_swift_object':
u'extra_hardware-df6eb8fd-2e9f-4fba-                            |
|             | a4f7-46ee2b7b811f'}   |

Is this expected?

If so, the OSP-d v8 docs need to reflect this change and include
instructions on how to inspect the contents of the hardware_swift_object
(sorry, dmacpher).

Per shardy:

Sounds like the product docs need an update to match the upstream ones,
which do now reflect this new setup for introspection data storage:

http://docs.openstack.org/developer/tripleo-docs/advanced_deployment/introspection_data.html
Comment 14 Dan Yocum 2016-04-25 15:06:45 EDT
dmacpher - comment 13 is in regards to https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/director-installation-and-usage/#sect-Defining_the_Root_Disk_for_Nodes

OSP-d v8 contains python-ironic-inspector-client.noarch-1.2.0-6.el7ost, so the user will have to use the following 2 commands to gleen the info to determine the right disk to install the OS on to:

[stack@ops2 ~]$ token=$(openstack token issue -f value -c id)
[stack@ops2 ~]$ curl -H "X-Auth-Token: $token" http://127.0.0.1:5050/v1/introspection/<UUID>/data | jq '.extra.disk' | grep -i 'sd\|serial\|id\|size'
Comment 15 Dan Yocum 2016-04-25 15:46:21 EDT
In section  https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/director-installation-and-usage/#sect-Customizing_Overcloud_PreConfiguration

This note is poorly worded:

IMPORTANT
The server parameter the server to apply the configuration and is provided by the parent template. This parameter is mandatory in all pre-configuration templates.

It should be:

IMPORTANT
The server parameter is the server on which to apply the configuration and is provided by the parent template. This parameter is mandatory in all OS::TripleO::NodeExtraConfigPre templates.

Also... is it supposed to be "server" (singular) or "servers" (plural)?
Comment 16 Dan Yocum 2016-04-25 16:06:34 EDT
Section 6.16 is a little light on details:  https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/director-installation-and-usage/#sect-Customizing_Puppet_Configuration_Data

6.16 should contain the same info as, say, 6.15 and 6.17.
Comment 17 Dan Yocum 2016-04-25 17:07:05 EDT
Several openstack deploy overcloud options specified in the guide are marked as deprecated in the 'openstack help deploy overcloud' text.  They should be removed from the docs.
Comment 18 Dan Macpherson 2016-04-26 00:32:27 EDT
(In reply to Dan Yocum from comment #8)
> Found a typo in
> https://access.redhat.com/documentation/en-US/
> Red_Hat_Enterprise_Linux_OpenStack_Platform/7/html-single/
> Director_Installation_and_Usage/index.html#sect-Advanced-
> Automatically_Tagging_Nodes_with_Automated_Health_Check_AHC_Tools
> 
> Search for 'controller.specs'; should be 'control.specs'

Implemented for OSP 7, but does not apply to OSP 8
Comment 19 Dan Macpherson 2016-04-26 00:33:41 EDT
(In reply to Dan Yocum from comment #9)
> No where in the doc is there a complete 'openstack overcloud deploy ...'
> statement.  Not even in section 6.2.9, which is where an operator would
> expect to find one.  
> 
> I suggest the following:
> 
> openstack overcloud deploy \
> -t 120 \
> --templates \
> --control-scale 3 \
> --compute-scale 1 \
> --ceph-storage-scale 4 \
> --control-flavor control \
> --compute-flavor compute \
> --ceph-storage-flavor ceph-storage \
> --ntp-server 10.5.26.10 \
> --neutron-network-type vxlan \
> --neutron-tunnel-types vxlan \
> --validation-errors-fatal \
> --validation-warnings-fatal \
> -e
> /usr/share/openstack-tripleo-heat-templates/overcloud-resource-registry-
> puppet.yaml \
> -e
> /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.
> yaml \
> -e ~/templates/network-environment.yaml \
> -e ~/templates/ceph-wipe-environment.yaml \
> -e ~/templates/storage-environment.yaml \
> -e ~/templates/enable-tls.yaml \
> -e ~/templates/cloudname.yaml \
> -e ~/templates/inject-trust-anchor.yaml \
> -e ~/templates/rhel-registration/environment-rhel-registration.yaml \
> -e ~/templates/rhel-registration/rhel-registration-resource-registry.yaml \

I've implemented a new section specifically for the overcloud deploy command, including a section for an example:

https://access.redhat.com/documentation/en/red-hat-openstack-platform/8/director-installation-and-usage/73-overcloud-creation-example

I might modify this and add some of the config options you've mentioned here.
Comment 20 Dan Macpherson 2016-04-26 00:37:36 EDT
(In reply to Dan Yocum from comment #10)
> A VERY LARGE WARNING MUST PUT IN SECTION 3.4!!!!
> 
> Something like "IF YOU USE THE EPEL REPOSITORY IT MUST BE DISABLED UNTIL THE
> OVERCLOUD IS DEPLOYED!!  Set enabled=0 in the /etc/yum.repos.d/epel.repo
> file!"

I've added a note not to enable ANY repositories other than the ones specified. 

I should note, EPEL is pretty much unsupported by Red Hat and, if they follow the specific director registration instructions, people shouldn't be enabling this repository in the first place.
Comment 21 Dan Macpherson 2016-04-26 00:38:00 EDT
(In reply to Dan Yocum from comment #12)
> https://access.redhat.com/documentation/en/red-hat-openstack-platform/
> version-8/red-hat-ceph-storage-for-the-overcloud/
> 
> In the code block exists text that should be in the normal page format, not
> code format:
> 
> ````
> 
> This Heat template makes reference to a Bash script called `wipe-disk.sh`.
> This script contains your procedure to wipe the non-root disks. The
> following script is an example of `wipe-disk.sh` that wipes all disks except
> for the root disk:
> ````

Added a fix to correct this.
Comment 22 Dan Macpherson 2016-04-26 00:41:27 EDT
(In reply to Dan Yocum from comment #13)
> In OSP-d v7, the 'extra' field looked something like this:
> 
> | extra       | {u'newly_discovered': u'true', u'block_devices':      |
> |             | {u'serials': [u'100000000', u'100000001',             |
> |             | u'100000002', u'100000003', u'100000004',             |
> |             | u'100000005', u'100000006', u'100000007',             |
> 
> 
> In OSP-d v8, the 'extra' field looks like this:
> 
> | extra       | {u'hardware_swift_object':
> u'extra_hardware-df6eb8fd-2e9f-4fba-                            |
> |             | a4f7-46ee2b7b811f'}   |
> 
> Is this expected?
> 
> If so, the OSP-d v8 docs need to reflect this change and include
> instructions on how to inspect the contents of the hardware_swift_object
> (sorry, dmacpher).
> 
> Per shardy:
> 
> Sounds like the product docs need an update to match the upstream ones,
> which do now reflect this new setup for introspection data storage:
> 
> http://docs.openstack.org/developer/tripleo-docs/advanced_deployment/
> introspection_data.html

(In reply to Dan Yocum from comment #14)
> dmacpher - comment 13 is in regards to
> https://access.redhat.com/documentation/en/red-hat-openstack-platform/
> version-8/director-installation-and-usage/#sect-
> Defining_the_Root_Disk_for_Nodes
> 
> OSP-d v8 contains python-ironic-inspector-client.noarch-1.2.0-6.el7ost, so
> the user will have to use the following 2 commands to gleen the info to
> determine the right disk to install the OS on to:
> 
> [stack@ops2 ~]$ token=$(openstack token issue -f value -c id)
> [stack@ops2 ~]$ curl -H "X-Auth-Token: $token"
> http://127.0.0.1:5050/v1/introspection/<UUID>/data | jq '.extra.disk' | grep
> -i 'sd\|serial\|id\|size'

I'll be tracking this in

https://bugzilla.redhat.com/show_bug.cgi?id=1330220
Comment 23 Dan Macpherson 2016-04-26 00:43:51 EDT
(In reply to Dan Yocum from comment #15)
> In section 
> https://access.redhat.com/documentation/en/red-hat-openstack-platform/
> version-8/director-installation-and-usage/#sect-
> Customizing_Overcloud_PreConfiguration
> 
> This note is poorly worded:
> 
> IMPORTANT
> The server parameter the server to apply the configuration and is provided
> by the parent template. This parameter is mandatory in all pre-configuration
> templates.
> 
> It should be:
> 
> IMPORTANT
> The server parameter is the server on which to apply the configuration and
> is provided by the parent template. This parameter is mandatory in all
> OS::TripleO::NodeExtraConfigPre templates.

Added a fix for this is OSP 7 and OSP 8 docs

> Also... is it supposed to be "server" (singular) or "servers" (plural)?

For preconfig, it's serve andis a string. I think for post config its servers and uses json. I had originally documented them as the same for OSP 7 but a few months ago I received a BZ that they were different, and confirmed it.
Comment 24 Dan Macpherson 2016-04-26 00:45:02 EDT
(In reply to Dan Yocum from comment #16)
> Section 6.16 is a little light on details: 
> https://access.redhat.com/documentation/en/red-hat-openstack-platform/
> version-8/director-installation-and-usage/#sect-
> Customizing_Puppet_Configuration_Data
> 
> 6.16 should contain the same info as, say, 6.15 and 6.17.

This is pretty much intentional since 6.15 and 6.17 use full Heat templates. 6.16 only uses params in an environment files, so it will be shorter and simpler.
Comment 25 Dan Macpherson 2016-04-26 00:58:19 EDT
(In reply to Dan Yocum from comment #17)
> Several openstack deploy overcloud options specified in the guide are marked
> as deprecated in the 'openstack help deploy overcloud' text.  They should be
> removed from the docs.

Updated options. I've marked deprecated options accordingly since they're not removed completely yet (legacy support).
Comment 26 Dan Yocum 2016-04-26 08:48:28 EDT
In https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/director-installation-and-usage/#sect-Tagging_Nodes_into_Profiles

This code block should be changed:

$ ironic node-update 58c3d07e-24f2-48a7-bbb6-6843f0e8ee13 add properties/capabilities='profile:compute,boot_option:local'
$ ironic node-update 1a4e30da-b6dc-499d-ba87-0bd8a3819bc0 add properties/capabilities='profile:control,boot_option:local'

To this:

$ ironic node-update [UUID of compute node] add properties/capabilities='profile:compute,boot_option:local'

$ ironic node-update [UUID of controller node] add properties/capabilities='profile:control,boot_option:local'
Comment 27 Dan Yocum 2016-04-26 12:42:52 EDT
https://access.redhat.com/documentation/en/red-hat-openstack-platform/version-8/director-installation-and-usage/#sect-Undercloud_Requirements

Change the following requirement from:

A minimum of 40 GB of available disk space.

To:

A minimum of 40 GB of available disk space for the root (/) filesystem.

Note You need to log in before you can comment on or make changes to this bug.