Clean up usage.rst
Various changes to help usage.rst make more use of RST features, particular inline code snippets. The intent here is mostly to make the doc more readable by being more clear about which values are exact filenames, exact network names, and so on. Change-Id: Ic7335379a3c036a1265cac7032042fa351d5606e
This commit is contained in:
James Polley
parent
91376b7b4a
commit
189330be07
|
|
@ -4,20 +4,20 @@ Usage
|
|||
|
||||
To use os-cloud-config in a project::
|
||||
|
||||
import os_cloud_config
|
||||
import os_cloud_config
|
||||
|
||||
-----------------------------------
|
||||
Initializing Keystone for a host
|
||||
-----------------------------------
|
||||
|
||||
The init-keystone command line utility initializes Keystone for use with normal
|
||||
The ``init-keystone`` command line utility initializes Keystone for use with normal
|
||||
authentication by creating the admin and service tenants, the admin role, the
|
||||
admin user, configure certificates and finally registers the initial identity
|
||||
endpoint.
|
||||
|
||||
.. note::
|
||||
|
||||
init-keystone will wait for a user-specified amount of time for a Keystone
|
||||
init-keystone will wait for a user-specified amount of time for a Keystone
|
||||
service to be running on the specified host. The default is a 10 minute
|
||||
wait time with 10 seconds between poll attempts.
|
||||
|
||||
|
|
@ -25,15 +25,15 @@ For example::
|
|||
|
||||
init-keystone -o 192.0.2.1 -t unset -e admin@example.com -p unset -u root
|
||||
|
||||
That acts on the 192.0.2.1 host, sets the admin token and the admin password
|
||||
to the string "unset", the admin e-mail address to "admin@example.com", and
|
||||
That acts on the host ``192.0.2.1``, sets the admin token and the admin password
|
||||
to the string ``unset``, the admin e-mail address to ``admin@example.com``, and
|
||||
uses the root user to connect to the host via ssh to configure certificates.
|
||||
|
||||
--------------------------------------------
|
||||
Registering nodes with a baremetal service
|
||||
--------------------------------------------
|
||||
|
||||
The register-nodes command line utility supports registering nodes with
|
||||
The ``register-nodes`` command line utility supports registering nodes with
|
||||
either Ironic or Nova-baremetal. Ironic will be used if the Ironic service
|
||||
is registered with Keystone.
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ For example::
|
|||
|
||||
register-nodes -s seed -n /tmp/one-node
|
||||
|
||||
Where /tmp/one-node contains::
|
||||
Where ``/tmp/one-node`` contains::
|
||||
|
||||
[
|
||||
{
|
||||
|
|
@ -83,7 +83,7 @@ Where /tmp/one-node contains::
|
|||
Generating keys and certificates for use with Keystone PKI
|
||||
----------------------------------------------------------
|
||||
|
||||
The generate-keystone-pki command line utility generates keys and certificates
|
||||
The ``generate-keystone-pki`` command line utility generates keys and certificates
|
||||
which Keystone uses for signing authentication tokens.
|
||||
|
||||
- Keys and certificates can be generated into separate files::
|
||||
|
|
@ -91,13 +91,13 @@ which Keystone uses for signing authentication tokens.
|
|||
generate-keystone-pki /tmp/certificates
|
||||
|
||||
That creates four files with signing and CA keys and certificates in
|
||||
/tmp/certificates directory.
|
||||
``/tmp/certificates`` directory.
|
||||
|
||||
- Key and certificates can be generated into heat environment file::
|
||||
|
||||
generate-keystone-pki -j overcloud-env.json
|
||||
|
||||
That adds following values into overcloud-env.json file::
|
||||
That adds following values into ``overcloud-env.json`` file::
|
||||
|
||||
{
|
||||
"parameters": {
|
||||
|
|
@ -129,7 +129,7 @@ which Keystone uses for signing authentication tokens.
|
|||
Setting up networking
|
||||
---------------------
|
||||
|
||||
The setup-neutron command line utility allows setting up of a physical control
|
||||
The ``setup-neutron`` command line utility allows setting up of a physical control
|
||||
plane network suitable for deployment clouds, or an external network with an
|
||||
internal floating network suitable for workload clouds.
|
||||
|
||||
|
|
@ -137,7 +137,7 @@ The network JSON argument allows specifying the network(s) to be created::
|
|||
|
||||
setup-neutron -n /tmp/ctlplane
|
||||
|
||||
Where /tmp/ctlplane contains::
|
||||
Where ``/tmp/ctlplane`` contains::
|
||||
|
||||
{
|
||||
"physical": {
|
||||
|
|
@ -150,16 +150,16 @@ Where /tmp/ctlplane contains::
|
|||
}
|
||||
}
|
||||
|
||||
This will create a Neutron flat net with a name of 'ctlplane', and a subnet
|
||||
with a CIDR of '192.0.2.0/24', a metadata server and gateway of '192.0.2.1',
|
||||
and will allocate DHCP leases in the range of '192.0.2.2' to '192.0.2.20', as
|
||||
well as adding a route for 169.254.169.254/32.
|
||||
This will create a Neutron flat net with a name of ``ctlplane``, and a subnet
|
||||
with a CIDR of ``192.0.2.0/24``, a metadata server and gateway of ``192.0.2.1``,
|
||||
and will allocate DHCP leases in the range of ``192.0.2.2`` to ``192.0.2.20``, as
|
||||
well as adding a route for ``169.254.169.254/32``.
|
||||
|
||||
setup-neutron also supports datacentre networks that require 802.1Q VLAN tags::
|
||||
|
||||
setup-neutron -n /tmp/ctlplane-dc
|
||||
|
||||
Where /tmp/ctlplane-dc contains::
|
||||
Where ``/tmp/ctlplane-dc`` contains::
|
||||
|
||||
{
|
||||
"physical": {
|
||||
|
|
@ -174,8 +174,9 @@ Where /tmp/ctlplane-dc contains::
|
|||
}
|
||||
}
|
||||
|
||||
This creates a Neutron 'net' called ``public`` using VLAN tag 25, that uses
|
||||
the existing 'net' called ``ctlplane`` as a physical transport.
|
||||
This creates a Neutron 'net' called ``public`` using VLAN tag ``25``, that uses
|
||||
an existing 'net' called ``ctlplane`` as a physical transport.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -186,7 +187,7 @@ setup-neutron can also create two networks suitable for workload clouds::
|
|||
|
||||
setup-neutron -n /tmp/float
|
||||
|
||||
Where /tmp/float contains::
|
||||
Where ``/tmp/float`` contains::
|
||||
|
||||
{
|
||||
"float": {
|
||||
|
|
@ -202,19 +203,19 @@ Where /tmp/float contains::
|
|||
}
|
||||
}
|
||||
|
||||
This creates two Neutron nets, the first with a name of 'default-net' and set
|
||||
as shared, and second with a name 'ext-net' with the 'router:external'
|
||||
property set to true. The default-net subnet has a CIDR of 10.0.0.0/8 and a
|
||||
default nameserver of 8.8.8.8, and the ext-net subnet has a CIDR of
|
||||
192.0.2.0/24, a gateway of 192.0.2.1 and allocates DHCP from 192.0.2.45 until
|
||||
192.0.2.64. setup-neutron will also create a router for the float network,
|
||||
setting the external network as the gateway.
|
||||
This creates two Neutron nets, the first with a name of ``default-net`` and
|
||||
set as shared, and second with a name ``ext-net`` with the ``router:external``
|
||||
property set to true. The ``default-net`` subnet has a CIDR of ``10.0.0.0/8`` and a
|
||||
default nameserver of ``8.8.8.8``, and the ``ext-net`` subnet has a CIDR of
|
||||
``192.0.2.0/24``, a gateway of ``192.0.2.1`` and allocates DHCP from
|
||||
``192.0.2.45`` until ``192.0.2.64``. setup-neutron will also create a router
|
||||
for the float network, setting the external network as the gateway.
|
||||
|
||||
----------------
|
||||
Creating flavors
|
||||
----------------
|
||||
|
||||
The setup-flavors command line utility creates flavors in Nova -- either using
|
||||
The ``setup-flavors`` command line utility creates flavors in Nova -- either using
|
||||
the nodes that have been registered to provide a distinct set of hardware that
|
||||
is provisioned, or by specifing the set of flavors that should be created.
|
||||
|
||||
|
|
@ -225,22 +226,22 @@ is provisioned, or by specifing the set of flavors that should be created.
|
|||
is a cloud only using baremetal hardware, so only needs to describe the
|
||||
hardware available.
|
||||
|
||||
Utilising the /tmp/one-node file specified in the register-nodes example
|
||||
Utilising the ``/tmp/one-node`` file specified in the ``register-nodes`` example
|
||||
above, create a flavor::
|
||||
|
||||
setup-flavors -n /tmp/one-node
|
||||
|
||||
Which results in a flavor called "baremetal_2048_30_None_1".
|
||||
Which results in a flavor called ``baremetal_2048_30_None_1``.
|
||||
|
||||
If the ROOT_DISK environment variable is set in the environment, that will be
|
||||
If the ``ROOT_DISK`` environment variable is set in the environment, that will be
|
||||
used as the disk size, leaving the remainder set as ephemeral storage, giving
|
||||
a flavor name of "baremetal_2048_10_20_1".
|
||||
a flavor name of ``baremetal_2048_10_20_1``.
|
||||
|
||||
Conversely, you can specify a JSON file describing the flavors to create::
|
||||
|
||||
setup-flavors -f /tmp/one-flavor
|
||||
|
||||
Where /tmp/one-flavor contains::
|
||||
Where ``/tmp/one-flavor`` contains::
|
||||
|
||||
[
|
||||
{
|
||||
|
|
@ -252,7 +253,7 @@ Where /tmp/one-flavor contains::
|
|||
}
|
||||
]
|
||||
|
||||
The JSON file can also contain an 'extra_specs' parameter, which is a JSON
|
||||
The JSON file can also contain an ``extra_specs`` parameter, which is a JSON
|
||||
object describing the key-value pairs to add into the flavor metadata::
|
||||
|
||||
[
|
||||
|
|
|
|||
Loading…
Reference in New Issue