Managing applications and devices
The following sections will guide you through the basic management capabilities of Drogue Cloud.
All management operations are available through the API. However, for an easier getting started experience,
the following examples will use the command line tool drg for performing the operations.
All following examples require that you are already logged in to a Drogue Cloud cluster using the command line
tool drg.
|
Applications
An application is the container for devices.A user can have multiple applications, but each device belongs to a single application.
Creating a new application
Create a new application using the following command:
drg create app my-appThis will create a new application named my-app. If the application name is already used, you will receive an
error, as application names are unique.
Modifying an application
Applications are defined by a JSON structure. It is possible to edit this structure in YAML format (for easier editing) using the following command:
drg edit app my-appThis will open an editor, and allow you to make modifications to the YAML source. When you close the editor, the change will be sent to the server for updating.
Deleting an application
An existing application can be deleted using the following command:
drg delete app my-app| Deleting an application may be delayed, as first all devices which require to be cleaned up will be processed. Once this is finished, the application might require cleanup too. Only once all resources are properly cleaned up, the application will be actually deleted. |
Devices
As devices belong to an application, you need to create an application first.
The following commands will explicitly select the application by providing the --app <app name> argument. You can
however use drg config set-default-app, to set a default application and omit the --app argument.
Create a new device
A new device is being created using the following command:
drg create device --app my-app my-device-1This will create my-device-1 as part of my-app.
In most cases a device will require additional information, like access credentials or gateway assignments. You can
provide initial configuration using the --spec <json> argument:
drg create device --app my-app my-device-1 --spec '{"credentials": {"credentials":[{ "pass": "foobar" }]}}'The --spec argument accepts a JSON string of the full "spec" section of the device.
Modifying a device
You can edit the device configuration in YAML the same as the application:
drg edit device --app my-app my-device-1This will open an editor, and allow you to make modifications to the YAML source. When you close the editor, the change will be sent to the server for updating.
Deleting a device
An existing device can be deleted using the following command:
drg delete device --app my-app my-device-1| If a device requires any cleanup, the device will be first marked as deleted, the cleanup will be processed, and then the device will be deleted. |
Setting password credentials
It is possible to set a password as access credentials. This way, when connecting, the username will be the device name.
Procedure
Configure the device, adding a password credentials entry:
metadata:
name: device
# …
spec:
# …
credentials:
credentials:
- pass: my-password (1)| 1 | One credential entry of type "password". |
You can also use hashed passwords. For this, you need to specify the hash algorithm:
metadata:
name: device
# …
spec:
# …
credentials:
credentials:
- pass:
bcrypt: "$2a$12$WsLmgORBv3WHZ3CjCiMzXOeo2hL5UEeq8PEd11q9BfbM/RWqb7c3G" (1)| 1 | One credential entry of type "password" as "bcrypt" hash. |
See Supported hashes for a list of supported password hashes.
Setting username/password credentials
It is also possible to set a username and password as credentials. In this case, the device ID must be transmitted through an alternate way, in order to look up the device. The provided username/password combination will then be checked against the configured username/password combination.
The way the device name is transmitted to the endpoint depends on the capabilities of the protocol endpoint. For example, using HTTP, the device name can be provided as an additional query parameter.
Procedure
Configure the device, adding a password credentials entry:
metadata:
name: device (1)
# …
spec:
# …
credentials:
credentials:
- user:
username: device-user (2)
password: bar (3)| 1 | The device name |
| 2 | The username |
| 3 | The plain text password |
You can also use hashed passwords, instead of plain text:
metadata:
name: device (1)
# …
spec:
# …
credentials:
credentials:
- user:
username: device-user (2)
password:
bcrypt: "$2a$12$WsLmgORBv3WHZ3CjCiMzXOeo2hL5UEeq8PEd11q9BfbM/RWqb7c3G" (3)| 1 | The device name |
| 2 | The username |
| 3 | The bcrypt hashed password |
See Supported hashes for a list of supported password hashes.
Setting username/password credentials (unique username)
If you want to use the username only for authenticating your device, without the need to provide an additional device identifier, you can use "unique usernames". These usernames are unique per application.
Procedure
Configure the device, adding a password credentials entry:
metadata:
name: device
# …
spec:
# …
credentials:
credentials:
- user:
username: device-user
password: bar
unique: true (1)| 1 | Setting the value to true makes the entry a unique username entry. |
As described in Setting username/password credentials, you can use hashed passwords too.
Configuring a gateway device
Every device can act as a gateway for another device. However, it must be granted the permission to act on behalf of that other device.
The way this is done, is by adding this information to the device connects through a gateway.