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-app

This 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-app

This 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-1

This 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 '{"authentication": {"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-1

This 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.

Pre-requisites

You have created a device

Procedure

Configure the device, adding a password credentials entry:

metadata:
  name: device
  # …
spec:
  # …
  authentication:
    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:
  # …
  authentication:
    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.

Pre-requisites

You have created a device

Procedure

Configure the device, adding a password credentials entry:

metadata:
  name: device (1)
  # …
spec:
  # …
  authentication:
    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:
  # …
  authentication:
    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.

Pre-requisites

You have created a device

Procedure

Configure the device, adding a password credentials entry:

metadata:
  name: device
  # …
spec:
  # …
  authentication:
    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.

Setting X.509 client certificate credentials

If you want to use client certificates to authenticate your device, your application must be configured with a trust root that can verify the device.

Pre-requisites

You have created an application

Procedure

Configure the application, adding a password credentials entry:

metadata:
  name: application
  # …
spec:
  # …
  trustAnchors:
    anchors:
      - certificate: <base64 encoded certificate> (1)

1	The certificate must be a base64-encoded DER-encoded X.509 certificate.

The device authenticating must present the client certificate in the (D)TLS handshake. The X.509 certificate issuer must correspond to the application name, and the subject must correspond to the device id.

Setting TLS-PSK credentials

If you want to use pre-shared keys to authenticate your device, your device must be configured with the pre-shared key you wish to use.

Pre-requisites

You have created a device

Procedure

Configure the device, adding a password credentials entry:

metadata:
  name: device
  # …
spec:
  # …
  authentication:
    credentials:
      - psk:
          key: aGV5LXJvZG5leQ== (1)
          validity: (2)
            notBefore: 2022-10-05T07:05:26Z (3)
            notAfter: 2023-10-05T07:05:26Z (4)

1	The key must be base64-encoded.
2	(Optional) If not present, the pre-shared key is valid forever.
3	The earliest date (ISO 8601 date) the key will be valid.
4	The latest date (ISO 8601 date) the key will be valid.

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.

Pre-requisites

You have created two devices.
- One that should act as gateway (named gateway in the following steps).
- One that should act as the actual device (named sensor in the following steps).
The gateway device has access credentials configured, so that the gateway can connect to the cloud.

Procedure

In the configuration of the actual device, select the devices that can act as a gateway:

metadata:
  name: sensor
  # …
spec:
  # …
  gatewaySelector:
    matchNames:
      - gateway

It is possible to use one or more devices as gateway.

Hashed passwords

It is possible to store passwords either plain text or hashed.

Supported hashes

The following hash types are currently supported:

bcrypt – Bcrypt hash
sha512 – SHA512 crypt (Scheme ID 6)