From 7556dc6a76e011ae08b5a05f9bda29831cf4fac5 Mon Sep 17 00:00:00 2001 From: Ruby Loo Date: Tue, 27 Sep 2016 21:43:04 -0400 Subject: [PATCH] Update multi-tenancy documentation This updates the multi-tenancy documentation. The changes include: - use the service name (e.g. the Bare Metal service) instead of the project name (e.g. ironic) - fix some grammatical issues - refer to the ironic conductor as 'ironic-conductor' instead of 'conductor' - remove note about setting enabled_network_interfaces config option in ironic-api's config file; that is no longer needed since the checks have been moved to the conductor side (when node creation was moved). Change-Id: Ic4b1512672c16c1bff5b43595abd90190e23b0fe --- doc/source/deploy/multitenancy.rst | 153 +++++++++++++++-------------- 1 file changed, 77 insertions(+), 76 deletions(-) diff --git a/doc/source/deploy/multitenancy.rst b/doc/source/deploy/multitenancy.rst index d1e4d17e09..73d37b2d3f 100644 --- a/doc/source/deploy/multitenancy.rst +++ b/doc/source/deploy/multitenancy.rst @@ -1,8 +1,8 @@ .. _multitenancy: -================================== -Multitenancy in Bare Metal service -================================== +======================================= +Multi-tenancy in the Bare Metal service +======================================= Overview ======== @@ -14,8 +14,8 @@ nodes in a separate provisioning network. The result of this is that multiple tenants can use nodes in an isolated fashion. However, this configuration does not support trunk ports belonging to multiple networks. -Network interface is one of the driver interfaces, that manages network -switching for nodes. Currently there are 3 network interfaces available in +Network interface is one of the driver interfaces that manages network +switching for nodes. There are 3 network interfaces available in the Bare Metal service: - ``noop`` interface is used for standalone deployments, and does not perform @@ -25,58 +25,55 @@ the Bare Metal service: a single layer 2 network, separated from the cleaning network; - ``neutron`` interface provides tenant-defined networking by integrating with - neutron, while also separating tenant networks from the provisioning and - cleaning provider networks. + the Networking service, while also separating tenant networks from the + provisioning and cleaning provider networks. -Configuring Ironic -================== +Configuring the Bare Metal service +================================== -Below is an example flow of how to setup ironic so that node provisioning will -happen in a multitenant environment (which means using ``neutron`` network -interface as stated above): +Below is an example flow of how to set up the Bare Metal service so that node +provisioning will happen in a multi-tenant environment (which means using +``neutron`` network interface as stated above): -#. Network interfaces can be enabled on ironic-conductor by adding them to - ``enabled_network_interfaces`` configuration option under the default - section:: +#. Network interfaces can be enabled on ironic-conductor by adding them to the + ``enabled_network_interfaces`` configuration option under the ``default`` + section of the configuration file:: [DEFAULT] ... enabled_network_interfaces=noop,flat,neutron - Please note that ``enabled_network_interfaces`` has to be set in the - ironic-api configuration file too, as its value is used on the API side to - check if the requested network interface is available. + Keep in mind that, ideally, all ironic-conductors should have the same list + of enabled network interfaces, but it may not be the case during + ironic-conductor upgrades. This may cause problems if one of the + ironic-conductors dies and some node that is taken over is mapped to an + ironic-conductor that does not support the node's network interface. + Any actions that involve calling the node's driver will fail until that + network interface is installed and enabled on that ironic-conductor. - Keep in mind that, ideally, all conductors should have the same list of - enabled network interfaces, but it may not be the case during conductor - upgrades. This may cause problems if one of the conductors dies and some - node that is taken over is mapped to a conductor that does not support the - node's network interface. Any actions that involve calling the node's driver - will fail until that network interface is installed and enabled on that - conductor. - -#. It is recommended to set the default network interface via - ``default_network_interface`` configuration option under the default - section:: +#. It is recommended to set the default network interface via the + ``default_network_interface`` configuration option under the ``default`` + section of the configuration file:: [DEFAULT] ... default_network_interface=neutron - It will be used for all nodes that will be created without explicitly - specifying the network interface. + This default value will be used for all nodes that don't have a network + interface explicitly specified in the creation request. - If it is not set, the default network interface is determined by looking at - the ``[dhcp]dhcp_provider`` configuration option value. If it is - ``neutron`` - ``flat`` network interface becomes the default, otherwise - ``noop`` is the default. + If this configuration option is not set, the default network interface is + determined by looking at the ``[dhcp]dhcp_provider`` configuration option + value. If it is ``neutron``, then ``flat`` network interface becomes the + default, otherwise ``noop`` is the default. -#. Define a provider network in neutron, which we shall refer to as the - "provisioning" network, and add it in under the neutron section in - ironic-conductor configuration file. Using ``neutron`` network interface +#. Define a provider network in the Networking service, which we shall refer to + as the "provisioning" network, and add it in the ``neutron`` section of + the ironic-conductor configuration file. Using ``neutron`` network interface requires that ``provisioning_network`` and ``cleaning_network`` - configuration options are set to a valid neutron network UUIDs or names, - otherwise cleaning or provisioning will fail to start:: + configuration options are set to valid Networking service's network + identifiers (UUID or name); otherwise cleaning or provisioning will fail to + start:: [neutron] ... @@ -87,53 +84,54 @@ interface as stated above): information about cleaning. .. warning:: - Please make sure ironic is exclusive to the provisioning and cleaning - network. Spawning instances by non-admin users in these networks and - getting access to ironic control plane is a security risk. For this - reason, the provisioning and cleaning network should be configured as - non-shared network in the admin tenant. + Please make sure that the Bare Metal service has exclusive access to the + provisioning and cleaning networks. Spawning instances by non-admin users + in these networks and getting access to the Bare Metal service's control + plane is a security risk. For this reason, the provisioning and cleaning + networks should be configured as non-shared networks in the ``admin`` + tenant. .. note:: Spawning a bare metal instance onto the provisioning network is impossible, the deployment will fail. The node should be deployed onto a different network than the provisioning network. When you boot a bare - metal instance from nova, you should choose a different network in - neutron for your instance. + metal instance from the Compute service, you should choose a different + network in the Networking service for your instance. .. note:: - The "provisioning" and "cleaning" networks may be the same neutron - provider network, or may be distinct networks. To ensure communication - between ironic and the deploy ramdisk works, it's important to ensure - that security groups are disabled for these networks, *or* the default + The "provisioning" and "cleaning" networks may be the same network or + distinct networks. To ensure that communication between the Bare Metal + service and the deploy ramdisk works, it is important to ensure that + security groups are disabled for these networks, *or* that the default security groups allow: * DHCP * TFTP - * egress port used for ironic (6385 by default) + * egress port used for the Bare Metal service (6385 by default) * ingress port used for ironic-python-agent (9999 by default) * if using the iSCSI deploy method (``pxe_*`` and ``iscsi_*`` drivers), the ingress port used for iSCSI (3260 by default) * if using the direct deploy method (``agent_*`` drivers), the egress - port used for swift (typically 80 or 443) + port used for the Object Storage service (typically 80 or 443) * if using iPXE, the egress port used for the HTTP server running - on the ironic conductor nodes (typically 80). + on the ironic-conductor nodes (typically 80). #. This step is optional and applicable only if you want to use security groups during provisioning and/or cleaning of the nodes. If not specified, default security groups are used. - First define security groups in neutron to be used for provisioning - and/or cleaning networks. Then add the list of these security group - UUIDs under the neutron section in ironic-conductor configuration file - as shown below:: + First define security groups in the Networking service, to be used for + provisioning and/or cleaning networks. Then add the list of these security + group UUIDs under the ``neutron`` section of ironic-conductor's + configuration file as shown below:: [neutron] ... cleaning_network=$CLEAN_UUID_OR_NAME - cleaning_network_security_groups=[$LIST_OF_CLEAN_SEC_GROUPS] + cleaning_network_security_groups=[$LIST_OF_CLEAN_SECURITY_GROUPS] provisioning_network=$PROVISION_UUID_OR_NAME - provisioning_network_security_groups=[$LIST_OF_PROVISION_SEC_GROUPS] + provisioning_network_security_groups=[$LIST_OF_PROVISION_SECURITY_GROUPS] Multiple security groups may be applied to a given network, hence, they are specified as a list. @@ -143,10 +141,10 @@ interface as stated above): .. warning:: If security groups are configured as described above, do not set the "port_security_enabled" flag to False for the corresponding - neutron network or port. This will cause the deploy to fail. + Networking service's network or port. This will cause the deploy to fail. - For example: if provisioning_network_security_groups configuration - option is used, ensure that "port_security_enabled" flag for + For example: if ``provisioning_network_security_groups`` configuration + option is used, ensure that "port_security_enabled" flag for the provisioning network is set to True. This flag is set to True by default; make sure not to override it by manually setting it to False. @@ -155,7 +153,8 @@ interface as stated above): `_ for details. -#. Restart the ironic conductor and API services after the modifications: +#. Restart the ironic-conductor and ironic-api services after the + modifications: - Fedora/RHEL7/CentOS7:: @@ -167,8 +166,8 @@ interface as stated above): sudo service ironic-api restart sudo service ironic-conductor restart -#. Make sure that the conductor is reachable over the provisioning network - by trying to download a file from a TFTP server on it, from some +#. Make sure that the ironic-conductor is reachable over the provisioning + network by trying to download a file from a TFTP server on it, from some non-control-plane server in that network:: tftp $TFTP_IP -c get $FILENAME @@ -178,7 +177,7 @@ interface as stated above): Configuring nodes ================= -#. Multitenancy support was added in the 1.20 API version. The following +#. Multi-tenancy support was added in the 1.20 API version. The following examples assume you are using python-ironicclient version 1.5.0 or higher. They show the usage of both ``ironic`` and ``openstack baremetal`` commands. @@ -192,10 +191,11 @@ Configuring nodes export OS_BAREMETAL_API_VERSION=1.20 -#. Node's ``network_interface`` field should be set to valid network interface - that is listed in the ``[DEFAULT]/enabled_network_interfaces`` configuration - option in the ironic-api config. Set it to ``neutron`` to use neutron ML2 - driver: +#. The node's ``network_interface`` field should be set to a valid network + interface. Valid interfaces are listed in the + ``[DEFAULT]/enabled_network_interfaces`` configuration option in the + ironic-conductor's configuration file. Set it to ``neutron`` to use the + Networking service's ML2 driver: - ``ironic`` command:: @@ -208,11 +208,12 @@ Configuring nodes --driver agent-ipmitool .. note:: - If the ``[DEFAULT]/default_network_interface`` configuration option was + If the ``[DEFAULT]/default_network_interface`` configuration option is set, the ``--network-interface`` option does not need to be specified - when defining the node. + when creating the node. -#. To update existing node's network interface, use the following commands: +#. To update an existing node's network interface to ``neutron``, use the + following commands: - ``ironic`` command:: @@ -224,7 +225,7 @@ Configuring nodes --network-interface neutron #. The Bare Metal service provides the ``local_link_connection`` information to - the Networking service ML2 driver. The ML2 driver uses that information to + the Networking service's ML2 driver. The ML2 driver uses that information to plug the specified port to the tenant network. .. list-table:: ``local_link_connection`` fields @@ -239,7 +240,7 @@ Configuring nodes - Required. Port ID on the switch, for example, Gig0/1. * - ``switch_info`` - Optional. Used to distinguish different switch models or other - vendor specific-identifier. Some ML2 plugins may require this + vendor-specific identifier. Some ML2 plugins may require this field. Create a port as follows: