Module: Grafana::Admin

Included in:
Client
Defined in:
lib/grafana/admin.rb

Overview

All Admin API Calls found under docs.grafana.org/http_api/admin/

The Admin HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role.

They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission.

(The default admin user is called admin and has permission to use this API.)

Instance Method Summary collapse

Instance Method Details

#add_user(params) ⇒ Hash|FalseClass

Create new user

Only works with Basic Authentication (username and password).

Examples:

params = {
  user_name: 'foo',
  email: '[email protected]',
  password: 'pass'
}
add_user( params )

Parameters:

Options Hash (params):

  • user_name (String) —

    name for user (required)

  • email (String) —

    email for user (required)

  • login_name (String) —

    login name for user (optional) - if ‘login_name’ is not set, ‘name’ is used

  • password (String) —

    password (required)

Returns:

Raises:

  • (ArgumentError) 


182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/grafana/admin.rb', line 182

def add_user( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
  raise ArgumentError.new('missing params') if( params.size.zero? )

  user_name = validate( params, required: true, var: 'user_name', type: String )
  email = validate( params, required: true, var: 'email', type: String )
   = validate( params, required: false, var: 'login_name', type: String ) || user_name
  password = validate( params, required: true, var: 'password', type: String )

  usr = user(user_name)

  if( usr.nil? || usr.dig('status').to_i == 200 )
    return {
      'status' => 404,
      'id' => usr.dig('id'),
      'email' => usr.dig('email'),
      'name' => usr.dig('name'),
      'login' => usr.dig('login'),
      'message' => format( 'user \'%s\' with email \'%s\' exists', user_name, email )
    }
  end

  #
  payload = {
    name: user_name,
    email: email,
    login: ,
    password: password
  }
  payload.reject!{ |_k, v| v.nil? }

  endpoint = '/api/admin/users'
  logger.debug("Create user #{user_name} (PUT #{endpoint})") if @debug
  logger.debug(payload.to_json) if(@debug)

  post( endpoint, payload.to_json)
end

#admin_settings ⇒ Hash

get all admin settings

Examples:

admin_settings

Returns:



24
25
26
27
 
# File 'lib/grafana/admin.rb', line 24

def admin_settings
  logger.debug('Getting admin settings') if @debug
  get('/api/admin/settings')
end

#admin_stats ⇒ Hash

get all grafana statistics

Examples:

admin_stats

Returns:



36
37
38
39
 
# File 'lib/grafana/admin.rb', line 36

def admin_stats
  logger.debug('Getting admin statistics') if @debug
  get('/api/admin/stats')
end

#delete_user(user_id) ⇒ Hash

Delete an Global User

Only works with Basic Authentication (username and password).

Examples:

delete_user( 1 )
delete_user( 'foo' )

Parameters:

  • user_id (Mixed) —

    Username (String) or Userid (Integer) for delete User The Admin User can’t be delete!

Returns:

Raises:

  • (ArgumentError) 


143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/grafana/admin.rb', line 143

def delete_user( user_id )

  raise ArgumentError.new(format('wrong type. user \'user_id\' must be an String (for an User name) or an Integer (for an User Id), given \'%s\'', user_id.class.to_s)) if( user_id.is_a?(String) && user_id.is_a?(Integer) )
  raise ArgumentError.new('missing \'user_id\'') if( user_id.size.zero? )

  if(user_id.is_a?(String))
    usr = user(user_id)
    user_id = usr.dig('id')
  end

  return { 'status' => 404, 'message' => format( 'No User \'%s\' found', user_id) } if( user_id.nil? )
  return { 'status' => 403, 'message' => format( 'Can\'t delete user id %d (admin user)', user_id ) } if( user_id.is_a?(Integer) && user_id.to_i.zero? )

  endpoint = format('/api/admin/users/%d', user_id )
  logger.debug( "Deleting user id #{user_id} (DELETE #{endpoint})" ) if @debug

  delete( endpoint )
end

#pause_all_alerts ⇒ Hash

Pause all alerts

Only works with Basic Authentication (username and password).

Examples:

pause_all_alerts

Returns:



273
274
275
276
277
278
279
 
# File 'lib/grafana/admin.rb', line 273

def pause_all_alerts

  endpoint = '/api/admin/pause-all-alerts'
  logger.debug("pause all alerts (POST #{endpoint})") if @debug

  post( endpoint, nil )
end

#update_user_password(params) ⇒ Hash

Change Password for User

Only works with Basic Authentication (username and password). Change password for a specific user.

Examples:

params = {
  user_name: 'foo',
  password: 'bar'
}
update_user_password( params )

Parameters:

Options Hash (params):

  • user_name (String) —

    user_name for user (required)

  • password (String) —

    password to set (required)

Returns:

Raises:

  • (ArgumentError) 


239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/grafana/admin.rb', line 239

def update_user_password( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
  raise ArgumentError.new('missing params') if( params.size.zero? )

  user_name = validate( params, required: true, var: 'user_name', type: String )
  password  = validate( params, required: true, var: 'password', type: String )

  usr = user(user_name)

  return { 'status' => 404, 'message' => format('User \'%s\' not found', user_name) } if( usr.nil? || usr.dig('status').to_i != 200 )

  user_id = usr.dig('id')

  endpoint = format( '/api/admin/users/%d/password', user_id )
  payload = {
    password: password
  }

  logger.debug("Updating password for user id #{user_id} (PUT #{endpoint})") if @debug
  logger.debug(payload.to_json) if(@debug)

  put( endpoint, payload.to_json )
end

#update_user_permissions(params) ⇒ Hash

set User Permissions

Only works with Basic Authentication (username and password).

Examples:

update_user_permissions( user_name: 'admin', permissions: 'Viewer' )
update_user_permissions( user_name: 'admin', permissions: { grafana_admin: true } )

Parameters:

Options Hash (params):

  • name (String) —

    login or email for user

  • permissions (Mixed) —

    string or hash to change permissions

    String

    only ‘Viewer’, ‘Editor’, ‘Read Only Editor’ or ‘Admin’ allowed

    Hash

    grafana_admin: true or false

Returns:

Raises:

  • (ArgumentError) 


57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/grafana/admin.rb', line 57

def update_user_permissions( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
  raise ArgumentError.new('missing params') if( params.size.zero? )

  user_name   = validate( params, required: true, var: 'user_name', type: String )
  permissions = validate( params, required: true, var: 'permissions' )
  raise ArgumentError.new(format('wrong type. \'permissions\' must be an String or Hash, given %s', permissions.class.to_s ) ) unless( permissions.is_a?(String) || permissions.is_a?(Hash) )
  valid_roles    = ['Viewer', 'Editor', 'Read Only Editor', 'Admin']

  downcased = Set.new valid_roles.map(&:downcase)

  if( permissions.is_a?(String) )
    unless( downcased.include?( permissions.downcase ) )
      return {
        'status' => 404,
        'name' => user_name,
        'permissions' => permissions,
        'message' => format( 'wrong permissions. Must be one of %s, given \'%s\'', valid_roles.join(', '), permissions )
      }
    end
  end

  if( permissions.is_a?(Hash) && !permissions.dig(:grafana_admin).nil? )
    grafana_admin = permissions.dig(:grafana_admin)
    unless( grafana_admin.is_a?(Boolean) )
      return {
        'status' => 404,
        'name' => user_name,
        'permissions' => permissions,
        'message' => 'Grafana admin permission must be either \'true\' or \'false\''
      }
    end
  end

  usr = user(user_name)

  return { 'status' => 404, 'message' => format('User \'%s\' not found', user_name) } if( usr.nil? || usr.dig('status').to_i != 200 )

  user_id = usr.dig('id')

  if( permissions.is_a?(Hash) )

    endpoint = format( '/api/admin/users/%s/permissions', user_id )
    payload = {
      isGrafanaAdmin: grafana_admin
    }

    logger.debug("Updating user id #{user_id} permissions (PUT #{endpoint})") if @debug
    logger.debug(payload.to_json) if(@debug)

    return put(endpoint, payload.to_json )
  end

  org = current_organization

  return { 'status' => 404, 'message' => 'No current Organization found' } if( org.nil? || org.dig('status').to_i != 200 )

  endpoint = format( '/api/orgs/%s/users/%s', org.dig('id'), user_id )
  logger.debug( format( 'Updating user id %s permissions', user_id ) ) if @debug

  payload = {
    name: org.dig('name'),
    orgId: org.dig('id'),
    role: permissions.downcase.capitalize
  }

  logger.debug("Updating user id #{user_id} permissions (PATCH #{endpoint})") if @debug
  logger.debug(payload.to_json) if(@debug)

  patch( endpoint, payload.to_json )
end