Add an event-state diagram for containers

[moxiegirl]

In the course of a pull request a contributor provided an event-state diagram to illustrate his technical point: (#11827 (comment))

The example he produced looks like this:

The diagram includes proposed states but eliminating those would produce a pretty sweet diagram for the docs. We could use the diagram in a container states page.

[mgood]

Oh thanks for opening an issue for this. While the other issue proposes a new "exit" event, I didn't include that in this diagram (in the current proposal, it would be following the "die" event at the bottom middle).

You can make a copy of the original Google Drawings doc if you'd like to make some changes.

This should cover the events as of API 1.17, except "exec_create", "exec_start", "export" and "import". Since those are out-of-band from the container's lifecycle, they didn't seem to fit here.

I'd love to see something like this included in the API docs, so let me know if I can help.

[moxiegirl]

@mgood It is a great diagram thank you for putting it together. (We will definitely shout out to you in the docs for this diagram). I was thinking of using it to have an article on container state. Do you have a suggestion for where you see it in the API docs?

[mgood]

Ah, I see that under "Container State" it refers to the state as "exited" which I called "stopped".

I think it would also be useful with the docs for the "events" API and events CLI, though they could just link to the Container State documentation. I was referring to those docs for how to use the events API, but they currently only include the event names without further description (the CLI docs also seem to be missing a couple events).

[thaJeztah]

Oh, that's looking great! Think this will be very useful, also for example when teaching colleagues.

Count me in 😄

Out of interest; is it in SVG (because that would even allow making the diagram interactive in future)

[LK4D4]

Supernice. Thank you!

[mgood]

Thanks, this diagram was part of a post I was working on for the @gliderlabs blog, which is now live here: http://gliderlabs.com/blog/2015/04/14/docker-events-explained/

@thaJeztah the original is on Google Drawings which has an SVG export option.

[thaJeztah]

@mgood thanks for the link, will read it straight on!

Are you willing to contribute the image (and possibly the docs changes)?

[mgood]

@thaJeztah well it sounded like @moxiegirl may have already started on the docs changes.

@moxiegirl let me know if you do want any more help or feedback.
Do you need something for copyright / licensing on the diagram?

[thaJeztah]

@mgood to follow the procedure properly, I think you'll have to create a PR and sign off your commit. That'll make sure that Docker has legal permission to use your work.

If the graphic has to be incorporated with docs changes written by @moxiegirl, I can see two options;

• Wait for the docs changes she's writing, and create a PR to add the image to that document
• Create a PR with just the image, then she can send you the text to add to the PR

It's quite busy at this moment because of the pending 1.6 release, so it'll probably have to wait a few days.

[mgood]

@thaJeztah I don't think that's necessary. To satisfy the DCO it's fine under item (b) for @moxiegirl or anyone to submit a change "based upon previous work ... covered under an appropriate open source license". So, I was trying to figure out how best to indicate this.

I'm in no rush, I just wanted to make sure it didn't get held up on anything from my end 😃

[thaJeztah]

@mgood shows how much I know about that legal mumbo jumbo 😄

[moxiegirl]

Hi folks, I've got the diagram done now. I've got to talk to the engine folks about placement --- so I expect to have full review later tomorrow once it appears in text. Here, for now, is the diagram:

[mgood]

@moxiegirl oh that looks great. Though, the arrow from "die" to "kill" stops a little short, and I'm assuming it was meant to connect. Thanks for the nice visual upgrade :)

[thaJeztah]

Oh that's looking awesome. Only "nit" I can come with is that some text is a bit close to the boxes, perhaps centering them on the connection-line could improve that.

I looked at the actual states/events, I think they're correct, but someone should check, to be sure.

Great work!

[moxiegirl]

OK, I've tweaked based on your suggestions.

[moxiegirl]

I'll get some time later this week to drop it into the API material. Email me if you want to do that yourself. mary@docker.com and I'll send the files.