Class: Puppet::HTTP::Service::Compiler

Inherits:
Puppet::HTTP::Service show all
Defined in:
lib/puppet/http/service/compiler.rb

Overview

The Compiler service is used to submit and retrieve data from the puppetserver.

Constant Summary collapse

API =

Returns Default API for the Compiler service.

Returns:

  • (String) —

    Default API for the Compiler service

'/puppet/v3'.freeze

Constants inherited from Puppet::HTTP::Service

EXCLUDED_FORMATS, SERVICE_NAMES

Instance Attribute Summary

Attributes inherited from Puppet::HTTP::Service

#url

Instance Method Summary collapse

Methods inherited from Puppet::HTTP::Service

#connect, create_service, valid_name?, #with_base_url

Constructor Details

#initialize(client, session, server, port) ⇒ Compiler

Use `Puppet::HTTP::Session.route_to(:puppet)` to create or get an instance of this class.

Parameters:

  • client (Puppet::HTTP::Client)
  • session (Puppet::HTTP::Session)
  • server (String) —

    (`Puppet`) If an explicit server is given, create a service using that server. If server is nil, the default value is used to create the service.

  • port (Integer) —

    (`Puppet`) If an explicit port is given, create a service using that port. If port is nil, the default value is used to create the service.


20
21
22
23
 
# File 'lib/puppet/http/service/compiler.rb', line 20

def initialize(client, session, server, port)
  url = build_url(API, server || Puppet[:server], port || Puppet[:serverport])
  super(client, session, url)
end

Instance Method Details

#get_facts(name, environment:) ⇒ Array<Puppet::HTTP::Response, Puppet::Node::Facts>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Submit a GET request to retrieve the facts for the named node

Parameters:

  • name (String) —

    Name of the node to retrieve facts for

  • environment (String) —

    Name of the environment we are operating in

Returns:


209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/puppet/http/service/compiler.rb', line 209

def get_facts(name, environment:)
  headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node::Facts).join(', '))

  response = @client.get(
    with_base_url("/facts/#{name}"),
    headers: headers,
    params: { environment: environment }
  )

  process_response(response)

  [response, deserialize(response, Puppet::Node::Facts)]
end

#get_filebucket_file(path, environment:, bucket_path: nil, diff_with: nil, list_all: nil, fromdate: nil, todate: nil) ⇒ Array<Puppet::HTTP::Response, Puppet::FileBucket::File>

Submit a GET request to retrieve a file stored with filebucket.

Parameters:

  • path (String) —

    The request path, formatted by `Puppet::FileBucket::Dipper`

  • environment (String) —

    Name of the environment we are operating in. This should not impact filebucket at all, but is included to be consistent with legacy code.

  • bucket_path (String) (defaults to: nil)
  • diff_with (String) (defaults to: nil) —

    a checksum to diff against if we are comparing files that are both stored in the bucket

  • list_all (String) (defaults to: nil)
  • fromdate (String) (defaults to: nil)
  • todate (String) (defaults to: nil)

Returns:


270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/puppet/http/service/compiler.rb', line 270

def get_filebucket_file(path, environment:, bucket_path: nil, diff_with: nil, list_all: nil, fromdate: nil, todate: nil)
  headers = add_puppet_headers('Accept' => 'application/octet-stream')

  response = @client.get(
    with_base_url("/file_bucket_file/#{path}"),
    headers: headers,
    params: {
      environment: environment,
      bucket_path: bucket_path,
      diff_with: diff_with,
      list_all: list_all,
      fromdate: fromdate,
      todate: todate
    }
  )

  process_response(response)

  [response, deserialize(response, Puppet::FileBucket::File)]
end

#get_node(name, environment:, configured_environment: nil, transaction_uuid: nil) ⇒ Array<Puppet::HTTP::Response, Puppet::Node>

Submit a GET request to retrieve a node from the server.

Parameters:

  • name (String) —

    The name of the node being requested

  • environment (String) —

    The name of the environment we are operating in

  • configured_environment (String) (defaults to: nil) —

    Optional, the name of the configured environment. If unset, `environment` is used.

  • transaction_uuid (String) (defaults to: nil) —

    An agent generated transaction uuid, used for connecting catalogs and reports.

Returns:


38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/puppet/http/service/compiler.rb', line 38

def get_node(name, environment:, configured_environment: nil, transaction_uuid: nil)
  headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node).join(', '))

  response = @client.get(
    with_base_url("/node/#{name}"),
    headers: headers,
    params: {
      environment: environment,
      configured_environment: configured_environment || environment,
      transaction_uuid: transaction_uuid,
    }
  )

  process_response(response)

  [response, deserialize(response, Puppet::Node)]
end

#head_filebucket_file(path, environment:, bucket_path: nil) ⇒ Puppet::HTTP::Response

Submit a HEAD request to check the status of a file stored with filebucket.

Parameters:

  • path (String) —

    The request path, formatted by `Puppet::FileBucket::Dipper`

  • environment (String) —

    Name of the environment we are operating in. This should not impact filebucket at all, but is included to be consistent with legacy code.

  • bucket_path (String) (defaults to: nil)

Returns:


333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/puppet/http/service/compiler.rb', line 333

def head_filebucket_file(path, environment:, bucket_path: nil)
  headers = add_puppet_headers('Accept' => 'application/octet-stream')

  response = @client.head(
    with_base_url("/file_bucket_file/#{path}"),
    headers: headers,
    params: {
      environment: environment,
      bucket_path: bucket_path
    }
  )

  process_response(response)

  response
end

#post_catalog(name, facts:, environment:, configured_environment: nil, check_environment: false, transaction_uuid: nil, job_uuid: nil, static_catalog: true, checksum_type: Puppet[:supported_checksum_types]) ⇒ Array<Puppet::HTTP::Response, Puppet::Resource::Catalog>

Submit a POST request to submit a catalog to the server.

Parameters:

  • name (String) —

    The name of the catalog to be submitted

  • facts (Puppet::Node::Facts) —

    Facts for this catalog

  • environment (String) —

    The name of the environment we are operating in

  • configured_environment (String) (defaults to: nil) —

    Optional, the name of the configured environment. If unset, `environment` is used.

  • check_environment (Boolean) (defaults to: false) —

    If true, request that the server check if our `environment` matches the server-specified environment. If they do not match, then the server may return an empty catalog in the server-specified environment.

  • transaction_uuid (String) (defaults to: nil) —

    An agent generated transaction uuid, used for connecting catalogs and reports.

  • job_uuid (String) (defaults to: nil) —

    A unique job identifier defined when the orchestrator starts a puppet run via pxp-agent. This is used to correlate catalogs and reports with the orchestrator job.

  • static_catalog (Boolean) (defaults to: true) —

    Indicates if the file metadata(s) are inlined in the catalog. This informs the agent if it needs to make a second request to retrieve metadata in addition to the initial catalog request.

  • checksum_type (Array<String>) (defaults to: Puppet[:supported_checksum_types]) —

    An array of accepted checksum types.

Returns:


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
 
# File 'lib/puppet/http/service/compiler.rb', line 82

def post_catalog(name, facts:, environment:, configured_environment: nil, check_environment: false, transaction_uuid: nil, job_uuid: nil, static_catalog: true, checksum_type: Puppet[:supported_checksum_types])
  if Puppet[:preferred_serialization_format] == "pson"
    formatter = Puppet::Network::FormatHandler.format_for(:pson)
    # must use 'pson' instead of 'text/pson'
    facts_format = 'pson'
  else
    formatter = Puppet::Network::FormatHandler.format_for(:json)
    facts_format = formatter.mime
  end

  facts_as_string = serialize(formatter, facts)

  # query parameters are sent in the POST request body
  body = {
    facts_format: facts_format,
    facts: Puppet::Util.uri_query_encode(facts_as_string),
    environment: environment,
    configured_environment: configured_environment || environment,
    check_environment: !!check_environment,
    transaction_uuid: transaction_uuid,
    job_uuid: job_uuid,
    static_catalog: static_catalog,
    checksum_type: checksum_type.join('.')
  }.map do |key, value|
    "#{key}=#{Puppet::Util.uri_query_encode(value.to_s)}"
  end.join("&")

  headers = add_puppet_headers(
    'Accept' => get_mime_types(Puppet::Resource::Catalog).join(', '),
    'Content-Type' => 'application/x-www-form-urlencoded'
  )

  response = @client.post(
    with_base_url("/catalog/#{name}"),
    body,
    headers: headers,
    # for legacy reasons we always send environment as a query parameter too
    params: { environment: environment },
  )

  process_response(response)

  [response, deserialize(response, Puppet::Resource::Catalog)]
end

#post_catalog4(certname, persistence:, environment:, facts: nil, trusted_facts: nil, transaction_uuid: nil, job_id: nil, options: nil) ⇒ Array<Puppet::HTTP::Response, Puppet::Resource::Catalog, Array<String>>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Submit a POST request to request a catalog to the server using v4 endpoint

Parameters:

  • certname (String) —

    The name of the node for which to compile the catalog.

  • persistent (Hash) —

    A hash containing two required keys, facts and catalog, which when set to true will cause the facts and reports to be stored in PuppetDB, or discarded if set to false.

  • environment (String) —

    The name of the environment for which to compile the catalog.

  • facts (Hash) (defaults to: nil) —

    A hash with a required values key, containing a hash of all the facts for the node. If not provided, Puppet will attempt to fetch facts for the node from PuppetDB.

  • trusted_facts (Hash) (defaults to: nil) —

    A hash with a required values key containing a hash of the trusted facts for a node

  • transaction_uuid (String) (defaults to: nil) —

    The id for tracking the catalog compilation and report submission.

  • job_id (String) (defaults to: nil) —

    The id of the orchestrator job that triggered this run.

  • options (Hash) (defaults to: nil) —

    A hash of options beyond direct input to catalogs. Options:

    • prefer_requested_environment Whether to always override a node's classified environment with the one supplied in the request. If this is true and no environment is supplied, fall back to the classified environment, or finally, 'production'.

    • capture_logs Whether to return the errors and warnings that occurred during compilation alongside the catalog in the response body.

    • log_level The logging level to use during the compile when capture_logs is true. Options are 'err', 'warning', 'info', and 'debug'.

Returns:

  • (Array<Puppet::HTTP::Response, Puppet::Resource::Catalog, Array<String>>) —

    An array containing the request response, the deserialized catalog returned by the server and array containing logs (log array will be empty if capture_logs is false)

Raises:

  • (ArgumentError) 

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/puppet/http/service/compiler.rb', line 158

def post_catalog4(certname, persistence:, environment:, facts: nil, trusted_facts: nil, transaction_uuid: nil, job_id: nil, options: nil)
  unless persistence.is_a?(Hash) && (missing = [:facts, :catalog] - persistence.keys.map(&:to_sym)).empty?
    raise ArgumentError.new("The 'persistence' hash is missing the keys: #{missing.join(', ')}")
  end
  raise ArgumentError.new("Facts must be a Hash not a #{facts.class}") unless facts.nil? || facts.is_a?(Hash)
  body = {
    certname: certname,
    persistence: persistence,
    environment: environment,
    transaction_uuid: transaction_uuid,
    job_id: job_id,
    options: options
  }
  body[:facts] = { values: facts } unless facts.nil?
  body[:trusted_facts] = { values: trusted_facts } unless trusted_facts.nil?
  headers = add_puppet_headers(
    'Accept' => get_mime_types(Puppet::Resource::Catalog).join(', '),
    'Content-Type' => 'application/json'
  )

  url = URI::HTTPS.build(host: @url.host, port: @url.port, path: Puppet::Util.uri_encode("/puppet/v4/catalog"))
  response = @client.post(
    url,
    body.to_json,
    headers: headers
  )
  process_response(response)
  begin
    response_body = JSON.parse(response.body)
    catalog = Puppet::Resource::Catalog.from_data_hash(response_body['catalog'])
  rescue => err
    raise Puppet::HTTP::SerializationError.new("Failed to deserialize catalog from puppetserver response: #{err.message}", err)
  end
  
  logs = response_body['logs'] || []
  [response, catalog, logs]
end

#put_facts(name, environment:, facts:) ⇒ Puppet::HTTP::Response

Submits a PUT request to submit facts for the node to the server.

Parameters:

  • name (String) —

    Name of the node we are submitting facts for

  • environment (String) —

    Name of the environment we are operating in

  • facts (Puppet::Node::Facts) —

    Facts for the named node

Returns:


232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/puppet/http/service/compiler.rb', line 232

def put_facts(name, environment:, facts:)
  formatter = Puppet::Network::FormatHandler.format_for(Puppet[:preferred_serialization_format])

  headers = add_puppet_headers(
    'Accept' => get_mime_types(Puppet::Node::Facts).join(', '),
    'Content-Type' => formatter.mime
  )

  response = @client.put(
    with_base_url("/facts/#{name}"),
    serialize(formatter, facts),
    headers: headers,
    params: { environment: environment },
  )

  process_response(response)

  response
end

#put_filebucket_file(path, body:, environment:) ⇒ Puppet::HTTP::Response

Submit a PUT request to store a file with filebucket.

Parameters:

  • path (String) —

    The request path, formatted by `Puppet::FileBucket::Dipper`

  • body (String) —

    The contents of the file to be backed

  • environment (String) —

    Name of the environment we are operating in. This should not impact filebucket at all, but is included to be consistent with legacy code.

Returns:


302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/puppet/http/service/compiler.rb', line 302

def put_filebucket_file(path, body:, environment:)
  headers = add_puppet_headers({
    'Accept' => 'application/octet-stream',
    'Content-Type' => 'application/octet-stream'
    })

  response = @client.put(
    with_base_url("/file_bucket_file/#{path}"),
    body,
    headers: headers,
    params: {
      environment: environment
    }
  )

  process_response(response)

  response
end