Skip to content

network: add container networking intro from docker run reference #18753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thaJeztah merged 1 commit into from
Dec 12, 2023
Merged

network: add container networking intro from docker run reference #18753

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 80 additions & 15 deletions content/network/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,78 @@ aliases:
Container networking refers to the ability for containers to connect to and
communicate with each other, or to non-Docker workloads.

A container has no information about what kind of network it's attached to,
or whether their peers are also Docker workloads or not.
A container only sees a network interface with an IP address,
a gateway, a routing table, DNS services, and other networking details.
That is, unless the container uses the `none` network driver.
Containers have networking enabled by default, and they can make outgoing
connections. A container has no information about what kind of network it's
attached to, or whether their peers are also Docker workloads or not. A
container only sees a network interface with an IP address, a gateway, a
routing table, DNS services, and other networking details. That is, unless the
container uses the `none` network driver.

This page describes networking from the point of view of the container,
and the concepts around container networking.
This page doesn't describe OS-specific details about how Docker networks work.
For information about how Docker manipulates `iptables` rules on Linux,
see [Packet filtering and firewalls](packet-filtering-firewalls.md).

## User-defined networks

You can create custom, user-defined networks, and connect multiple containers
to the same network. Once connected to a user-defined network, containers can
communicate with each other using container IP addresses or container names.

The following example creates a network using the `bridge` network driver and
running a container in the created network:

```console
$ docker network create -d bridge my-net
$ docker run --network=my-net -itd --name=container3 busybox
```

### Drivers

The following network drivers are available by default, and provide core
networking functionality:

| Driver | Description |
| :-------- | :----------------------------------------------------------------------- |
| `bridge` | The default network driver. |
Copy link
Member

@thaJeztah thaJeztah Dec 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we document the Windows drivers, such as nat, default, and transparent anywhere? Also see moby/moby#46447

Copy link
Contributor Author

@dvdksn dvdksn Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤷🏻 :windows-fire-fine:

Copy link
Member

@thaJeztah thaJeztah Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, let's create a tracking ticket for this one somewhere. There's quite a gap in our docs in this area because Microsoft at the time decided to document these in their own "container" documentation only, and not to contribute those parts to our docs 😞 (and most of these are not defined in our code, but provided by the Windows API / sdk so we may not even be aware of all options).

| `host` | Remove network isolation between the container and the Docker host. |
| `none` | Completely isolate a container from the host and other containers. |
| `overlay` | Overlay networks connect multiple Docker daemons together. |
| `ipvlan` | IPvlan networks provide full control over both IPv4 and IPv6 addressing. |
| `macvlan` | Assign a MAC address to a container. |

For more information about the different drivers, see [Network drivers
overview](./drivers/_index.md).

## Container networks

In addition to user-defined networks, you can attach a container to another
container's networking stack directly, using the `--network
container:<name|id>` flag format.

The following flags aren't supported for containers using the `container:`
networking mode:
Comment on lines +69 to +70
Copy link
Member

@thaJeztah thaJeztah Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some / all of these also apply to host mode networking (in which case the container doesn't have a network-namespace, and no IP-address of its own).

We can look at that in a follow-up as well.


- `--add-host`
- `--hostname`
- `--dns`
- `--dns-search`
- `--dns-option`
- `--mac-address`
- `--publish`
- `--publish-all`
- `--expose`

The following example runs a Redis container, with Redis binding to
`localhost`, then running the `redis-cli` command and connecting to the Redis
server over the `localhost` interface.

```console
$ docker run -d --name redis example/redis --bind 127.0.0.1
$ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1
Comment on lines +87 to +88
Copy link
Contributor Author

@dvdksn dvdksn Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

followup: s/redis/nginx/, maybe (not only here but generally)

```

## Published ports

By default, when you create or run a container using `docker create` or `docker run`,
Expand All @@ -38,12 +98,12 @@ This creates a firewall rule in the host,
mapping a container port to a port on the Docker host to the outside world.
Here are some examples:

| Flag value | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 8080:80` | Map port `8080` on the Docker host to TCP port `80` in the container. |
| Flag value | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 8080:80` | Map port `8080` on the Docker host to TCP port `80` in the container. |
| `-p 192.168.1.100:8080:80` | Map port `8080` on the Docker host IP `192.168.1.100` to TCP port `80` in the container. |
| `-p 8080:80/udp` | Map port `8080` on the Docker host to UDP port `80` in the container. |
| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port `8080` on the Docker host to TCP port `80` in the container, and map UDP port `8080` on the Docker host to UDP port `80` in the container.|
| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port `8080` on the Docker host to TCP port `80` in the container, and map UDP port `8080` on the Docker host to UDP port `80` in the container. |

> **Important**
>
Expand Down Expand Up @@ -90,8 +150,11 @@ you can use the `--alias` flag to specify an additional network alias for the co

## DNS services

By default, containers inherit the DNS settings of the host,
as defined in the `/etc/resolv.conf` configuration file.
Containers use the same DNS servers as the host by default, but you can
override this with `--dns`.

By default, containers inherit the DNS settings as defined in the
`/etc/resolv.conf` configuration file.
Containers that attach to the default `bridge` network receive a copy of this file.
Containers that attach to a
[custom network](network-tutorial-standalone.md#use-user-defined-bridge-networks)
Expand Down Expand Up @@ -128,10 +191,12 @@ resolution.

### Custom hosts

Custom hosts, defined in `/etc/hosts` on the host machine, aren't inherited by containers.
To pass additional hosts into container, refer to
[add entries to container hosts file](../engine/reference/commandline/run.md#add-host)
in the `docker run` reference documentation.
Your container will have lines in `/etc/hosts` which define the hostname of the
container itself, as well as `localhost` and a few other common things. Custom
hosts, defined in `/etc/hosts` on the host machine, aren't inherited by
containers. To pass additional hosts into container, refer to [add entries to
container hosts file](../engine/reference/commandline/run.md#add-host) in the
`docker run` reference documentation.

## Proxy server

Expand Down