Skip to content

Provisioning API

Jump to bottom
Robert Hafner edited this page Jul 6, 2018 · 3 revisions

The Provisioning API can be used to integrate an organizations provisioning process with Nebula in a number of ways, including-

  • Restricting access to machines until their provisioning cycle has completed,
  • Updating machine Name tags without giving the machine access to update its own AWS Tags,
  • Passing information to provisioning systems that can be used to customize the machines, such as locking machines down to the user who launched them.

Authentication

Token Based

Admins can create API Tokens from the Tokens screen. These tokens come in two flavors-

  • API Tokens can be used from any machine to interact with the API without restriction.

  • Instance Tokens can make the same calls the API Tokens can, but have the added restriction that they can only access or modify data from the instance they are being used on. This allows a newly provisioned machine to do things like change its status, but not allow it to change the status of other instances. Thus a single Instance Token can be used for a whole fleet without the machines interfering with each other.

When using tokens the HTTP Headers id and token should be set with the token id and token.

LDAP Based

The API can also be accessed using the credentials of a Nebula Admin. This method is not recommended as Admin credentials can do a lot more and should be guarded carefully. If used it is recommended that a dedicated admin user be created which does not have access to the rest of the system.

When using this method the HTTP Headers username and password should be set with user's credentials.

NebulaCLI

The NebulaCLI provides a simple program that can be used in shell scripts to handle most needed tasks without having to get into the specifics of the API itself.

With it you can set the system status to Live-

nebulacli set_status Live

You can also have it tell Nebula the system's name-

nebulacli set_name $(cat /etc/hostname)

API Endpoints

GET /api/sshkeys

This returns all of the public keys stored by active users (users who have keys stored and have not been banned). The object returned has the usernames as the key with a list of ssh keys as the value of each user.

GET /api/instances/<instance_id>/name

This returns the name of the machine. This is the equivalent of looking up the Name tag in AWS.

PUT /api/instances/<instance_id>/name

This changes the name of the machine. This is the equivalent of changing the Name tag in AWS.

GET /api/instances/<instance_id>/status

This returns the status of the machine. This is the equivalent of looking up the Status tag in AWS.

PUT /api/instances/<instance_id>/status

This changes the status of the machine. This is the equivalent of changing the Status tag in AWS.

Status is used by Nebula to determine where in the provisioning process a machine is. To signify that a machine is ready for the User to access the status must be set to Live.

GET /api/instances/<instance_id>/user

This returns the user of the machine. This is the equivalent of looking up the User tag in AWS.

This can be used alongside provisioning scripts to ensure that the specific user is present, or to lock a machine down to just that user.

There is no equivalent function to change the user via the API. If that is desired it can be done by the administrator using the AWS console or API.

Clone this wiki locally