Menyesuaikan image container

Image dasar yang telah dikonfigurasi sebelumnya yang disediakan oleh Cloud Workstations hanya berisi lingkungan minimal dengan IDE, terminal Linux dasar dan alat bahasa, serta server sshd. Untuk mempercepat penyiapan lingkungan kasus penggunaan pengembangan tertentu, Anda dapat membuat image container kustom yang memperluas image dasar ini untuk menginstal alat dan dependensi terlebih dahulu serta menjalankan skrip otomatisasi.

Untuk image container kustom, sebaiknya siapkan pipeline untuk otomatis membangun ulang image ini saat image dasar Cloud Workstations diperbarui, selain menjalankan alat pemindaian container seperti Analisis Artefak untuk memeriksa dependensi tambahan yang Anda tambahkan. Anda bertanggung jawab untuk memelihara dan mengupdate paket kustom dan dependensi yang ditambahkan ke image kustom.

Sebelum memulai

  1. Anda memerlukan mesin dengan alat untuk membangun image container seperti Docker, dan untuk mengirim image ke Artifact Registry menggunakan Google Cloud CLI. Anda dapat menggunakan Cloud Workstations atau Cloud Shell Editor untuk melakukan langkah-langkah ini, yang telah menginstal alat ini sebelumnya.

  2. Pilih image dasar yang ingin Anda gunakan dari daftar image dasar yang didukung, seperti us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest.

    Atau, Anda dapat menggunakan image container Anda sendiri atau menggunakan image container eksternal dengan mengikuti petunjuk untuk Menggunakan image container Anda sendiri.

  3. Buat folder seperti CUSTOM_IMAGE_FOLDER dan Dockerfile di dalam folder ini yang memperluas image dasar yang dipilih, seperti yang ditunjukkan dalam contoh berikut.

Struktur image dasar Cloud Workstations

Image dasar Cloud Workstations memiliki struktur yang ditentukan berikut:

  • File titik entri image dasar ditetapkan ke /google/scripts/entrypoint.sh.

  • Saat startup, image dasar menjalankan file di bawah /etc/workstation-startup.d/* dalam urutan leksikografis untuk menginisialisasi lingkungan workstation.

    File dan perilakunya adalah sebagai berikut:

    • 000_configure-docker.sh: Mengonfigurasi dan menjalankan Docker di dalam workstation.

    • 010_add-user.sh: Membuat pengguna default di Cloud Workstations.

      Karena persistent disk dipasang secara dinamis ke container, pengguna harus ditambahkan saat workstation dimulai, bukan di Dockerfile.

    • 020_start-sshd.sh: Memulai layanan sshd di penampung.

    • 030_customize-environment.sh: Mengeksekusi /home/user/.workstation/customize_environment sebagai user.

    • 110_start-$IDE.sh: Memulai IDE untuk image.

  • Cloud Workstations menyimpan image Docker di direktori beranda di /home/.docker_data sehingga image dipertahankan di antara sesi.

Untuk menambahkan fungsi tambahan selama startup workstation, tambahkan skrip Anda di direktori /etc/workstation-startup.d/:

  • Skrip di direktori ini berjalan sebagai root secara default. Untuk menjalankan skrip sebagai pengguna lain, gunakan perintah runuser.

  • Karena skrip dijalankan dalam urutan leksikografis, sebaiknya Anda menggunakan awalan tiga digit yang lebih besar dari 200 untuk skrip.

Atau, jika Anda tidak ingin memperluas image workstation, Anda dapat membuat skrip customize_environment di direktori beranda Anda.

Modifikasi direktori beranda

Jika konfigurasi workstation menentukan direktori utama persisten (yang merupakan perilaku default), disk persisten yang mendukung direktori utama akan dilampirkan secara dinamis ke container saat runtime. Proses ini akan menggantikan modifikasi yang dilakukan pada direktori /home pada waktu pembuatan image container.

Untuk mempertahankan update, ubah direktori /home pada runtime penampung dengan menambahkan skrip di direktori /etc/workstation-startup.d, atau dengan menambahkan konfigurasi per pengguna di direktori /etc/profile.d. Untuk mempercepat proses, pertimbangkan untuk menjalankan skrip penyiapan sebagai proses latar belakang (tambahkan ampersand, &, di akhir perintah) untuk menghindari pemblokiran startup container.

Beberapa contoh konfigurasi waktu build yang harus dipindahkan ke runtime penampung:

  • Konfigurasi git per pengguna
  • Repositori git yang di-clone di direktori utama
  • Konfigurasi pengguna langsung, seperti menempatkan file di direktori $HOME/.config
  • Pembuatan pengguna

Pembuatan dan modifikasi pengguna

Karena disk persisten terpasang secara dinamis ke container saat runtime, pengguna harus ditambahkan saat workstation dimulai, bukan di Dockerfile. Untuk mengubah atau membuat pengguna tambahan, sebaiknya perbarui /etc/workstation-startup.d/010_add-user.sh, atau buat skrip Anda sendiri yang dijalankan saat startup.

Selain itu, Anda dapat mengubah profil bash default untuk pengguna dengan memperbarui file di /etc/profile.d.

Memperbarui kunci Secure APT yang telah dikonfigurasi sebelumnya

Image dasar Cloud Workstations telah diinstal sebelumnya dengan sejumlah alat yang diperoleh dari berbagai repositori pihak ketiga menggunakan Secure APT. Sebagai bagian dari proses penginstalan, kunci publik yang disediakan oleh pemilik repositori diimpor menggunakan gpg dan ditempatkan ke dalam file individual di bagian /usr/share/keyrings/. File ini dirujuk dari file list yang sesuai di bagian /etc/apt/sources.list.d/. Hal ini memungkinkan apt memverifikasi integritas repositori tertentu saat berinteraksi dengannya.

Terkadang, pemilik repositori pihak ketiga dapat memutuskan untuk mengubah kunci publik yang digunakan untuk memvalidasi integritas repositori mereka, yang menyebabkan apt menampilkan error saat berinteraksi dengannya. Untuk mengatasi potensi masalah ini, Anda dapat menggunakan /google/scripts/refresh-preinstalled-apt-keys.sh, yang mendapatkan versi terbaru kunci publik yang sudah diinstal sebelumnya dan mengimpornya kembali.

Anda juga dapat menjalankan skrip ini secara langsung di Dockerfile kustom sebelum Anda menjalankan apt-get update:

# Refresh the preinstalled APT keys
RUN /google/scripts/refresh-preinstalled-apt-keys.sh

RUN apt-get update

Mencantumkan versi IDE yang diinstal

Beberapa image dasar Cloud Workstations telah diinstal sebelumnya dengan IDE. Untuk memudahkan, lihat skrip /google/scripts/preinstalled-ide-versions.sh yang disertakan, yang mencantumkan informasi nama dan versi IDE yang diinstal di image.

Menonaktifkan hak istimewa root sudo

Pengguna workstation default memiliki hak istimewa akses root sudo di penampung ini. Untuk menonaktifkan akses root ke container Docker, tetapkan variabel lingkungan CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO ke true saat membuat konfigurasi workstation.

Untuk menetapkan variabel lingkungan ini melalui konsol Google Cloud saat membuat konfigurasi workstation, ikuti langkah-langkah berikut:

  1. Saat membuat konfigurasi workstation, selesaikan konfigurasi untuk Informasi dasar dan Konfigurasi mesin.
  2. Pada dialog Environment customization, luaskan bagian Advanced container options, lalu pilih Environment variables.
  3. Klik tambahkanTambahkan variabel.
  4. Masukkan CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO dan true sebagai nilai.

Menyesuaikan tanpa memperluas gambar

Untuk memudahkan, semua image dasar Cloud Workstations memeriksa keberadaan file yang dapat dieksekusi yang berada di /home/user/.workstation/customize_environment dan, jika ada, menjalankannya di latar belakang sebagai user. Dengan begitu, Anda dapat menjalankan skrip atau biner apa pun saat startup. Tidak seperti .profile atau .bashrc, skrip hanya berjalan satu kali saat workstation dimulai, bukan satu kali untuk setiap login shell.

Karena skrip customize_environment berjalan sebagai user, pastikan untuk memperbarui izin sesuai kebutuhan saat menulis skrip. Misalnya, jika Anda ingin menginstal Emacs setiap kali workstation Anda dimulai, konten customize_environment mungkin mirip dengan berikut ini:

#!/bin/bash
sudo apt-get update
sudo apt-get install -y emacs

Log eksekusi untuk customize_environment dapat ditemukan di container di /var/log/customize_environment dan juga ditulis ke log output container. Jika customize_environment berhasil dieksekusi, file akan dibuat di /var/run/customize_environment_done. Karena customize_environment berjalan secara paralel dengan startup Workstation, paket yang diinstal oleh skrip dapat tersedia segera setelah workstation Anda dimulai.

Mencegah waktu tunggu tidak ada aktivitas

Untuk memudahkan, semua image dasar Cloud Workstations menyertakan skrip yang telah diinstal sebelumnya di /google/scripts/keep_alive.sh. Skrip ini mengirim pesan keep-alive secara rutin, yang dapat mencegah workstation dimatikan karena waktu tunggu tidak ada aktivitas saat Anda menjalankan proses latar belakang tanpa interaksi langsung.

Mencegah waktu tunggu karena tidak ada aktivitas dengan agen AI

Selain itu, image dasar Cloud Workstations menyertakan skrip konfigurasi agen contoh di bagian /google/samples/agents/keepalive/. Konfigurasi contoh ini memungkinkan Anda mengonfigurasi agen coding AI (seperti Claude Code dan Antigravity CLI) di dalam workstation untuk otomatis menjaga workstation tetap aktif saat agen tersebut aktif mengerjakan tugas. Saat agen menyelesaikan tugasnya atau dijeda untuk menunggu input pengguna, skrip berhenti mengirim pesan tetap aktif, sehingga workstation akan mengalami waktu tunggu karena tidak ada aktivitas. Konfigurasi ini berfungsi paling baik jika konfigurasi workstation disetel untuk menggunakan penangguhan workstation (idleAction disetel ke SUSPEND), sehingga workstation dapat menyimpan status memori dan melanjutkan dengan lancar saat Anda kembali.

Untuk mengetahui informasi selengkapnya tentang penyiapan alur kerja yang dibantu agen dan hook tetap aktif, lihat Pengembangan yang dioptimalkan untuk agen.

Menggunakan image container Anda sendiri

Anda juga dapat menggunakan image container Anda sendiri atau menggunakan image container eksternal, selama image tersebut berbasis Linux dan menjalankan proses pemblokiran saat container dimulai.

Saat menyiapkan Dockerfile, petunjuk ENTRYPOINT harus menjalankan proses pemblokiran seperti sleep infinity agar container terus berjalan, bukan langsung keluar. Atau, dalam konfigurasi workstation, Anda dapat menetapkan kolom config.container.args untuk menentukan proses pemblokiran.

Saat menggunakan image container Anda sendiri, perhatikan hal berikut:

  • Cloud Workstations tidak memerlukan skrip tambahan dari image dasar Cloud Workstations.

    Namun, Anda dapat melihat skrip di direktori /etc/workstation-startup.d/ dalam container yang menjalankan image dasar Cloud Workstations. Nama file menunjukkan fungsi setiap skrip.

  • Sebaiknya jalankan server SSH di penampung. Lihat /etc/workstation-startup.d/020_start-sshd.sh di image dasar default untuk mempelajari cara Cloud Workstations menyiapkannya secara default.

  • Sebaiknya jalankan IDE atau server web default Anda di port 80.

Google Cloud menyediakan image dasar standar yang dapat Anda gunakan untuk membuat image container yang sepenuhnya kustom.

Memperluas image dasar Cloud Workstations

Saat memperluas image dasar Cloud Workstations untuk membuat image kustom bagi lingkungan workstation, Anda dapat mengambil tiga pendekatan:

  1. Perbarui Dockerfile Anda untuk menyertakan aset statis tambahan yang ingin Anda tambahkan.
  2. Tambahkan file yang dapat dieksekusi tambahan di /etc/workstation-startup.d/ untuk menyesuaikan container yang sedang berjalan. File di direktori ini otomatis berjalan dalam urutan leksikografis saat penampung dimulai, sehingga Anda dapat menambahkan awalan pada nama file untuk menjalankannya pada waktu yang tepat selama peluncuran workstation.
  3. Ganti ENTRYPOINT di Dockerfile Anda untuk menyesuaikan sepenuhnya startup container Anda.

Contoh Dockerfile kustom

Bagian ini menyediakan contoh skenario dan petunjuk untuk membuat Dockerfile Anda sendiri.

Image container dengan emacs yang sudah diinstal

Untuk membuat image container dengan emacs yang sudah diinstal, jalankan perintah berikut:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN sudo apt update
RUN sudo apt install -y emacs

Image container dengan penyesuaian pengguna

Ikuti langkah-langkah berikut untuk menyesuaikan image container:

  1. Buat skrip di /etc/workstation-startup.d/* yang berjalan setelah 010_add-user.sh—misalnya, 011_customize-user.sh:

    #!/bin/bash
# Create new group
groupadd $GROUP
# Add the user to a new group
usermod -a -G $GROUP $USERNAME

    Ganti $GROUP dengan nama grup baru dan $USERNAME dengan nama pengguna pengguna.

  2. Dengan asumsi Anda menamai skrip Anda, 011_customize-user.sh, tambahkan berikut ke image Anda di Dockerfile dan buat agar dapat dieksekusi:

    FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

COPY 011_customize-user.sh /etc/workstation-startup.d/

RUN chmod +x /etc/workstation-startup.d/011_customize-user.sh

Image container yang menetapkan variabel lingkungan container dalam sesi SSH

Variabel lingkungan yang ditetapkan di konfigurasi workstation atau tingkat workstation diteruskan ke subproses langsung menggunakan perintah titik entri. Hal ini mencakup IDE dalam image dasar yang telah dikonfigurasi sebelumnya. Namun, sesi SSH bukan proses turunan dari titik entri, dan tidak memiliki setelan variabel lingkungan kustom ini.

Untuk menetapkan variabel lingkungan tersebut di sesi SSH, siapkan image container kustom yang meneruskan variabel lingkungan ini dari perintah titik entri container ke file /etc/environment.

Untuk melakukannya, ikuti langkah-langkah berikut:

  1. Buat skrip di /etc/workstation-startup.d/* yang berjalan setelah 010_add-user.sh—misalnya, 011_add-ssh-env-variables.sh:

    #!/bin/bash
#
echo "CUSTOM_ENV_VAR=$CUSTOM_ENV_VAR" >> /etc/environment

    Ganti CUSTOM_ENV_VAR dengan nama variabel lingkungan yang diinginkan.

  2. Dengan asumsi Anda menamai skrip Anda, 011_add-ssh-env-variables.sh, tambahkan berikut ke image Anda di Dockerfile dan buat agar dapat dieksekusi:

    FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

COPY 011_add-ssh-env-variables.sh /etc/workstation-startup.d/

RUN chmod +x /etc/workstation-startup.d/011_add-ssh-env-variables.sh

Image container yang memungkinkan penerusan X11 untuk sesi SSH

Penerusan X11 memungkinkan Anda memulai aplikasi jarak jauh dan meneruskan tampilan aplikasi ke komputer lokal.

Untuk membuat image container yang memungkinkan penerusan X11, ubah file konfigurasi daemon OpenSSH (/etc/ssh/sshd_config) yang disediakan oleh image dasar Cloud Workstations dengan menambahkan X11Forwarding yes (untuk mengizinkan penerusan X11) dan AddressFamily inet (untuk memastikan hanya IPv4 yang digunakan). Untuk mengetahui informasi selengkapnya tentang kata kunci ini, lihat halaman web OpenBSD tentang AddressFamily dan X11Forwarding.

Berikut adalah contoh Dockerfile yang melakukan modifikasi yang diperlukan:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

# Permit X11 forwarding using only IPv4
RUN cat >> /etc/ssh/sshd_config <<-EOF

AddressFamily inet
X11Forwarding yes
EOF

Menyalin Code OSS for Cloud Workstations ke image container lain

Build multi-level memungkinkan Anda menggunakan beberapa pernyataan FROM dalam Dockerfile. Setiap instruksi FROM dapat menggunakan basis yang berbeda, dan memungkinkan penyalinan artefak antar-tahap build. Untuk menambahkan Code OSS for Cloud Workstations ke image container lain, gunakan build multi-tahap untuk menyalin folder aplikasi /opt/code-oss ke dalam image Anda. Jika Anda ingin memulai Code OSS untuk Cloud Workstations pada waktu startup container, salin juga skrip /etc/workstation-startup.d/110_start-code-oss.sh ke dalam container Anda.

Berikut adalah contoh Dockerfile yang menyalin Code OSS ke image JetBrains IntelliJ Ultimate. Kemudian, Anda dapat berinteraksi dengan IDE:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest as code-oss-image

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/jetbrains-intellij:latest

# Copy Code OSS for Cloud Workstations and startup scripts into our custom image
COPY --from=code-oss-image /opt/code-oss /opt/code-oss
COPY --from=code-oss-image /etc/workstation-startup.d/110_start-code-oss.sh /etc/workstation-startup.d/110_start-code-oss.sh

# Use the existing entrypoint script which will execute all scripts in /etc/workstation-startup.d/
ENTRYPOINT ["/google/scripts/entrypoint.sh"]

Image container yang telah menginstal ekstensi IDE di Code OSS untuk Cloud Workstations untuk pengembangan Java

Untuk membuat image container yang telah menginstal ekstensi IDE di Code OSS untuk Cloud Workstations untuk pengembangan Java pada waktu build, jalankan perintah berikut:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN wget https://open-vsx.org/api/vscjava/vscode-java-debug/0.40.1/file/vscjava.vscode-java-debug-0.40.1.vsix && \
unzip vscjava.vscode-java-debug-0.40.1.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-debug

RUN wget https://open-vsx.org/api/vscjava/vscode-java-dependency/0.19.1/file/vscjava.vscode-java-dependency-0.19.1.vsix && \
unzip vscjava.vscode-java-dependency-0.19.1.vsix