Merge pull request #6186 from AlanCoding/scm_inv_stability

SCM Inventory task system and variables stability edits

docs/scm_inventory.md

@@ -1,4 +1,4 @@
-# SCM Flat File Inventory
+# SCM Inventory
 
 Users can create inventory sources that use content in the source tree of
 a project as an Ansible inventory file.
@@ -17,14 +17,29 @@ Additionally:
 
  - `source_vars` - if these are set on a "file" type inventory source
    then they will be passed to the environment vars when running
+ - `update_on_project_update` - if set, a project update of the source
+   project will automatically update this inventory source as a side effect
 
-A user should not be able to update this inventory source via through
-the endpoint `/inventory_sources/N/update/`. Instead, they should update
-the linked project.
+If `update_on_project_update` is not set, then they can manually update
+just the inventory source with a POST to its update endpoint,
+`/inventory_sources/N/update/`.
 
-An update of the project automatically triggers an inventory update within
-the proper context. An update _of the project_ is scheduled immediately
-after creation of the inventory source.
+If `update_on_project_update` is set, the POST to the inventory source's
+update endpoint will trigger an update of the source project, which may,
+in turn, trigger an update of the inventory source.
+Also, with this flag set, an update _of the project_ is
+scheduled immediately after creation of the inventory source.
+Also, if this flag is set, no inventory updates will be triggered
+_unless the scm revision of the project changes_.
+
+### RBAC
+
+User needs `admin` role to the project in order to use it as a source
+project for inventory (this entails permission to run arbitrary scripts).
+To update the project, they need `update` permission to the project,
+even if the update is done indirectly.
+
+### Inventory File Suggestions
 
 The project should show a listing of suggested inventory locations, at the
 endpoint `/projects/N/inventories/`, but this is not a comprehensive list of
@@ -32,6 +47,7 @@ all paths that could be used as an Ansible inventory because of the wide
 range of inclusion criteria. The list will also max out at 50 entries.
 The user should be allowed to specify a location manually in the UI.
 This listing should be refreshed to latest SCM info on a project update.
+
 If no inventory sources use a project as an SCM inventory source, then
 the inventory listing may not be refreshed on update.
 
@@ -47,7 +63,7 @@ update the project.
 > Any Inventory Ansible supports should be supported by this feature
 
 This is accomplished by making use of the `ansible-inventory` command.
-the inventory import tower-manage command will check for the existnce
+the inventory import tower-manage command will check for the existence
 of `ansible-inventory` and if it is not present, it will call a backported
 version of it. The backport is maintained as its own GPL3 licensed
 repository.
@@ -83,9 +99,9 @@ standard use.
 
 ## Update-on-launch
 
-This type of inventory source will not allow the `update_on_launch` field
-to be set to True. This is because of concerns related to the task
-manager job dependency tree.
+If the SCM inventory source is configured to follow the project updates,
+the `update_on_launch` field can not to be set to True. This is because
+of concerns related to the task manager job dependency tree.
 
 We should document the alternatives for a user to accomplish the same thing
 through in a different way.
@@ -110,8 +126,3 @@ until the inventory update is finished.
 
 Note that a failed inventory update does not mark the project as failed.
 
-## Lazy inventory updates
-
-It should also be noted that not every project update will trigger a
-corresponding inventory update. If the project revision has not changed
-and the inventory has not been edited, the inventory update will not fire.