[Openstack-operators] [OpenStack-docs] [doc] Operations Guide removal

Yuki Kasuya yu-kasuya at kddi-research.jp
Mon Aug 14 01:44:54 UTC 2017


How about that if some directives can be ignored (using pandoc), I'll 
create one new ops-guide page as a example on wiki. After that could you 
review it ? I don't know any approval to create/edit pages on wiki. Or I 
can send you converting files. Attached is a converting example.
And let's discuss which url is good for new ops-guides like below. Which 
is good using file name or first header as url of wiki? And which 
directory is fine?

https://wiki.openstack.org/wiki/OpsGuide (as index)

Best regards,

On 8/12/17 23:38, Chris Morgan wrote:
> I just got back from the ops meetup in Mexico City and I think I
> volunteered to help with this ops guide transition and maintaining it on
> the wiki. So if the current output of the conversion is available
> anywhere for review I could try being a proofreader for it. It seems
> there is approval to put it as is on the wiki, what does that require?
> I am not very familiar with the docs build process so if we are still
> attempting to get a minimally viable conversion I may be able to help
> but will need more time to come up to speed with that.
> Chris
> On Thu, Aug 10, 2017 at 8:47 AM, Anne Gentle
> <annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>>
> wrote:
>     On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>     <yu-kasuya at kddi-research.jp <mailto:yu-kasuya at kddi-research.jp>> wrote:
>     > Hi,
>     >
>     >
>     > On 7/19/17 23:51, Anne Gentle wrote:
>     >>
>     >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>     <doug at doughellmann.com <mailto:doug at doughellmann.com>>
>     >> wrote:
>     >>>
>     >>> Excerpts from Blair Bethwaite's message of 2017-07-19 20:40:25
>     +1000:
>     >>>>
>     >>>> Hi Alex,
>     >>>>
>     >>>> I just managed to take a half hour to look at this and have a few
>     >>>> questions/comments towards making a plan for how to proceed with
>     >>>> moving the Ops Guide content to the wiki...
>     >>>>
>     >>>> 1) Need to define wiki location and structure. Curiously at the
>     moment
>     >>>> there is already meta content at
>     >>>> https://wiki.openstack.org/wiki/Documentation/OpsGuide
>     <https://wiki.openstack.org/wiki/Documentation/OpsGuide>, Maybe the
>     >>>> content could live at https://wiki.openstack.org/wiki/OpsGuide
>     <https://wiki.openstack.org/wiki/OpsGuide>? I
>     >>>> think it makes sense to follow the existing structure with possible
>     >>>> exception of culling wrong / very-out-of-date content (but perhaps
>     >>>> anything like that should be done as a later step and keep it
>     simple
>     >>>> aiming for a "like-for-like" migration to start with)...?
>     >>>
>     >>>
>     >>> Yes, I would recommend moving the existing content and then
>     making any
>     >>> major changes to it.
>     >>>
>     >>>> 2) Getting the content into the wiki. Looks like there is no
>     obvious
>     >>>> up-to-date RST import functionality for MediaWiki. Pandoc seems as
>     >>>> though it might support some useful conversions but I didn't
>     try this
>     >>>> yet and don't have any experience with it - can anyone say with
>     >>>> authority whether it is worth pursuing?
>     >>>
>     >>>
>     >>> I can't say with authority myself, but I can refer to Anne as an
>     >>> authority. :-)
>     >>
>     >>
>     >> Ha, well, I think Pandoc is the one to try first, let's say that for
>     >> starters.
>     >>
>     >> Here's what I was thinking:
>     >> If you're interested in the export, run an experiment with Pandoc to
>     >> convert from RST to Mediawiki.
>     >>
>     >> http://pandoc.org/demos.html
>     >>
>     >> You'll likely still have cleanup but it's a start. Only convert
>     >> troubleshooting to start, which gets the most hits:
>     docs.openstack.org/ <http://docs.openstack.org/>
>     >> ops-guide/ops-network-troubleshooting.html
>     >> Then see how much you get from Pandoc.
>     >>
>     >
>     > I tried to convert all docs under ops-guide dir using pandoc. Like below,
>     > toctree,term and some directives doesn't work after converting. But, at
>     > glance, almost fine after converting.
>     > If you don't mind, I'll able to create wiki pages of ops-guide.
>     >
>     > xxx at devstack02:~/work/openstack-manuals/doc/ops-guide/source$ pandoc
>     > index.rst -t mediawiki -o index
>     > .wiki
>     > pandoc: ignoring unknown directive: toctree "source" (line 58, column 1)
>     > pandoc: ignoring unknown role :term: in "source" (line 20, column 13)
>     > pandoc: ignoring unknown role :term: in "source" (line 19, column 59)
>     >
>     Fantastic! That's better that I thought it would do, I'll admit. :)
>     You may have figured this out, but :term: [1] is for glossary entries,
>     and a toctree directive [2] is for a table of contents insertion.
>     Thanks for testing the theory and making it practical.
>     Anne
>     1. http://www.sphinx-doc.org/en/stable/markup/inline.html
>     <http://www.sphinx-doc.org/en/stable/markup/inline.html>
>     2. http://www.sphinx-doc.org/en/stable/markup/toctree.html
>     <http://www.sphinx-doc.org/en/stable/markup/toctree.html>
>     >>
>     >> Hope this helps -
>     >> Anne
>     >>
>     >>>
>     >>>> 3) Future management - obvious can of worms given this is much better
>     >>>> addressed by all the tooling and scaffolding the docs team already
>     >>>> provides around the repos... but nonetheless some expectations may
>     >>>> need to be set upfront to avoid future pain.
>     >>>
>     >>>
>     >>> What sort of issues do you foresee?
>     >>>
>     >>> Doug
>     >>>
>     >>> _______________________________________________
>     >>> OpenStack-operators mailing list
>     >>> OpenStack-operators at lists.openstack.org
>     <mailto:OpenStack-operators at lists.openstack.org>
>     >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>     >>
>     >>
>     >>
>     >>
>     >
>     > --
>     > ---------------------------------------------
>     > KDDI Research, Inc.
>     > Integrated Core Network Control
>     > And Management Laboratory
>     > Yuki Kasuya
>     > yu-kasuya at kddilabs.jp <mailto:yu-kasuya at kddilabs.jp>
>     > +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>     --
>     Read my blog: justwrite.click
>     Subscribe to Docs|Code: docslikecode.com <http://docslikecode.com>
>     _______________________________________________
>     OpenStack-operators mailing list
>     OpenStack-operators at lists.openstack.org
>     <mailto:OpenStack-operators at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
> --
> Chris Morgan <mihalis68 at gmail.com <mailto:mihalis68 at gmail.com>>

KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
yu-kasuya at kddilabs.jp
+81 80 9048 8405
-------------- next part --------------
= User Management =

The OpenStack Dashboard provides a graphical interface to manage users. This section describes user management with the Dashboard.

You can also [https://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html manage projects, users, and roles] from the command-line clients.

In addition, many sites write custom tools for local needs to enforce local policies and provide levels of self-service to users that are not currently available with packaged tools.

== Creating New Users ==

To create a user, you need the following information:

* Username
* Description
* Email address
* Password
* Primary project
* Role
* Enabled

Username and email address are self-explanatory, though your site may have local conventions you should observe. The primary project is simply the first project the user is associated with and must exist prior to creating the user. Role is almost always going to be "member." Out of the box, OpenStack comes with two roles defined:

; member
: A typical user
; admin
: An administrative super user, which has full permissions across all projects and should be used with great care

It is possible to define other roles, but doing so is uncommon.

Once you've gathered this information, creating the user in the dashboard is just another web form similar to what we've seen before and can be found by clicking the Users link in the Identity navigation bar and then clicking the Create User button at the top right.

Modifying users is also done from this Users page. If you have a large number of users, this page can get quite crowded. The Filter search box at the top of the page can be used to limit the users listing. A form very similar to the user creation dialog can be pulled up by selecting Edit from the actions drop-down menu at the end of the line for the user you are modifying.

== Associating Users with Projects ==

Many sites run with users being associated with only one project. This is a more conservative and simpler choice both for administration and for users. Administratively, if a user reports a problem with an instance or quota, it is obvious which project this relates to. Users needn't worry about what project they are acting in if they are only in one project. However, note that, by default, any user can affect the resources of any other user within their project. It is also possible to associate users with multiple projects if that makes sense for your organization.

Associating existing users with an additional project or removing them from an older project is done from the Projects page of the dashboard by selecting Manage Members from the Actions column, as shown in the screenshot below.

From this view, you can do a number of useful things, as well as a few dangerous ones.

The first column of this form, named All Users, includes a list of all the users in your cloud who are not already associated with this project. The second column shows all the users who are. These lists can be quite long, but they can be limited by typing a substring of the username you are looking for in the filter field at the top of the column.

From here, click the + icon to add users to the project. Click the - to remove them.


The dangerous possibility comes with the ability to change member roles. This is the dropdown list below the username in the Project Members list. In virtually all cases, this value should be set to Member. This example purposefully shows an administrative user where this value is <code>admin</code>.


The admin is global, not per project, so granting a user the <code>admin</code> role in any project gives the user administrative rights across the whole cloud.
Typical use is to only create administrative users in a single project, by convention the admin project, which is created by default during cloud setup. If your administrative users also use the cloud to launch and manage instances, it is strongly recommended that you use separate user accounts for administrative access and normal operations and that they be in distinct projects.

=== Customizing Authorization ===

The default authorization settings allow administrative users only to create resources on behalf of a different project. OpenStack handles two kinds of authorization policies:

; Operation based
: Policies specify access criteria for specific operations, possibly with fine-grained control over specific attributes.
; Resource based
: Whether access to a specific resource might be granted or not according to the permissions configured for the resource (currently available only for the network resource). The actual authorization policies enforced in an OpenStack service vary from deployment to deployment.

The policy engine reads entries from the <code>policy.json</code> file. The actual location of this file might vary from distribution to distribution: for nova, it is typically in <code>/etc/nova/policy.json</code>. You can update entries while the system is running, and you do not have to restart services. Currently, the only way to update such policies is to edit the policy file.

The OpenStack service's policy engine matches a policy directly. A rule indicates evaluation of the elements of such policies. For instance, in a <code>compute:create: "rule:admin_or_owner"</code> statement, the policy is <code>compute:create</code>, and the rule is <code>admin_or_owner</code>.

Policies are triggered by an OpenStack policy engine whenever one of them matches an OpenStack API operation or a specific attribute being used in a given operation. For instance, the engine tests the <code>create:compute</code> policy every time a user sends a <code>POST /v2/{tenant_id}/servers</code> request to the OpenStack Compute API server. Policies can be also related to specific API extensions
<API extension>. For instance, if a user needs an extension like <code>compute_extension:rescue</code>, the attributes defined by the provider extensions trigger the rule test for that operation.

An authorization policy can be composed by one or more rules. If more rules are specified, evaluation policy is successful if any of the rules evaluates successfully; if an API operation matches multiple policies, then all the policies must evaluate successfully. Also, authorization rules are recursive. Once a rule is matched, the rule(s) can be resolved to another rule, until a terminal rule is reached. These are the rules defined:

; Role-based rules
: Evaluate successfully if the user submitting the request has the specified role. For instance, <code>"role:admin"</code> is successful if the user submitting the request is an administrator.
; Field-based rules
: Evaluate successfully if a field of the resource specified in the current request matches a specific value. For instance, <code>"field:networks:shared=True"</code> is successful if the attribute shared of the network resource is set to <code>true</code>.
; Generic rules
: Compare an attribute in the resource with an attribute extracted from the user's security credentials and evaluates successfully if the comparison is successful. For instance, <code>"tenant_id:%(tenant_id)s"</code> is successful if the tenant identifier in the resource is equal to the tenant identifier of the user submitting the request.

Here are snippets of the default nova <code>policy.json</code> file:

<pre class="sourceCode none">{
        "context_is_admin":  "role:admin",
        "admin_or_owner":  "is_admin:True", "project_id:%(project_id)s", ~~~~(1)~~~~
        "default": "rule:admin_or_owner", ~~~~(2)~~~~
        "compute:create": "",
        "compute:create:attach_network": "",
        "compute:create:attach_volume": "",
        "compute:get_all": "",
        "admin_api": "is_admin:True",
        "compute_extension:accounts": "rule:admin_api",
        "compute_extension:admin_actions": "rule:admin_api",
        "compute_extension:admin_actions:pause": "rule:admin_or_owner",
        "compute_extension:admin_actions:unpause": "rule:admin_or_owner",
        "compute_extension:admin_actions:migrate": "rule:admin_api",
        "compute_extension:aggregates": "rule:admin_api",
        "compute_extension:certificates": "",
        "compute_extension:flavorextraspecs": "",
        "compute_extension:flavormanage": "rule:admin_api", ~~~~(3)~~~~
# Shows a rule that evaluates successfully if the current user is an administrator or the owner of the resource specified in the request (tenant identifier is equal).
# Shows the default policy, which is always evaluated if an API operation does not match any of the policies in <code>policy.json</code>.
# Shows a policy restricting the ability to manipulate flavors to administrators using the Admin API only.

In some cases, some operations should be restricted to administrators only. Therefore, as a further example, let us consider how this sample policy file could be modified in a scenario where we enable users to create their own flavors:

<pre class="sourceCode none">"compute_extension:flavormanage": "",</pre>
=== Users Who Disrupt Other Users ===

Users on your cloud can disrupt other users, sometimes intentionally and maliciously and other times by accident. Understanding the situation allows you to make a better decision on how to handle the disruption.

For example, a group of users have instances that are utilizing a large amount of compute resources for very compute-intensive tasks. This is driving the load up on compute nodes and affecting other users. In this situation, review your user use cases. You may find that high compute scenarios are common, and should then plan for proper segregation in your cloud, such as host aggregation or regions.

Another example is a user consuming a very large amount of bandwidth. Again, the key is to understand what the user is doing. If she naturally needs a high amount of bandwidth, you might have to limit her transmission rate as to not affect other users or move her to an area with more bandwidth available. On the other hand, maybe her instance has been hacked and is part of a botnet launching DDOS attacks. Resolution of this issue is the same as though any other server on your network has been hacked. Contact the user and give her time to respond. If she doesn't respond, shut down the instance.

A final example is if a user is hammering cloud resources repeatedly. Contact the user and learn what he is trying to do. Maybe he doesn't understand that what he's doing is inappropriate, or maybe there is an issue with the resource he is trying to access that is causing his requests to queue or lag.

More information about the OpenStack-operators mailing list