Module: Icinga2::ConfigurationManagement

Included in:
Client
Defined in:
lib/icinga2/configuration_management.rb

Overview

namespace for config packages

The main idea behind configuration management is to allow external applications creating configuration packages and stages based on configuration files and directory trees.

This replaces any additional SSH connection and whatnot to dump configuration files to Icinga 2 directly.

In case you are pushing a new configuration stage to a package, Icinga 2 will validate the configuration asynchronously and populate a status log which can be fetched in a separated request.

original API Documentation: www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/#configuration-management

Instance Method Summary collapse

Instance Method Details

#create_config_package(name) ⇒ Hash

create a new empty configuration package.

Package names starting with an underscore are reserved for internal packages and can not be used.

Examples:

create_config_package('cfg-package')

Parameters:

  • name (String) —

    the name for the new package.

Returns:

Raises:

  • (ArgumentError) 


29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/icinga2/configuration_management.rb', line 29

def create_config_package(name)

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

  return { 'code' => 404, 'name' => name, 'status' => 'Package names starting with an underscore are reserved for internal packages and can not be used.'  } if( name.initial == '_' )

  post(
    url: format( '%s/config/packages/%s', @icinga_api_url_base, name ),
    headers: @headers,
    options: @options
  )
end

#fetch_config_stages(params) ⇒ String

fetched the whole config package and return them as a String.

Examples:

params = {
  package: 'cfg-package',
  stage: 'example.localdomain-1441625839-0',
  name: 'host1',
  cluster: false
}
fetch_config_stages(params)

Parameters:

Options Hash (params):

  • package (String)
  • stage (String)
  • cluser (Bool) — default: false —

    package for an satellite

  • name (String)

Returns:

Raises:

  • (ArgumentError) 


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/icinga2/configuration_management.rb', line 164

def fetch_config_stages(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? )

  package = validate( params, required: true, var: 'package', type: String )
  stage   = validate( params, required: true, var: 'stage', type: String )
  name    = validate( params, required: true, var: 'name', type: String )
  cluster = validate( params, required: false, var: 'cluster', type: Boolean ) || false
  name    = name.gsub('.conf','')

  return { 'code' => 404, 'status' => format('no package \'%s\' exists', package) } unless(package_exists?(package))

  path = 'conf.d'
  path = 'zones.d/satellite' if(cluster)
  file = format( '%s/%s/%s/%s.conf', package, stage, path, name )

  get(
    url: format( '%s/config/files/%s', @icinga_api_url_base, file ),
    headers: {},
    options: @options
  )
end

#list_config_packages ⇒ Hash

A list of packages.

Examples:

list_config_packages

Returns:



105
106
107
108
109
110
111
112
 
# File 'lib/icinga2/configuration_management.rb', line 105

def list_config_packages

  get(
    url: format( '%s/config/packages', @icinga_api_url_base ),
    headers: @headers,
    options: @options
  )
end

#list_config_stages(params) ⇒ Hash

A list of packages and their stages.

Examples:

params = {
  package: 'cfg-package',
  stage: 'example.localdomain-1441625839-0'
}
list_config_stages(params)

Parameters:

Options Hash (params):

Returns:

Raises:

  • (ArgumentError) 


129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/icinga2/configuration_management.rb', line 129

def list_config_stages(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? )

  package = validate( params, required: true, var: 'package', type: String )
  stage   = validate( params, required: true, var: 'stage', type: String )

  get(
    url: format( '%s/config/stages/%s/%s', @icinga_api_url_base, package, stage ),
    headers: @headers,
    options: @options
  )
end

#package_exists?(name) ⇒ Bool

check if a package exists

Examples:

package_exists?('cfg-package')

Parameters:

  • name (String) —

    the name for the package.

Returns:

  • (Bool)

Raises:

  • (ArgumentError) 


292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/icinga2/configuration_management.rb', line 292

def package_exists?(name)

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

  current_packages = list_config_packages

  return { 'code' => 404, 'status' => 'error to get packages' } if( current_packages.nil? && current_packages.dig('code') != 200 )

  current_packages = current_packages.dig('results')

  data = current_packages.select { |k,_| k['name'] == name }
  data = data.first if( data )

  return false unless(data)

  true
end

#package_stage_errors(params) ⇒ String

fetch the startup.log from the named packe / stage combination to see possible errors.

Examples:

params = {
  package: 'cfg-package',
  stage: 'example.localdomain-1441625839-0',
  cluster: false
}
package_stage_errors(params)

Parameters:

Options Hash (params):

  • package (String)
  • stage (String)
  • cluser (Bool) — default: false —

    package for an satellite

Returns:

Raises:

  • (ArgumentError) 


205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/icinga2/configuration_management.rb', line 205

def package_stage_errors(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? )

  package = validate( params, required: true, var: 'package', type: String )
  stage   = validate( params, required: true, var: 'stage', type: String )
  # cluster = validate( params, required: false, var: 'cluster', type: Boolean ) || false

  return { 'code' => 404, 'status' => format('no package \'%s\' exists', package) } unless(package_exists?(package))

  file = format( '%s/%s/startup.log', package, stage )

  get(
    url: format( '%s/config/files/%s', @icinga_api_url_base, file ),
    headers: {},
    options: @options
  )
end

#remove_config_package(name) ⇒ Hash

Deleting Configuration Package

Examples:

remove_config_package('cfg-package')

Parameters:

  • name (String) —

    the name for the package.

Returns:

Raises:

  • (ArgumentError) 


268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/icinga2/configuration_management.rb', line 268

def remove_config_package(name)

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

  return { 'code' => 404, 'name' => name, 'status' => 'Package names starting with an underscore are reserved for internal packages and can not be used.'  } if( name.initial == '_' )
  return { 'code' => 404, 'status' => format('no package \'%s\' exists', name) } unless(package_exists?(name))

  delete(
    url: format( '%s/config/packages/%s', @icinga_api_url_base, name ),
    headers: @headers,
    options: @options
  )
end

#remove_config_stage(params) ⇒ Hash

Deleting Configuration Package Stage

Examples:

params = {
  package: 'cfg-package',
  stage: 'example.localdomain-1441625839-0',
  cluster: false
}
remove_config_stage(params)

Parameters:

Options Hash (params):

Returns:

Raises:

  • (ArgumentError) 


241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/icinga2/configuration_management.rb', line 241

def remove_config_stage(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? )

  package = validate( params, required: true, var: 'package', type: String )
  stage   = validate( params, required: true, var: 'stage', type: String )

  return { 'code' => 404, 'name' => package, 'status' => 'Package names starting with an underscore are reserved for internal packages and can not be used.'  } if( package.initial == '_' )
  return { 'code' => 404, 'status' => format('no package \'%s\' exists', name) } unless(package_exists?(package))

  delete(
    url: format( '%s/config/stages/%s/%s', @icinga_api_url_base, package, stage ),
    headers: @headers,
    options: @options
  )
end

#upload_config_package(params) ⇒ Hash

Configuration files in packages are managed in stages. Stages provide a way to maintain multiple configuration versions for a package.

Examples:

params = {
  package: 'cfg-package',
  name: 'host1',
  cluster: false,
  vars:  'object Host "cmdb-host" { chec_command = "dummy" }',
  reload: false
}
upload_config_package(params)

Parameters:

Options Hash (params):

  • package (String) —

    name of the package

  • name (String) —

    name for the package

  • cluser (Bool) — default: false —

    package for an satellite

  • reload (Bool) — default: true —

    reload icinga2 after upload

  • vars (String)

Returns:

Raises:

  • (ArgumentError) 


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
 
# File 'lib/icinga2/configuration_management.rb', line 65

def upload_config_package(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? )

  package = validate( params, required: true, var: 'package', type: String )
  name    = validate( params, required: true, var: 'name', type: String )
  cluster = validate( params, required: false, var: 'cluster', type: Boolean ) || false
  vars    = validate( params, required: false, var: 'vars', type: String )
  reload  = validate( params, required: false, var: 'reload', type: Boolean ) || true
  name    = name.gsub('.conf','')

  return { 'code' => 404, 'status' => format('no package \'%s\' exists', package) } unless(package_exists?(package))

  path = 'conf.d'
  path = 'zones.d/satellite' if(cluster)
  file = format( '%s/%s.conf', path, name )

  payload = {
    'files' => {
      file.to_s => vars
    },
    'reload' => reload
  }

  post(
    url: format( '%s/config/stages/%s', @icinga_api_url_base, package ),
    headers: @headers,
    options: @options,
    payload: payload
  )
end