From a5c26972b28018083e0a76c0dbc41d738ca84fff Mon Sep 17 00:00:00 2001 From: Devananda van der Veen Date: Thu, 21 Jul 2016 09:18:12 -0700 Subject: [PATCH] Update documentation for keystone policy support This change adds information about keystone policy support in the following places: * api-ref: add notes to the Nodes reference, indicating that password and configdrive contents may be hidden in responses * deploy security guide: add a section about limiting API access by using the new policies and roles * deploy install guide: add instructions for creating the necessary Roles with the Identity service * dev quickstart guide: use devstack "demo" user throughout the guide, and add a note about why. Incidentally, switch to using "openstack" client instead of "ironic" and "nova" clients. Partial-bug: #1526752 Change-Id: I392cabbf04badabd8ae7bb00a914b0a06db3d421 --- api-ref/source/baremetal-api-v1-nodes.inc | 5 ++ doc/source/deploy/install-guide.rst | 98 +++++++++++++++++------ doc/source/deploy/security.rst | 44 +++++++--- doc/source/dev/dev-quickstart.rst | 31 +++---- 4 files changed, 126 insertions(+), 52 deletions(-) diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc index 14a09036b6..c25f9fa2a5 100644 --- a/api-ref/source/baremetal-api-v1-nodes.inc +++ b/api-ref/source/baremetal-api-v1-nodes.inc @@ -17,6 +17,11 @@ and by a unique human-readable "name" in any request. Throughout this documentation, this is referred to as the ``node_ident``. Responses clearly indicate whether a given field is a ``uuid`` or a ``name``. +Depending on the Roles assigned to the authenticated OpenStack User, and upon +the configuration of the Bare Metal service, API responses may change. For +example, the default value of the "show_password" settings cause all API +responses to mask passwords within ``driver_info`` with the literal string +"\*\*\*\*\*\*". Create Node =========== diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index 043dd2668a..bc342a3506 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -26,13 +26,14 @@ includes: - the OpenStack Image service (glance) from which to retrieve images and image meta-data - the OpenStack Networking service (neutron) for DHCP and network configuration - the OpenStack Compute service (nova) works with the Bare Metal service and acts as - a user-facing API for instance management, while the Bare Metal service provides - the admin/operator API for hardware management. - The OpenStack Compute service also provides scheduling facilities (matching - flavors <-> images <-> hardware), tenant quotas, IP assignment, and other - services which the Bare Metal service does not, in and of itself, provide. + a user-facing API for instance management, while the Bare Metal service + provides the admin/operator API for hardware management. The OpenStack + Compute service also provides scheduling facilities (matching flavors <-> + images <-> hardware), tenant quotas, IP assignment, and other services which + the Bare Metal service does not, in and of itself, provide. -- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not yet available. +- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not + yet available. The Bare Metal service includes the following components: @@ -96,33 +97,77 @@ Configure the Identity service for the Bare Metal service Use the ``service`` tenant and give the user the ``admin`` role:: openstack user create --password IRONIC_PASSWORD \ - --email ironic@example.com ironic + --email ironic@example.com ironic openstack role add --project service --user ironic admin #. You must register the Bare Metal service with the Identity service so that other OpenStack services can locate it. To register the service:: openstack service create --name ironic --description \ - "Ironic baremetal provisioning service" baremetal + "Ironic baremetal provisioning service" baremetal #. Use the ``id`` property that is returned from the Identity service when registering the service (above), to create the endpoint, and replace IRONIC_NODE with your Bare Metal service's API node:: openstack endpoint create --region RegionOne \ - baremetal admin http://IRONIC_NODE:6385 + baremetal admin http://IRONIC_NODE:6385 openstack endpoint create --region RegionOne \ - baremetal public http://IRONIC_NODE:6385 + baremetal public http://IRONIC_NODE:6385 openstack endpoint create --region RegionOne \ - baremetal internal http://IRONIC_NODE:6385 + baremetal internal http://IRONIC_NODE:6385 If only keystone v2 API is available, use this command instead:: openstack endpoint create --region RegionOne \ - --publicurl http://IRONIC_NODE:6385 \ - --internalurl http://IRONIC_NODE:6385 \ - --adminurl http://IRONIC_NODE:6385 \ - baremetal + --publicurl http://IRONIC_NODE:6385 \ + --internalurl http://IRONIC_NODE:6385 \ + --adminurl http://IRONIC_NODE:6385 \ + baremetal + +#. You may delegate limited privileges related to the Bare Metal service + to your Users by creating Roles with the OpenStack Identity service. By + default, the Bare Metal service expects the "baremetal_admin" and + "baremetal_observer" Roles to exist, in addition to the default "admin" + Role. There is no negative consequence if you choose not to create these + Roles. They can be created with the following commands:: + + openstack role create baremetal_admin + openstack role create baremetal_observer + + If you choose to customize the names of Roles used with the Bare Metal + service, do so by changing the "is_member", "is_observer", and "is_admin" + policy settings in ``/etc/ironic/policy.json``. + + More complete documentation on managing Users and Roles within your + OpenStack deployment are outside the scope of this document, but may be + found here_. + +#. You can further restrict access to the Bare Metal service by creating a + separate "baremetal" Project, so that Bare Metal resources (Nodes, Ports, + etc) are only accessible to members of this Project:: + + openstack project create baremetal + + At this point, you may grant read-only access to the Bare Metal service API + without granting any other access by issuing the following commands:: + + openstack user create \ + --domain default --project-domain default --project baremetal \ + --password PASSWORD USERNAME + openstack role add \ + --user-domain default --project-domain default --project baremetal\ + --user USERNAME baremetal_observer + +#. Further documentation is available elsewhere for the ``openstack`` + `command-line client`_ and the Identity_ service. A policy.json.sample_ + file, which enumerates the service's default policies, is provided for + your convenience with the Bare Metal Service. + +.. _Identity: http://docs.openstack.org/admin-guide/identity-management.html +.. _`command-line client`: http://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html +.. _here: http://docs.openstack.org/admin-guide/identity-concepts.html#user-management +.. _policy.json.sample: https://github.com/openstack/ironic/blob/master/etc/ironic/policy.json.sample Set up the database for Bare Metal @@ -138,9 +183,9 @@ MySQL database that is used by other OpenStack services. # mysql -u root -p mysql> CREATE DATABASE ironic CHARACTER SET utf8; mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \ - IDENTIFIED BY 'IRONIC_DBPASSWORD'; + IDENTIFIED BY 'IRONIC_DBPASSWORD'; mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \ - IDENTIFIED BY 'IRONIC_DBPASSWORD'; + IDENTIFIED BY 'IRONIC_DBPASSWORD'; Install the Bare Metal service ------------------------------ @@ -152,13 +197,13 @@ Install the Bare Metal service Fedora 21/RHEL7/CentOS7: sudo yum install openstack-ironic-api openstack-ironic-conductor \ - python-ironicclient + python-ironicclient sudo systemctl enable openstack-ironic-api openstack-ironic-conductor sudo systemctl start openstack-ironic-api openstack-ironic-conductor Fedora 22 or higher: sudo dnf install openstack-ironic-api openstack-ironic-conductor \ - python-ironicclient + python-ironicclient sudo systemctl enable openstack-ironic-api openstack-ironic-conductor sudo systemctl start openstack-ironic-api openstack-ironic-conductor @@ -227,17 +272,18 @@ Configuring ironic-api service # "keystone" or "noauth". "noauth" should not be used in a # production environment because all authentication will be # disabled. (string value) - #auth_strategy=keystone + auth_strategy=keystone [keystone_authtoken] ... - # Complete public Identity API endpoint (string value) - auth_uri=http://IDENTITY_IP:5000/ + # Authentication type to load (string value) + auth_type = v3password - # Complete admin Identity API endpoint. This should specify - # the unversioned root endpoint e.g. https://localhost:35357/ - # (string value) - identity_uri=http://IDENTITY_IP:35357/ + # Complete public Identity API endpoint (string value) + auth_uri=http://PUBLIC_IDENTITY_IP:5000/v3/ + + # Complete admin Identity API endpoint. (string value) + auth_url=http://PRIVATE_IDENTITY_IP:35357/v3/ # Service username. (string value) admin_user=ironic diff --git a/doc/source/deploy/security.rst b/doc/source/deploy/security.rst index 3964c72c75..0005c3a579 100644 --- a/doc/source/deploy/security.rst +++ b/doc/source/deploy/security.rst @@ -1,29 +1,49 @@ .. _security: -======== -Security -======== - -Overview -======== +================= +Security Overview +================= While the Bare Metal service is intended to be a secure application, it is important to understand what it does and does not cover today. Deployers must properly evaluate their use case and take the appropriate -actions to secure their environment appropriately. This document is intended to -provide an overview of what risks an operator of the Bare Metal service should -be aware of. It is not intended as a How-To guide for securing a data center -or an OpenStack deployment. +actions to secure their environment(s). This document is intended to provide an +overview of what risks an operator of the Bare Metal service should be aware +of. It is not intended as a How-To guide for securing a data center or an +OpenStack deployment. .. TODO: add "Security Considerations for Network Boot" section .. TODO: add "Credential Storage and Management" section -.. TODO: add "Securing Ironic's REST API" section - .. TODO: add "Multi-tenancy Considerations" section + +REST API: user roles and policy settings +======================================== + +Beginning with the Newton (6.1.0) release, the Bare Metal service allows +operators significant control over API access: + +* Access may be restricted to each method (GET, PUT, etc) for each + REST resource. Defaults are provided with the release and defined in code. +* Access may be divided between an "administrative" role with full access and + "observer" role with read-only access. By default, these roles are assigned + the names ``baremetal_admin`` and ``baremetal_observer``, respectively. +* As before, passwords may be hidden in ``driver_info``. + +Prior to the Newton (6.1.0) release, the Bare Metal service only supported two +policy options: + +* API access may be secured by a simple policy rule: users with administrative + privileges may access all API resources, whereas users without administrative + privileges may only access public API resources. +* Passwords contained in the ``driver_info`` field may be hidden from all API + responses with the ``show_password`` policy setting. This defaults to always + hide passwords, regardless of the user's role. + + Firmware security ================= diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index edcff22677..4daad342a8 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -462,6 +462,13 @@ up to date and has the latest packages installed before beginning this process. http://docs.openstack.org/developer/devstack/ +.. note:: + The devstack "demo" tenant is now granted the "baremetal_observer" role + and thereby has read-only access to ironic's API. This is sufficient for + all the examples below. Should you want to create or modify bare metal + resources directly (ie. through ironic rather than through nova) you will + need to use the devstack "admin" tenant. + Devstack will no longer create the user 'stack' with the desired permissions, but does provide a script to perform the task:: @@ -609,7 +616,7 @@ Run stack.sh:: ./stack.sh -Source credentials, create a key, and spawn an instance:: +Source credentials, create a key, and spawn an instance as the ``demo`` user:: source ~/devstack/openrc @@ -618,22 +625,22 @@ Source credentials, create a key, and spawn an instance:: # create keypair ssh-keygen - nova keypair-add default --pub-key ~/.ssh/id_rsa.pub + openstack keypair create --public-key ~/.ssh/id_rsa.pub default # spawn instance - nova boot --flavor baremetal --image $image --key-name default testing + openstack server create --flavor baremetal --image $image --key-name default testing .. note:: Because devstack create multiple networks, we need to pass an additional parameter ``--nic net-id`` to the nova boot command when using the admin account, for example:: - net_id=$(neutron net-list | egrep "$PRIVATE_NETWORK_NAME"'[^-]' | awk '{ print $2 }') + net_id=$(openstack network list | egrep "$PRIVATE_NETWORK_NAME"'[^-]' | awk '{ print $2 }') - nova boot --flavor baremetal --nic net-id=$net_id --image $image --key-name default testing + openstack server create --flavor baremetal --nic net-id=$net_id --image $image --key-name default testing -As the demo tenant, you should now see a Nova instance building:: +You should now see a Nova instance building:: - nova list + openstack server list +--------------------------------------+---------+--------+------------+-------------+----------+ | ID | Name | Status | Task State | Power State | Networks | +--------------------------------------+---------+--------+------------+-------------+----------+ @@ -644,9 +651,7 @@ Nova will be interfacing with Ironic conductor to spawn the node. On the Ironic side, you should see an Ironic node associated with this Nova instance. It should be powered on and in a 'wait call-back' provisioning state:: - # Note that 'ironic' calls must be made with admin credentials - . ~/devstack/openrc admin admin - ironic node-list + openstack baremetal node list +--------------------------------------+--------------------------------------+-------------+--------------------+ | UUID | Instance UUID | Power State | Provisioning State | +--------------------------------------+--------------------------------------+-------------+--------------------+ @@ -671,7 +676,7 @@ This provisioning process may take some time depending on the performance of the host system, but Ironic should eventually show the node as having an 'active' provisioning state:: - ironic node-list + openstack baremetal node list +--------------------------------------+--------------------------------------+-------------+--------------------+ | UUID | Instance UUID | Power State | Provisioning State | +--------------------------------------+--------------------------------------+-------------+--------------------+ @@ -683,9 +688,7 @@ the host system, but Ironic should eventually show the node as having an This should also be reflected in the Nova instance state, which at this point should be ACTIVE, Running and an associated private IP:: - # Note that 'nova' calls must be made with the credentials of the demo tenant - . ~/devstack/openrc demo demo - nova list + openstack server list +--------------------------------------+---------+--------+------------+-------------+------------------+ | ID | Name | Status | Task State | Power State | Networks | +--------------------------------------+---------+--------+------------+-------------+------------------+