Expose the machine readable state of a container when listing containers

[mariusGundersen]

PoC implementation of #18962 C

[calavera]

Change LGTM. We'll need to document this new field in the API reference guide.

[icecrime]

Makes sense to me! LGTM, thanks :-)

[mariusGundersen]

Maybe update the diagram of the state machine too, to match the names of the states?

[mariusGundersen]

I've updated the documentation for the /containers/json endpoint

[thaJeztah]

Thanks @mariusGundersen! can you also;

• Add a note to the API changes for 1.22; https://github.com/docker/docker/blob/master/docs/reference/api/docker_remote_api.md#v122-api-changes
• Squash your commits (so that there's only one commit in this PR)?

[mariusGundersen]

OK, so the valid states are: created|restarting|running|paused|exited|dead. This is what State will now return when calling /containers/json, but to filter you need to use the key Status rather than the key State. This is slightly confusing, so I propose that both Status and State can be used to filter the result, but that Status be deprecated.

[mariusGundersen]

@thaJeztah, I have updated the documentation, and I have added the ability to filter using the state key. I've also changed the diagram to use the states exposed through the api. If this looks OK I will squash the commits

[thaJeztah]

Thanks @mariusGundersen if we want to deprecate the "status" filter, that will also affect the command line, and we need to add a deprecation notice, so these docs need to be updated as well if we deprecate this;

• https://github.com/docker/docker/blob/master/docs/misc/deprecated.md
• https://github.com/docker/docker/blob/master/docs/reference/commandline/ps.md
• https://github.com/docker/docker/blob/master/man/docker-ps.1.md

I'm not sure yet if we want this, given that filtering by status is pretty common, and deprecating that filter may affect many people.

I'll move this PR back to "design review" so that we can discuss the deprecation

[thaJeztah]

ping @calavera @icecrime wdyt on deprecating the status filter in favor of state?

[mariusGundersen]

I'll break this pull-request apart into two pull requests: one that adds state to the /containers/json response, and one that replaces status with state in the filters in the request, both in the API and in the CLI

[thaJeztah]

sgtm,that will probably make merging easier, and moves the discussion to another PR. thanks!

[thaJeztah]

thanks! docs LGTM

[vdemeester]

ping @mariusGundersen We need to make a change to docker/engine-api. I'm making a PR to get it quick. See docker/engine-api#45.

But for the time beeing, moving back to code-review 😅

[thaJeztah]

@mariusGundersen unfortunately, it looks like this just didn't make the cut for the 1.10 release, so the docs changes need to be updated to be in the v1.23 API version 😢

[mariusGundersen]

I love deadlines, especially the whooshing sound they make as they fly by...

[cpuguy83]

Looks like we're still waiting on that engine-api update?

[calavera]

Looks like we're still waiting on that engine-api update?

the vendored version in master should have this field already.

[cpuguy83]

Ah yep, it's there now, and a duplicate field now.

@mariusGundersen Can you remove your changes from vendor since this is now in?

[mariusGundersen]

I've force pushed a fix. I kept the order of the variables from engine-api (State before Status, which is the alphabetical order).

[runcom]

LGTM moving again back to doc review since this was previously there

[thaJeztah]

LGTM

ping @vdemeester @MHBauer

[vdemeester]

LGTM 🐹