docs: document custom networking
This commit is contained in:
1 parent
9818cc6461
commit
c8537bff48
4 files changed
+169
-4
No files matched your search
@@ -147,4 +147,4 @@ By default, Dokku will execute your buildpack application processes as the `hero
|
|||||||
|
|
||||||
> NOTE: this user must exist in your herokuish image.
|
> NOTE: this user must exist in your herokuish image.
|
||||||
|
|
||||||
Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [scheduler-docker-local documentation](/docs/advanced-usage/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information.
|
Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [docker-local scheduler documentation](/docs/advanced-usage/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information.
|
||||||
@@ -36,7 +36,7 @@ will show logs continually from the web process.
|
|||||||
|
|
||||||
### Failed deploy logs
|
### Failed deploy logs
|
||||||
|
|
||||||
> Warning: The default `docker-local` scheduler will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.
|
> Warning: The default [docker-local scheduler](/docs/advanced-usage/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.
|
||||||
|
|
||||||
In some cases, it may be useful to retrieve the logs from a previously failed deploy.
|
In some cases, it may be useful to retrieve the logs from a previously failed deploy.
|
||||||
|
|
||||||
|
|||||||
+162
-2
@@ -1,8 +1,13 @@
|
|||||||
# Network Management
|
# Network Management
|
||||||
|
|
||||||
> New as of 0.11.0
|
> New as of 0.11.0, Enhanced in 0.20.0
|
||||||
|
|
||||||
```
|
```
|
||||||
|
network:create <network>, # Creates an attachable docker network
|
||||||
|
network:destroy <network>, # Destroys a docker network
|
||||||
|
network:exists <network>, # Checks if a docker network exists
|
||||||
|
network:info <network>, # Outputs information about a docker network
|
||||||
|
network:list # Lists all docker networks
|
||||||
network:report [<app>] [<flag>] # Displays a network report for one or more apps
|
network:report [<app>] [<flag>] # Displays a network report for one or more apps
|
||||||
network:rebuild <app> # Rebuilds network settings for an app
|
network:rebuild <app> # Rebuilds network settings for an app
|
||||||
network:rebuildall # Rebuild network settings for all apps
|
network:rebuildall # Rebuild network settings for all apps
|
||||||
@@ -13,6 +18,161 @@ The Network plugin allows developers to abstract the concept of container networ
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
### Listing networks
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
You can easily list all available networks using the `network:list` command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:list
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
=====> Networks
|
||||||
|
bridge
|
||||||
|
host
|
||||||
|
none
|
||||||
|
test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that you can easily hide extra output from Dokku commands by using the `--quiet` flag, which makes it easier to parse on the command line.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku --quiet network:list
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
bridge
|
||||||
|
host
|
||||||
|
none
|
||||||
|
test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a network
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
Docker networks can be created via the `network:create` command. Executing this command will create an attachable `bridge` network. This can be used to route requests between containers without going through any public network.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:create test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
-----> Creating network test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
Specifying other additional flags or other types of networks can be created directly via the `docker` command.
|
||||||
|
|
||||||
|
### Destroying a network
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
A Docker network without any associated containers may be destroyed via the `network:destroy` command. Docker will refuse to destroy networks that have containers attached.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:destroy test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
```shell
|
||||||
|
! WARNING: Potentially Destructive Action
|
||||||
|
! This command will destroy network test.
|
||||||
|
! To proceed, type "test"
|
||||||
|
> test
|
||||||
|
-----> Destroying network test
|
||||||
|
```
|
||||||
|
|
||||||
|
As the command is destructive, it will default to asking for confirmation before executing the removal of the network. This may be avoided by providing the `--force` flag:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku --force network:destroy test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
```shell
|
||||||
|
-----> Destroying network test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Checking if a network exists
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the `network:exists` command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:exists nonexistent-network
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Network does not exist
|
||||||
|
```
|
||||||
|
|
||||||
|
The `network:exists` command will return non-zero if the network does not exist, and zero if it does.
|
||||||
|
|
||||||
|
### Checking network info
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
Network information can be retrieved via the `network:info` command. This is a slightly different version of the `docker network` command.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:info test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
// TODO
|
||||||
|
```
|
||||||
|
|
||||||
|
### Attaching an app to a network
|
||||||
|
|
||||||
|
> New as of 0.20.0, Requires Docker 1.21+
|
||||||
|
|
||||||
|
Apps will default to being associated with the `bridge` network, but can be attached to `attachable` networks by changing the `attach-post-create` or `attach-post-deploy` network properties when using the [docker-local scheduler](/docs/advanced-usage/schedulers/docker-local.md). A change in these values will require an app deploy or rebuild.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# associates the network after a container is created but before it is started
|
||||||
|
dokku network:set node-js-app attach-post-create test-network
|
||||||
|
|
||||||
|
# associates the network after the deploy is successful but before the proxy is updated
|
||||||
|
dokku network:set node-js-app attach-post-create other-test-network
|
||||||
|
```
|
||||||
|
|
||||||
|
Setting the `attach` network property to an empty value will de-associate the container with the network.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dokku network:set node-js-app attach-post-create
|
||||||
|
dokku network:set node-js-app attach-post-deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
When a container created for a deployment is being attached to a network - regardless of which `attach` property was used - a network alias of the pattern `APP.PROC_TYPE` will be added to all containers. This can be used to load-balance requests between containers.
|
||||||
|
|
||||||
|
#### When to attach containers to a network
|
||||||
|
|
||||||
|
Containers can be attached to a network for a variety of reasons:
|
||||||
|
|
||||||
|
- A background process in one app needs to communicate to a webservice in another app
|
||||||
|
- An app needs to talk to a container not managed by Dokku in a secure manner
|
||||||
|
- A custom network that allows transparent access to another host exists and is necessary for an app to run
|
||||||
|
|
||||||
|
Whatever the reason, the semantics of the two network hooks are important and are outlined before.
|
||||||
|
|
||||||
|
- `attach-post-create`:
|
||||||
|
- Phase it applies to:
|
||||||
|
- `build`: Intermediate containers created during the build process.
|
||||||
|
- `deploy`: Deployed app containers.
|
||||||
|
- `run`: Containers created by the `run` command.
|
||||||
|
- Container state on attach: `created` but not `running`
|
||||||
|
- Use case: When the container needs to access a resource on the network.
|
||||||
|
- Example: The app needs to talk to a database on the same network when it first boots.
|
||||||
|
- `attach-post-deploy`
|
||||||
|
- Phase it applies to:
|
||||||
|
- `deploy`: Deployed app containers.
|
||||||
|
- Container state on attach: `running`
|
||||||
|
- Use case: When another container on the network needs to access _this_ container.
|
||||||
|
- Example: A background process needs to communicate with the web process exposed by this container.
|
||||||
|
|
||||||
|
> Warning: If the attachment fails at this stage, this may result in your application failing to respond to proxied requests once older containers are removed.
|
||||||
|
|
||||||
### Rebuilding network settings
|
### Rebuilding network settings
|
||||||
|
|
||||||
There are cases where you may need to rebuild the network configuration for an app, such as on app boot or container restart. In these cases, you can use the `network:rebuild` command:
|
There are cases where you may need to rebuild the network configuration for an app, such as on app boot or container restart. In these cases, you can use the `network:rebuild` command:
|
||||||
@@ -37,7 +197,7 @@ dokku network:rebuildall
|
|||||||
|
|
||||||
> This functionality does not control the `--network` docker flag. Please use the [docker-options plugin](docs/advanced-usage/docker-options.md) to manage this flag.
|
> This functionality does not control the `--network` docker flag. Please use the [docker-options plugin](docs/advanced-usage/docker-options.md) to manage this flag.
|
||||||
|
|
||||||
By default, an application will only bind to the internal interface. This behavior can be modified per app by changing the `bind-all-interfaces` network property.
|
By default, an app will only bind to the internal interface. This behavior can be modified per app by changing the `bind-all-interfaces` network property.
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
# bind to the default docker interface (`docker0`) with a random internal ip
|
# bind to the default docker interface (`docker0`) with a random internal ip
|
||||||
|
|||||||
@@ -19,6 +19,11 @@ Manages network settings for an app
|
|||||||
Additional commands:`
|
Additional commands:`
|
||||||
|
|
||||||
helpContent = `
|
helpContent = `
|
||||||
|
network:create <network>, Creates an attachable docker network
|
||||||
|
network:destroy <network>, Destroys a docker network
|
||||||
|
network:exists <network>, Checks if a docker network exists
|
||||||
|
network:info <network>, Outputs information about a docker network
|
||||||
|
network:list, Lists all docker networks
|
||||||
network:report [<app>] [<flag>], Displays a network report for one or more apps
|
network:report [<app>] [<flag>], Displays a network report for one or more apps
|
||||||
network:rebuild <app>, Rebuilds network settings for an app
|
network:rebuild <app>, Rebuilds network settings for an app
|
||||||
network:rebuildall, Rebuild network settings for all apps
|
network:rebuildall, Rebuild network settings for all apps
|
||||||
|
|||||||
Reference in new issue
Block a user