github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

refactor: only use detected port mapping if override is not specified

Browse Source 
Previously, we would always set the port mapping during a dockerfile build, making it difficult for users to override mappings. We also only _sometimes_ updated the detected port mapping, further confusing issues when users were migrating from Dockerfile to Buildpacks for builds.

Now, we always detect the port mapping during the build process, and only use that detected port mapping if an override is not specified. This greatly simplifies the experience around port mapping, as now a user can create an app, set a port mapping, and that first deploy will respect the port mapping without an additional deploy.

The builder always has the best context for what the app should be listening on, and thus we can always specify a "default" port mapping at this stage. Users can override this map as desired later.

This change also results in the removal of a ton of internal code that is now centralized in the ports plugin.

Closes #4067
This commit is contained in:
Jose Diaz-Gonzalez
2023-07-11 21:06:40 -04:00
parent 6168b0c71c
commit f8ccf52079
36 changed files with 238 additions and 416 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/appendices/0.31.0-migration-guide.md
View File

@@ -7,15 +7,25 @@
- The `traefik` integration now mounts config to `/data` instead of the path `/acme.json`, fixing permissions issues under certain architectures. To take advantage of the new functionality, the traefik container should be stopped (via `dokku traefik:stop`) and then started (via `dokku traefik:start`).
- Users no longer need to clear the `source-image` git property when transitioning from image-based deploys (`git:from-image` and `git:load-image`) to other deployment methods (git push, `git:from-archive`, `git:sync`).
- For deploys via the `git:from-image` and `git:load-image` commands, the `CHECKS` file is now extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `CHECKS` extracted directly from the source code. The filename in both cases is `CHECKS` and cannot be modified.
- The environment variable `DOKKU_PROXY_PORT_MAP` has been migrated to the properties system. Direct changes to the value will be ignored, and users should interact with port maps via the `ports` plugin.
- Port mappings are now auto-detected during the build process. Users may override detected port mappings via the `ports` plugin. A default port mapping of `http:80:5000` will be used if none is otherwise specified.
## Deprecations
- The `proxy:ports*` commands have been replaced with the new `ports` plugin. Users will be able to use the old `proxy:ports*` commands for a single minor release, and they will be removed in the next minor release.
- The `common#get_app_raw_tcp_ports()` function has been deprecated and will be removed in the next release. Users should avoid interacting with this function for dockerfile ports and instead use the `ports-get` plugin trigger for fetching ports for an app.
- The `common#get_available_port()` function has been deprecated and will be removed in the next release. Users should avoid interacting with this function and instead use the `ports-get-available` plugin trigger for fetching an available port.
- The `proxy-configure-ports` plugin trigger has been deprecated and will be removed in the next release. Users should instead trigger the `ports-configure` plugin trigger.
- The `common#get_dockerfile_exposed_ports()` function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was in the `builder-dockerfile` plugin.
- The `common#get_exposed_ports_from_image()` function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was during the build process.
- The environment variable `DOKKU_PROXY_PORT_MAP` has been migrated to the properties system. Direct changes to the value will be ignored, and users should interact with port maps via the `ports` plugin.
## Un-Deprecations
- The bare `apps` and `config` cli aliases are no longer deprecated. This better follows Heroku's output and is more useful to users. The subcommands will be treated as the primary, documented versions, while the aliases are there for convenience.
## Removals
- The variable `RAW_TCP_PORTS` is no longer exposed for `nginx.conf.sigil` templating.
- The environment variable `DOKKU_DOCKERFILE_PORTS` is no longer in use. Users wishing to change port mappings should instead use the `ports` plugin.
- The `common#get_app_raw_tcp_ports()` function has been removed in the next release. Users should instead use the `ports-get` plugin trigger for fetching ports for an app.
- The plugin trigger `network-compute-ports` has been removed. It's only use was in the `scheduler-docker-local` plugin, for exposing ports. It's functionality is now implemented via the `ports` plugin.
- The plugin trigger `network-get-port` has been removed. It's only use was in the `scheduler-docker-local` plugin, for recording ports. It's functionality is now implemented via the `ports` plugin.

1
docs/configuration/environment-variables.md
View File

@@ -111,7 +111,6 @@ The following config variables have special meanings and can be set in a variety
| `DOKKU_DISABLE_APP_AUTOCREATION` | none | `dokku config:set` | Disables automatic creation of a non-existent app on deploy. |
| `DOKKU_DOCKER_STOP_TIMEOUT` | `10` | `dokku config:set` | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
| `DOKKU_DOCKERFILE_CACHE_BUILD` | none | `dokku config:set` | |
| `DOKKU_DOCKERFILE_PORTS` | dockerfile ports | `dokku config:set` | |
| `DOKKU_DOCKERFILE_START_CMD` | none | `dokku config:set` | |
| `DOKKU_PARALLEL_ARGUMENTS`. | none | `dokku config:set` | Allows passing custom arguments to parallel for `ps:*all` commands |
| `DOKKU_PROXY_PORT` | automatically assigned | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set` | |

66
docs/development/plugin-triggers.md
View File

@@ -1021,21 +1021,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `network-compute-ports`
- Description: Computes the ports for a given app container
- Invoked by: `internally triggered by proxy-build-config within proxy implementations`
- Arguments: `$APP $PROC_TYPE $IS_HEROKUISH_CONTAINER $CONTAINER_INDEX`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `network-config-exists`
- Description: Returns whether the network configuration for a given app exists
@@ -1081,21 +1066,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `network-get-port`
- Description: Return the port for a given app container
- Invoked by: `internally triggered by a deploy`
- Arguments: `$APP $PROCESS_TYPE $CONTAINER_ID $IS_HEROKUISH_CONTAINER`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `network-get-property`
- Description: Return the value for an app's network property
@@ -1258,24 +1228,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
### `ports-configure`
- Description: Configures the port mapping
- Invoked by: `internally triggered by proxy plugins`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `ports-dockerfile-raw-tcp-ports`
> Warning: This trigger is for internal use and will be removed in a future release. Do not use it in your codebase.
- Description: Extracts raw tcp port numbers from DOCKERFILE_PORTS config variable
- Description: Configures the initial proxy ports
- Invoked by: `internally triggered by proxy plugins`
- Arguments: `$APP`
- Example:
@@ -1318,7 +1271,24 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `ports-get-property`
- Description: Return the value for an app's ports property
- Invoked by:
- Arguments: `$APP $KEY`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"; PROPERTY="$2"
# TODO
```
### `ports-set-detected`
- Description: Allows builders to specify detected port mappings for a given app
- Invoked by: Builder plugins
- Arguments: `$APP [$PORT_MAPPING...]`

22
docs/networking/port-management.md
View File

@@ -180,28 +180,6 @@ Any application that does not use an `EXPOSE` directive will result in Dokku def
- modify your application to support the `PORT` environment variable.
- switch to using an `EXPOSE` directive in your Dockerfile.
#### Switching between `EXPOSE` usage modes
When switching between `EXPOSE` usage modes, it is important to reset your port management. The following two commands can be used to reset your state and redeploy your application.
```shell
# assuming your application is called `node-js-app`
dokku config:unset --no-restart node-js-app DOKKU_DOCKERFILE_PORTS PORT
dokku ports:clear node-js-app
```
### Docker Image
When deploying an image, we will use `docker inspect` to extract the `ExposedPorts` configuration and if defined, use that to populate port mapping. If this behavior is not desired, you can override that configuration variable with the following commands.
```shell
# assuming your application is called `node-js-app`
dokku config:set node-js-app DOKKU_DOCKERFILE_PORTS="1234/tcp 80/tcp"
dokku ports:clear node-js-app
```
All other port-related behavior is the same as when deploying via Dockerfile.
### Displaying ports reports for an app
You can get a report about the app's ports status using the `ports:report` command:

1
docs/networking/proxies/nginx.md
View File

@@ -378,7 +378,6 @@ Unsetting this value is the same as enabling custom nginx config usage.
{{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS
{{ .PROXY_PORT_MAP }} List of port mappings (same as the `map` ports property)
{{ .PROXY_UPSTREAM_PORTS }} List of configured upstream ports (derived from the `map` ports property)
{{ .RAW_TCP_PORTS }} List of exposed tcp ports as defined by Dockerfile `EXPOSE` directive (**Dockerfile apps only**)
{{ .SSL_INUSE }} Boolean set when an app is SSL-enabled
{{ .SSL_SERVER_NAME }} List of SSL VHOSTS
```