Add docker network command

[jaudiger]

Reference: https://docs.docker.com/engine/reference/commandline/network/

Proposed initial syntax (more can be added in future):

• Command: docker network create networkName

docker:
  description: "Create a network"
  network:
    name: networkName

• Command: docker network rm networkName

docker:
  description: "Delete a network"
  network:
    name: networkName
    absent: false

• Command: docker network connect networkName containerA containerB

docker:
  description: "Add container to a network"
  network:
    name: networkName
    connected:
    - containerA
    - containerB

• Command: docker network disconnect networkName containerA containerB

docker:
  description: "Disconnect container from a network"
  network:
    name: networkName
    disconnected:
    - containerA
    - containerB

• Command: docker network disconnect -f networkName containerA containerB

docker:
  description: "Force container disconnect on a network"
  network:
    name: networkName
    disconnected:
    - containerA
    - containerB
    force: true

The network command can be useful to create/delete a network and associated them with containers.

[vdice]

Nice! In each section/example above, can we add the corresponding docker cli command that the syntax would translate into? It would help me comprehend :)

The network command and the volume command (#35) are tricky in that they both have sub-commands, unlike, say, docker pull, etc.

Would we want to support the full suite of docker network actions/sub-commands besides create/delete/connect? Such as prune, inspect, rm, etc.?

If so, thoughts on how to represent in syntax? Should we have a dedicated section for command (or something similar)? E.g.,

docker:
  description: "Remove all unused networks"
  network:
    command: prune
    force: true

(Similar thoughts apply to #35)

[jaudiger]

Nice! In each section/example above, can we add the corresponding docker cli command that the syntax would translate into? It would help me comprehend :)

I added the commands.

Would we want to support the full suite of docker network actions/sub-commands besides create/delete/connect? Such as prune, inspect, rm, etc.?

If we want to support all the possible commands, well, I guess, we should have another approach to handle them without too much complexity for the end-user. I created those issues to talk about the correct design. And what you suggested could go in this direction, let me try to adapt the above examples with your approach. Like that, we'll have examples for both designs:

• Command: docker network create networkName

docker:
  description: "Create a network"
  network:
    command: create
    name: networkName

• Command: docker network rm networkName

docker:
  description: "Delete a network"
  network:
    command: rm
    name: networkName

• Command: docker network connect networkName containerA containerB

docker:
  description: "Add container to a network"
  network:
    command: connect
    name: networkName
    containers:
    - containerA
    - containerB

• Command: docker network disconnect networkName containerA containerB

docker:
  description: "Disconnect container from a network"
  network:
    command: disconnect
    name: networkName
    containers:
    - containerA
    - containerB

• Command: docker network disconnect -f networkName containerA containerB

docker:
  description: "Force container disconnect on a network"
  network:
    command: disconnect
    name: networkName
    containers:
    - containerA
    - containerB
    force: true

[vdice]

@jaudiger thanks for adding the commands in-line -- super helpful.

I do think, even if we don't implement all of the network sub-commands in a first PR, we design things such that more could be added. Somehow my initial suggestion of command: <command> doesn't feel perfect... I wonder if we just make it top-level, e.g.

docker:
  description: "Force container disconnect on a network"
  network:
    disconnect:
      name: networkName
      containers:
      - containerA
      - containerB
      force: true

I have a feeling that doing so might help keep each (sub-)command's schema distinct from others... though that's just a hunch as I haven't looked at what the updated schema is like.

These are just thoughts/suggestions, though. Happy to learn about what you're leaning towards as well.

[jaudiger]

My feedbacks about the three approaches (list in the same order as inside this issue):

• Pros: The command is hidden, it can help people who don't know how the CLI of docker is working. They don't need to be aware of the subcommands. But in my opinion, the persons that will use this mixin will not be new to the docker world.
• Cons: If we need to add more commands in the future, it could be painful. And since we don't have a specific schema for a subcommand, we will have to check the arguments provided and if they are correct for the current "pattern".

• Pros: Here we have the sub-commands, and I think for people already knowing Docker, it will not look like as magic as in the first option. If we want to support a new subcommand, it will be much easier.
• Cons: As the first option, since we don't have a specific schema for a subcommand, we will have to check the arguments provided and if they are correct for the current command.

• Pros: This time, we can have a specific schema for the subcommand. And arguments checking will just be a question of checking if we are able to deserialize the yaml. Adding a new command is just a matter of adding a new structure.
• Cons: Should we allow multiple subcommands? I would tend to say no, but it's just my personal opinion. Since we will have to check it when we will deserialize the yaml.

Example:

docker:
  description: "Force container disconnect on a network"
  network:
    connect:
      name: networkName
      containers:
      - containerA
      - containerB
    disconnect:
      name: networkName
      containers:
      - containerA
      - containerB
      force: true

[vdice]

Should we allow multiple subcommands?

I agree, I don't think we should allow multiple subcommands under one network invocation.

I'm still leaning towards 3, with direct mapping of yaml fields to docker network subcommands/args, for clarity/easy comprehension. I find the approach in 1, employing a bit more magic, as well as yaml fields that don't map directly to docker command flags, less immediately clear.

[jaudiger]

I'm still leaning towards 3, with direct mapping of yaml fields to docker network subcommands/args, for clarity/easy comprehension. I find the approach in 1, employing a bit more magic, as well as yaml fields that don't map directly to docker command flags, less immediately clear.

I tend to the same conclusion. My favorite approach is the last one. Since it's easier to understand and to expand for future commands.