go-c8y-cli icon indicating copy to clipboard operation
go-c8y-cli copied to clipboard
verified publisher icon reubenmiller

Support of Advanced Software Management

Open k-butz opened this issue 3 years ago • 4 comments

With 10.14 the 'Advanced Software Management Microservice' got introduced to Cumulocity. It can be used to:

  • list all software packages installed on a device via GET /service/advanced-software-mgmt/software?deviceId=<deviceId>
  • set a list of installed software packages on a device via POST /service/advanced-software-mgmt/software?deviceId=<deviceId>
  • append software packages to the list of installed software via PUT /service/advanced-software-mgmt/software?deviceId=<deviceId>
  • remove software from a device DELETE /service/advanced-software-mgmt/software?deviceId=<deviceId>

See details in docs here: https://cumulocity.com/guides/reference/device-management-library/#advanced-software-management.

=> Would be benefitial to support this new service in go-c8y-cli. Maybe with a c8y devices software sub-command?

k-butz avatar Feb 04 '23 19:02 k-butz

I started integrating it (not timeline just yet), but ran into the following thing that I don't like too much, mainly regarding the deletion of software (e.g. c8y devices software delete)

To delete a software item both the name and version needs to match. If it does not match both then it does not delete anything.

So my problems are:

  • No indication from the server that the package was successfully deleted...very hard for the user to know which version is on the device without doing their check first (though this could be solved by tab completion)

    • Also the device will be the pipeline object, so you can't pipe the result from c8y devices software list as the output does not contain the device id (just a list of software, without the context)

  • The user needs to know the version they are deleting so it makes it impossible to easy purge a software by name only (as the version might be different across devices):

    # This will not work :(
c8y devices list | c8y devices software delete --name "myPackage"

reubenmiller avatar Feb 05 '23 21:02 reubenmiller

@ButKor I've been playing around with this recently and this is the current interface that I put together, can you give feedback on it?

Current implementation

The following shows the current implementation to give an idea of the upcoming feature.

Set/replace software list

c8y devices software set --device 129203 --name app --version 1.0.0 --url "http://example.com" --type apt

Note: The command does not have any output

Software list afterwards

| name       | softwareType | url                     | version    |
|------------|--------------|-------------------------|------------|
| app        | apt          | http://example.com      | 1.0.0      |

List software

c8y devices software list --device 129203

# Filtering is also supported
c8y devices software list --device 129203 --name "a*" --version "*"

Output

| name       | softwareType | url                     | version    |
|------------|--------------|-------------------------|------------|
| app        | apt          | http://example.com      | 1.0.0      |

Add software packages

Add a single package to the existing software list on a device.

c8y devices software add --device 129203 --name customApp1 --version 2.0.1 --url "http://example.com" --type apt

Note: The command does not have any output

Software list afterwards

| name       | softwareType | url                     | version    |
|------------|--------------|-------------------------|------------|
| app        | apt          | http://example.com      | 1.0.0      |
| customApp1 | apt          | http://example.com      | 2.0.1      |

Delete software packages

Delete a single package from the existing software list on a device.

c8y devices software delete --device 129203 --name customApp1 --version "2.0.1"

Note: The command does not have any output

Software list afterwards

| name       | softwareType | url                     | version    |
|------------|--------------|-------------------------|------------|
| app        | apt          | http://example.com      | 1.0.0      |

Open questions

Handling multiple packages is not so nice

At the moment the commands only work for a single package as it relies on --name, --version and --type to be defined. You can set multiple packages using the --template flag but this means you need to know the expected data structure, e.g. [{name:'app1',version:'1.2.3'},{name:'app2',version:'3.0.0'}]

Option 1: Accept csv values for a flag, and allow it be provided multiple times

Support a --software flag which accepts the package info as a csv, e.g. {name},{version},{url},{type}.

c8y devices software set --device 12345 --software "app1,1.0.0" --software "app2,2.0.0,,apt"

The only thing I don't like about this is that it is not very explicit.

reubenmiller avatar Mar 09 '23 19:03 reubenmiller

Thanks for looking into it - I like it!

Just few comments:

  • Would this subcommand also work for legacy devices which use e.g. the c8y_SoftwareList? If not it might get confusing as the command has the generic name "software" but only works for certain/new device integrations. I can do some research here.
  • I know that its the server who does not respond a body when setting/adding software packages. But some output that confirms it worked would be benefitial imho. Maybe CLI should just respond in the output e.g. 201: Software package created.
  • I like the idea of the --software CSV-Syntax. I would just make sure it has the same order than the existing Smart Rest 2 templates (name,version,type,url)

k-butz avatar Mar 10 '23 09:03 k-butz

Would this subcommand also work for legacy devices which use e.g. the c8y_SoftwareList? If not it might get confusing as the command has the generic name "software" but only works for certain/new device integrations. I can do some research here.

Yes, the microservice seems to work fine with also using the c8y_SoftwareList fragment on the device management object.

I know that its the server who does not respond a body when setting/adding software packages. But some output that confirms it worked would be benefitial imho. Maybe CLI should just respond in the output e.g. 201: Software package created

I would avoid this if possible as other commands don't currently do this (with the exception of delete commands). However no response does not always indicate that something was done. For example in the software delete command, if no matches are found, then the service still responds with status code 200 (and not 404), so printing out a message saying "deleted" might be misleading.

Also I just tested the c8y devices software add and it returns status code 200 as well (not 201).

I like the idea of the --software CSV-Syntax. I would just make sure it has the same order than the existing Smart Rest 2 templates (name,version,type,url)

Ok I will put together something along those lines. The csv field order name,version,type,url to align with the smartrest 2.0 format. Though the --software flag would replace the --name, --version, --url and --type.

reubenmiller avatar Mar 10 '23 11:03 reubenmiller