github.com/esnet/gdg@v0.6.1-0.20240412190737-6b6eba9c14d8/website/content/docs/usage_guide/tools_guide.md (about)

     1  ---
     2  title: "Tools Guide"
     3  weight: 17
     4  ---
     5  
     6  This guide focuses on the 'tools' subcommand.  Every command that isn't specific to a CRUD operation falls under the tools command.
     7  
     8  There are a few utility functions that have been introduced that might be useful to the user, or is geared at managing the configuration,
     9  switching contexts or Orgs for a given user and so on.
    10  
    11  ### Authentication Management
    12  
    13  This is mainly added as a convenience mechanism.  It was needed to support some testing and exposing the feature is useful as a really simple CLI to create tokens / service Keys.  You probably should be using other tooling for managing all your service files and tokens.   Unlike most other entities, this is not a backup feature as much as utility.
    14  
    15  There are two sub commands for auth, service-accounts and tokens (will be deprecated at some point).
    16  
    17  #### Token Management
    18  
    19  
    20  ```sh
    21  ./bin/gdg tools auth tokens list -- list current tokens (No access to the actual token secret)
    22  ./bin/gdg tools auth tokens new --  Create a new token.  new <name> <role> [ttl in seconds, forever otherwise]
    23  ./bin/gdg tools auth tokens clear -- Deletes all tokens
    24  ```
    25  
    26  {{< details "Token Listing" >}}
    27  ```
    28  ┌────┬─────────┬───────┬───────────────┐
    29  │ ID │ NAME    │ ROLE  │ EXPIRATION    │
    30  ├────┼─────────┼───────┼───────────────┤
    31  │  1 │ testing │ Admin │ No Expiration │
    32  └────┴─────────┴───────┴───────────────┘
    33  ```
    34  {{< /details >}}
    35  
    36  Example of creating a new token.
    37  
    38  ```sh
    39  ./bin/gdg auth tokens new foobar Admin 3600
    40  ```
    41  
    42  {{< details "New Token" >}}
    43  
    44  ┌────┬────────┬─────────────────────────────────────────────────────────────┐
    45  │ ID │ NAME   │ TOKEN                                                       │
    46  ├────┼────────┼─────────────────────────────────────────────────────────────┤
    47  │  2 │ foobar │ eyJrIjoiNzU2WVhiMEZpVWNlV3hWSUVZQTuIjoiZm9vYmFyIiwiaWQiOjF9 │
    48  └────┴────────┴─────────────────────────────────────────────────────────────┘
    49  
    50  {{< /details >}}
    51  
    52  
    53  #### Service Accounts
    54  
    55  
    56  ```sh
    57  ./bin/gdg tools auth svc  clear       delete all Service Accounts
    58  ./bin/gdg tools auth svc  clearTokens delete all tokens for Service Account
    59  ./bin/gdg tools auth svc  list        list API Keys
    60  ./bin/gdg tools auth svc  newService  newService <serviceName> <role> [ttl in seconds]
    61  ./bin/gdg tools auth svc  newToken    newToken <serviceAccountID> <name> [ttl in seconds]
    62  ```
    63  
    64  ```sh
    65  ./bin/gdg tools auth svc newService AwesomeSauceSvc admin
    66  ```
    67  
    68  {{< details "New Service" >}}
    69  
    70  ┌────┬─────────────────┬───────┐
    71  │ ID │ NAME            │ ROLE  │
    72  ├────┼─────────────────┼───────┤
    73  │  4 │ AwesomeSauceSvc │ Admin │
    74  └────┴─────────────────┴───────┘
    75  {{< /details >}}
    76  
    77  ```sh
    78  ./bin/gdg tools auth svc newToken 4 AwesomeToken
    79  ```
    80  
    81  {{< details "New Service" >}}
    82  
    83  ┌───────────┬──────────┬──────────────┬────────────────────────────────────────────────┐
    84  │ SERVICEID │ TOKEN_ID │ NAME         │ TOKEN                                          │
    85  ├───────────┼──────────┼──────────────┼────────────────────────────────────────────────┤
    86  │         4 │        3 │ AwesomeToken │ glsa_a14JOaGExOkDuJHjDWScXbxjTBIXScsw_39df7bf5 │
    87  └───────────┴──────────┴──────────────┴────────────────────────────────────────────────┘
    88  {{< /details >}}
    89  
    90  ```sh
    91  ./bin/gdg tools auth svc list
    92  ```
    93  
    94  {{< details "Service Listing" >}}
    95  
    96  ┌────┬─────────────────┬───────┬────────┬──────────┬──────────────┬───────────────┐
    97  │ ID │ SERVICE NAME    │ ROLE  │ TOKENS │ TOKEN ID │ TOKEN NAME   │ EXPIRATION    │
    98  ├────┼─────────────────┼───────┼────────┼──────────┼──────────────┼───────────────┤
    99  │ 4  │ AwesomeSauceSvc │ Admin │ 1      │          │              │               │
   100  │    │                 │       │        │        3 │ AwesomeToken │ No Expiration │
   101  └────┴─────────────────┴───────┴────────┴──────────┴──────────────┴───────────────┘
   102  {{< /details >}}
   103  
   104  ### Dashboard Linter
   105  
   106  Integrated the official grafana [linter](https://github.com/grafana/dashboard-linter/) into GDG. Allows you to run the linter as part of gdg.
   107  
   108  ```sh
   109  gdg tools dashboard lint -d bandwidth-patterns -f testing
   110  ```
   111  
   112  You can execute this on a single dashboard, or a folder.  --autofix is available but should be considered a beta feature.
   113  
   114  
   115  ### Devel
   116  Some developer helper utilities
   117  
   118  
   119  ```sh
   120  ./bin/gdg tools devel completion  [bash|fish|powershell|zsh] --  Will generate autocompletion for GDG for your favorite shell
   121  ./bin/gdg tools devel srvinfo -- print grafana server info
   122  ```
   123  
   124  
   125  
   126  ### Organizations
   127  Command can use `organizations` or `org` to set the organizations in the configuration file.
   128  
   129  NOTE: this only manages top level of the orgs structure. Mainly used for a lazy man pattern.
   130  
   131  ```sh
   132  ./bin/gdg tools org set --orgName <name> OR --orgSlugName <name> -- Sets a given Org filter.  All Dashboards and Datasources etc are uploaded to the given Org only.
   133  ```
   134  
   135  Additionally `addUser`, `updateUserRole`, `deleteUser`, `listUsers` are all used to manage a user's membership within a given organization.
   136  
   137  
   138  ### Organizations Preferences
   139  
   140  There are a few properties that can be set to change behavior.  Keep in mind that all of these entity need to be owned by the Org, you cannot reference to a dashboard outside of a given org.
   141  
   142  ```sh
   143  ## will set the weekstart as Tuesday and a default Org theme of dark
   144  gdg t orgs prefs set --orgName "Main Org." --theme dark --weekstart tuesday
   145  ## Retrieve the Orgs Preferences
   146  gdg t orgs prefs get --orgName "Main Org."
   147  ```
   148  
   149  
   150  ```
   151  ┌──────────────────┬─────────┐
   152  │ FIELD            │ VALUE   │
   153  ├──────────────────┼─────────┤
   154  │ HomeDashboardUID │         │
   155  │ Theme            │ dark    │
   156  │ WeekStart        │ tuesday │
   157  └──────────────────┴─────────┘
   158  ```
   159  
   160  ### Users
   161  
   162  CRUD is under the 'backup' command.  The tools subcommand allows you to promote a given user to a grafana admin if you have the permission to do so.
   163  
   164  NOTE: admin user is always ignored.
   165  
   166  ```sh
   167  ./bin/gdg tools users promote -u user@foobar.com -- promotes the user to a grafana admin
   168  ```