openstack/openstack-manuals
Code Issues Proposed changes

Testing including content based on meta definitions

Browse Source 
- To try it yourself, use:
sphinx-build -t admin_only \
doc/playground-user-guide/source/ \
doc/playground-user-guide/build/html/.
- Adds a simple scope.py extension, is this the right place for the extension
to be maintained, or should it go to openstack-doc-tools repo?
- This approach is a file-by-file approach for conditionals and will not do
conditional output based on a smaller chunk, such as a note or paragraph. Is
this a good approach for the RST migration? I have also investigated smaller
chunks with the .. only:: directive but it is wonky with non-para content such
as admonitions, tables, list items.

Change-Id: Ia9a44ea45319c97073ab4de55320c1851def232e
This commit is contained in:
Anne Gentle 2015-02-11 14:57:24 -06:00
parent 3c565ab973
commit a7cebe06be
5 changed files with 711 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/playground-user-guide/source/conf.py
View File

@ -20,8 +20,9 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
# import os
# import sys
import os
import sys
import openstackdocstheme
@ -30,6 +31,13 @@ import openstackdocstheme
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
# Defines conditions for end user guide and admin user guide
# When a piece of content has an "admin" indicator, it will be
# output with the admin guide. Otherwise it's output for both
# the end user guide and the admin user guide.
# This is the path where you find the scope.py file that does conditional TOCs.
sys.path.append(os.path.abspath('../sphinx-ext/'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -38,7 +46,7 @@ import openstackdocstheme
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
extensions = ['sphinx.ext.ifconfig', 'scope']
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']

4
doc/playground-user-guide/source/index.rst
View File

@ -1,5 +1,5 @@
Welcome to the end user documentation for OpenStack
===================================================
OpenStack User Guide
====================
Contents:

439
doc/playground-user-guide/source/manage_projects_users_and_roles.rst Normal file
View File

@ -0,0 +1,439 @@
.. meta::
:scope: admin_only
=================================
Manage projects, users, and roles
=================================
As a cloud administrator, you manage projects, users, and
roles. Projects are organizational units in the cloud to which
you can assign users. Projects are also known as ``tenants`` or
``accounts``. Users can be members of one or more projects. Roles
define which actions users can perform. You assign roles to
user-project pairs.
You can define actions for OpenStack service roles in the
``/etc/PROJECT``/policy.json files. For example, define actions for
Compute service roles in the ``/etc/nova/policy.json`` file.
You can manage projects, users, and roles independently from each other.
During cloud set up, the operator defines at least one project, user,
and role.
Learn how to add, update, and delete projects and users, assign users to
one or more projects, and change or remove the assignment. To enable or
temporarily disable a project or user, you update that project or user.
You can also change quotas at the project level.
Before you can delete a user account, you must remove the user account
from its primary project.
Before you can run keystone client commands, you must download and
source an OpenStack RC file. See `Download and source the OpenStack RC
file <http://docs.openstack.org/user-guide/content/cli_openrc.html>`__.
Services
~~~~~~~~
To look at your service catalog, use these keystone client commands.
``service-create``
^^^^^^^^^^^^^^^^^^
Keyword arguments:
- Name
- Type
- Description
Example:
.. code::
$ keystone service-create \
--name nova \
--type compute \
--description "Nova Compute Service"
``service-list``
^^^^^^^^^^^^^^^^
Example:
.. code::
$ keystone service-list
``service-get``
^^^^^^^^^^^^^^^
Arguments
- service\_id
Example:
.. code::
$ keystone service-get 08741d8ed88242ca88d1f61484a0fe3b
``service-delete``
^^^^^^^^^^^^^^^^^^
Arguments
- service\_id
Example:
.. code::
$ keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b
Create a tenant (project)
^^^^^^^^^^^^^^^^^^^^^^^^^
A tenant is a group of zero or more users. In nova, a tenant owns
virtual machines. In swift, a tenant owns containers. In the Dashboard,
tenants are represented as projects. Users can be associated with more
than one tenant. Each tenant and user pairing can have a role associated
with it.
#. To list all projects with their ID, name, and whether they are
enabled or disabled:
.. code::
$ keystone tenant-list
.. code::
+----------------------------------+--------------------+---------+
| id | name | enabled |
+----------------------------------+--------------------+---------+
| f7ac731cc11f40efbc03a9f9e1d1d21f | admin | True |
| c150ab41f0d9443f8874e32e725a4cc8 | alt_demo | True |
| a9debfe41a6d4d09a677da737b907d5e | demo | True |
| 9208739195a34c628c58c95d157917d7 | invisible_to_admin | True |
| 3943a53dc92a49b2827fae94363851e1 | service | True |
| 80cab5e1f02045abad92a2864cfd76cb | test_project | True |
+----------------------------------+--------------------+---------+
#. Create a project named ``new-project``:
.. code::
$ keystone tenant-create --name new-project --description 'my new project'
By default, the project is enabled.
.. code::
+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | my new project |
| enabled | True |
| id | 1a4a0618b306462c9830f876b0bd6af2 |
| name | new-project |
+-------------+----------------------------------+
Note the ID for the project so you can update it in the next
procedure.
Update a project
^^^^^^^^^^^^^^^^
Specify the project ID to update a project. You can update the name,
description, and enabled status of a project.
#. To temporarily disable a project:
.. code::
$ keystone tenant-update PROJECT_ID --enabled false
#. To enable a disabled project:
.. code::
$ keystone tenant-update PROJECT_ID --enabled true
#. To update the name of a project:
.. code::
$ keystone tenant-update PROJECT_ID --name project-new
#. To verify your changes, show information for the updated project:
.. code::
$ keystone tenant-get PROJECT_ID
.. code::
+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | my new project |
| enabled | True |
| id | 1a4a0618b306462c9830f876b0bd6af2 |
| name | project-new |
+-------------+----------------------------------+
Delete a project
^^^^^^^^^^^^^^^^
- To delete a project:
.. code::
$ keystone tenant-delete PROJECT_ID
Create a user
^^^^^^^^^^^^^
#. To list all users:
.. code::
$ keystone user-list
The output shows the ID, name, enabled status, and e-mail address for
each user:
.. code::
+----------------------------------+----------+---------+----------------------+
| id | name | enabled | email |
+----------------------------------+----------+---------+----------------------+
| 352b37f5c89144d4ad0534139266d51f | admin | True | admin@example.com |
| 86c0de739bcb4802b8dc786921355813 | demo | True | demo@example.com |
| 32ec34aae8ea432e8af560a1cec0e881 | glance | True | glance@example.com |
| 7047fcb7908e420cb36e13bbd72c972c | nova | True | nova@example.com |
+----------------------------------+----------+---------+----------------------+
#. To create a user, you must specify a name. Optionally, you can
specify a tenant ID, password, and email address. It is recommended
that you include the tenant ID and password because the user cannot
log in to the dashboard without this information.
To create the ``new-user`` user:
.. code::
$ keystone user-create --name new-user --tenant_id 1a4a0618b306462c9830f876b0bd6af2 --pass PASSWORD
.. code::
+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| email | |
| enabled | True |
| id | 6e5140962b424cb9814fb172889d3be2 |
| name | new-user |
| tenantId | 1a4a0618b306462c9830f876b0bd6af2 |
+----------+----------------------------------+
Update a user
^^^^^^^^^^^^^
You can update the name, email address, and enabled status for a user.
#. To temporarily disable a user account:
.. code::
$ keystone user-update USER_ID --enabled false
If you disable a user account, the user cannot log in to the
dashboard. However, data for the user account is maintained, so you
can enable the user at any time.
#. To enable a disabled user account:
.. code::
$ keystone user-update USER_ID --enabled true
#. To change the name and description for a user account:
.. code::
$ keystone user-update USER_ID --name user-new --email new-user@example.com
.. code::
User has been updated.
Delete a user
^^^^^^^^^^^^^
- To delete a specified user account:
.. code::
$ keystone user-delete USER_ID
Create and assign a role
^^^^^^^^^^^^^^^^^^^^^^^^
Users can be members of multiple projects. To assign users to multiple
projects, define a role and assign that role to a user-project pair.
#. To list the available roles:
.. code::
$ keystone role-list
.. code::
+----------------------------------+---------------+
| id | name |
+----------------------------------+---------------+
| 71ccc37d41c8491c975ae72676db687f | Member |
| 149f50a1fe684bfa88dae76a48d26ef7 | ResellerAdmin |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| 6ecf391421604da985db2f141e46a7c8 | admin |
| deb4fffd123c4d02a907c2c74559dccf | anotherrole |
+----------------------------------+---------------+
#. To create the ``new-role`` role:
.. code::
$ keystone role-create --name new-role
.. code::
+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | bef1f95537914b1295da6aa038ef4de6 |
| name | new-role |
+----------+----------------------------------+
#. To assign a user to a project, you must assign the role to a
user-project pair. To do this, you need the user, role, and project
IDs.
#. To list users:
.. code::
$ keystone user-list
.. code::
+----------------------------------+----------+---------+----------------------+
| id | name | enabled | email |
+----------------------------------+----------+---------+----------------------+
| 352b37f5c89144d4ad0534139266d51f | admin | True | admin@example.com |
| 981422ec906d4842b2fc2a8658a5b534 | alt_demo | True | alt_demo@example.com |
| 036e22a764ae497992f5fb8e9fd79896 | cinder | True | cinder@example.com |
| 86c0de739bcb4802b8dc786921355813 | demo | True | demo@example.com |
| 32ec34aae8ea432e8af560a1cec0e881 | glance | True | glance@example.com |
| 7047fcb7908e420cb36e13bbd72c972c | nova | True | nova@example.com |
+----------------------------------+----------+---------+----------------------+
Note the ID of the user to which you want to assign the role.
#. To list role IDs:
.. code::
$ keystone role-list
.. code::
+----------------------------------+---------------+
| id | name |
+----------------------------------+---------------+
| 71ccc37d41c8491c975ae72676db687f | Member |
| 149f50a1fe684bfa88dae76a48d26ef7 | ResellerAdmin |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| 6ecf391421604da985db2f141e46a7c8 | admin |
| deb4fffd123c4d02a907c2c74559dccf | anotherrole |
| bef1f95537914b1295da6aa038ef4de6 | new-role |
+----------------------------------+---------------+
Note the ID of the role that you want to assign.
#. To list projects:
.. code::
$ keystone tenant-list
.. code::
+----------------------------------+--------------------+---------+
| id | name | enabled |
+----------------------------------+--------------------+---------+
| f7ac731cc11f40efbc03a9f9e1d1d21f | admin | True |
| c150ab41f0d9443f8874e32e725a4cc8 | alt_demo | True |
| a9debfe41a6d4d09a677da737b907d5e | demo | True |
| 9208739195a34c628c58c95d157917d7 | invisible_to_admin | True |
| caa9b4ce7d5c4225aa25d6ff8b35c31f | new-user | True |
| 1a4a0618b306462c9830f876b0bd6af2 | project-new | True |
| 3943a53dc92a49b2827fae94363851e1 | service | True |
| 80cab5e1f02045abad92a2864cfd76cb | test_project | True |
+----------------------------------+--------------------+---------+
Note the ID of the project to which you want to assign the role.
#. Assign a role to a user-project pair. In this example, you assign the
``new-role`` role to the ``demo`` and ``test-project`` pair:
.. code::
$ keystone user-role-add --user USER_ID --role ROLE_ID --tenant TENANT_ID
#. To verify the role assignment:
.. code::
$ keystone user-role-list --user USER_ID --tenant TENANT_ID
.. code::
+----------------------------------+----------+----------------------------------+----------------------------------+
| id | name | user_id | tenant_id |
+----------------------------------+----------+----------------------------------+----------------------------------+
| bef1f95537914b1295da6aa038ef4de6 | new-role | 86c0de739bcb4802b8dc786921355813 | 80cab5e1f02045abad92a2864cfd76cb |
+----------------------------------+----------+----------------------------------+----------------------------------+
#. To get details for a specified role:
.. code::
$ keystone role-get ROLE_ID
.. code::
+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | bef1f95537914b1295da6aa038ef4de6 |
| name | new-role |
+----------+----------------------------------+
#. To remove a role from a user-project pair:
.. code::
$ keystone user-role-remove --user USER_ID --role ROLE_ID --tenant TENANT_ID
#. To verify the role removal, run the following command:
.. code::
$ keystone user-role-list --user USER_ID --tenant TENANT_ID
If the role was removed, the command output omits the removed role.

204
doc/playground-user-guide/source/nova_cli_manage_projects_security.rst Normal file
View File

@ -0,0 +1,204 @@
.. meta::
:scope: admin_only
=======================
Manage project security
=======================
Security groups are sets of IP filter rules that are applied to all
project instances, which define networking access to the instance. Group
rules are project specific; project members can edit the default rules
for their group and add new rule sets.
All projects have a "default" security group which is applied to any
instance that has no other defined security group. Unless you change the
default, this security group denies all incoming traffic and allows only
outgoing traffic to your instance.
You can use the ``allow_same_net_traffic`` option in the
``/etc/nova/nova.conf`` file to globally control whether the rules apply
to hosts which share a network.
If set to:
- ``True`` (default), hosts on the same subnet are not filtered and are
allowed to pass all types of traffic between them. On a flat network,
this allows all instances from all projects unfiltered communication.
With VLAN networking, this allows access between instances within the
same project. You can also simulate this setting by configuring the
default security group to allow all traffic from the subnet.
- ``False``, security groups are enforced for all connections.
Additionally, the number of maximum rules per security group is
controlled by the ``security_group_rules`` and the number of allowed
security groups per project is controlled by the ``security_groups``
quota.
**Procedure: List and view current security groups**
From the command line you can get a list of security groups for the
project, using the nova command:
#. Ensure your system variables are set for the user and tenant for
which you are checking security group rules for. For example:
.. code::
export OS_USERNAME=demo00
export OS_TENANT_NAME=tenant01
#. Output security groups, as follows:
.. code::
$ nova secgroup-list
+---------+-------------+
| Name | Description |
+---------+-------------+
| default | default |
| open | all ports |
+---------+-------------+
#. View the details of a group, as follows:
.. code::
$ nova secgroup-list-rules groupName
For example:
.. code::
$ nova secgroup-list-rules open
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| icmp | -1 | 255 | 0.0.0.0/0 | |
| tcp | 1 | 65535 | 0.0.0.0/0 | |
| udp | 1 | 65535 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+
These rules are allow type rules as the default is deny. The first
column is the IP protocol (one of icmp, tcp, or udp). The second and
third columns specify the affected port range. The third column
specifies the IP range in CIDR format. This example shows the full
port range for all protocols allowed from all IPs.
**Procedure: Create a security group**
When adding a new security group, you should pick a descriptive but
brief name. This name shows up in brief descriptions of the instances
that use it where the longer description field often does not. For
example, seeing that an instance is using security group "http" is much
easier to understand than "bobs\_group" or "secgrp1".
#. Ensure your system variables are set for the user and tenant for
which you are checking security group rules for.
#. Add the new security group, as follows:
.. code::
$ nova secgroup-create Group Name Description
For example:
.. code::
$ nova secgroup-create global_http "Allows Web traffic anywhere on the Internet."
+--------------------------------------+-------------+----------------------------------------------+
| Id | Name | Description |
+--------------------------------------+-------------+----------------------------------------------+
| 1578a08c-5139-4f3e-9012-86bd9dd9f23b | global_http | Allows Web traffic anywhere on the Internet. |
+--------------------------------------+-------------+----------------------------------------------+
#. Add a new group rule, as follows:
.. code::
$ nova secgroup-add-rule secGroupName ip-protocol from-port to-port CIDR
The arguments are positional, and the "from-port" and "to-port"
arguments specify the local port range connections are allowed to
access, not the source and destination ports of the connection. For
example:
.. code::
$ nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+
You can create complex rule sets by creating additional rules. For
example, if you want to pass both HTTP and HTTPS traffic, run:
.. code::
$ nova secgroup-add-rule global_http tcp 443 443 0.0.0.0/0
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+
Despite only outputting the newly added rule, this operation is
additive (both rules are created and enforced).
#. View all rules for the new security group, as follows:
.. code::
$ nova secgroup-list-rules global_http
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | |
| tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+
**Procedure 3. Delete a security group**
#. Ensure your system variables are set for the user and tenant for
which you are deleting a security group for.
#. Delete the new security group, as follows:
.. code::
$ nova secgroup-delete GroupName
For example:
.. code::
$ nova secgroup-delete global_http
**Procedure 4. Create security group rules for a cluster of instances**
Source Groups are a special, dynamic way of defining the CIDR of allowed
sources. The user specifies a Source Group (Security Group name), and
all the users' other Instances using the specified Source Group are
selected dynamically. This alleviates the need for individual rules to
allow each new member of the cluster.
#. Make sure to set the system variables for the user and tenant for
which you are deleting a security group for.
#. Add a source group, as follows:
.. code::
$ nova secgroup-add-group-rule secGroupName source-group ip-protocol from-port to-port
For example:
.. code::
$ nova secgroup-add-group-rule cluster global_http tcp 22 22
The ``cluster`` rule allows ssh access from any other instance that
uses the ``global_http`` group.

55
doc/playground-user-guide/sphinx-ext/scope.py Normal file
View File

@ -0,0 +1,55 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import os
import re
from sphinx import addnodes
docs_for_admin = []
def setup(app):
app.ignore = []
app.connect('builder-inited', builder_inited)
app.connect('env-get-outdated', env_get_outdated)
app.connect('doctree-read', doctree_read)
def builder_inited(app):
for doc in app.env.found_docs:
first_directive = None
path = os.path.join(app.env.srcdir, doc + app.env.config.source_suffix)
with open(path, 'r') as f:
first_directive = f.readline() + f.readline()
if first_directive:
m = re.match(r'^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)',
first_directive)
if m and not app.tags.has(m.group(1)):
docs_for_admin.append(doc)
app.env.found_docs.difference_update(docs_for_admin)
def env_get_outdated(app, env, added, changed, removed):
added.difference_update(docs_for_admin)
changed.difference_update(docs_for_admin)
removed.update(docs_for_admin)
return []
def doctree_read(app, doctree):
for toctreenode in doctree.traverse(addnodes.toctree):
for e in toctreenode['entries']:
ref = str(e[1])
if ref in docs_for_admin:
toctreenode['entries'].remove(e)