External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-01-22 23:18:03 -03:30
Code Issues Packages Projects Releases Wiki Activity

These are stale docs files, see doc repo (private) for official docs.

Browse Source 
This dir internal use.
This commit is contained in:
Michael DeHaan 2013-07-11 10:58:26 -04:00
parent 6e28fac463
commit 31d77b3bab
4 changed files with 0 additions and 909 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/TODO.md
View File

@ -1,60 +0,0 @@
TODO items for ansible commander
================================
CC TODO
=======
* supervisord to start celery, modify ansible playbook to set up supervisord <- ChrisC
* documentation on how to run with callbacks from NOT a launchjob <-- ChrisC
* default_playbook should be relative to scm_repository and not allow "../" out of the directory
* do we need something other than default playbook (ProjectOptions) <-- MPD later
* make a way to start a job via the API (create a new job) <-- MPD
* make job rest triggerable & job status readable. now happens just by creating a new job <-- MPD
* figure out how to mark each object generically w/ whether it can be edited/etc
* if you delete a subgroup, hosts go up to parent
* verify unique_together on inventory and host name
* finish REST around permissions <-- MPD
* tags (later)
* audit trails (later)
* related resources on everything that makes sense <--- MPD, important
* make /api and /api/v1 have useful content in it
LATER
=====
* clean up initial migrations
* init scripts (supervisord), Apache proxying, etc
* support multiple project launch options (different flags, etc)
TWEAKS/ASSORTED
---------------
* security check - playbook must be fully pathed when executed by commander and relative to project
directory. Project directories must be unique and be (also no ../, etc). default_playbook MUST be a relative path (no starting with . or / or containing ..).
* idea: when creating a project, write a '.acom' file, this file contains a JSON list of valid project GUIDs that are allowed to use it. This can be created automatically by the system if it does not already exist, but not overwritten by the system.
* document multi-org content limitations with regard to access security and sensitive vars
* when app starts it creates a default organization and all superusers are automatically added to it
* audit/test read only fields like creation_date
* ability to import inventory from script (adds variables and merges, does not override, does not remove anything) -- merge control, possibly via script
* ability to import inventory from inventory files (upgrade case) -- write a inventory script that is ansible-inventory API compatible maybe?
* when associating inventory objects, objects should share common inventory records (user_can_attach method should check)
* permissions on launching a job should be same as creating a job template
* should be able to access permissions as subcollection off of users or teams (no need for permissions tab)
* make sure all can_user_add/edit methods ensure ownership/access on subobjects
* project should have a method to list valid YAML files and not require default playbook
* do not allow ../ in paths (etc)
* should be able to specify in a launch job a limit string, combine with shell=False when using subprocess
QUESTIONS
---------
* if creating a new project, do we want to have an appliance style path for them, like /storage/projects/GUID ??? may want to keep somewhere else ?
* for dashboard purposes, should there be a URL where I can see all hosts in an inventory whose last job status
is a failed playbook run?
* what else do we need for dashboarding?

392
docs/api2.md
View File

@ -1,392 +0,0 @@
API Overview
============
This was an early sketch of the API.
Just use this as an idea of what we want to shoot for,
there will be formal API docs soon.
Versioning and Semantics
========================
* All results will either be JSON lists or hashes.
* Only new fields will be added.
* Fields will not be removed.
* URLs are all discoverable, so discover them. Hardcode to prevent against changes, though we'll try not to move anything.
* If you have a 'href' value in JSON, the last part after the last "/", if a number, corresponds to a database ID.
* No IDs will be returned bare, that is, just as integers.
* Objects in list results will be summarized and not include all field info. Usually just an href + type + name + description. Sometimes more.
* All IDs are "big serial" type.
* All JSON returns should have a 'type' in easy structure saying the object type.
Hashes will typically have:
{
'href' : 'http://...' # the resource URL
'name' : 'Fred' # the name of the object (non-unique)
'description' : '...' # some free text describing the object
'tags' : [ # some optional freeform tags
'asdf', 'jkl'
]
'audit_trail': href,
}
API discovery
=============
The root of the API here will be denoted as '/', though for all practical purposes it could be anything.
Getting '/' will return the URLs of other endpoints that are useful. There is no security to get '/',
though everything else requires a username+password. If you first get "/" you can see all of the API URLs
you can use and walk them.
/
GET -- List all of the available API endpoints to enable service discoverability
{
'organizations' : '/orgs',
'users' : '/users',
'projects' : '/projects',
# etc
}
Authentication
==============
An initial user will be created in the database.
URLs require authentication (AuthN) in basic username:password format.
Tokens also supported (/login). TBA.
Authorization varies by URL (see use_cases.md for roles)
Sync scripts will be created to pull from AD and so on.
Pagination
==========
API calls for lists will be paginated.
The default start index will be 0 and the default number of records per page will be 99.
Affix the following the URL to specify differently.
?
Audit Records
=============
Audit trail records are recorded for most edit types.
/audit
GET -- lists all the audit records the user has access to
/audit/#{audit_id}
GET
{
'href' : /audit/12345
'id' : ...
'record_type' : ... # what type of audit trail, for example 'user'
'resource' : href
'date' : ...
'modified_by' : href
'delta' : # for put operations, any fields that are changed, for creation, any added. RAW JSON.
'detail' : some string message set by the system
'comment' : [], comments supplied by the user, if any
'tags' : [] # tags the user may have added, like 'investigate'
}
PUT -- requires org admin
allows modification, but only to set tag fields and add comments. Previous comments
are not edited, so the last comment in the list only will be saved (if different)
Organizations
=============
/orgs
GET -- List all of the available organizations the user is in, or all, if site admin
[
{
'href' : '...',
'id' : 12345,
'name' : 'Finance',
'description' : '...'
}, ...
]
POST -- Add a new organization
/orgs/#{org_id}
GET -- Get the details of an organization
PUT -- Updates an organization
DELETE -- Expires an organization
/orgs/#{org_id}/users/
GET -- Lists users in an organization
POST -- Add a user record to the organization
/orgs/#{org_id}/users/#{user_id}
/orgs/#{org_id}/admins/
GET -- list the admins
POST -- make a user an admin
/orgs/#{org_id}/admins/{#user_id}
DELETE -- demote an admin
Users
=====
/users/
GET - list all users I can see based on my permissions
/users/#{user_id}/
GET - show the specific user if I have permission
DELETE - expires the user but doesn't delete them, requires org admin access
/users/#{user_id}/credentials/
GET - show the credentials set on the user
other ops through the /credentials/#{cred_id} URL
/users/#{user_id}/permissions/
GET - see what permissions the user has assigned, but can't edit here
other ops through the /permissions/#{cred_id} URL
/users/#{user_id}/teams/
GET - see what teams the user has defined, but not editable here
other ops through the /teams/#{team_id} URL
/users/#{user_id}/projects/
GET - see what projects the user is a part of, but you can get this through the indiv teams too
other ops through the /projects/#{project_id} URL
Teams
=====
/teams/
GET -- shows all the teams the user is on, or if admin/org admin, all teams
POST -- make a new team
/teams/#{team_id}/users/
GET -- show users on the team
POST -- add an existing user to the team
/teams/#{team_id}/users/#{user_id}
DELETE -- kick the user off the team
/teams/#{team_id}/projects/
GET -- shows all the projects on the team if you can see the team
POST -- share a project with a team
other ops through /projects/#{project_id}
/teams/#{team_id}/users/
GET -- shows all uses on the team if you can see the team
other ops through /users/#{user_id}
/teams/#{team_id}/credentials
GET -- gets the credential records of the team, recommended for close friends, otherwise upload to user acct
other ops through
/teams/#{team_id}/permissions/
GET -- show all permissions that were assigned to the team
Projects
========
/projects/
GET -- show all the projects the user can see
POST -- make a new project
/projects/#{project_id}
GET -- show the project if someone is allowed to read the info
/projects/#{project_id}/inventory/
GET -- get the inventory records assigned to this project
/projects/#{project_id}/inventory/#{inventory_id}
DELETE -- remove inventory source from project
/projects/#{project_id}/users/
GET -- users on the project
/projects/#{project_id}/users/#{user_id}
DELETE(id) -- remove user from project
POST -- add user to project if allowed
/project/#{project_id}/credentials/
GET -- show credentials on project
/project/#{project_id}/credentials/#{credential_id}
DELETE -- remove credentials
/project/#{project_id}/permissions
GET -- see all the permissions on the project
delete permissions through /permissions/#{permission_id}
Inventory
=========
/inventory/
GET -- see all the inventory sources the user is allowed to see
/inventory/#{inventory_id}
GET -- see the specific source
DELETE -- expire the inventory source if sufficient permission
/inventory/#{inventory_id}/hosts
GET -- see hosts
POST -- add hosts and associate
/inventory/#{inventory_id}/groups
GET -- see groups
POST -- add groups and associate
/inventory/#{inventory_id}/permissions
GET -- see all permissions for everyone granted on the inventory source, if you have access
Hosts
=====
Note: must be created via inventory source
/hosts/
/hosts/#{host_id}
GET -- see the host record
/hosts/#{host_id}/vars
GET -- see the host vars
PUT -- edit them
/hosts/#{host_id}/groups/
GET -- see the groups
POST -- add some more groups to the host
Groups
======
/groups/
GET -- see all the groups the user can see
/groups/#{group_id}
GET -- see the specific group
/groups/#{group_id}/vars
GET -- see the vars
PUT -- edit them
/groups/#{group_id}/hosts/
GET -- see the hosts in the group
POST -- add existing host records to the group
/groups/#{group_id}/subgroups/
GET -- see the direct subgroups
POST - add an existing group to the group as a subgroup
Permissions
=====================
/permissions/
GET -- see all the permissions that map to any of the users contexts (??)
/permissions/#{permission_id}
{
href: href,
project: href,
team: href,
user: href,
inventory: href,
allowed: [
'edit', 'push', 'check', 'view', 'logs'
]
}
GET
DELETE
Jobs
====
/jobs/
GET -- get a list of active jobs you can see
POST -- add a job, rather specific as to what this is...
/jobs/#{job_id}
GET -- get info about a job
DELETE -- remove a job
The most obvious job you will want to do is to deploy a project against an inventory source.
POST /jobs/
{
'inventory_id' : href,
'project_id' : href,
'ansible_tags' : [],
'job_type' : href,
}
and you'll get back an event ID you can poll
{
'id' : href,
'type' : event,
}
Where job_types are in the database too and public:
/job_types/
As are job status types
/job_status_types/
Events
======
/events/
GET -- root of the event service
/events/jobs/
GET -- get all events for the job
/events/jobs/#{job_id}
GET -- event info
{
id: 'href'
type: 'event'
status: 'running'
}
/host_status/
/hosts_status/#{host_id}/status
GET -- get all statuses for the host
{
id: href
date: date
host_id: href
success: true
event_id: href
}
/host_log_records/#{host_log_id}
GET
{
id: href
host_id: href
event_id: href
success: true/false
skipped: true/false
failed: true/false
dark: true/false
}
Reporting
=========
/reporting/ <- incoming messages go here
POST -- accepts remote reporting events. Requires a host id.

383
docs/api_guide.md
View File

@ -1,383 +0,0 @@
API Guide
=========
This document describes how to do nearly everything in Ansible commander via the REST API.
To begin, you should have set up Ansible Commander (see SETUP.md) and created at least one Django super user.
To do this from the development project, run "make adduser".
For the purposes of this guide, we will assume the superuser username and password is admin/admin.
Conventions
===========
* Ansible Commander uses a standard REST API, rooted at /api/v1/ on the server.
* All data is JSON. You may have to specify the content/type on POST or PUT requests accordingly.
* All URIs should end in "/" or you will get a 301 redirect.
Time to get started.
Aside: Django Admin
===================
When working with REST objects it is often helpful to use the Django admin interface to pre-create objects,
and then retrieve collections of objects with GET request to look at their structure. This will help
users understand how to create new objects as well as how to edit them.
Aside: Read Only Fields
=======================
Certain fields in the REST API are marked read only. These usually include the URL of a resource, the ID,
and occasionally some internal fields. For instance, the 'created_by' attribute of each object indicates
which user created the resource, and can not be edited.
A Prelude: Workflow
===================
Assume you are starting out with a blank Ansible Commander instance, and don't intend to use the GUI.
What sort of REST operations do you need to perform to seed everything out and deploy your first
playbook entirely via web services? It would look something like this.
Create Users and Organizations
------------------------------
* Confirm your super user account at /api/v1/me/
* Create some organizations at /api/v1/organizations/
* Create some users by posting to /api/v1/organizations/X/users/
* Add some users to be admins of those organizations by posting to /api/v1/organizations/X/admins/
* At this point, use your org admin account, instead of your superuser account, if you wish
Build Out Inventory
-------------------
* Create an inventory resource by posting to /api/v1/organizations/X/inventories/
* Create a new host by posting to /api/v1/inventories/X/hosts/
* Add the group to inventory at /api/v1/inventories/X/groups/
* PUT variables to /api/v1/hosts/X/variables/
* PUT variables to /api/v1/groups/X/variables/
* POST a subgroup to a group at /api/v1/groups/X/children/
Set Up Projects and Teams
-------------------------
* Create a new project by posting to /api/v1/organizations/X/projects/
* Create some teams at /api/v1/organizations/X/teams/
* Create some projects at /api/v1/organizations/X/projects/
* Assign some projects to one or more teams at /api/v1/teams/X/projects/
Save Login Credentials and Grant Role (Team) Based Permissions
--------------------------------------------------------------
* Add credentials to some teams at /api/v1/teams/X/credentials/ OR
* Add credentials to some users at /api/v1/user/X/credentials/ (no fancy priveledges required)
* Create a permission tuple to allow a user or project to be used with an inventory source at /api/v1/permissions/
or /api/v1/users/permissions or /api/v1/teams/permissions/
* Permission tuples can allow execution, dry run execution, or inventory editing.
Launch Playbooks and View Results
---------------------------------
* Create a job request by posting project, permission, and credential to /api/v1/jobs/
* Monitor the job results at /api/v1/jobs/X (API subject to change)
* See the history of runs on each host at /api/v1/hosts/X/events/ or /api/v1/groups/X/events/ or /api/v1/inventories/X/events/
Audit API based Activity, Search For Resources
----------------------------------------------
* Apply tags or see applied tags on any resource at /api/v1/RESOURCE/X/tags/
* View audit trail information on any resource change at /api/v1/RESOURCE/X/audit_trail/
Working With Users
==================
After a fresh install, there should be no organizations and only the superuser.
Since we're explaining our first resource, we'll be a bit more verbose with the user
information than with some other REST resources.
Listing Users
-------------
We will pay special attention to this first access request, as any list view looks basically
the same.
curl http://admin:admin@127.0.0.1:8013/api/v1/users/
{
"count": 1, "next": null, "previous": null,
"results": [
{
"url": "/api/v1/users/1/",
"id": 1, "username": "admin",
"first_name": "",
"last_name": "",
"email": "root@localhost.localdomain",
"is_active": true,
"is_superuser": true,
"related": {
"admin_of_organizations": "/api/v1/users/1/admin_of_organizations/",
"organizations": "/api/v1/users/1/organizations/",
"teams": "/api/v1/users/1/teams/"
}
}
]
}
Notice that the requests are paginated, so you may have to access additional URLs if 'previous' and 'next'
are set to access the full collection.
You will also see 'related' URLs on each object, which tell you from any point in the API what resources
you can get to from a particular resource.
Adding Users
------------
To add a user, just POST to the users collection:
curl -X POST -d @input http://admin:admin@127.0.0.1:8013/api/v1/users/
{
"username" : "foo", "password: "foo"
}
And optionally specify other fields. Super users or organization admins can create users. We'll learn more about
organizations shortly!
Getting a User
--------------
As you would expect, a user, superuser, or organization admin can retrieve the record of a user directly via:
curl http://admin:admin@127.0.0.1/api/v1/users/1/
And recieves something very much like this:
{
"url": "/api/v1/users/1/",
"id": 1, "username": "admin",
"first_name": "",
"last_name": "",
"email": "root@localhost.localdomain",
"is_active": true,
"is_superuser": true,
"related": {
"admin_of_organizations": "/api/v1/users/1/admin_of_organizations/",
"organizations": "/api/v1/users/1/organizations/",
"teams": "/api/v1/users/1/teams/"
}
}
Deleting Users
--------------
In ansible commander, nothing is truly deleted, objects are only set inactive and renamed. This allows recovery
of those objects using the Django administrative interface or the database command line.
To delete an object, just DELETE to a resource, like so:
curl -X DELETE http://admin:admin@127.0.0.1:8013/api/v1/users/2/
Only a user's organization admins, or a superuser, can mark a user as deleted.
Updating Users
--------------
A user may update only his password, and an organization admin or superuser can update a lot more about the
user. To update a user, just PUT to the resource, like so:
curl -X PUT -d @input http://admin:admin@127.0.0.1:8013/api/v1/users/2/
{
'password': 'new_password'
}
Organizations
=============
Organizations are the basic unit of multi-tenancy and access in Ansible Commander.
At the basic level, when a user is created, he should then be added to one or more organziations.
These may represent concepts like "Engineering" or "Finance".
Under each organization, there will also be multiple teams, like "Engineering QA Team", or "Engineering Release Team".
Organizations also have admin users (which can be assigned by the super user or other organization admins) whom also
have most of the powers of a superuser to users inside that organization.
Listing Organizations
---------------------
GET /api/v1/organizations/
Editing Organizations
---------------------
PUT /api/v1/organizations/1/
Adding users to an organization
-------------------------------
POST the data you recieved from GET /api/v1/users/X/ to /api/v1/organizations/Y/organizations/
Similarly, you can list users of an organization if you are an org admin or superuser with:
GET /api/v1/organizations/X/users/
Note as a shortcut, most related resources in Ansible Commander will allow object creation if you post
a resource without an 'id' field, and have a permission to create that resource.
Adding admins to an organization
--------------------------------
POST the data you recieved from GET /api/v1/users/X/ to /api/v1/organizations/Y/admins/
Similarly, you can list admins of an organization if you are an org admin or superuser, with:
GET /api/v1/organizations/X/admins/
Note that adding a user as an admin does not automatically add them as a regular organization user. If the user
is to be a member of any project teams, add them both to the admin list and the users list for a given organization.
Adding projects to an organization
----------------------------------
An organization may also have projects, which would be a concept like "ACME Corp Application" or "Application Foo".
Projects are covered in a later section, but are added to organizations, once created, by posting the record
recieved from /api/v1/projects/X/ to /api/v1/organizations/Y/.
Removing users, admins, and projects from organizations
-------------------------------------------------------
Deleting from sub-collections in Ansible Commander is not handled by a DELETE verb, but by a modified POST.
To remove a user ID X from an organization Y, simply POST the following to the collection /api/v1/organizations/Y/users/:
{ 'id' : X, 'disassociate' : 1 }
A similar post can also be made to /api/v1/organizations/Y/admins/ to remove an admin user or
/api/v1/organizations/Y/projects/.
The same removal facility is available elsewhere in Ansible commander for most related resources.
Project
========
...
Teams
=====
...
Inventories
===========
...
Adding Inventories
------------------
Adding Hosts
------------
Adding Groups
-------------
Editing Hosts or Groups
-----------------------
Adding Host Variables
---------------------
Adding Group Variables
----------------------
Editing Host or Group Variables
-------------------------------
Removing Host or Group Variables
--------------------------------
Adding Sub Groups
-----------------
Removing Sub Groups
-------------------
Access Via Inventory Script
---------------------------
Credentials
===========
Creating credentials
--------------------
Adding credentials to users, teams, or projects
-----------------------------------------------
Seeing what credentials a user has access to
--------------------------------------------
Launch Jobs
===========
Submitting A Launch Job
-----------------------
Getting Job Results
-------------------
Browsing Log Data
-----------------
Tags
====
Adding Tags
-----------
Finding Tagged Resources
------------------------
Editing/Removing Tags
---------------------
Permissions
===========
Permissions can be granted to users or teams and indicate they are allowed to use
certain combinations of credentials, inventories to deploy to certain projects.
For instance, a permission may define that the QA Team can use certain credentials to push
to a Test Inventory, while another permission may indicate the Release Engineering team can
push a different project with different credentials to a Production inventory source.
Audit Trails
============
Viewing object audit trails
---------------------------
Additional Topics
=================
API Sorting And Filtering
-------------------------
Pagination Controls
-------------------
Alternative Content Types
-------------------------

74
docs/use_cases.md
View File

@ -1,74 +0,0 @@
About
=====
This was an early doc of some of the things we want to be able to do.
As database and plans change, this is not neccessarily our most up
to date plan, but leaving this here for reference.
Roles
=====
a user can be:
Regular User
Site Admin
Org Admin
User on a Team
Regular User
============
* can login
* can logout
* can change some user info but not their username (can change pass)
Site Admin
==========
* probably installed the platform from a playbook before using the tool
* can make user accounts
* can promote users to site admin (or remove that)
* can add existing users to any organization
* is automatically an admin of all orgs
Org Admin
=========
* can create users (they are auto assigned to the org)
* can kick users out of the org
* can promote users to org admin or demote them
* can create an inventory source
* can share an inventory source with a team or user with set permissions
- ability to edit
- ability to push
- ability to run in check mode
- ability to view
- ability to see log data
* can create a project in the org
* can create a team in the org
* can associate a project with one or more teams in the org
* can add users to projects or take them away
A Project
=========
* has a git repository path (previously unused or used exactly once in DB)
* may have credentials
A Credential
============
* ssh key location (new or only used once)
* ssh unlock
* password
* sudo password
* pem file location (new or only used once)
A User
======
* can login
* can logout
* may have credentials
* can push to any inventory source (or check, view, etc) if they have permission on that source via a team membership, directly, an org membership, etc. The links to do so are found in the context of the project. A user may acquire permissions on an inventory source via multiple routes. Permissions are usually locked around a particular project.
* can view logs on hosts if they have similar permissions on that inv. source