Get-DockerImageUpdate.ps1

<#PSScriptInfo
.VERSION 1.0.0
.GUID 1bbbc68f-8558-57a8-93ce-e5c47e9afa32
.AUTHOR Torsten Weise
.COMPANYNAME powerscripting.de
.COPYRIGHT (c) 2026 Torsten Weise. MIT-Lizenz.
.TAGS Powerscripting German Homelab Linux PSEdition_Core Docker
.LICENSEURI https://powerscripting.de/skripte/files/LICENSE.txt
.PROJECTURI https://powerscripting.de/skripte/get-dockerimageupdate.html
.ICONURI https://powerscripting.de/assets/icon-192.png
.EXTERNALMODULEDEPENDENCIES
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES
Erste Veröffentlichung in der PowerShell Gallery.
.PRIVATEDATA
#>


<#
.SYNOPSIS
    Prüft, für welche laufenden Docker-Container ein neueres Image in der Registry liegt, ohne etwas zu ziehen.
 
.DESCRIPTION
    Automatische Updates mit Watchtower oder Dockhand sind bequem, aber nicht für jeden Dienst gewollt.
    Datenbanken, Vaultwarden oder Home Assistant aktualisiert man lieber bewusst, nachdem man die
    Release Notes gelesen hat. Dafür braucht es eine Liste: Was ist veraltet?
 
    Das Skript vergleicht für jeden laufenden Container den Digest des lokalen Images mit dem Digest, den
    die Registry für denselben Tag gerade ausliefert. Es lädt dabei nur das Manifest, kein Image, und ändert
    nichts am System. Bewertung pro Container:
    - Update verfügbar: Unter dem Tag liegt in der Registry ein anderes Image.
    - Aktuell: Digest stimmt überein.
    - Fest gepinnt: Das Image ist per Digest (image@sha256:...) festgelegt, ein Vergleich ist nicht nötig.
    - Lokal gebaut: Das Image stammt aus keiner Registry, etwa aus docker compose build.
    - Nicht prüfbar: Die Registry hat nicht geantwortet oder verlangt eine Anmeldung.
 
    Ein Tag wie :latest oder :2 bewegt sich mit jedem Release. Ein Tag wie :1.32.4 bleibt meist gleich,
    dann sagt "Aktuell" nur, dass es kein neueres Build dieses Tags gibt, nicht dass keine neue Version
    existiert. Den Versionssprung musst du selbst machen.
 
    Exitcode: 0 alles aktuell, 1 Updates verfügbar oder nicht prüfbar.
 
.PARAMETER Name
    Optional. Nur Container prüfen, deren Name auf dieses Muster passt (Platzhalter erlaubt).
 
.PARAMETER IncludeStopped
    Auch gestoppte Container prüfen.
 
.PARAMETER ReportPath
    Optional. Ordner für einen CSV-Bericht. Ohne Angabe nur Ausgabe in der Konsole.
 
.EXAMPLE
    ./Get-DockerImageUpdate.ps1
 
    Prüft alle laufenden Container auf diesem Docker-Host.
 
.EXAMPLE
    ./Get-DockerImageUpdate.ps1 | Where-Object Bewertung -eq 'Update verfügbar' | Format-Table Container, Image, Projekt
 
    Zeigt nur die Container mit Update und ihr Compose-Projekt.
 
.NOTES
    Autor: Torsten Weise, powerscripting.de
    Benötigt: PowerShell 7, Docker CLI mit dem Plugin buildx (bei Docker Engine aus dem offiziellen
    Repository dabei) und Zugriff auf den Docker-Socket, also root oder Mitglied der Gruppe docker.
    Für private Registries vorher docker login ausführen.
    Updaten danach im Projektordner: docker compose pull, docker compose up -d.
    Das Skript liest nur und ändert nichts.
#>

#Requires -Version 7.0
[CmdletBinding()]
param(
    [string] $Name = '*',
    [switch] $IncludeStopped,
    [string] $ReportPath
)

if (-not (Get-Command docker -ErrorAction SilentlyContinue)) { throw 'docker wurde nicht gefunden.' }
& docker buildx version *> $null
if ($LASTEXITCODE -ne 0) { throw 'Das Docker-Plugin buildx fehlt. Installation: Paket docker-buildx-plugin.' }

$psArgs = @('ps', '--format', '{{json .}}', '--no-trunc')
if ($IncludeStopped) { $psArgs += '--all' }
$containers = @(& docker @psArgs | ForEach-Object { $_ | ConvertFrom-Json } | Where-Object { $_.Names -like $Name })
Write-Host "$($containers.Count) Container werden geprüft"

# Remote-Digest pro Image-Referenz nur einmal abfragen
$remote = @{}
function Get-RemoteDigest([string] $Ref) {
    if ($remote.ContainsKey($Ref)) { return $remote[$Ref] }
    $out = & docker buildx imagetools inspect $Ref --format '{{json .Manifest}}' 2>$null
    $digest = if ($LASTEXITCODE -eq 0 -and $out) { ($out -join '' | ConvertFrom-Json).digest } else { $null }
    $remote[$Ref] = $digest
    return $digest
}

$rows = foreach ($c in $containers) {
    $info = (& docker inspect $c.ID) -join "`n" | ConvertFrom-Json
    $ref  = $info.Config.Image                     # so wie im Compose-File angegeben, z. B. nginx:1.27
    $img  = (& docker image inspect $info.Image) -join "`n" | ConvertFrom-Json
    $local = @($img.RepoDigests)                   # z. B. nginx@sha256:...
    $project = $info.Config.Labels.'com.docker.compose.project'

    $rating = ''; $note = ''
    if ($ref -match '@sha256:') {
        $rating = 'Fest gepinnt'
    }
    elseif (-not $local) {
        $rating = 'Lokal gebaut'
    }
    else {
        # Ohne Tag meint Docker :latest
        $full = if ($ref -match ':[^/]+$') { $ref } else { "${ref}:latest" }
        $rd = Get-RemoteDigest $full
        if (-not $rd) {
            $rating = 'Nicht prüfbar'; $note = 'Registry nicht erreichbar oder Anmeldung nötig'
        }
        elseif ($local | Where-Object { $_ -like "*@$rd" }) {
            $rating = 'Aktuell'
        }
        else {
            $rating = 'Update verfügbar'; $note = "Registry: $($rd.Substring(0, 19))…"
        }
    }

    $created = if ($img.Created) { ([datetime]$img.Created).ToLocalTime().ToString('dd.MM.yyyy') } else { '' }
    [pscustomobject]@{
        Container    = $c.Names
        Image        = $ref
        Projekt      = $project
        Bewertung    = $rating
        'Image vom'  = $created
        Status       = $c.Status
        Hinweis      = $note
    }
}

$order  = @{ 'Update verfügbar' = 0; 'Nicht prüfbar' = 1; 'Lokal gebaut' = 2; 'Fest gepinnt' = 3; 'Aktuell' = 4 }
$sorted = @($rows | Sort-Object @{ e = { $order[$_.Bewertung] } }, Projekt, Container)
$sorted

$stats = $sorted | Group-Object Bewertung | ForEach-Object { "$($_.Name): $($_.Count)" }
Write-Host ($stats -join ' | ')

if ($ReportPath) {
    $file = Join-Path $ReportPath ("Docker-Updates_{0:yyyy-MM-dd}.csv" -f (Get-Date))
    $sorted | Export-Csv -Path $file -NoTypeInformation -Delimiter ';' -Encoding UTF8
    Write-Host "Bericht: $file"
}

if (@($sorted | Where-Object { $_.Bewertung -in 'Update verfügbar', 'Nicht prüfbar' }).Count) { exit 1 } else { exit 0 }