Add `entrypoint` routing, which supports routing string-based commands to different executables, with special logic for `pwsh`

[TravisEz13]

Goal

Add entrypoint routing, which supports routing string-based commands to different executables, with special logic for pwsh. In order to:

• Provide actionable error messages. Users should know that the entrypoint syntax they used failed in PowerShell, in Bash (or other shell), or in the script itself.
• Support on Linux and Windows (a number of these appear like general concerns, not Linux-specific).
• This avoids needing to
  • use the --entrypoint syntax to specify an executable, and
  • split the entrypoint (an argument to docker run) from its arguments (arguments to the container; they show up last).

Background

The best practice in docker is for an image to run the product in contains.
https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#entrypoint

Currently our images only run PowerShell when no command is specified. This is specified in the CMD entry in the Dockerfile.

Unfortunately, making the change causes a breaking change to the image in what is hopefully a corner case.

Customer requests for this are in #274 and #394

Proof of concept is here: #399

Other Language images

• Work similar to the proposal
  • php
  • node
• Like our current image
  • perl (perldebug)
  • python
• Dumps you in bash
  • golang

Proposal

1. Add a shell script that will detect if you are running pwsh (or similar), if so, send it to bash, otherwise run pwsh -nologo -l -c "$@"
2. set that script as the ENTRYPOINT
3. SetCMD to [ "pwsh" ]

• Maintain the most features
• Achieves the goals of the best practices

New Scenario

Note the lack of pwsh -c.

docker  run --rm  mcr.microsoft.com/powershell:7.1.0-preview.1-ubuntu-18.04 '$psversiontable.PSVersion.ToString()'

Will continue to work

docker  run --rm  mcr.microsoft.com/powershell:7.1.0-preview.1-ubuntu-18.04 pwsh -c '$psversiontable.PSVersion.ToString()'

Breaking change

Scenario - Running PowerShell using container

Working command with current images

docker  run --rm  mcr.microsoft.com/powershell:7.1.0-preview.1-ubuntu-18.04 /opt/microsoft/powershell/7-preview/pwsh -c '$psversiontable.PSVersion.ToString()'

Scenario - Expected result (with current image)

7.1.0-preview.1

Actual result (with private build with change)

ParserError: 
Line |
   1 |  7.1.0-preview.1
     |       ~~~~~~~~
     | Unexpected token '-preview' in expression or statement.

Workaround

Use --% to prevent the new PowerShell entrypoint from parsing the command.

docker  run --rm  mcr.microsoft.com/powershell:7.1.0-preview.1-ubuntu-18.04 /opt/microsoft/powershell/7-preview/pwsh --% -c '$psversiontable.PSVersion.ToString()'

Entry point script - Ubuntu

#!/bin/sh
set -e

# first arg is `pwsh` or similar
if ! { [ $1 = 'pwsh' ] || [ $1 = 'pwsh-preview' ]; }; then
 set -- pwsh -nologo -l -c "$@"
fi

exec "$@"

[RDIL]

I feel like this would be ideal for the refactor we were discussing a month or so ago, and I feel like in between these releases is the perfect time to get that in motion.

[TravisEz13]

I found this, which would break, but it is our code and no longer used.
https://github.com/O330oei/vlea/blob/b7295deaf506d55c590491132dc6cb16e3d99355/test/nanoserver/nanoserver.tests.ps1

GitHub

O330oei/vlea

Contribute to O330oei/vlea development by creating an account on GitHub.

[TravisEz13]

add support for
/bin/bash
/bin/sh

[TravisEz13]

1/3 of the docker files define entry point and definitely won't be affected.

Most executions of the image where either pwsh -c or interactive.

[MichaelSimons]

When I first saw this issue I thought it was pretty cut and dried but the more I think about it, that definitely does not seem to be the case 😸.

FWIW, I have a couple questions/comments

1. If I understand the proposal correctly, both a CMD and an ENTRYPOINT would be defined. If you docker run the resulting image you would be launching pwsh twice in a nested format as docker run will pass the exec form CMD as parameters to the ENTRYPOINT. Is the CMD defined just so that the parameterless docker run scenario works e.g. docker run -it --rm test? Edit: I realize this is not an issue with the proposal because the CMD is passed into the script which results in the CMD being executed.

1. The entrypoint script feels strange to me. The differing behavior based on the docker run args is what feels strange. Is being done only for compatibility reasons? Do you not want to make this breaking change during a major/minor release? It feels like in the long term, you would want the entry point to be simply be pwsh -nologo -l. Have you measured the performance impact to startup?

Maybe it would be helpful to capture the usage scenarios and the expected behavior in this issue.

[joeyaiello]

So I spoke to @TravisEz13 offline and spent a bunch more time with Docker entrypoint scripts in some home projects, and think I can accurately describe the behavior now.

1. docker run -it mcr.microsoft.com/powershell:foo pwsh
   For this one, the entrypoint script is checking to see if it's getting pwsh or pwsh-preview so that it doesn't run pwsh inside of pwsh.

2. docker run -it mcr.microsoft.com/powershell:foo 'Do-Stuff -Bar'
   In this case, the entrypoint script doesn't see pwsh or pwsh-preview, so it passes the script block to the default pwsh in the container. This is the scenario that's being lit up by this PR.

3. docker run -it mcr.microsoft.com/powershell:foo bash
   In this case, the user expects to be dropped into bash, as the default behavior of Docker is to look for bash on the PATH of powershell:foo and execute it. However, because the entrypoint script isn't detecting pwsh or pwsh-preview, bash is actually being executed from within PowerShell as a script block. The implication being that startup time for non-pwsh binaries could be slower, but I'm okay with that tradeoff given that the point of the powershell container is to run PowerShell.

4. docker run -it mcr.microsoft.com/powershell:foo 'bash -c 1'
   Today, this doesn't work. With the new entrypoint script, this should now work because bash -c 1 is being passed as a script block to PowerShell.

5. docker run -it mcr.microsoft.com/powershell:foo '/bar.ps1'
   In this example, running the script bar.ps1 on the root of the filesystem requires an absolute path or a ./ because it's being executed as a script block.

6. docker run -it mcr.microsoft.com/powershell:foo bar.ps1
   This only works today if bar.ps1 has a properly set shebang, a +x attribute, and is on the PATH. I believe that should still hold true today (though I believe it also means that shebang is no longer required as PowerShell trusts just the .ps1 file extension).

7. docker run -it mcr.microsoft.com/powershell:foo '/usr/bin/pwsh'
   This will actually run a PowerShell inside PowerShell because the full path is not parsed as pwsh or pwsh-preview by the entrypoint script.

[joeyaiello]

@PowerShell/powershell-committee reviewed the behavior I outlined above, there's a couple other cases without quotes around the last arg of the run, but none of them are problematic either. We're marking as approved.