Merge branch 'master' into fix/dockerSocket

Author: jetersen

.travis.yml

@@ -11,7 +11,7 @@ cache:
     - "/home/travis/.local/share/powershell/Modules"
 
 if: |
-  repo != 3shapeAS/dockerbuild-pwsh OR \
+  repo != 3shapeAS/docker-ci OR \
   type = pull_request OR \
   branch = master OR \
   tag IS present

README.md

@@ -72,31 +72,54 @@ To build an image based on a Dockerfile, use the Invoke-DockerBuild CmdLet, like
 
 ```powershell
 PS C:\docker> Invoke-DockerBuild . -ImageName structure
+Sending build context to Docker daemon  4.608kB
+
+Step 1/8 : FROM ubuntu:18.04
+ ---> 775349758637
+Step 2/8 : SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+ ---> Using cache
+ ---> b3d8c49615a7
+Step 3/8 : RUN apt-get update     && apt-get install -y --no-install-recommends curl=7.* ca-certificates=*     && apt-get clean     && rm -rf /var/lib/apt/lists/*
+ ---> Using cache
+ ---> 9470f9c9ecea
+Step 4/8 : RUN update-ca-certificates
+ ---> Using cache
+ ---> 80853c222946
+Step 5/8 : RUN curl -sL https://get.docker.com/ | sh
+ ---> Using cache
+ ---> af17b9b8fb1b
+Step 6/8 : RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64     && chmod +x container-structure-test-linux-amd64     && mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test
+ ---> Using cache
+ ---> bea1dca8e10e
+Step 7/8 : VOLUME /configs
+ ---> Using cache
+ ---> 97e90bf8481b
+Step 8/8 : ENTRYPOINT [ "/usr/local/bin/container-structure-test" ]
+ ---> Using cache
+ ---> 6b9746ab76d8
+Successfully built 6b9746ab76d8
+Successfully tagged structure:latest
+SECURITY WARNING: You are building a Docker image from Windows against a non-Windows Docker host. All files and directories added to build context will have '-rwxr-xr-x' permissions. It is recommended to double check and reset permissions for sensitive files and directories.
 
 Dockerfile    : Dockerfile
 ImageName     : structure
 Registry      :
 Tag           : latest
 CommandResult : CommandResult
 ```
-In this scenario, you will see the result of the execution which is a PSCustomObject that holds the command result and image name of the image you just created.
 
-You can verify the existence of the image using `docker images`
-```
-PS C:\docker> docker images
-```
+In this scenario, you will see the both the output from Docker and the result of the execution which is a PSCustomObject that holds:
 
-This is fine when everything goes well. But it's not very practial for troubleshooting. It would be better, if we could get some feedback while on the go.
-To see the output of the Docker command being run, use the `-PassThru` switch of the pertinent CmdLet.
-For example:
+- The path to the Dockerfile being used as the basis for the image.
+- The name of the image being produced.
+- The registry (if unset defaults to Docker's default registry)
+- The command result object which has more detailed information about the execution.
 
-```powershell
-PS C:\docker> Invoke-DockerBuild . -ImageName structure -PassThru
-```
-which will yield output along these lines:
+In most cases you will want to store the result in a variable for further processing or output to a CI/CD pipeline, like so:
 
 ```powershell
-Sending build context to Docker daemon   2.56kB
+PS C:\docker> Invoke-DockerBuild . -ImageName structure
+Sending build context to Docker daemon  4.608kB
 
 Step 1/8 : FROM ubuntu:18.04
  ---> 775349758637
@@ -107,26 +130,36 @@ Step 3/8 : RUN apt-get update     && apt-get install -y --no-install-recommends
  ---> Using cache
  ---> 9470f9c9ecea
 Step 4/8 : RUN update-ca-certificates
-
- (snip)
-
-
-Dockerfile    : Dockerfile
-ImageName     : structure
-Registry      :
-Tag           : latest
-CommandResult : CommandResult
+ ---> Using cache
+ ---> 80853c222946
+Step 5/8 : RUN curl -sL https://get.docker.com/ | sh
+ ---> Using cache
+ ---> af17b9b8fb1b
+Step 6/8 : RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64     && chmod +x container-structure-test-linux-amd64     && mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test
+ ---> Using cache
+ ---> bea1dca8e10e
+Step 7/8 : VOLUME /configs
+ ---> Using cache
+ ---> 97e90bf8481b
+Step 8/8 : ENTRYPOINT [ "/usr/local/bin/container-structure-test" ]
+ ---> Using cache
+ ---> 6b9746ab76d8
+Successfully built 6b9746ab76d8
+Successfully tagged structure:latest
+SECURITY WARNING: You are building a Docker image from Windows against a non-Windows Docker host. All files and directories added to build context will have '-rwxr-xr-x' permissions. It is recommended to double check and reset permissions for sensitive files and directories.
 ```
+in which case you will only see the output from Docker, the result object is stored in $result.
 
-Now, we get both the result and the output from the docker command.
-
-In most cases you will want to store the result in a variable for further processing or output to a CI/CD pipeline, like so:
-
+You can verify the existence of the image you just created using `docker images`
 ```
-PS C:\docker> $result = Invoke-DockerBuild . -ImageName structure -PassThru
+PS C:\docker> docker images
 ```
 
-Which would then output the status of the command and store the final result object in `$result`.
+If you want less output, use `-Quiet` switch to output only the final result of the command. Combined with storing the result in a variable, this will give a completely silent execution of the CmdLet.
+
+### Disabling verbose output
+The -Quiet setting for CmdLets that support it, defaults to the value of the enviromenment variable `DOCKER_CI_QUIET_MODE`.
+So you can set this environment variable to the desired setting for the `-Quiet` switch so you don't have to set it for each invocation of a cmdlet that supports it.
 
 ### Linting a Dockerfile
 An important aspect of writing quality Docker images is to try and learn from the best in the community. To this end, we provide a convenient way to run `hadolint` against a Dockerfile. Hadolint is a 3rd party component that scans a dockerfile and produces linted output. You can find the hadolint project here: https://github.com/hadolint/hadolint
@@ -135,7 +168,6 @@ Here's how to use the linter via a CmdLet:
 
 ```powershell
 PS C:\docker> $result = Invoke-DockerLint .\Dockerfile
-PS C:\docker> $result.LintOutput
 1: FROM ubuntu:18.04
 2:
 3: SHELL ["/bin/bash", "-o", "pipefail", "-c"]
@@ -158,11 +190,10 @@ PS C:\docker> $result.LintOutput
 20: ENTRYPOINT [ "/usr/local/bin/container-structure-test" ]
 ```
 
-This Dockerfile in particular has no linting remarks, so it is just output in its entirety with line numbers. Being a mere human, I will forget things from time to time. Let's imagine I omitted the instruction in line 3 on how to deal with commands that fail in a piped execution and run the same commands:
+This Dockerfile in particular has no linting remarks, so it is just output in its entirety with line numbers. Imagine I omitted the instruction in line 3 on how to deal with commands that fail in a piped execution and run the linting again:
 
 ```powershell
 PS C:\docker> $result = Invoke-DockerLint .\Dockerfile
-PS C:\docker> $result.LintOutput
 1: FROM ubuntu:18.04
 2:
 3: RUN apt-get update \
@@ -196,7 +227,7 @@ To run tests, you first define them in .yml configs. Then you build the image th
 So let's start by building an image called `structure`
 
 ```powershell
-PS C:\docker> Invoke-DockerBuild . -ImageName structure
+PS C:\docker> Invoke-DockerBuild . -Quiet -ImageName structure
 
 Dockerfile    : Dockerfile
 ImageName     : structure
@@ -227,9 +258,17 @@ commandTests:
 And you run the tests like this:
 
 ```powershell
-PS C:\docker> Invoke-DockerTests -ImageName 3shape/containerized-structure-test -ConfigFiles gcs-commands.yml
+PS C:\docker> $result = Invoke-DockerTests -ImageName 3shape/containerized-structure-test -ConfigFiles gcs-commands.yml
+@{Pass=1; Fail=0; Total=1; Results=System.Object[]}
+PS C:\docker> $result
+
+TestResult                                          TestReportPath            CommandResult ImageName
+----------                                          --------------            ------------- ---------
+@{Pass=1; Fail=0; Total=1; Results=System.Object[]} C:\docker\testreport.json CommandResult 3shape/containerized-structure-test
 ```
 
+This concludes the section with examples. Let us know if there is something missing, that is not clear from the documentation.
+
 # Development environment setup
 
 * Install PowerShell Core 6.x latest

Source/Private/Write-PassThruOutput.ps1

@@ -1,4 +1,4 @@
-function Write-PassThruOuput {
+function Write-CommandOuput {
     [CmdletBinding()]
     param (
         [String[]]

Source/Public/Invoke-DockerBuild.ps1

@@ -31,7 +31,7 @@ function Invoke-DockerBuild {
         $ExtraParams = '',
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
     $postfixedRegistry = Add-Postfix -Value $Registry
     if ($ExtraParams) {
@@ -47,8 +47,8 @@ function Invoke-DockerBuild {
         'Tag'           = $Tag;
         'CommandResult' = $commandResult
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($commandResult.Output)
     }
     return $result
 }

Source/Public/Invoke-DockerLint.ps1

@@ -14,7 +14,7 @@ function Invoke-DockerLint {
         $TreatLintRemarksFoundAsException,
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
     $pathToDockerFile = Format-AsAbsolutePath $DockerFile
     $dockerFileExists = Test-Path -Path $pathToDockerFile -PathType Leaf
@@ -36,8 +36,8 @@ function Invoke-DockerLint {
         'CommandResult' = $commandResult
         'LintOutput'    = $lintedDockerfile
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($result.LintOutput)
     }
     return $result
 }

Source/Public/Invoke-DockerLogin.ps1

@@ -16,15 +16,15 @@ function Invoke-DockerLogin {
         $Registry,
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
     [String] $plaintextPassword = [System.Net.NetworkCredential]::new("", $Password).Password
     $command = "Write-Output `"${plainTextPassword}`" | docker login --username `"${Username}`" --password-stdin ${Registry}".TrimEnd()
     $maskedCommand = $command.Replace($plaintextPassword, "*********")
     Write-Debug ($maskedCommand)
     [CommandResult] $commandResult = Invoke-Command $command
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($commandResult.Output)
     }
     # Mask password from being shown
     $commandResult.Command = $maskedCommand

Source/Public/Invoke-DockerPull.ps1

@@ -25,7 +25,7 @@ function Invoke-DockerPull {
         $Digest = '',
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
 
     if ($ImageName.Contains(':') -or $ImageName.Contains('@')) {
@@ -55,8 +55,8 @@ function Invoke-DockerPull {
         'Registry'      = $postfixedRegistry
         'Digest'        = $Digest
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($commandResult.Output)
     }
     return $result
 }

Source/Public/Invoke-DockerPush.ps1

@@ -18,7 +18,7 @@ function Invoke-DockerPush {
         $Tag = 'latest',
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
     $postfixedRegistry = Add-PostFix $Registry
     $command = "docker push ${postfixedRegistry}${ImageName}:${Tag}"
@@ -30,8 +30,8 @@ function Invoke-DockerPush {
         'Registry'      = $postfixedRegistry;
         'Tag'           = $Tag;
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($commandResult.Output)
     }
     return $result
 }

Source/Public/Invoke-DockerTag.ps1

@@ -28,7 +28,7 @@ function Invoke-DockerTag {
         $NewTag = 'latest',
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
 
     $postfixedRegistry = Add-Postfix -Value $Registry
@@ -39,13 +39,13 @@ function Invoke-DockerTag {
     $commandResult = Invoke-Command "docker tag ${source} ${target}"
     Assert-ExitCodeOk $commandResult
     $result = [PSCustomObject]@{
-        'Tag'           = $NewTag
-        'ImageName'     = $NewImageName
         'Registry'      = $postfixedNewRegistry
+        'ImageName'     = $NewImageName
+        'Tag'           = $NewTag
         'CommandResult' = $commandResult
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($commandResult.Output)
     }
     return $result
 }

Source/Public/Invoke-DockerTests.ps1

@@ -21,7 +21,7 @@ function Invoke-DockerTests {
         $TreatTestFailuresAsExceptions = $false,
 
         [Switch]
-        $PassThru
+        $Quiet = [System.Convert]::ToBoolean($env:DOCKER_CI_QUIET_MODE)
     )
     if ($null -eq $ConfigFiles -or $ConfigFiles.Length -eq 0) {
         throw [System.ArgumentException]::new('$ConfigFiles must contain one more test configuration file paths.')
@@ -58,17 +58,21 @@ function Invoke-DockerTests {
     }
 
     $testReportPath = Join-Path $absoluteTestReportDir $TestReportName
+    $testReportExists = Test-Path -Path $testReportPath -PathType Leaf
+    if ($testReportExists) {
+        $testResult = $(ConvertFrom-Json $(Get-Content $testReportPath))
+    }
 
     $result = [PSCustomObject]@{
         # Todo: Need to check if the test report folder is missing.
         # It should not crash when folder is not there, but should simply return nothing
-        'TestResult'     = $(ConvertFrom-Json $(Get-Content $testReportPath))
+        'TestResult'     = $testResult
         'TestReportPath' = $testReportPath
         'CommandResult'  = $commandResult
         'ImageName'      = $ImageName
     }
-    if ($PassThru) {
-        Write-PassThruOuput $($commandResult.Output)
+    if (!$Quiet) {
+        Write-CommandOuput $($result.TestResult)
     }
     return $result
 }

Test-Source/Docker.Build.Tests.psm1

@@ -13,6 +13,9 @@ function Set-GlobalVar {
     }
 }
 
+# Set the module to quiet mode for testing purposes so we don't spam the test logs.
+$env:DOCKER_CI_QUIET_MODE = $true
+
 # Add any variables that are needed globally in test scope
 Set-GlobalVar -Variable TestDataDir -Value (Join-Path $PSScriptRoot '../Test-Data')
 Set-GlobalVar -Variable DockerImagesDir -Value(Join-Path $Global:TestDataDir 'DockerImage')

Test-Source/Invoke-DockerBuild.Tests.ps1

@@ -99,14 +99,22 @@ Describe 'Build docker images' {
         }
     }
 
-    Context 'Passthru execution' {
+    Context 'Verbosity of execution' {
 
-        It 'Captures the output of the command invoked' {
+        It 'outputs the result if Quiet is disabled' {
             $tempFile = New-TemporaryFile
-            Invoke-DockerBuild -ImageName "leeandrasmus" -Dockerfile $dockerFile -Passthru 6> $tempFile
+            Invoke-DockerBuild -ImageName "leeandrasmus" -Dockerfile $dockerFile -Quiet:$false 6> $tempFile
             $result = Get-Content $tempFile
 
             $result | Should -Be @('Hello', 'World')
         }
+
+        It 'produces no output if quiet mode is enabled' {
+            $tempFile = New-TemporaryFile
+            Invoke-DockerBuild -ImageName "leeandrasmus" -Dockerfile $dockerFile -Quiet:$true 6> $tempFile
+            $result = Get-Content $tempFile
+
+            $result | Should -BeNullOrEmpty
+        }
     }
 }