Overzicht van het maken van .NET SDK-containers

Hoewel het mogelijk is om .NET-apps te containeriseren met een Dockerfile-, zijn er aantrekkelijke redenen voor apps rechtstreeks te containeriseren met de .NET SDK-. Dit artikel bevat een overzicht van de functie voor het maken van .NET SDK-containers, met details met betrekking tot telemetrie, publicatieoverwegingen, buildeigenschappen en verificatie voor containerregisters.

Overwegingen bij het publiceren van projecten

Nu u een .NET-app hebt, kunt u deze publiceren als een container. Voordat u dit doet, zijn er verschillende belangrijke overwegingen waarmee u rekening moet houden. Vóór .NET SDK versie 8.0.200 hebt u het 📦 Microsoft.NET.Build.Containers NuGet-pakket nodig. Dit pakket is niet vereist voor .NET SDK-versie 8.0.200 en hoger, omdat de containerondersteuning standaard is opgenomen.

Als u het publiceren van een .NET-app als container wilt inschakelen, zijn de volgende build-eigenschappen vereist:

• IsPublishable: Ingesteld op true. Deze eigenschap is impliciet ingesteld op true voor uitvoerbare projecttypen, zoals console, webappen worker.
• EnableSdkContainerSupport: ingesteld op true wanneer uw projecttype een console-app is.

Als u sdk-containerondersteuning expliciet wilt inschakelen, kunt u het volgende projectbestandsfragment overwegen:

<PropertyGroup>
  <IsPublishable>true</IsPublishable>
  <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
</PropertyGroup>

Schakelopties en build-eigenschappen publiceren

Net als bij alle .NET CLI-opdrachten kunt u MSBuild-eigenschappen opgeven op de opdrachtregel. Er zijn veel geldige syntaxisformulieren beschikbaar om eigenschappen op te geven, zoals:

• /p:PropertyName=Value
• -p:PropertyName=Value
• -p PropertyName=Value
• --property PropertyName=Value

U kunt de gewenste syntaxis gebruiken, maar in de documentatie worden voorbeelden weergegeven met behulp van het formulier -p.

Profielen en doelen publiceren

Wanneer u dotnet publishgebruikt, kunt u een profiel opgeven met -p PublishProfile=DefaultContainer, een eigenschap instellen waardoor de SDK na het publicatieproces een ander doelwit activeert. Dit is een indirecte manier om het gewenste resultaat te bereiken. Aan de andere kant roept het gebruik van dotnet publish /t:PublishContainer het PublishContainer doel rechtstreeks aan, waardoor hetzelfde resultaat wordt bereikt, maar op een eenvoudigere manier.

Met andere woorden, de volgende .NET CLI-opdracht:

dotnet publish -p PublishProfile=DefaultContainer

Hiermee wordt de eigenschap PublishProfile ingesteld op DefaultContainer, is gelijk aan de volgende opdracht:

dotnet publish /t:PublishContainer

Het verschil tussen de twee methoden is dat de eerste een profiel gebruikt om de eigenschap in te stellen, terwijl de laatste het doel rechtstreeks aanroept. De reden hiervoor is dat profielen een functie van MSBuild zijn en ze kunnen worden gebruikt om eigenschappen op een complexere manier in te stellen dan ze rechtstreeks in te stellen.

Een belangrijk probleem is dat niet alle projecttypen profielen ondersteunen of dezelfde set profielen beschikbaar hebben. Daarnaast is er een verschil in het ondersteuningsniveau voor profielen tussen verschillende hulpprogramma's, zoals Visual Studio en de .NET CLI. Daarom is het gebruik van doelen over het algemeen een duidelijkere en meer ondersteunde methode om hetzelfde resultaat te bereiken.

Authenticeren bij containerregisters

Voor interactie met privécontainerregisters is verificatie met deze registers vereist.

Docker heeft een vastgesteld patroon met dit via de docker login-opdracht. Dit is een manier om te communiceren met een Docker-configuratiebestand dat regels bevat voor verificatie met specifieke registers. Dit bestand en de verificatietypen die worden gecodeerd, worden ondersteund door Microsoft.Net.Build.Containers voor registerverificatie. Dit moet ervoor zorgen dat dit pakket naadloos werkt met elk register dat u kunt docker pull van en docker push. Dit bestand wordt normaal gesproken opgeslagen op ~/.docker/config.json, maar het kan ook worden opgegeven via de DOCKER_CONFIG variabele, die verwijst naar een map met een config.json bestand.

Soorten verificatie

Het bestand config.json bevat drie soorten verificatie:

• expliciete gebruikersnaam/wachtwoord
• hulpjes voor inloggegevens
• systeemsleutelhanger

Expliciete gebruikersnaam/wachtwoord

De auths sectie van het bestand config.json is een sleutel/waardetoewijzing tussen registernamen en met Base64 gecodeerde gebruikersnaam:wachtwoordtekenreeksen. In een veelvoorkomend Docker-scenario maakt het uitvoeren van docker login <registry> -u <username> -p <password> nieuwe items in deze kaart. Deze referenties zijn populair in CI-systemen (continue integratie), waarbij aanmelding wordt uitgevoerd door tokens aan het begin van een uitvoering. Ze zijn echter minder populair voor ontwikkelcomputers van eindgebruikers vanwege het beveiligingsrisico dat er nauwelijks referenties in een bestand voorkomen.

Helpers voor referenties

De credHelpers sectie van het bestand config.json is een sleutel/waardetoewijzing tussen registernamen en de namen van specifieke programma's die kunnen worden gebruikt om referenties voor dat register te maken en op te halen. Dit wordt vaak gebruikt wanneer bepaalde registers complexe verificatievereisten hebben. Als u dit type verificatie wilt laten werken, moet u een toepassing hebben met de naam docker-credential-{name} op de PATHvan uw systeem. Dit soort inloggegevens is geneigd veilig te zijn, maar kan lastig zijn om in te stellen op ontwikkel- of CI-machines.

Systeemwachtwoordbeheer

De sectie credsStore is een tekenreekseigenschap waarvan de waarde de naam is van een Docker-inloggegevenshulpprogramma dat kan communiceren met het wachtwoordbeheer van het systeem. Voor Windows kan dit bijvoorbeeld wincred zijn. Deze zijn populair bij Docker-installatieprogramma's voor macOS en Windows.

Verificatie via omgevingsvariabelen

In sommige scenario's volstaat het standaard Docker-authenticatiemechanisme dat hierboven is beschreven niet. Deze hulpprogramma's hebben een extra mechanisme voor het opgeven van referenties voor registers: omgevingsvariabelen. Als omgevingsvariabelen worden gebruikt, wordt het mechanisme voor referentiegegevens helemaal niet gebruikt. De volgende omgevingsvariabelen worden ondersteund:

• DOTNET_CONTAINER_REGISTRY_UNAME: dit moet de gebruikersnaam voor het register zijn. Als het wachtwoord voor het register een token is, moet de gebruikersnaam worden "<token>".
• DOTNET_CONTAINER_REGISTRY_PWORD: dit moet het wachtwoord of token voor het register zijn.

Dit mechanisme is mogelijk kwetsbaar voor het lekken van referenties, dus moet dit alleen worden gebruikt in scenario's waarin het andere mechanisme niet beschikbaar is. Als u bijvoorbeeld de SDK-containerhulpprogramma's in een Docker-container zelf gebruikt. Daarnaast is dit mechanisme niet naamruimtelijk. Het probeert dezelfde referenties te gebruiken voor zowel het bronregister (waar uw basisinstallatiekopieën zich bevinden) als het doelregister (waar u de uiteindelijke installatiekopieën pusht).

Onveilige registers gebruiken

De meeste toegang tot het register wordt verondersteld veilig te zijn, wat betekent dat HTTPS wordt gebruikt voor interactie met het register. Niet alle registers worden echter geconfigureerd met TLS-certificaten, met name in situaties zoals een persoonlijk bedrijfsregister achter een VPN. Ter ondersteuning van deze use cases bieden containerhulpprogramma's manieren om te declareren dat een specifiek register onveilige communicatie gebruikt.

Vanaf .NET 8.0.400 begrijpt de SDK deze configuratiebestanden en -indelingen en gebruikt deze configuratie automatisch om te bepalen of HTTP of HTTPS moet worden gebruikt. Het configureren van een register voor onveilige communicatie varieert op basis van uw containerhulpprogramma naar keuze.

Docker

Docker slaat de registerconfiguratie op in de daemon-configuratie. Als u nieuwe onveilige registers wilt toevoegen, worden nieuwe hosts toegevoegd aan de eigenschap "insecure-registries" matrix:

{
  "insecure-registries": [
    "registry.mycorp.net"
  ]
}

Podman

Podman maakt gebruik van een registries.conf TOML-bestand voor het opslaan van registerverbindingsgegevens. Dit bestand bevindt zich meestal op /etc/containers/registries.conf. Als u nieuwe onveilige registers wilt toevoegen, wordt er een TOML-sectie toegevoegd om de instellingen voor het register op te slaan. De optie insecure moet worden ingesteld op true.

[[registry]]
location = "registry.mycorp.net"
insecure = true

Omgevingsvariabelen

Vanaf 9.0.100 herkent de .NET SDK onveilige registers die worden doorgegeven via de omgevingsvariabele DOTNET_CONTAINER_INSECURE_REGISTRIES. Deze variabele gebruikt een door komma's gescheiden lijst met domeinen om te behandelen als onveilig op dezelfde manier als de bovenstaande Docker- en Podman-voorbeelden.

$Env:DOTNET_CONTAINER_INSECURE_REGISTRIES=localhost:5000,registry.mycorp.com; dotnet publish -t:PublishContainer -p:ContainerRegistry=registry.mycorp.com -p:ContainerBaseImage=localhost:5000/dotnet/runtime:9.0

DOTNET_CONTAINER_INSECURE_REGISTRIES=localhost:5000,registry.mycorp.com dotnet publish -t:PublishContainer -p:ContainerRegistry=registry.mycorp.com -p:ContainerBaseImage=localhost:5000/dotnet/runtime:9.0

Telemetrie

Wanneer u een .NET-app publiceert als een container, verzamelt en verzendt de .NET SDK-containerhulpprogramma's gebruikstelemetrie over hoe de hulpprogramma's worden gebruikt. De verzamelde gegevens zijn naast de telemetrie die wordt verzonden door de .NET CLI, en maakt daarnaast gebruik van dezelfde mechanismen en, wat belangrijk is, voldoet aan dezelfde opt-out-opties.

De verzamelde telemetrie is bedoeld om algemeen van aard te zijn en geen persoonlijke gegevens te lekken. Het beoogde doel is om te meten:

• Het gebruik van de .NET SDK-containerisatiefunctie over het algemeen.
• Succes- en mislukkingspercentages, samen met algemene informatie over welke soorten fouten het vaakst optreden.
• Gebruik van specifieke functies van de technologie, zoals publiceren naar verschillende registertypen of hoe de publicatie is aangeroepen.

Als u zich wilt afmelden voor telemetrie, stelt u de omgevingsvariabele DOTNET_CLI_TELEMETRY_OPTOUT in op true. Zie .NET CLI-telemetrievoor meer informatie.

Telemetrie van inferentie

De volgende informatie over hoe het inferentieproces van de basisafbeelding heeft plaatsgevonden, wordt vastgelegd:

Telemetrie voor het maken van afbeeldingen

Volgende informatie over de totstandkoming en publicatie van containers is vastgelegd:

Bovendien, als er verschillende soorten fouten optreden tijdens het proces dat gegevens worden verzameld over wat voor soort fout het was:

Zie ook

• .NET-apps publiceren als containers
• containeriseren van een .NET-applicatieverwijzing