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'

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.



22
23
24
25
 
# File 'lib/puppet/http/service/compiler.rb', line 22

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:



216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/puppet/http/service/compiler.rb', line 216

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:



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/puppet/http/service/compiler.rb', line 277

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:



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

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:



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/puppet/http/service/compiler.rb', line 340

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: ) ⇒ 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: ) —

    An array of accepted checksum types.

Returns:



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

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 }
  )

  if (compiler = response['X-Puppet-Compiler-Name'])
    Puppet.notice("Catalog compiled by #{compiler}")
  end

  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) 


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
195
196
197
198
199
200
201
 
# File 'lib/puppet/http/service/compiler.rb', line 164

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, "The 'persistence' hash is missing the keys: #{missing.join(', ')}"
  end
  raise ArgumentError, "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:



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/puppet/http/service/compiler.rb', line 239

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:



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/puppet/http/service/compiler.rb', line 309

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