Environment modules
Sections
The environment modules API will return information about what modules are installed for the requested environment.
This endpoint is available only when the Puppet primary server is running Puppet Server, not on Ruby Puppet primary servers, such as the deprecated WEBrick Puppet primary server. It also ignores the Ruby-based Puppet primary server's authorization methods and configuration. See the Authorization section for more information.
GET /puppet/v3/environment_modules
Supported HTTP Methods
GET
Supported Formats
JSON
Responses
GET request with results
GET /puppet/v3/environment_modules
HTTP/1.1 200 OK
Content-Type: application/json
[{
"modules": [
{
"name": "puppetlabs/ntp",
"version": "6.0.0"
},
{
"name": "puppetlabs/stdlib",
"version": "4.14.0"
}
],
"name": "env"
},
{
"modules": [
{
"name": "puppetlabs/stdlib",
"version": "4.14.0"
},
{
"name": "puppetlabs/azure",
"version": "1.1.0"
}
],
"name": "production"
}]Copied!GET /puppet/v3/environment_modules?environment=:environment
Supported HTTP Methods
GET
Supported Formats
JSON
Query Parameters
Provide one parameter to the GET request:
environment: Request information about modules pertaining to the specified environment only.
Responses
GET request with results
GET /puppet/v3/environment_modules?environment=env
HTTP/1.1 200 OK
Content-Type: application/json
{
"modules": [
{
"name": "puppetlabs/ntp",
"version": "6.0.0"
},
{
"name": "puppetlabs/stdlib",
"version": "4.14.0"
}
],
"name": "env"
}Copied!Environment does not exist
If you send a request with an environment parameter that doesn't correspond to the name of a directory environment on the server, the server returns an HTTP 404 (Not Found) error:
GET /puppet/v3/environment_modules?environment=doesnotexist
HTTP/1.1 404 Not Found
Could not find environment 'doesnotexist'Copied!No environment given
GET /puppet/v3/environment_modules
HTTP/1.1 400 Bad Request
An environment parameter must be specifiedCopied!Environment parameter specified with no value
GET /puppet/v3/environment_modules?environment=
HTTP/1.1 400 Bad Request
The environment must be purely alphanumeric, not ''Copied!Environment includes non-alphanumeric characters
If the environment parameter in your request includes any characters that are
not A-Z, a-z, 0-9, or _ (underscore), the server returns an HTTP 400 (Bad Request) error:
GET /puppet/v3/environment_modules?environment=bog|us
HTTP/1.1 400 Bad Request
The environment must be purely alphanumeric, not 'bog|us'Copied!No metadata.json file
If your modules do not have a metadata.json
file, puppetserver will not be able to determine the version of your module. In
this case, puppetserver will return a null value for version in the response
body.
Schema
An environment modules response body conforms to the environment modules schema.
Validating your json
If you have a response body that you'd like to validate against the environment_modules.json schema, you can do so using the ruby library json-schema.
First, install the ruby gem to be used:
gem install json-schemaCopied!Next, given a json file, you can validate its schema.
Here is a basic json file called example.json:
{
"modules": [
{
"name": "puppetlabs/ntp",
"version": "6.0.0"
},
{
"name": "puppetlabs/stdlib",
"version": "4.16.0"
}
],
"name": "production"
}Copied!Run this command from the root dir of the puppetserver project (or update the path to the json schema file in the command below):
ruby -rjson-schema -e "puts JSON::Validator.validate!('./documentation/puppet-api/v3/environment_modules.json','example.json')"Copied!If the json is a valid schema, the command should output true. Otherwise, the
library will print a schema validation error detailing which key or keys validate
the schema.
If you have a response that is the entire list of environment modules (i.e. the environment_modules endpoint), you will need to use this command to validate the json schema:
ruby -rjson-schema -e "puts JSON::Validator.validate!('./documentation/puppet-api/v3/environment_modules.json','all.json', :list=>true)"Copied!Authorization
Unlike other Puppet primary server service-based API endpoints, the environment modules API is
provided exclusively by Puppet Server. All requests made to the environment
modules API are authorized using the Trapperkeeper-based auth.conf feature
introduced in Puppet Server 2.2.0, and ignores the older Ruby-based authorization process
and configuration. The value of the use-legacy-auth-conf setting in the jruby-puppet
configuration section of puppetserver.conf is ignored for requests
to the environment modules API, because the Ruby-based authorization process is not equipped to
authorize these requests.
For more information about the Puppet Server authorization process and configuration
settings, see the auth.conf documentation.