github.com/esnet/gdg@v0.6.1-0.20240412190737-6b6eba9c14d8/website/content/docs/usage_guide/backup_guide.md (about) 1 --- 2 title: "Backup Guide" 3 weight: 16 4 --- 5 6 Every namespace supporting CRUD operations has the functions: list, download, upload, clear operating on only the monitored folders. 7 8 9 ### Connections 10 11 {{< callout note >}} Starting with v0.4.6 "Datasources" was renamed to connections. {{< /callout >}} 12 13 Connections credentials are keyed by the name of the DataSource. See [config example](https://github.com/esnet/gdg/blob/master/config/importer-example.yml). If the connection JSON doesn't have auth enabled, the credentials are ignored. If Credentials are missing, we'll fall back on default credentials if any exist. The password is set as a value for basicAuthPassword in the API payload. 14 Datasources are imported or exported from _organization_ specified in configuration file otherwise current organization user is used. 15 16 17 All commands can use `connection` or `c` to manage datasources. 18 19 ```sh 20 ./bin/gdg backup c list -- Lists all current connections 21 ./bin/gdg backup c download -- Import all connections from grafana to local file system 22 ./bin/gdg backup c upload -- Exports all dashboard from local filesystem (matching folder filter) to Grafana 23 ./bin/gdg backup c clear -- Deletes all connections 24 ``` 25 26 27 ### Dashboards 28 29 Dashboards are imported or exported from _organization_ specified in configuration file otherwise current organization user is used. 30 31 All commands can use `dashboards` or `dash` to manage dashboards 32 33 ```sh 34 ./bin/gdg backup dash list -- Lists all current dashboards 35 ./bin/gdg backup dash download -- Import all dashboards from grafana to local file system 36 ./bin/gdg backup dash upload -- Exports all dashboard from local filesystem (matching folder filter) to Grafana 37 ./bin/gdg backup dash clear -- Deletes all dashboards 38 ``` 39 40 You can also use filtering options to list or import your dashboard by folder or by tags. 41 42 ```sh 43 ./bin/gdg backup dash download -f myFolder 44 ./bin/gdg backup dash download -t myTag 45 ./bin/gdg backup dash download -t tagA -t tagB -t complex,tagC 46 ``` 47 The command above will return any dashboard that is tagged with `tagA` or `tagB` or `complex,tagC` 48 49 50 **NOTE**: Starting with v0.5.2 full crud support for tag filtering. You can list,upload,clear,download dashboards using tag filters. Keep in mind the tag filtering on any matching tags. ie. Any dashboard that has tagA or tagB or complex,tagC will be listed,uploaded, etc. 51 52 ### Folders 53 54 Mostly optional as Dashboards will create/delete these are needed but if there is additional metadata you wish to persist you can use this to manage them. 55 56 ```sh 57 ./bin/gdg backup folders list -- Lists all current folders 58 ./bin/gdg backup folders download -- Import all folders from grafana to local file system 59 ./bin/gdg backup folders upload -- Exports all folders from local filesystem 60 ./bin/gdg backup folders clear -- Deletes all folders 61 ``` 62 63 ### Folder Permissions 64 65 This CRUD allows you to import / export folder permissions. Initial release will be part of v0.4.4. There are a lot of nested relationship that go with this. 66 67 Expectations: 68 - Users have to already exist. 69 - Teams (if used) need to already exist. 70 - Folders also need to already exist. 71 72 The Folder Permissions will list, import and re-apply permissions. But the expectations is that all other entities are already there. Next few iteration will try to add more concurrency for 73 this tool and more error checking when entities that don't exist are being referenced. 74 75 **NOTE:** Unlike other command, permissions does not have a `clear` function. Theoretically you could have a folder name with an emtpy array under folder-permissions to clear all known permissions to the folder, but otherwise 76 clearing permissions from all folders seems too destructive to really be a useful function. 77 78 ```sh 79 ./bin/gdg backup folders list -- Lists all current folder permissions 80 ./bin/gdg backup folders download -- Retrieve all folders permissions from Grafana 81 ./bin/gdg backup folders upload -- Exports all folders from local filesystem 82 ``` 83 84 ``` 85 ┌───────────┬──────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────┬─────────────┬────────────────────────────────┬────────┬─────────────────┐ 86 │ FOLDER ID │ FOLDERUID │ FOLDER NAME │ USERID │ TEAM NAME │ ROLE │ PERMISSION NAME │ 87 ├───────────┼──────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────┼────────────────────────────────┼────────┼─────────────────┤ 88 │ 2272 │ dfba969d-565b-481e-a930-53aa5684992c │ sub-flow │ │ │ │ │ 89 │ │ PERMISSION---> │ admin │ │ Admin │ 90 │ 520 │ GPmSOQNnk │ EngageMap (internal beta) │ │ │ │ │ 91 │ │ PERMISSION---> │ │ Admin │ Edit │ 92 │ │ PERMISSION---> │ │ Editor │ Edit │ 93 │ │ PERMISSION---> │ │ Viewer │ View │ 94 │ 2031 │ n3xS8TwVk │ Team CMS - US dumb dumb │ │ │ │ │ 95 │ │ PERMISSION---> │ │ authscope_team_cms │ │ Edit │ 96 │ 1746 │ pASPyoQVk │ Team DOE-IN-PNNL - DOE-IN Pacific Northwest National Laboratory │ │ │ │ │ 97 └──────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────┴─────────────┴────────────────────────────────┴────────┴─────────────────┘ 98 ``` 99 100 The listing includes the folder name, followed by several lines with "PERMISSION--->" which will each list a permission. It can a user being granted access or a team being granted a role etc. 101 102 103 104 ### Library Elements 105 106 Library elements are components that can be shared among multiple dashboards. Folder matching will still be applied, so any folders not monitored will be ignored unless explicitly specified. If wildcard flag is enabled, all elements will be acted on irrelevant of folder location 107 108 All commands can use `libraryelements` aliased to `library` and `lib` for laziness purposes. A more extensive tutorial is available [here](https://software.es.net/gdg/docs/tutorials/library_elements/) 109 110 ```sh 111 ./bin/gdg backup lib list -- Lists all library components 112 ./bin/gdg backup lib download -- Import all library components from grafana to local file system 113 ./bin/gdg backup lib upload -- Exports all library components from local filesystem (matching folder filter) to Grafana 114 ./bin/gdg backup lib clear -- Deletes all library components 115 ./bin/gdg backup lib list-connections <Lib Element UID> -- Will list all of the dashboards connected to the Lib Element (Coming in v0.4.2) 116 ``` 117 118 119 120 ### Organizations 121 122 {{< callout context="danger" title="Danger" icon="alert-octagon" >}} 123 Auth: Requires Grafana Admin 124 125 - Tokens/service account tokens are tied to a specific org and are therefore not supported. 126 - Organization Admins don't have access to list all Orgs, therefore are also not supported. 127 128 {{< /callout >}} 129 130 Command can use `organizations` or `org` to manage organizations. 131 132 133 ```sh 134 ./bin/gdg backup org list -- Lists all organizations 135 ./bin/gdg backup org upload -- Upload Orgs to grafana 136 ./bin/gdg backup org download -- Download Orgs to grafana 137 ``` 138 139 A tutorial on working with [organizations](https://software.es.net/gdg/docs/tutorials/organization-and-authentication/) is available. 140 141 ### Teams 142 143 {{< callout context="caution" title="Caution" icon="alert-triangle" >}} 144 Users need to be created before team export can succeed 145 {{< /callout >}} 146 147 148 ```sh 149 ./bin/gdg backup team list -- Lists all known team members 150 ./bin/gdg backup team download -- download all known team members 151 ./bin/gdg backup team upload -- upload all known team members 152 ./bin/gdg backup team clear -- Delete all known team except admin 153 ``` 154 155 {{< details "Team Listing" >}} 156 ``` 157 158 ┌────┬───────────┬───────┬───────┬─────────┬─────────────┬──────────────┬───────────────────┐ 159 │ ID │ NAME │ EMAIL │ ORGID │ CREATED │ MEMBERCOUNT │ MEMBER LOGIN │ MEMBER PERMISSION │ 160 ├────┼───────────┼───────┼───────┼─────────┼─────────────┼──────────────┼───────────────────┤ 161 │ 4 │ engineers │ │ 1 │ 2 │ │ │ │ 162 │ │ │ │ │ │ admin │ Admin │ │ 163 │ │ │ │ │ │ tux │ Member │ │ 164 │ 5 │ musicians │ │ 1 │ 1 │ │ │ │ 165 │ │ │ │ │ │ admin │ Admin │ │ 166 └────┴───────────┴───────┴───────┴─────────┴─────────────┴──────────────┴───────────────────┘ 167 168 ``` 169 {{< /details >}} 170 171 172 ### Users 173 174 Only supported with basic auth. Users is the only one where basic auth is given priority. API Auth is not supported, so will try to use basic auth if configured otherwise will warn the user and exit. 175 176 NOTE: admin user is always ignored. 177 178 ```sh 179 ./bin/gdg backup users list -- Lists all known users 180 ./bin/gdg backup users download -- Lists all known users 181 ./bin/gdg backup users upload -- Export all users (Not yet supported) 182 ./bin/gdg backup users clear -- Delete all known users except admin 183 ``` 184