Gambaran umum pembuatan kontainer .NET SDK
Meskipun dimungkinkan untuk mengontainerisasi aplikasi .NET dengan Dockerfile, ada alasan menarik untuk mengontainerisasi aplikasi secara langsung dengan .NET SDK. Artikel ini memberikan gambaran umum tentang fitur pembuatan kontainer .NET SDK, dengan detail yang terkait dengan telemetri, pertimbangan penerbitan, properti build, dan autentikasi ke registri kontainer.
Menerbitkan pertimbangan proyek
Setelah memiliki aplikasi .NET, Anda dapat menerbitkannya sebagai kontainer. Sebelum melakukannya, ada beberapa pertimbangan penting yang perlu diingat. Sebelum .NET SDK versi 8.0.200, Anda memerlukan paket 📦 Microsoft.NET.Build.Containers NuGet. Paket ini tidak diperlukan untuk .NET SDK versi 8.0.200 dan yang lebih baru, karena dukungan kontainer disertakan secara default.
Untuk mengaktifkan penerbitan aplikasi .NET sebagai kontainer, properti build berikut diperlukan:
-
IsPublishable
: Atur ketrue
. Properti ini secara implisit diatur ketrue
untuk jenis proyek yang dapat dieksekusi, seperticonsole
,webapp
, danworker
. -
EnableSdkContainerSupport
: Atur ketrue
saat jenis proyek Anda adalah aplikasi konsol.
Untuk mengaktifkan dukungan kontainer SDK secara eksplisit, pertimbangkan cuplikan file proyek berikut:
<PropertyGroup>
<IsPublishable>true</IsPublishable>
<EnableSdkContainerSupport>true</EnableSdkContainerSupport>
</PropertyGroup>
Menerbitkan opsi dan properti pembangunan
Seperti semua perintah .NET CLI, Anda dapat menentukan properti MSBuild pada baris perintah. Ada banyak formulir sintaks yang valid yang tersedia untuk menyediakan properti, seperti:
/p:PropertyName=Value
-p:PropertyName=Value
-p PropertyName=Value
--property PropertyName=Value
Anda bebas menggunakan sintaks apa pun yang Anda inginkan, tetapi dokumentasi menunjukkan contoh menggunakan formulir -p
.
Saran
Untuk membantu memecahkan masalah, pertimbangkan untuk menggunakan log MSBuid. Untuk menghasilkan file log biner (binlog), tambahkan sakelar -bl
ke perintah dotnet publish
. File binlog berguna untuk mendiagnosis masalah build dan dapat dibuka di MSBuild Structured Log Viewer. Mereka memberikan jejak terperinci dari proses build, penting untuk analisis MSBuild. Untuk informasi selengkapnya, lihat Pemecahan masalah dan pembuatan log untuk MSBuild.
Publikasikan profil dan target
Saat menggunakan dotnet publish
, menentukan profil dengan -p PublishProfile=DefaultContainer
dapat mengatur properti yang menyebabkan SDK memicu target lain setelah proses penerbitan. Ini adalah cara tidak langsung untuk mencapai hasil yang diinginkan. Di sisi lain, menggunakan dotnet publish /t:PublishContainer
secara langsung memanggil target PublishContainer
, mencapai hasil yang sama tetapi dengan cara yang lebih mudah.
Dengan kata lain, perintah .NET CLI berikut:
dotnet publish -p PublishProfile=DefaultContainer
Yang mengatur properti PublishProfile
ke DefaultContainer
, setara dengan perintah berikut:
dotnet publish /t:PublishContainer
Perbedaan antara kedua metode adalah bahwa yang pertama menggunakan profil untuk mengatur properti, sementara yang terakhir langsung memanggil target. Alasan pentingnya adalah profil adalah fitur MSBuild, dan dapat digunakan untuk mengatur properti dengan cara yang lebih kompleks daripada hanya mengaturnya secara langsung.
Salah satu masalah utamanya adalah tidak semua jenis proyek mendukung profil atau memiliki kumpulan profil yang sama yang tersedia. Selain itu, ada disparitas dalam tingkat dukungan untuk profil antara alat yang berbeda, seperti Visual Studio dan .NET CLI. Oleh karena itu, menggunakan target umumnya merupakan metode yang lebih jelas dan didukung lebih luas untuk mencapai hasil yang sama.
Mengautentikasi ke registri kontainer
Berinteraksi dengan registri kontainer privat memerlukan autentikasi dengan registri tersebut.
Docker memiliki pola yang mapan dengan ini melalui perintah docker login
, yang merupakan cara berinteraksi dengan file konfigurasi Docker yang berisi aturan untuk mengautentikasi dengan registri tertentu. File ini, dan jenis autentikasi yang dikodekannya, didukung oleh Microsoft.Net.Build.Containers untuk autentikasi registri. Ini harus memastikan bahwa paket ini bekerja tanpa hambatan dengan registri mana pun dari mana Anda dapat docker pull
dan docker push
. File ini biasanya disimpan di ~/.docker/config.json, tetapi dapat ditentukan juga melalui variabel DOCKER_CONFIG
, yang menunjuk ke direktori yang berisi file config.json.
Jenis autentikasi
File config.json berisi tiga jenis autentikasi:
- nama pengguna/kata sandi eksplisit
-
Pembantu Kredensial - rantai kunci Sistem
Nama pengguna/kata sandi eksplisit
Bagian auths
dari file config.json adalah peta kunci/nilai antara nama registri dan string nama pengguna:kata sandi yang dikodekan Base64. Dalam skenario Docker umum, menjalankan docker login <registry> -u <username> -p <password>
membuat item baru di peta ini. Kredensial ini populer dalam sistem integrasi berkelanjutan (CI), di mana proses masuk dilakukan menggunakan token pada awal pengoperasian. Namun, mereka kurang populer untuk mesin pengembangan pengguna akhir karena risiko keamanan memiliki kredensial kosong dalam file.
Pembantu kredensial
Bagian credHelpers
dari file config.json adalah peta kunci/nilai antara nama registri dan nama program tertentu yang dapat digunakan untuk membuat dan mengambil kredensial untuk registri tersebut. Ini sering digunakan ketika registri tertentu memiliki persyaratan autentikasi yang kompleks. Agar autentikasi semacam ini berfungsi, Anda harus memiliki aplikasi bernama docker-credential-{name}
pada PATH
sistem Anda. Kredensial semacam ini cenderung aman, namun bisa sulit diatur pada mesin pengembangan atau CI.
Rantai kunci sistem
Bagian credsStore
adalah properti string tunggal yang nilainya adalah nama program pembantu kredensial docker yang tahu cara berinteraksi dengan pengelola kata sandi sistem. Untuk Windows, ini mungkin wincred
misalnya. Ini banyak digunakan oleh penginstal Docker untuk macOS dan Windows.
Autentikasi melalui variabel lingkungan
Dalam beberapa skenario, mekanisme autentikasi Docker standar yang dijelaskan di atas tidak cukup efektif. Alat ini memiliki mekanisme tambahan untuk memberikan kredensial ke registri: variabel lingkungan. Jika variabel lingkungan digunakan, mekanisme penyediaan kredensial tidak akan digunakan sama sekali. Variabel lingkungan berikut didukung:
-
DOTNET_CONTAINER_REGISTRY_UNAME
: Ini harus menjadi nama pengguna untuk registri. Jika kata sandi untuk registri adalah token, maka nama pengguna harus"<token>"
. -
DOTNET_CONTAINER_REGISTRY_PWORD
: Ini harus menjadi kata sandi atau token untuk registri.
Nota
Pada .NET SDK 8.0.400, variabel lingkungan untuk operasi kontainer telah diperbarui. Variabel SDK_CONTAINER_*
sekarang diawali dengan DOTNET_CONTAINER_*
.
Mekanisme ini berpotensi rentan terhadap kebocoran kredensial, sehingga hanya boleh digunakan dalam skenario di mana mekanisme lain tidak tersedia. Misalnya, jika Anda menggunakan alat Kontainer SDK di dalam kontainer Docker itu sendiri. Selain itu, mekanisme ini tidak memiliki namespace—mekanisme ini mencoba menggunakan kredensial yang sama untuk registri sumber (tempat citra dasar Anda berada) dan registri tujuan (tempat Anda mendorong citra akhir).
Menggunakan registri yang tidak aman
Sebagian besar akses registri diasumsikan aman, yang berarti HTTPS digunakan untuk berinteraksi dengan registri. Namun, tidak semua registri dikonfigurasi dengan sertifikat TLS - terutama dalam situasi seperti registri perusahaan swasta di belakang VPN. Untuk mendukung kasus penggunaan ini, alat kontainer menyediakan cara mendeklarasikan bahwa registri tertentu menggunakan komunikasi yang tidak aman.
Mulai dari .NET 8.0.400, SDK memahami file dan format konfigurasi ini dan akan secara otomatis menggunakan konfigurasi tersebut untuk menentukan apakah HTTP atau HTTPS harus digunakan. Mengonfigurasi registri untuk komunikasi yang tidak aman bervariasi berdasarkan alat pilihan kontainer Anda.
Docker
Docker menyimpan konfigurasi registrinya dalam konfigurasi daemon . Untuk menambahkan registri baru yang tidak aman, host baru ditambahkan ke properti array "insecure-registries"
:
{
"insecure-registries": [
"registry.mycorp.net"
]
}
Nota
Anda harus memulai ulang daemon Docker untuk menerapkan perubahan apa pun pada file ini.
Podman
Podman menggunakan file TOML registries.conf
untuk menyimpan informasi koneksi registri. File ini biasanya berada di /etc/containers/registries.conf
. Untuk menambahkan registri tidak aman baru, bagian TOML ditambahkan untuk menahan pengaturan untuk registri, maka opsi insecure
harus diatur ke true
.
[[registry]]
location = "registry.mycorp.net"
insecure = true
Nota
Anda harus menghidupkan ulang Podman untuk menerapkan perubahan apa pun pada file registries.conf.
Variabel lingkungan
Mulai dari 9.0.100, .NET SDK mengenali registri yang tidak aman melewati variabel lingkungan DOTNET_CONTAINER_INSECURE_REGISTRIES
. Variabel ini mengambil daftar domain yang dipisahkan koma untuk diperlakukan tidak aman dengan cara yang sama seperti contoh Docker dan Podman di atas.
- Windows
- Linux
$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
Telemetri
Saat Anda menerbitkan aplikasi .NET sebagai kontainer, alat kontainer .NET SDK mengumpulkan dan mengirim telemetri penggunaan tentang cara alat digunakan. Data yang dikumpulkan ini merupakan tambahan dari telemetri yang dikirim oleh .NET CLI, tetapi menggunakan mekanisme yang sama dan, yang penting, mematuhi kontrol penolakan yang sama .
Telemetri yang dikumpulkan dimaksudkan untuk bersifat umum dan tidak membocorkan informasi pribadi apa pun—tujuan yang dimaksudkan adalah untuk membantu mengukur:
- Penggunaan fitur kontainerisasi .NET SDK secara keseluruhan.
- Tingkat keberhasilan dan kegagalan, bersama dengan informasi umum tentang jenis kegagalan apa yang paling sering terjadi.
- Penggunaan fitur khusus dari teknologi, seperti penerbitan ke berbagai jenis registri, atau bagaimana penerbitan dijalankan.
Untuk menolak telemetri, atur variabel lingkungan DOTNET_CLI_TELEMETRY_OPTOUT
ke true
. Untuk informasi selengkapnya, lihat telemetri .NET CLI.
Telemetri inferensi
Informasi berikut tentang bagaimana proses inferensi gambar dasar terjadi dicatat:
Titik tanggal | Penjelasan | Nilai sampel |
---|---|---|
InferencePerformed |
Jika pengguna secara manual menentukan gambar dasar dibandingkan dengan menggunakan inferensi. | true |
TargetFramework |
TargetFramework dipilih saat melakukan inferensi gambar dasar. |
net8.0 |
BaseImage |
Nilai gambar dasar yang dipilih, tetapi hanya jika gambar dasar tersebut adalah salah satu gambar yang diproduksi Microsoft. Jika pengguna menentukan gambar apa pun selain gambar yang diproduksi Microsoft di mcr.microsoft.com, nilai ini null. | mcr.microsoft.com/dotnet/aspnet |
BaseImageTag |
Nilai tag yang dipilih, tetapi hanya jika tag tersebut adalah untuk salah satu gambar yang diproduksi Microsoft. Jika pengguna menentukan gambar apa pun selain gambar yang diproduksi Microsoft di mcr.microsoft.com, nilai ini null. | 8.0 |
ContainerFamily |
Nilai properti ContainerFamily jika pengguna menggunakan fitur ContainerFamily untuk memilih 'rasa' dari salah satu gambar dasar kami. Ini hanya diatur jika pengguna memilih atau menyimpulkan salah satu gambar .NET yang diproduksi Microsoft dari mcr.microsoft.com |
jammy-chiseled |
ProjectType |
Jenis proyek yang sedang dikontainerisasi. |
AspNetCore atau Console |
PublishMode |
Bagaimana aplikasi dikemas. |
Aot , Trimmed , SelfContained , atau FrameworkDependent |
IsInvariant |
Jika gambar yang dipilih memerlukan globalisasi yang tidak berubah atau pengguna memilihnya secara manual. | true |
TargetRuntime |
RID tempat aplikasi ini diterbitkan. | linux-x64 |
Telemetri pembuatan gambar
Informasi berikut tentang bagaimana proses pembuatan dan penerbitan kontainer terjadi dicatat:
Titik tanggal | Penjelasan | Nilai sampel |
---|---|---|
RemotePullType |
Jika gambar dasar berasal dari registri jarak jauh, registri seperti apa itu? | Azure, AWS, Google, GitHub, DockerHub, MRC, atau Lainnya |
LocalPullType |
Jika gambar dasar berasal dari sumber lokal, seperti daemon kontainer atau tarball. | Docker, Podman, Tarball |
RemotePushType |
Jika gambar didorong ke registri jarak jauh, registri jenis apa itu? | Azure, AWS, Google, GitHub, DockerHub, MRC, atau Lainnya |
LocalPushType |
Jika gambar dikirim ke tujuan lokal, apa tujuannya? | Docker, Podman, Tarball |
Selain itu, jika berbagai jenis kesalahan terjadi selama proses data dikumpulkan tentang jenis kesalahan apa itu:
Titik tanggal | Penjelasan | Nilai sampel |
---|---|---|
Error |
Jenis kesalahan yang terjadi |
unknown_repository , credential_failure , rid_mismatch , local_load . |
Direction |
Jika kesalahan adalah credential_failure , apakah itu ke registri pendorongan atau penarikan? |
push |
Target RID | Jika kesalahan adalah rid_mismatch , RID apa yang dimohon |
linux-x64 |
RID yang tersedia | Jika kesalahan adalah rid_mismatch , RID apa saja yang didukung oleh gambar dasar? |
linux-x64,linux-arm64 |