Internet Explorer is no longer supported. Many things will still work, but your experience will be degraded and some things won't function. Please use a modern browser such as Edge, Chrome, or Firefox.
 
No matching results found

Infrastructure Management

Modified on July 26, 2024view on GitHub

The Infrastructure Management API endpoints can query, create, and update servers, environments, and server roles; they are designed to automate the setup and management of a BuildMaster instance.

API Key Usage

All of these endpoints require that an API key with Infrastructure Management access is passed into each request. The examples use a query string for simplicity, but you can also use a header, a form value, or a JSON property. For more information, see API Access and API Keys for more information.

Data Specification

This endpoint sends and receives entries as JSON objects.

Server

Property Format
name A string of no more than fifty characters: numbers (0–9), upper- and lower-case letters (a–z), dashes (-), and underscores (_); must start with a letter, and may not start or end with a dash or underscore
roles An array of strings, each consisting of a server role name
environments An array of strings, each consisting of an environment name
drift A string value of reportOnly; this is always ignored by BuildMaster when importing or comparing, and is only used by Otter
serverType A string value of windows, ssh, powershell, or local
agentType A string value of Inedo, Indeo Listener, SSH, PowerShell, or Local
agentVersion A string value representing the version of an Inedo or Inedo Listener agent
hostName A string of the hostname of the server; this property is not present when the type is local
port An integer of the port to use of the server; this property is not present when the type is local
encryptionType A string value of aes, ssl, or none; this property is only present when the type is windows
encryptionKey A string containing exactly 32 hexidecimal characters; this property is only present when the encryption is aes
requireSsl A boolean indicating whether to only connect using SSL; this property is only present when the encryption is ssl
credentialsName A string containing the name of a resource credential to use; this property is only present when the type is ssh or powershell
tempPath A string containing the name of the temporary path to use for files; this property is only present when the type is ssh or powershell
wsManUrl A string containing the WSMan endpoint; this property is only present when the type is powershell
active A boolean indicating whether the server is active or disabled
variables An object with property/values representing variable names and values
  • A variable name is a string of no more than fifty characters: numbers (0–9), upper- and lower-case letters (a–z), dashes (-), spaces ( ), and underscores (_) and must start with a letter, and may not start or end with a dash, underscore, or space; a variable
  • A variable value is a string of any number of characters

Server Role

Property Format
name same format as server.name
variables same format as server.variables

Environment

Property Format
name same format as server.name
parentName a string containing the name of the parent environment, or null if there is no parent environment
variables same format as server.variables
active A boolean indicating whether the environment is active or disabled (as of BuildMaster 6.1.10)

Endpoint Specifications

All of the infrastructure management endpoints follow the same convention:

POST /api/infrastructure/«entry-type»/«action-type»/«entry-name»?key=«api-key»

  • entry-type is one of servers, roles, or environments
  • action-type is one of [list](#list), [create](#create), [update](#update), or [delete](#delete)
  • entry-name is the name of the entry being created, updated, or deleted; it is not valid on a list action type

List Entries

This returns a status of 200 (on success), or 403 (api key not authorized), and a body containing only an array of entry objects.

List Servers

POST /api/infrastructure/servers/list?key=secure123

[
  {
    "name": "hdarsintsv1",
    "roles": \["web","hdars"\],
    "environments": \["integration"\],
    ...
    "variables": { 
                   "disk-path": "/var/hdars/1000", 
                   "app-name": "hdars" 
                 },
    "active": true
  },
  {
    "name": "mdapxsv",
    "roles": \[\],
    "environments": \["test1","test2"\],
    ...
    "variables": {}
  },
  { ... }
]

List Server Roles

POST /api/infrastructure/roles/list?key=secure123

[
  {
    "name": "web",
    "variables": { 
                   "websites-root": "c:\\webroots\\"
                 }
  },
  {
    "name": "hdars",
    "variables": {}
  },    
  { ... }
]

List Environments

POST /api/infrastructure/environments/list?key=secure123

[
  {
    "name": "integration",
    "parent": null,
    "variables": { 
                   "database-alias": "intagration"
                 }
  },
  {
    "name": "testing",
    "parent": null,
    "variables": { 
                   "database-alias": "test"
                 }
  },
  {
    "name": "test1",
    "parent": "testing",
    "variables": {}
  },
  {
    "name": "test2",
    "parent": "testing",
    "variables": {}
  },
  { ... }
]

The above is an example, and truncates responses for readability with ellipses; the API key used requires the Infrastructure_View permission.

Create Entry

This returns a status of 201 (on success), 403 (api key not authorized), or 422 (invalid entry), and an body containing either the entry object, or a description of the 422 status.

If the entity references another entity (e.g., in the roles property of a server, or the parent property of environment) and the referenced entity does not exist, an invalid entry (422) will be returned.

We opted not to provide an example, as the request body is simply a JSON object formatted like the list examples. The API key used requires the Infrastructure_Manage permission.

Update Entry

This returns a status of 200 (on success), 403 (api key not authorized), 404 (entry not found), or 422 (invalid entry), and an body containing either the entry object, or a description of the 422 status.

If the entity references another entity (e.g., in the roles property of a server, or the parent property of environment) and the referenced entity does not exist, an invalid entry (422) will be returned.

If there are missing properties on the entity, only the specified properties will be updated.

Update Server

POST /api/infrastructure/servers/update/hdarsintsv1?key=secure123

{
  "roles": \["web","hdars","code-server"\], 
  "encryption": "none"
}

Note that, in this case, the encryptionKey property would be removed on update because the encryption type changed.

Rename Server Role

POST /api/infrastructure/roles/update/hdars?key=secure123

{ "name": "new-hdars"}

Remove Parent Environment

POST /api/infrastructure/environments/update/test1?key=secure123

{ "parent" : null }

Delete Entry

This returns a status of 200 (on success), 403 (api key not authorized), or 404 (entry not found), and an empty body.

In this article

inedo.com | Support | MyInedo

docs © 2024 Inedo, LLC