diff --git a/docs/advanced-usage/persistent-storage.md b/docs/advanced-usage/persistent-storage.md index b11a50638..f1aa62ad6 100644 --- a/docs/advanced-usage/persistent-storage.md +++ b/docs/advanced-usage/persistent-storage.md @@ -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. -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. diff --git a/docs/deployment/logs.md b/docs/deployment/logs.md index 8c10208e8..712065f31 100644 --- a/docs/deployment/logs.md +++ b/docs/deployment/logs.md @@ -36,7 +36,7 @@ will show logs continually from the web process. ### 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. diff --git a/docs/networking/network.md b/docs/networking/network.md index 584ef7fa4..0b2572584 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -1,8 +1,13 @@ # Network Management -> New as of 0.11.0 +> New as of 0.11.0, Enhanced in 0.20.0 ``` +network:create , # Creates an attachable docker network +network:destroy , # Destroys a docker network +network:exists , # Checks if a docker network exists +network:info , # Outputs information about a docker network +network:list # Lists all docker networks network:report [] [] # Displays a network report for one or more apps network:rebuild # Rebuilds network settings for an app 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 +### 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 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. -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 # bind to the default docker interface (`docker0`) with a random internal ip diff --git a/plugins/network/src/commands/commands.go b/plugins/network/src/commands/commands.go index b18de6202..fc270c213 100644 --- a/plugins/network/src/commands/commands.go +++ b/plugins/network/src/commands/commands.go @@ -19,6 +19,11 @@ Manages network settings for an app Additional commands:` helpContent = ` + network:create , Creates an attachable docker network + network:destroy , Destroys a docker network + network:exists , Checks if a docker network exists + network:info , Outputs information about a docker network + network:list, Lists all docker networks network:report [] [], Displays a network report for one or more apps network:rebuild , Rebuilds network settings for an app network:rebuildall, Rebuild network settings for all apps