Modul 2: Melakukan migrasi dari App Engine ndb ke Cloud NDB

Rangkaian codelab ini (tutorial praktik mandiri) bertujuan untuk membantu developer Google App Engine (Standar) memodernisasi aplikasi mereka dengan memandu mereka melalui serangkaian migrasi. Langkah yang paling signifikan adalah beralih dari layanan paket runtime asli karena runtime generasi berikutnya lebih fleksibel, sehingga memberikan opsi layanan yang lebih beragam kepada pengguna. Peralihan ke runtime generasi baru memungkinkan Anda berintegrasi dengan produk Google Cloud dengan lebih mudah, menggunakan berbagai layanan yang didukung, dan mendukung rilis bahasa saat ini.

Tutorial ini menunjukkan cara bermigrasi dari library klienndb (Database Berikutnya) bawaan App Engine ke library klien Cloud NDB.

Anda akan mempelajari cara

  • Menggunakan library App Engine ndb (jika Anda belum terbiasa dengannya)
  • Melakukan migrasi dari ndb ke Cloud NDB
  • Melakukan migrasi aplikasi Anda lebih lanjut ke Python 3

Yang akan Anda perlukan

Survei

Bagaimana Anda akan menggunakan codelab ini?

Hanya membacanya Membacanya dan menyelesaikan latihan

Di Modul 1, kita memigrasikan framework web dari webapp2 bawaan App Engine ke Flask. Dalam codelab ini, kita terus beralih dari layanan bawaan App Engine dengan beralih dari library ndb App Engine ke Google Cloud NDB.

Dengan menyelesaikan migrasi ini, Anda dapat:

  1. Bermigrasi ke Python 3 dan runtime App Engine generasi berikutnya
  2. Bermigrasi ke Cloud Datastore (library klien untuk aplikasi non-App Engine)
  3. Melakukan containerization aplikasi Python 2 (atau 3) dan bermigrasi ke Cloud Run
  4. Menambahkan penggunaan task queue App Engine (push) lalu bermigrasi ke Cloud Tasks

Namun, kami belum sampai sana. Selesaikan codelab ini sebelum mempertimbangkan langkah-langkah berikutnya. Migrasi dalam tutorial ini memaparkan langkah-langkah utama berikut:

  1. Penyiapan/Prakerja
  2. Tambahkan library Cloud NDB
  3. Perbarui file aplikasi

Sebelum memulai bagian utama tutorial, mari kita siapkan project, dapatkan kodenya, lalu deploy aplikasi dasar pengukuran sehingga kita tahu bahwa kita memulai dengan kode yang berfungsi.

1. Siapkan project

Jika Anda sudah menyelesaikan codelab Modul 1, sebaiknya gunakan kembali project (dan kode) yang sama. Atau, Anda dapat membuat project baru atau menggunakan kembali project lain yang sudah ada. Pastikan project memiliki akun penagihan yang aktif dan App Engine diaktifkan.

2. Dapatkan aplikasi contoh dasar pengukuran

Salah satu prasyarat adalah memiliki aplikasi contoh Modul 1 yang berfungsi. Gunakan solusi Anda jika Anda telah menyelesaikan tutorial tersebut. Anda dapat menyelesaikannya sekarang (link di atas), atau jika Anda ingin melewatinya, salin repo Modul 1 (link di bawah).

Baik Anda menggunakan kode Anda atau kode kami, kode Modul 1 adalah tempat kita akan memulai (START). Codelab Modul 2 ini akan memandu Anda melalui setiap langkah, dan setelah selesai, kode akan menyerupai kode pada titik FINISH (termasuk port "bonus" opsional dari Python 2 hingga 3):

Folder kode Modul 1 tempat Anda memulai (START) akan memiliki konten berikut:

$ ls
README.md               appengine_config.py     requirements.txt
app.yaml                main.py                 templates

Jika sudah menyelesaikan tutorial Modul 1, Anda juga akan memiliki folder lib dengan Flask dan dependensinya. Jika Anda tidak memiliki folder lib, buat dengan perintah pip install -t lib -r requirements.txt agar kita dapat men-deploy aplikasi pengukuran dasar ini di langkah berikutnya. Jika Anda memiliki Python 2 maupun 3, sebaiknya gunakan pip2 bukan pip untuk menghindari kebingungan dengan Python 3.

3. Deploy (ulang) aplikasi Modul 1

Langkah prakerja yang tersisa untuk dijalankan sekarang:

  1. Biasakan kembali diri Anda dengan alat command-line gcloud (jika perlu)
  2. Deploy (ulang) kode Modul 1 ke App Engine (jika perlu)

Setelah Anda berhasil menjalankan langkah-langkah tersebut dan mengonfirmasikan operasinya, kita akan melanjutkan tutorial ini, dimulai dengan file konfigurasi.

Banyak layanan bawaan App Engine asli telah disertakan ke dalam produk mereka sendiri, dan Datastore merupakan salah satunya. Saat ini, aplikasi non-App Engine dapat menggunakan Cloud Datastore. Untuk pengguna lama ndb, tim Google Cloud telah membuat library klien Cloud NDB untuk berbicara dengan Cloud Datastore. Ini tersedia untuk Python 2 dan 3.

Mari perbarui file konfirmasi untuk mengganti App Engine ndb dengan Cloud NDB, lalu ubah aplikasi.

1. Perbarui requirements.txt

Di Modul 1, satu-satunya dependensi eksternal untuk aplikasi adalah Flask. Sekarang kita akan menambahkan Cloud NDB. Berikut adalah tampilan file requirements.txt Anda di akhir Modul 1:

  • SEBELUM:
Flask==1.1.2

Migrasi dari App Engine ndb memerlukan library Cloud NDB (google-cloud-ndb), jadi tambahkan paketnya ke requirements.txt.

  • SETELAH:
Flask==1.1.2
google-cloud-ndb==1.7.1

Saat codelab ini ditulis, versi terbaru yang direkomendasikan adalah 1.7.1, namun requirements.txt dalam repo mungkin memiliki versi yang lebih baru. Kami merekomendasikan versi terbaru dari setiap library, tetapi jika tidak berfungsi, Anda dapat melakukan roll back ke rilis yang lebih lama.

Hapus folder lib jika ada dan tidak baru saja dibuat di atas. Sekarang (kembali) instal library yang diperbarui dengan perintah pip install -t lib -r requirements.txt, menggunakan pip2 bukan pip sebagaimana diperlukan.

2. Perbarui app.yaml

Menambahkan library klien Google Cloud seperti google-cloud-ndb memiliki beberapa persyaratan, semuanya berkisar pada penyertaan library "bawaan", paket pihak ketiga yang sudah tersedia di server Google. Anda tidak mencantumkannya di requirements.txt atau tidak menyalinnya dengan pip install. Satu-satunya persyaratan:

  1. Tentukan library bawaan di app.yaml
  2. Arahkan mereka ke library pihak ketiga yang disalin yang dapat mereka gunakan (dalam lib)

Berikut adalah app.yaml untuk memulai (START) dari Modul 1:

  • SEBELUM:
runtime: python27
threadsafe: yes
api_version: 1

handlers:
- url: /.*
  script: main.app

Sekarang tambahkan baris berikut ke app.yaml untuk mereferensikan pasangan paket pihak ketiga: grpcio dan setuptools di bagian libraries baru:

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0

Mengapa menggunakan library bawaan ini?gRPC adalah framework RPC terbuka yang digunakan oleh semua library klien Google Cloud, termasukgoogle-cloud-ndb. Library grpcio adalah adaptor gRPC Python dan karenanya diperlukan. Alasan untuk menyertakan setuptools akan segera dipaparkan.

  • SETELAH:

Dengan perubahan di atas, app.yaml yang diperbarui sekarang akan terlihat seperti ini:

runtime: python27
threadsafe: yes
api_version: 1

handlers:
- url: /.*
  script: main.app

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0

3. Perbarui appengine_config.py

Alat pkg_resources, bagian dari library setuptools, digunakan untuk memungkinkan library pihak ketiga bawaan mengakses library pihak ketiga yang dipaketkan. Perbarui appengine_config.py untuk menggunakan pkg_resources agar mengarahkan ke library ke library yang dipaketkan dalam lib. Setelah Anda menyelesaikan perubahan ini, seluruh file akan terlihat seperti ini:

import pkg_resources
from google.appengine.ext import vendor

# Set PATH to your libraries folder.
PATH = 'lib'
# Add libraries installed in the PATH folder.
vendor.add(PATH)
# Add libraries to pkg_resources working set to find the distribution.
pkg_resources.working_set.add_entry(PATH)

Setelah formalitas file konfigurasi disingkirkan, sekarang Anda dapat bermigrasi dari ndb ke Cloud NDB. Untuk menyelesaikan migrasi, perbarui library yang diimpor dan tambahkan penggunaan pengelolaan konteks di main.py.

1. Impor

Lakukan pertukaran impor berikut di main.py:

  • SEBELUM
from google.appengine.ext import ndb
  • SETELAH:
from google.cloud import ndb

Perubahan dari library App Engine ke library Google Cloud terkadang sama rumitnya dengan instance ini. Untuk layanan bawaan yang menjadi produk Google Cloud lengkap, Anda akan mengimpor atribut dari google.cloud, bukan google.appengine.

2. Akses Datastore

Agar dapat menggunakan library Cloud NDB, aplikasi Anda harus menggunakan pengelola konteks Python. Tujuannya adalah untuk "membuka" akses menuju resource sehingga resource harus diperoleh sebelum dapat digunakan. Pengelola konteks didasarkan pada teknik kontrol ilmu komputer yang dikenal sebagai Resource Allocation Is Initialization (atau RAII). Pengelola konteks digunakan dengan file Python (yang harus dibuka sebelum dapat diakses) dan bersamaan dengan itu, "kunci putar" harus diperoleh sebelum kode di "bagian kritis" dapat dijalankan.

Demikian pula, Cloud NDB mengharuskan Anda memperoleh konteks klien untuk berkomunikasi dengan Datastore sebelum perintah Datastore dapat dijalankan. Pertama, buat klien (ndb.Client()) dengan menambahkan ds_client = ndb.Client() di main.py langsung setelah inisialisasi Flask:

app = Flask(__name__)
ds_client = ndb.Client()

Perintah Python with digunakan hanya untuk mendapatkan konteks objek. Gabungkan semua blok kode yang mengakses Datastore dengan pernyataan with.

Di bawah ini adalah fungsi yang sama dari Modul 1 untuk menulis Entity baru ke Datastore, dan membaca untuk menampilkan Entity terbaru yang ditambahkan:

  • SEBELUM:

Berikut ini kode asli tanpa pengelolaan konteks:

def store_visit(remote_addr, user_agent):
    'create new Visit entity in Datastore'
    Visit(visitor='{}: {}'.format(remote_addr, user_agent)).put()

def fetch_visits(limit):
    'get most recent visits'
    return (v.to_dict() for v in Visit.query().order(
            -Visit.timestamp).fetch(limit))
  • SETELAH:

Sekarang tambahkan with ds_client.context(): dan pindahkan kode akses Datastore Anda ke blok with:

def store_visit(remote_addr, user_agent):
    'create new Visit entity in Datastore'
    with ds_client.context():
        Visit(visitor='{}: {}'.format(remote_addr, user_agent)).put()

def fetch_visits(limit):
    'get most recent visits'
    with ds_client.context():
        return (v.to_dict() for v in Visit.query().order(
                -Visit.timestamp).fetch(limit))

Aplikasi driver utama tetap sama dengan yang kita miliki dari Modul 1 karena tidak ada kode ndb (atau Cloud NDB) di sini:

@app.route('/')
def root():
    'main application (GET) handler'
    store_visit(request.remote_addr, request.user_agent)
    visits = fetch_visits(10)
    return render_template('index.html', visits=visits)

Praktik terbaiknya adalah memastikan perbedaan yang jelas antara kode aplikasi dan akses data. Dengan demikian, kode aplikasi utama tidak berubah ketika mekanisme penyimpanan data yang mendasarinya berubah seperti yang kita lakukan dengan migrasi ini.

Deploy aplikasi

Deploy ulang aplikasi Anda dengan gcloud app deploy dan konfirmasikan bahwa aplikasi berfungsi. Kode Anda sekarang seharusnya cocok dengan yang ada di repo Modul 2.

Jika Anda beralih ke rangkaian ini tanpa melakukan codelab sebelumnya, aplikasi itu sendiri tidak akan berubah. Aplikasi akan mendaftarkan semua kunjungan ke halaman web utama (/) dan terlihat seperti ini setelah Anda mengunjungi situs cukup waktu:

aplikasi visitme

Selamat, Anda telah menyelesaikan codelab Modul 2 ini. Anda baru saja berhasil melewati garis akhir, karena ini merupakan migrasi terakhir dari migrasi yang sangat direkomendasikan dalam seri ini sejauh batasan Datastore.

Opsional: Pembersihan

Bagaimana dengan pembersihan agar tidak ditagih hingga Anda siap untuk beralih ke codelab migrasi berikutnya? Sebagai developer yang sudah ada, Anda mungkin sudah mengetahui yang terbaru tentang informasi harga App Engine.

Opsional: Nonaktifkan aplikasi

Jika Anda belum siap melanjutkan ke tutorial berikutnya, nonaktifkan aplikasi untuk menghindari tagihan. Jika sudah siap untuk beralih ke codelab berikutnya, Anda dapat mengaktifkannya kembali. Meskipun dinonaktifkan, aplikasi tidak akan mendapatkan traffic yang dikenakan biaya, namun hal lain yang dapat ditagih adalah penggunaan Datastore jika melebihi kuota gratis, jadi cukup hapus hingga berada di bawah batas tersebut.

Di sisi lain, jika Anda tidak akan melanjutkan migrasi dan ingin menghapus semuanya, Anda dapat mematikan project.

Langkah berikutnya

Dari sini, ada fleksibilitas untuk langkah selanjutnya. Pilih salah satu opsi berikut:

  • Bonus Modul 2: Lanjutkan ke bagian bonus tutorial ini untuk mempelajari cara porting ke Python 3 dan runtime App Engine generasi berikutnya.
  • Modul 7: Task Queues Push App Engine (diperlukan jika Anda menggunakan Task Queues [push])
    • Tambahkan tugas push taskqueue App Engine ke aplikasi Modul 1
    • Siapkan pengguna untuk bermigrasi ke Cloud Tasks di Modul 8
  • Modul 4: Bermigrasi ke Cloud Run dengan Docker
    • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Docker
    • Memungkinkan Anda tetap berada di Python 2
  • Modul 5: Melakukan Migrasi ke Cloud Run dengan Cloud Buildpacks
    • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Cloud Buildpacks
    • Anda tidak perlu mengetahui apa pun tentang Docker, container, atau Dockerfile
    • Anda harus sudah memigrasikan aplikasi ke Python 3
  • Modul 3:
    • Memodernisasi akses Datastore dari Cloud NDB ke Cloud Datastore
    • Ini adalah library yang digunakan untuk aplikasi Python 3 App Engine dan aplikasi non-App Engine

Untuk mengakses runtime dan fitur App Engine terbaru, sebaiknya lakukan migrasi ke Python 3. Dalam aplikasi contoh kami, Datastore adalah satu-satunya layanan bawaan yang kami gunakan, dan karena kami telah bermigrasi dari ndb ke Cloud NDB, kini kami dapat melakukan porting ke runtime Python 3 App Engine.

Ringkasan

Meskipun melakukan porting ke Python 3 tidak berada dalam cakupan tutorial Google Cloud, bagian codelab ini memberikan gambaran kepada developer tentang perbedaan runtime App Engine Python 3. Salah satu fitur yang menonjol dari runtime generasi berikutnya adalah akses yang disederhanakan ke paket pihak ketiga. Tidak perlu menentukan paket bawaan di app.yaml, juga tidak perlu menyalin atau mengupload library non--bawaan. Mereka secara implisit terinstal agar tidak tercantum di requirements.txt.

Karena sampel kami begitu sederhana dan Cloud NDB kompatibel dengan Python 2-3, tidak ada kode aplikasi yang perlu ditransfer secara eksplisit ke 3.x. Aplikasi berjalan pada 2.x dan 3.x tanpa modifikasi, yang berarti hanya satu-satunya perubahan yang diperlukan adalah dalam konfigurasi dalam kasus ini:

  1. Sederhanakan app.yaml untuk mereferensikan Python 3 dan menghapus library pihak ketiga.
  2. Hapus appengine_config.py dan folder lib karena sudah tidak diperlukan lagi.

Selain main.py, file requirements.txt dan templates/index.html tetap tidak berubah.

Sederhanakan app.yaml

SEBELUM:

Satu-satunya perubahan nyata untuk aplikasi contoh ini adalah mempersingkat app.yaml secara signifikan. Sebagai pengingat, inilah yang kita miliki di app.yaml pada akhir Modul 2:

runtime: python27
threadsafe: yes
api_version: 1

handlers:
- url: /.*
  script: main.app

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0

SETELAH:

Pada Python 3, perintah threadsafe, api_version, dan libraries tidak digunakan lagi. Semua aplikasi dianggap threadsafe dan api_version tidak digunakan di Python 3. Tidak ada lagi paket pihak ketiga bawaan yang sudah terpasang di layanan App Engine, sehingga libraries juga tidak digunakan lagi. Lihat dokumentasi perubahan pada app.yaml untuk informasi selengkapnya tentang perubahan ini. Oleh karena itu, Anda harus menghapus ketiganya dari app.yaml dan memperbarui ke versi Python 3 yang didukung (lihat di bawah).

Penggunaan perintah handlers

Selain itu, perintah handlers, yang mengarahkan traffic pada aplikasi App Engine juga tidak digunakan lagi. Karena runtime generasi berikutnya mengharapkan framework web untuk mengelola perutean aplikasi, semua "skrip pengendali" harus diubah menjadi "auto". Dengan menggabungkan perubahan-perubahan dari atas, akan dihasilkan app.yaml ini:

runtime: python38

handlers:
- url: /.*
  script: auto

Pelajari lebih lanjut tentang script: auto dari halaman dokumentasinya.

Menghapus perintah handlers

Karena handlers tidak digunakan lagi, Anda juga dapat menghapus seluruh bagian, sehingga menyisakan app.yaml baris tunggal:

runtime: python38

Secara default, tindakan ini akan meluncurkan server web Gunicorn WSGI yang tersedia untuk semua aplikasi. Jika Anda terbiasa dengan gunicorn, ini adalah perintah yang dijalankan ketika dimulai secara default dengan barebones app.yaml:

gunicorn main:app --workers 2 -c /config/gunicorn.py

Opsional: penggunaan perintah entrypoint

Namun, jika aplikasi Anda memerlukan perintah start-up spesifik, yang dapat ditetapkan dengan perintah entrypoint sedangkan app.yaml akan terlihat seperti ini:

runtime: python38
entrypoint: python main.py

Contoh ini secara khusus meminta server pengembangan Flask untuk digunakan, bukan gunicorn. Kode yang memulai server pengembangan juga harus ditambahkan ke aplikasi Anda untuk diluncurkan pada antarmuka 0.0.0.0 pada port 8080 dengan menambahkan bagian kecil ini ke bagian bawah main.py:

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080, debug=True)

Pelajari lebih lanjut tentang entrypoint dari halaman dokumentasinya. Lebih banyak contoh dan praktik terbaik dapat ditemukan di Dokumen startup Standar App Engine serta Dokumen startup Fleksibel App Engine.

Hapus appengine_config.py dan lib

Hapus file appengine_config.py dan folder lib. Saat bermigrasi ke Python 3, App Engine memperoleh dan menginstal paket yang tercantum di requirements.txt.

File konfigurasi appengine_config.py digunakan untuk mengenali library/paket pihak ketiga, baik Anda menyalinnya atau menggunakan yang sudah tersedia di server App Engine (bawaan). Saat beralih ke Python 3, ringkasan perubahan besar adalah:

  1. Tidak ada paket library pihak ketiga yang disalin (tercantum di requirements.txt)
  2. Tidak ada pip install dalam folder lib, artinya tidak ada periode folder lib
  3. Tidak ada pencantuman library pihak ketiga bawaan di app.yaml
  4. Tidak perlu merujuk aplikasi ke library pihak ketiga, sehingga tidak ada file appengine_config.py

Anda hanya perlu mencantumkan semua library pihak ketiga yang diperlukan di requirements.txt.

Deploy aplikasi

Deploy ulang aplikasi Anda untuk memastikannya berfungsi. Anda juga dapat mengonfirmasi seberapa dekat solusi Anda dengan kode Python 3 contoh dari Modul 2. Untuk memvisualisasikan perbedaan dengan Python 2, bandingkan kode dengan versi Python 2.

Selamat, Anda telah menyelesaikan langkah bonus di Modul 2! Buka dokumentasi tentang menyiapkan file konfigurasi untuk runtime Python 3. Terakhir, kembali ke langkah "Ringkasan/Pembersihan" sebelumnya untuk langkah dan pembersihan berikutnya.

Menyiapkan aplikasi Anda

Saat tiba waktunya untuk memigrasikan aplikasi Anda, Anda harus mentransfer main.py Anda dan file aplikasi lain ke 3.x, jadi praktik terbaik adalah mencoba sebaik mungkin untuk membuat aplikasi 2.x Anda memiliki "kompatibilitas maju" setinggi mungkin.

Ada banyak resource online yang dapat membantu Anda mencapainya, namun beberapa tips penting:

  1. Pastikan semua dependensi aplikasi sepenuhnya kompatibel dengan versi 3.x
  2. Pastikan aplikasi Anda setidaknya bisa dijalankan minimal pada versi 2.6 (sebaiknya 2.7)
  3. Pastikan aplikasi lulus seluruh rangkaian pengujian (dan cakupan minimum 80%)
  4. Gunakan library kompatibilitas seperti six, Future, dan/atau Modernize
  5. Mendidik diri sendiri tentang perbedaan inkompatibilitas mundur 2.x vs. 3.x
  6. I/O apa pun kemungkinan besar akan menyebabkan inkompatibilitas string Unicode vs. byte

Aplikasi sampel dirancang dengan mempertimbangkan semua hal ini, itulah mengapa aplikasi langsung dapat dijalankan pada versi 2.x dan 3.x sehingga kita dapat berfokus untuk menunjukkan apa yang perlu diubah agar dapat menggunakan platform generasi berikutnya.

Masalah/masukan codelab modul migrasi App Engine

Jika Anda menemukan masalah dengan codelab ini, telusuri masalah Anda terlebih dahulu sebelum mengajukan masalah. Link untuk menelusuri dan membuat masalah baru:

Resource migrasi

Link ke folder repo untuk Modul 1 (START) dan Modul 2 (FINISH) dapat ditemukan pada tabel di bawah. Link tersebut juga dapat diakses dari repo untuk semua migrasi codelab App Engine yang dapat Anda clone atau download file ZIP.

Codelab

Python 2

Python 3

Modul 1

kode

(T/A)

Modul 2

kode

kode

Resource App Engine

Berikut adalah resource tambahan terkait migrasi khusus ini: