Add two new actions 'info' and 'list' with an optional quiet mode

[tortuetorche]

Hi,

Here two actions info and list, which can be useful in a Continuous Integration (CI)/Continuous Delivery CD workflow, with tool like GitLab CI:

The info action:

psu -a info -u admin -p password -l http://portainer.local -n mystack

Output the JSON object of the stack if it's already deployed:

{
  "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Name": "mystack",
  "Type": "1",
  "EndpointID": "1",
  "EntryPoint": "docker-compose.yml",
  "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
  "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Env": [
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "value": "password"
    }
  ]
}

The info action with the quiet mode enabled:

psu -a info -u admin -p password -l http://portainer.local -n mystack -q

Output the stack name if it's already deployed:

mystack

The list action:

psu -a list -u admin -p password -l http://portainer.local

Output a JSON array of the stacks already deployed:

[
  {
    "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Name": "mystack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
    "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Env": [
      {
        "name": "MYSQL_ROOT_PASSWORD",
        "value": "password"
      }
    ]
  },
  {
    "Id": "mysecondstack_i0649w9uo9wtx1zesujpofkck",
    "Name": "mysecondstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "i0649w9uo9wtx1zesujpofkck",
    "ProjectPath": "/data/compose/mysecondstack_i0649w9uo9wtx1zesujpofkck"
  },
  {
    "Id": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "Name": "mythirdstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "ProjectPath": "/data/compose/mythirdstack_mythirdstack_w9uo9wtxi064ujpofkck91zes"
  },
]

The list action with the quiet mode enabled:

psu -a list -u admin -p password -l http://portainer.local -q

Output the name of the stacks already deployed:

mystack
mysecondstack
mythirdstack

Feedback are welcome!

NB: I also plan to add two new actions status (borrowed from Helm) and rollout (borrowed from kubectl). But for services/tasks instead of stack centric with the help of theses resources: https://gist.github.com/deviantony/77026d402366b4b43fa5918d41bc42f8#execute-docker-queries-against-a-specific-endpoint and https://docs.docker.com/engine/api/v1.30/#operation/TaskList

Cheers,
Tortue Torche

[tortuetorche]

Here a use case for the info action:
Check if the stack is already deployed:

exist=$(psu -a info -u admin -p password -l http://portainer.local -n mystack -q)

if [ -n "$exist" ]; then
  echo OK
else
  echo KO
fi

# OR check the exit code of the last executed command:
status=$?
if $(exit $status); then
  echo OK
else
  echo KO
fi

[greenled]

Hello again @tortuetorche! Thank you for your interest and your contributions to this project. I have also been playing for a while with the idea of "list" and "info" features, and I am glad someone else did too and even implemented them.

The quiet mode (as proposed here), looks confusing to me: there already exists a verbose mode, which could be used with quiet mode. Both work different, but at first sight the terms could be confusing for new users. Moreover, the quiet mode would be relevant only for list and info actions, while the other modes work for all actions. Maybe a "mode" is not the most suitable place for this feature? Also, the same result could be obtained (with greater flexibility) just by piping the script output to jq and applying the .Name filter. I think (I have not tested it yet) your example to check if a stack is already deployed would also work without the quiet mode.

As you are bringing several features here please, would you mind using separate pull requests?

[greenled]

@tortuetorche sorry, I didn't notice yout comment about status and rollout actions until now. I like the idea. Please open two issues to shape the concepts better.

[tortuetorche]

Hi @greenled,

The quiet mode (as proposed here), looks confusing to me: there already exists a verbose mode

The quiet mode is inspired by the --quiet option of docker images command, I think it can be useful for end users who might not have knowledge of the jq command

I didn't notice you comment about status and rollout actions until now

I'm working on these new actions, right now, it looks promising but I need to clean up some code before publishing them

Have a good day,
Tortue Torche

[greenled]

Ok, I see your point. Let's have a quiet mode.

[tortuetorche]

Closing in favor of my upcoming pull request who add these two actions and even more...
See my progress here: https://github.com/tortuetorche/portainer-stack-utils/tree/next