Port Mapping Design

[bvtujo]

When a user initializes an application through either ecs init or ecs app init, we need to provide a more obvious, intuitive way to set the port on which the container listens and to which that application's target group will forward traffic. This design is an attempt to provide intelligent defaults, educated guesses, and a streamlined experience from start to finish.

Current UX

In Load Balanced Fargate Services, our default application pattern, there is a need for the user to be able to easily tell the ECS CLI what port the Dockerfile exposes. This value is used in creating target groups and is necessary when routing incoming HTTP traffic from the load balancer to the app container.

Currently, we allow users to edit the port in the manifest.yml file we generate during app init, leading to the following common workflow for apps which use nonstandard ports:

$ ecs app init --name my-cool-flask-app
...interactive prompts...
$ vim ecs-project/app-name/manifest.yml // set port to 5000
$ ecs app deploy

We do not expose any port flags or make educated guesses about which ports we should map from the load balancer to the container via target groups.

Proposed UX (init)

We'll follow the precedence order of Flag > educated guess > sane default.
This means that we will follow these rules:

1. Always use the value provided in a flag, even if we can see that the Dockerfile exposes a different port.
2. If we can parse the Dockerfile unambiguously, tell the user what information we deduced and go ahead.
3. If we don't have a flag and can't deduce the port because the Dockerfile has multiple exposes, prompt the user with the last exposed port as the default.
4. If we don't have a flag and the Dockerfile has no exposes, prompt the user with a default of 80.
   These options are roughly documented in the following table.

Flag	Single Expose	Mult. Expose	Behavior
x	x		flag
x		x	flag
	x		guess
		x	prompt (default guess)
			prompt (default 80)

We'll write some messages to default to in each of these options, and modify the app init command to implement this behavior with either an existing Dockerfile parser or a custom algorithm to generate the structure of EXPOSE and ARG statements.

This workflow will occur in both ecs init and ecs app init. We will

Proposed UX (deploy)

When a user runs app deploy as a standalone command, it's assumed that their use case is slightly more advanced. We'll assume for the most part that their manifest is configured correctly, but we can still prevent misconfigurations by parsing the Dockerfile at deploy time and comparing against the manifest. This will allow us to potentially interrupt a problematic deployment where the port would be misconfigured and allow the user to change things. This behavior can be bypassed by the --yes flag.

We'll follow these rules:

1. Always surface port information
2. Always deploy without interruption if the user provides --yes
3. Only interrupt with a prompt if there is an unambiguous port mismatch between the Dockerfile and the manifest (i.e. no EXPOSE statement matches the port that's in the manifest)

Unambiguous Match	Unambiguous Mismatch	Ambiguous Match (mult. EXPOSE)	--yes flag	behavior
x				Deploy
x			x	Deploy
	x			Interrupt deployment
	x		x	Deploy
		x		Deploy
		x	x	Deploy

We can surface the port information during every deployment in a helpful message.

Overview

Changes to flags

ecs app init
  --port (the port which the container exposes, to be used when constructing target groups 
         & routing traffic)

ecs init
  --port (ibid)

ecs app deploy
  --yes (overrules any objections we may have with manifest vs Dockerfile configuration 
        and goes ahead with deployment)

Changes to behavior

1. app init now parses the Dockerfile for EXPOSE statements and prompts for confirmation when port ambiguity is present.
2. app deploy will prompt the user to go ahead with a deployment iff there is an unambiguous mismatch between Dockerfile and manifest, unless --yes flag is passed in.

[kohidave]

maybe instead of --yes, a --skip-warnings flag

[bvtujo]

maybe instead of --yes, a --skip-warnings flag

My thought is that a --yes flag, since we use it to confirm in the delete commands and skip a check which requires user input, is a good fit here. We'd be using it to answer the question "The manifest doesn't match your dockerfile, deploy anyway?" which similarly interrupts the deployment and requires user input. Does that reasoning make sense?