File app.yaml
menentukan setelan konfigurasi untuk runtime serta setelan aplikasi, jaringan, dan resource umum lainnya.
Jangan tambahkan app.yaml
ke file .gcloudignore
. app.yaml
mungkin diperlukan untuk deployment, dan menambahkannya ke .gcloudignore
akan menyebabkan deployment gagal.
Sintaksis
Sintaksis file app.yaml
adalah format YAML.
Format YAML mendukung komentar, di mana setiap baris yang dimulai dengan karakter simbol hash (#
) akan diabaikan, misalnya:
# This is a comment.
Pola jalur file dan URL menggunakan sintaksis ekspresi reguler POSIX yang diperluas, kecuali elemen pengkolasi dan class kolasi. Referensi balik ke pencocokan yang dikelompokkan (misalnya \1
) didukung, begitu juga ekstensi Perl berikut: \w \W \s \S \d \D
.
Setelan umum
File app.yaml
dapat menyertakan setelan umum berikut. Perhatikan bahwa beberapa di antaranya bersifat wajib:
Nama | Deskripsi |
---|---|
build_env_variables
|
Opsional. Jika menggunakan runtime yang mendukung
buildpack, Anda
dapat menentukan variabel lingkungan build dalam
file Untuk mempelajari lebih lanjut, lihat Menggunakan variabel lingkungan build. |
runtime |
Wajib. Nama lingkungan runtime yang digunakan aplikasi Anda. Misalnya, untuk menentukan lingkungan runtime, gunakan: |
runtime_config |
Menentukan versi runtime Python. Mulai Python versi 3.8, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22" runtime_version: "3.12"
|
runtime_config |
Menentukan versi Go. Mulai Go versi 1.18, Anda harus menentukan versi sistem operasi. Misalnya, jika Anda memilih Go 1.22:
runtime_config: operating_system: "ubuntu22" runtime_version: "1.22"
|
runtime_config |
Menentukan versi Node.js. Mulai Node.js versi 18, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22" runtime_version: "20"
|
runtime_config |
Menentukan versi Java. Mulai Java versi 11, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22" runtime_version: "21"
|
runtime_config |
Mulai Ruby versi 3.2, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22"
Wajib untuk versi 3.2 dan yang lebih baru. Tidak didukung untuk Ruby versi 3.1 dan yang lebih lama. Lihat versi dan runtime Ubuntu yang didukung di halaman Runtime Ruby. |
runtime_config |
Mulai dari .NET versi 6 dan yang lebih baru, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22"
|
runtime_config |
Menentukan versi PHP. Mulai PHP versi 7.4, Anda harus menentukan versi sistem operasi.
runtime_config: operating_system: "ubuntu22" runtime_version: "8.3"
|
env: flex |
Wajib: Pilih lingkungan fleksibel. |
entrypoint |
Perintah untuk memulai aplikasi Anda. Titik entri ini memulai proses yang merespons permintaan HTTP di port yang ditentukan oleh variabel lingkungan PORT .
|
service: service_name |
Wajib jika membuat layanan. Opsional untuk layanan default. Setiap layanan dan setiap versi harus memiliki nama. Nama dapat berisi angka, huruf, dan tanda hubung. Di lingkungan fleksibel, panjang gabungan dari VERSION-dot-SERVICE-dot-PROJECT_ID (di mana VERSION adalah nama versi Anda, SERVICE adalah nama layanan, dan PROJECT_ID adalah project ID Anda) tidak boleh lebih dari 63 karakter dan tidak boleh diawali atau diakhiri dengan tanda hubung.
Jika Anda men-deploy tanpa menentukan nama layanan, versi baru layanan default akan dibuat. Jika Anda men-deploy dengan nama layanan yang sudah ada, versi baru layanan tersebut akan dibuat. Jika Anda men-deploy dengan nama layanan baru yang tidak ada, layanan dan versi baru akan dibuat. Sebaiknya gunakan nama unik untuk setiap kombinasi versi layanan. Catatan: Sebelumnya, layanan disebut "modul". |
service_account |
Opsional. Elemen Akun layanan harus diisikan dalam format berikut: service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com |
skip_files |
Opsional.
Elemen
Misalnya, untuk melewati file yang namanya diakhiri dengan skip_files: - ^.*\.bak$ |
Setelan jaringan
Anda dapat menentukan setelan jaringan di file konfigurasi app.yaml
, misalnya:
network: name: NETWORK_NAME instance_ip_mode: INSTANCE_IP_MODE instance_tag: TAG_NAME subnetwork_name: SUBNETWORK_NAME session_affinity: true forwarded_ports: - PORT - HOST_PORT:CONTAINER_PORT - PORT/tcp - HOST_PORT:CONTAINER_PORT/udp
Anda dapat menggunakan opsi berikut saat mengonfigurasi setelan jaringan:
Opsi | Deskripsi |
---|---|
name |
Setiap instance VM di lingkungan fleksibel ditetapkan ke jaringan Google Compute Engine saat dibuat. Gunakan setelan ini untuk menentukan nama jaringan. Berikan nama pendek, bukan jalur resource (misalnya default , bukan https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default ). Jika nama jaringan tidak ditentukan, instance akan ditetapkan ke jaringan default project (yang memiliki nama default ). Jika ingin menentukan nama subnetwork, Anda harus menentukan nama jaringan. |
instance_ip_mode |
Opsional. Agar instance tidak menerima alamat IP eksternal sementara, tetapkan opsi ini ke internal dan aktifkan Akses Google Pribadi. Jika instance Anda sebelumnya di-deploy tanpa setelan ini, atau di-deploy saat opsi ini ditetapkan ke external , men-deploy ulang instance saat opsi ini ditetapkan ke internal akan menghapus alamat IP eksternal sementara dari instance Anda. Setelan internal memiliki batasan. Default-nya adalah external . |
instance_tag |
Opsional. Tag dengan nama tersebut ditetapkan ke setiap instance layanan saat dibuat. Tag dapat berguna dalam perintah gcloud untuk menargetkan tindakan ke sekumpulan instance. Misalnya, lihat penggunaan flag --source-tags dan --target-tags dalam perintah compute firewalls-create. Jika tidak ditentukan, instance akan diberi tag aef-INSTANCE_ID saat VPC Bersama tidak digunakan. Jika VPC Bersama digunakan, instance akan diberi tag aef-INSTANCE_ID |
subnetwork_name |
Opsional. Anda dapat menyegmentasikan jaringan dan menggunakan subnetwork kustom. Pastikan name jaringan sudah ditentukan. Berikan nama pendek, bukan jalur resource (misalnya default , bukan https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default ).Subnetwork harus berada di region yang sama dengan aplikasi. |
session_affinity |
Opsional. Tetapkan opsi ini ke true untuk mengonfigurasi App Engine agar merutekan beberapa permintaan berurutan untuk pengguna tertentu ke instance App Engine yang sama, misalnya saat menyimpan data pengguna secara lokal selama sesi. Afinitas sesi memungkinkan pemeriksaan nilai cookie untuk mengidentifikasi beberapa permintaan oleh pengguna yang sama, lalu mengarahkan semua permintaan tersebut ke instance yang sama. Jika instance dimulai ulang, tidak responsif, kelebihan beban, atau menjadi tidak tersedia saat jumlah instance telah diperkecil, afinitas sesi akan rusak dan permintaan selanjutnya akan dirutekan ke instance berbeda. Perlu diperhatikan bahwa mengaktifkan afinitas sesi dapat memengaruhi konfigurasi load balancing Anda. Parameter ini dinonaktifkan secara default. |
forwarded_ports |
Opsional. Anda dapat meneruskan port dari instance Anda (HOST_PORT ) ke container Docker (CONTAINER_PORT ). HOST_PORT harus antara 1024 dan 65535 serta tidak boleh bertentangan dengan port berikut: 22, 8080, 8090, 8443, 10000, 10001, 10400-10500, 11211, 24231. CONTAINER_PORT harus antara 1 dan 65535 serta tidak boleh bertentangan dengan port berikut: 22, 10001, 10400-10500, 11211. Jika Anda hanya menentukan PORT , App Engine akan menganggap bahwa port tersebut adalah port yang sama di host dan container. Secara default, traffic TCP dan UDP diteruskan. Traffic harus diarahkan langsung ke alamat IP instance target, bukan melalui domain appspot.com atau domain kustom Anda. |
Konfigurasi jaringan lanjutan
Anda dapat menyegmentasikan jaringan Compute Engine menjadi beberapa subnetwork. Dengan begitu, Anda dapat mengaktifkan skenario VPN, seperti mengakses database dalam jaringan perusahaan.
Untuk mengaktifkan subnetwork untuk aplikasi App Engine Anda:
Tambahkan nama jaringan dan nama subnetwork ke file
app.yaml
Anda, seperti yang ditentukan di atas.Untuk membuat VPN sederhana berdasarkan perutean statis, buat gateway dan tunnel untuk jaringan subnet kustom. Jika tidak, lihat cara membuat jenis VPN lain.
Penerusan port
Penerusan port memungkinkan koneksi langsung ke container Docker di instance Anda. Traffic ini dapat mengalir melalui protokol apa pun. Penerusan port dimaksudkan untuk membantu dalam situasi ketika Anda mungkin perlu memasang debugger atau profiler. Traffic harus diarahkan langsung ke alamat IP instance target, bukan melalui domain appspot.com atau domain kustom Anda.
Secara default, traffic masuk dari luar jaringan Anda tidak diizinkan melalui firewall Google Cloud Platform.
Setelah menetapkan penerusan port dalam file app.yaml
, Anda harus menambahkan aturan firewall yang mengizinkan traffic dari port yang ingin dibuka.
Anda dapat menentukan aturan firewall di halaman Networking Firewall Rules pada Konsol Google Cloud atau menggunakan perintah gcloud
.
Misalnya, jika Anda ingin meneruskan traffic TCP dari port 2222
:
Di setelan jaringan
app.yaml
, sertakan:network: forwarded_ports: - 2222/tcp
Jika Anda menggunakan runtime Python, ubah
app.yaml
untuk menyertakan:entrypoint: gunicorn -b :$PORT -b :2222 main:app
Tentukan aturan firewall di Konsol Google Cloud atau gunakan
gcloud compute firewall-rules create
untuk mengizinkan traffic dari sumber mana pun (0.0.0.0/0
) dan daritcp:2222
.
Setelan resource
Setelan ini mengontrol resource komputasi. App Engine menetapkan jenis mesin berdasarkan jumlah CPU dan memori yang Anda tentukan. Mesin dijamin memiliki resource setidaknya sebanyak yang Anda tentukan, bahkan mungkin lebih.
Anda dapat menentukan hingga delapan volume tmpfs di setelan resource. Selanjutnya, Anda dapat mendukung workload yang memerlukan memori bersama melalui tmpfs dan dapat meningkatkan I/O sistem file.
Contoh:
resources:
cpu: 2
memory_gb: 2.3
disk_size_gb: 10
volumes:
- name: ramdisk1
volume_type: tmpfs
size_gb: 0.5
Anda dapat menggunakan opsi berikut saat mengonfigurasi setelan resource:
Opsi | Deskripsi | Default |
---|---|---|
cpu |
Jumlah core; harus satu, bilangan genap antara 2 dan 32, atau kelipatan 4 antara 32 dan 80. | 1 core |
memory_gb |
RAM dalam GB. Memori yang diminta untuk aplikasi Anda, yang tidak mencakup memori ~0,4 GB yang diperlukan untuk overhead beberapa proses. Setiap core CPU memerlukan total memori antara 1,0 dan 6,5 GB. Untuk menghitung memori yang diminta:
Untuk contoh di atas, di mana Anda telah menentukan 2 core, Anda dapat meminta memori antara 1,6 dan 12,6 GB. Jumlah total memori yang tersedia untuk aplikasi ditetapkan oleh lingkungan runtime sebagai variabel lingkungan |
0,6 GB |
disk_size_gb |
Ukuran dalam GB. Ukuran minimum adalah 10 GB dan maksimum adalah 10.240 GB. | 13 GB |
name |
Wajib diisi, jika menggunakan volume. Nama volume. Nama harus unik dan terdiri atas 1 hingga 63 karakter. Karakter dapat berupa huruf kecil, angka, atau tanda hubung. Karakter pertama harus berupa huruf, dan karakter terakhir tidak boleh berupa tanda hubung. Volume dipasang di container aplikasi sebagai /mnt/NAME .
|
|
volume_type |
Wajib diisi, jika menggunakan volume. Harus berupa tmpfs . |
|
size_gb |
Wajib diisi, jika menggunakan volume. Ukuran volume, dalam GB. Nilai minimumnya adalah 0,001 GB dan maksimumnya adalah jumlah memori yang tersedia di container aplikasi dan di perangkat dasar. Google tidak menambahkan RAM tambahan ke sistem Anda untuk memenuhi persyaratan disk. RAM yang dialokasikan untuk volume tmpfs akan dikurangkan dari memori yang tersedia untuk container aplikasi. Presisinya bergantung pada sistem. |
Health check terpisah
Secara default, health check terpisah diaktifkan. Anda dapat menggunakan permintaan health check berkala untuk mengonfirmasi bahwa instance VM telah berhasil di-deploy, dan untuk memastikan bahwa instance yang berjalan selalu berstatus responsif. Setiap health check harus dijawab dalam interval waktu yang ditentukan.
Instance dianggap tidak responsif jika gagal merespons sejumlah permintaan health check berturut-turut. Jika instance tidak aktif, instance akan dimulai ulang. Jika belum siap, instance tidak akan menerima permintaan klien. Health check juga dapat gagal jika tidak ada kapasitas disk yang kosong.
Ada dua jenis health check yang dapat Anda gunakan:
- Pemeriksaan keaktifan mengonfirmasi bahwa VM dan container Docker sedang berjalan. App Engine memulai ulang instance yang tidak responsif.
- Pemeriksaan kesiapan mengonfirmasi bahwa instance Anda siap menerima permintaan masuk. Instance yang gagal dalam pemeriksaan kesiapan tidak akan ditambahkan ke kumpulan instance yang tersedia.
Secara default, permintaan HTTP dari health check tidak diteruskan ke container aplikasi Anda. Jika Anda ingin memperluas health check ke aplikasi, tentukan jalur untuk pemeriksaan keaktifan atau pemeriksaan kesiapan. Health check yang disesuaikan untuk aplikasi Anda dianggap berhasil jika menampilkan kode respons 200 OK
.
Pemeriksaan keaktifan
Pemeriksaan keaktifan mengonfirmasi bahwa VM dan container Docker sedang berjalan. Instance yang dianggap tidak responsif akan dimulai ulang.
Anda dapat menyesuaikan permintaan pemeriksaan keaktifan dengan menambahkan bagian liveness_check
opsional ke file app.yaml
, misalnya:
liveness_check:
path: "/liveness_check"
check_interval_sec: 30
timeout_sec: 4
failure_threshold: 2
success_threshold: 2
Setelan berikut tersedia untuk pemeriksaan keaktifan:
Kolom | Default | Rentang (Minimum-Maksimum) | Deskripsi |
---|---|---|---|
path |
Tidak ada | Jika Anda ingin pemeriksaan keaktifan diteruskan ke container aplikasi, tentukan jalur URL, seperti "/liveness_check" |
|
timeout_sec |
4 detik | 1-300 | Interval waktu tunggu untuk setiap permintaan, dalam detik. |
check_interval_sec |
30 seconds | 1-300 | Interval waktu antar-pemeriksaan, dalam detik. Perhatikan bahwa nilai ini harus lebih besar daripada timeout_sec. |
failure_threshold |
4 pemeriksaan | 1-10 | Instance menjadi tidak responsif setelah gagal dalam pemeriksaan berturut-turut sebanyak ini. |
success_threshold |
2 pemeriksaan | 1-10 | Instance yang tidak responsif akan kembali menjadi responsif setelah berhasil merespons pemeriksaan berturut-turut sebanyak ini. |
initial_delay_sec |
300 detik | 0-3600 | Penundaan, dalam detik, setelah instance dimulai, yang selama rentang waktu tersebut respons health check diabaikan. Setelan ini berlaku untuk setiap instance yang baru dibuat dan dapat memberi instance baru lebih banyak waktu untuk aktif dan berjalan. Setelan ini menunda pemeriksaan autohealing dan berpotensi membuat ulang instance secara prematur jika instance sedang dalam proses dimulai. Timer penundaan awal dimulai saat instance berada dalam mode RUNNING. Misalnya, Anda dapat meningkatkan waktu tunda jika aplikasi memiliki tugas inisialisasi yang membutuhkan waktu lama sebelum siap menyalurkan traffic. |
Pemeriksaan kesiapan
Pemeriksaan kesiapan mengonfirmasi bahwa instance dapat menerima permintaan masuk. Instance yang tidak lulus pemeriksaan kesiapan tidak akan ditambahkan ke kumpulan instance yang tersedia.
Anda dapat menyesuaikan permintaan health check dengan menambahkan bagian readiness_check
opsional ke file app.yaml
, misalnya:
readiness_check:
path: "/readiness_check"
check_interval_sec: 5
timeout_sec: 4
failure_threshold: 2
success_threshold: 2
app_start_timeout_sec: 300
Setelan berikut tersedia untuk pemeriksaan kesiapan:
Kolom | Default | Rentang (Minimum-Maksimum) | Deskripsi |
---|---|---|---|
path |
Tidak ada | Jika Anda ingin pemeriksaan kesiapan diteruskan ke container aplikasi, tentukan jalur URL, seperti "/readiness_check" |
|
timeout_sec |
4 detik | 1-300 | Interval waktu tunggu untuk setiap permintaan, dalam detik. |
check_interval_sec |
5 detik | 1-300 | Interval waktu antar-pemeriksaan, dalam detik. Perhatikan bahwa nilai ini harus lebih besar daripada timeout_sec. |
failure_threshold |
2 pemeriksaan | 1-10 | Instance menjadi tidak responsif setelah gagal dalam pemeriksaan berturut-turut sebanyak ini. |
success_threshold |
2 pemeriksaan | 1-10 | Instance yang tidak responsif akan menjadi responsif kembali setelah berhasil merespons pemeriksaan berturut-turut sebanyak ini. |
app_start_timeout_sec |
300 detik | 1-1800 | Setelan ini berlaku untuk deployment baru, bukan untuk VM individual. Setelan ini menentukan waktu maksimum (dalam detik) yang diberikan agar instance dalam jumlah yang cukup di suatu deployment dapat lulus health check. Jika durasi ini terlampaui, deployment akan gagal dan di-roll back. Timer dimulai saat instance Compute Engine telah disediakan dan layanan backend Load Balancer dibuat. Misalnya, Anda dapat meningkatkan waktu tunggu jika ingin memberikan waktu lebih lama selama deployment agar instance dalam jumlah yang cukup menjadi responsif. |
Frekuensi health check
Untuk memastikan ketersediaan tinggi, App Engine membuat salinan redundan setiap health checker. Jika health checker gagal, health checker redundan dapat mengambil alih tanpa penundaan.
Saat memeriksa log nginx.health_check
aplikasi, Anda mungkin mendapati bahwa polling health check terjadi lebih sering daripada yang telah dikonfigurasi. Hal ini karena health checker redundan juga mengikuti setelan Anda. Health checker redundan ini dibuat secara otomatis dan Anda tidak dapat mengonfigurasinya.
Setelan penskalaan layanan
Kunci yang digunakan untuk mengontrol penskalaan layanan bergantung pada jenis penskalaan yang Anda tetapkan ke layanan.
Anda dapat menggunakan penskalaan otomatis atau manual. Default-nya adalah penskalaan otomatis.
Penskalaan otomatis
Anda dapat mengonfigurasi penskalaan otomatis dengan menambahkan bagian automatic_scaling
ke file app.yaml
. Contoh:
automatic_scaling:
min_num_instances: 1
max_num_instances: 15
cool_down_period_sec: 180
cpu_utilization:
target_utilization: 0.6
target_concurrent_requests: 100
Tabel berikut mencantumkan setelan yang dapat Anda gunakan dengan penskalaan otomatis:
Nama | Deskripsi |
---|---|
automatic_scaling |
Penskalaan otomatis diasumsikan secara default. Sertakan baris ini jika Anda ingin menentukan salah satu setelan penskalaan otomatis. |
min_num_instances |
Jumlah minimum instance yang diberikan ke layanan Anda. Saat di-deploy, layanan akan diberi instance sebanyak ini dan diskalakan sesuai dengan traffic.
Harus 1 atau lebih besar, default-nya adalah 2 untuk mengurangi latensi.
|
max_num_instances |
Jumlah maksimum instance yang dapat ditingkatkan skalanya oleh layanan Anda. Jumlah maksimum instance dalam project dibatasi oleh kuota resource project.
Default-nya adalah 20 .
|
cool_down_period_sec |
Jumlah detik autoscaler harus menunggu sebelum mulai mengumpulkan informasi dari instance baru. Setelan ini mencegah autoscaler mengumpulkan informasi saat instance sedang dimulai, karena selama waktu tersebut penggunaan yang terkumpul tidak dapat diandalkan. Periode tunggu ini harus lebih besar daripada atau sama dengan 60 detik.
Default-nya adalah 120 .
|
cpu_utilization |
Gunakan header ini jika Anda ingin menentukan target pemakaian CPU. |
target_utilization |
Target pemakaian CPU Penggunaan CPU di semua instance yang berjalan dirata-rata dan digunakan untuk memutuskan kapan harus mengurangi atau meningkatkan jumlah instance. Perhatikan bahwa jumlah instance akan dikurangi 25 detik setelah sinyal penonaktifan diterima, meskipun ada permintaan yang sedang diproses. Default-nya adalah 0.5 .
|
target_concurrent_requests |
(Beta) Jumlah target koneksi serentak per instance. Jika Anda menentukan nilai untuk parameter ini, autoscaler akan menggunakan jumlah rata-rata koneksi serentak di semua instance yang berjalan untuk memutuskan kapan harus mengurangi atau meningkatkan jumlah instance. Jumlah instance akan dikurangi 25 detik setelah sinyal penonaktifan diterima, meskipun ada permintaan yang sedang diproses. Jika Anda tidak menentukan nilai untuk parameter ini, autoscaler tidak akan menargetkan jumlah koneksi serentak per instance. Koneksi tidak sama dengan permintaan. Koneksi dapat digunakan kembali oleh klien untuk mengirim beberapa permintaan. |
Penskalaan manual
Anda dapat mengonfigurasi penskalaan manual dengan menambahkan bagian manual_scaling
ke file app.yaml
. Contoh:
manual_scaling:
instances: 5
Tabel berikut mencantumkan setelan yang dapat Anda gunakan dengan penskalaan manual:
Nama | Deskripsi |
---|---|
manual_scaling |
Harus ada untuk mengaktifkan penskalaan manual pada layanan. |
instances |
Jumlah instance yang akan ditetapkan ke layanan. |
Menentukan variabel lingkungan
Anda dapat menentukan variabel lingkungan di app.yaml
untuk disediakan bagi aplikasi Anda, misalnya:
env_variables:
MY_VAR: "my value"
di mana MY_VAR
dan my value
adalah nama dan nilai variabel lingkungan yang ingin Anda tentukan, dan setiap entri variabel lingkungan diindentasi dua spasi di bawah elemen env_variables
.
Menggunakan variabel lingkungan