POST /command/create-connection

Create a new connection entry in the node inventory service database.

Request format

Connection database entries contain connection settings, such as certnames, transport methods, and credentials, that are used to connect to nodes (identified by their certnames).

When Forming node inventory API requests to this endpoint, the request body must be a JSON object that uses these required keys:

• certnames: An array containing a list of certnames to associate with the supplied connection details.
• type: A string that is either ssh or winrm. This tells bolt-server which connection type to use to access the node when running a task.
• parameters: An object containing key/value pairs specifying the connection parameters for the specified transport type. Required and optional parameters depend on the transport method and are described further below.
  When the Puppet orchestrator targets a certname to run a task, it first considers the value of the hostname key present in the connection parameters, if supplied. Otherwise, it uses the value of the certnames key as the hostname. Make sure to include the hostname key only when the hostname differs from the certname. If you're configuring multiple connections (certnames) at once, do not include a hostname key.
• sensitive_parameters: An object containing key/value pairs defining the necessary sensitive data for connecting to the provided certnames, such as usernames and passwords. These values are stored in an encrypted format. Required and optional parameters depend on the transport method and are described further below.
• duplicates: A string that is either error or replace. This specifies how to handle cases where supplied certnames conflict with existing certnames stored in the node inventory connections database. If you specify error, the endpoint returns a 409 response if it finds any duplicate certnames. If you specify replace, the endpoint overwrites the existing certname with the new connection details if it finds a duplicate.

Here is an example of a complete request to the /command/create-connection endpoint that specifies and SSH connection:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/inventory/v1/command/create-connection"
data='{"certnames": [
           "sshnode1.example.com",
           "sshnode2.example.com"
        ], 
        "type": "ssh", 
        "parameters": {
            "port": 1234, 
            "connect-timeout": 90, 
            "user": "inknowahorse", 
            "run-as": "fred"
           },
        "sensitive_parameters": {
            "password": "password", 
            "sudo-password": "xtheowl"
         }, 
         "duplicates": "replace"
}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

SSH parameters and sensitive parameters

When the connection type is ssh, the following keys are available for the parameters object. Only the user key is required.

When the connection type is ssh, the following keys are available for the sensitive-parameters object:

WinRM parameters and sensitive parameters

When the connection type is winrm, the following keys are available for the parameters object. Only the user key is required.

When the connection type is winrm, the sensitive-parameters object allows only one key, which is the password key. This key required and contains a string specifying the password to use to authenticate the connection.

Response format

If the request is well-formed, valid, and the entries are successfully recorded in the database, the server returns a 201 response with a JSON object containing the connection_id for each connection's record. For example:

{
  "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec"
}

The endpoint also inserts each of the provided certnames into PuppetDB with an empty fact set, if they are not already present. After certnames are added to PuppetDB, you can view them from the Nodes page in the Puppet Enterprise (PE) console. You can also add them to your inventory node lists when you set up jobs to run tasks.

Error responses

Error responses follow the usual format of Node inventory API errors.