Hi,
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)
https://wiki.openstack.org/wiki/OpsGuide/acknowledgements
https://wiki.openstack.org/wiki/OpsGuide/app-crypt
...
Best regards,
Yuki
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
<annegen...@justwriteclick.com <mailto:annegen...@justwriteclick.com>>
wrote:
On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
<yu-kas...@kddi-research.jp <mailto:yu-kas...@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
<d...@doughellmann.com <mailto:d...@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@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@lists.openstack.org
<mailto:OpenStack-operators@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-kas...@kddilabs.jp <mailto:yu-kas...@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@lists.openstack.org
<mailto:OpenStack-operators@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 <mihali...@gmail.com <mailto:mihali...@gmail.com>>
--
---------------------------------------------
KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
yu-kas...@kddilabs.jp
+81 80 9048 8405
= 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.
[[File:figures/edit_project_member.png|frame|none]]
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>.
<blockquote>'''warning'''
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.
</blockquote>
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)~~~~
}</pre>
# 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.
_______________________________________________
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
