From 3eb675150148d3283b9eaa5752f629beedd44fb7 Mon Sep 17 00:00:00 2001 From: Jose Caballero Bejar Date: Tue, 7 Jan 2025 07:51:17 +0000 Subject: [PATCH] Make documentation clear for non-privileged users The previous snippets in the documentation only work if the user have admin privileges. Documentation now makes more clear what queries need to be executed for regular non-privileged users. Also, documentation gives some clue on how to find out the exact value of the cloud domain name to be passed as first argument to query.run() --- docs/user_docs/API.md | 2 ++ docs/user_docs/USAGE.md | 27 ++++++++++++++++++++++----- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/user_docs/API.md b/docs/user_docs/API.md index 93e720b..ebdc2ae 100644 --- a/docs/user_docs/API.md +++ b/docs/user_docs/API.md @@ -5,6 +5,8 @@ a query in a declarative way. This document describes how to use the SQL-like API to run Openstack Queries +Remember to replace `query.run("openstack-domain", as_admin=True, all_projects=True)` by `query.run("openstack-domain")` if you don't have admin privileges in the OpenStack service. + ## Querying on Resources The query library currently supports queries on the following Openstack resources diff --git a/docs/user_docs/USAGE.md b/docs/user_docs/USAGE.md index cd17160..2216454 100644 --- a/docs/user_docs/USAGE.md +++ b/docs/user_docs/USAGE.md @@ -1,5 +1,22 @@ # Usage -The following document contains different ways to use the query library +The following document contains different ways to use the query library. + +The examples assume: +* you do not have admin privileges for the OpenStack service +* the name of your Cloud domain is `prod` + +You can find the actual Cloud domain name in your `clouds.yaml` file. +If you have admin privileges, the queries can be perform for all projects in OpenStack. For that, replace the lines + +```python +query.run("prod") +``` + +by + +```python +query.run("prod", as_admin=True, all_projects=True) +``` ## Simple Query Find Errored and Shutoff VMs @@ -18,7 +35,7 @@ query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) # Run - this will run the query in the "prod" cloud domain and with meta-params as_admin and all_projects. # This will run the query as an admin and will find VMs on every available project -query.run("prod", as_admin=True, all_projects=True) +query.run("prod") # Group By - This will group the results by a property - project_id # NOTE: group by property and selected property are completely independent @@ -47,7 +64,7 @@ query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) query.where("older_than", "last_updated_date", days=60) -query.run("prod", as_admin=True, all_projects=True) +query.run("prod") query.group_by("id") print(query.to_string()) ``` @@ -81,7 +98,7 @@ server_query = user_query.then("SERVER_QUERY", keep_previous_results=True) server_query.select("name", "id") server_query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) server_query.where("older_than", "last_updated_date", days=60) -server_query.run("prod", as_admin=True, all_projects=True) +server_query.run("prod") server_query.group_by("project_id") # These results will contain VM associated values for user_name and user_email @@ -109,7 +126,7 @@ server_query = user_query.then("SERVER_QUERY", keep_previous_results=True) server_query.select("name", "id") server_query.where("any_in", "status", values=["ERROR", "SHUTOFF"]) server_query.where("older_than", "last_updated_date", days=60) -server_query.run("prod", as_admin=True, all_projects=True) +server_query.run("prod") # We need to get project name by running append_from() # append_from() command below is the same as doing the following: