Prepare your environment

Clone a sample app

The code for the Django sample app is in theGoogleCloudPlatform/python-docs-samples repository on GitHub.

1. You can eitherdownload the sample as a ZIP file and extract it or clone the repository to your local machine:

   gitclonehttps://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Go to the directory that contains the sample code:

   Linux/macOS

   cdpython-docs-samples/kubernetes_engine/django_tutorial

   Windows

   cdpython-docs-samples\kubernetes_engine\django_tutorial

Confirm your Python setup

This tutorial relies on Python to run the sample application on your machine. The sample code also requires installing dependencies

For more details, refer to thePython development environment guide.

1. Confirm your Python is at least version 3.10.

   python-V

   You should seePython 3.10.0 or higher.

   Note: If you see a version number starting with "2", you may need to runpython3 instead ofpython. If so, remember to reference your chosen Python installation when runningpython commands.

2. Create a Python virtual environment and install dependencies:

   Linux/macOS

   python-mvenvvenvsourcevenv/bin/activatepipinstall--upgradepippipinstall-rrequirements.txt

   Windows

   python-mvenvvenvvenv\scripts\activatepipinstall--upgradepippipinstall-rrequirements.txt

Download Cloud SQL Auth Proxy to connect to Cloud SQL from your local machine

When deployed, your app uses the Cloud SQL Auth Proxy that is built intothe Google Kubernetes Engine environment to communicate with your Cloud SQLinstance. However, to test your app locally, you must install and use a localcopy of the proxy in your development environment. For more details, refer to theCloud SQL Auth Proxy guide.

The Cloud SQL Auth Proxy uses the Cloud SQL API to interact with your SQL instance. To do this, it requires application authentication through thegcloud CLI.

1. Authenticate and acquire credentials for the API:

   gcloudauthapplication-defaultlogin

2. Download and install the Cloud SQL Auth Proxy to your local machine.

   Linux 64-bit

   1. Download the Cloud SQL Auth Proxy:

      curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.linux.amd64

   2. Make the Cloud SQL Auth Proxy executable:

      chmod+xcloud-sql-proxy

   Linux 32-bit

   1. Download the Cloud SQL Auth Proxy:

      curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.linux.386

   2. If thecurl command is not found, runsudo apt install curl and repeat the download command.
   3. Make the Cloud SQL Auth Proxy executable:

      chmod+xcloud-sql-proxy

   macOS 64-bit

   1. Download the Cloud SQL Auth Proxy:

      curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.darwin.amd64

   2. Make the Cloud SQL Auth Proxy executable:

      chmod+xcloud-sql-proxy

   Mac M1

   1. Download the Cloud SQL Auth Proxy:

      curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.darwin.arm64

   2. Make the Cloud SQL Auth Proxy executable:

      chmod+xcloud-sql-proxy

   Windows 64-bit

   Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.x64.exe and selectSave Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.

   Windows 32-bit

   Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.21.0/cloud-sql-proxy.x86.exe and selectSave Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.

   Cloud SQL Auth Proxy Docker image

   The Cloud SQL Auth Proxy has different container images, such asdistroless,alpine,andbuster. The default Cloud SQL Auth Proxy container image usesdistroless, whichcontains no shell. If you need a shell or related tools, then download an image based onalpine orbuster.For more information, seeCloud SQL Auth Proxy Container Images.

   You can pull the latest image to your local machine using Docker by using the following command:

   docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.21.0

   Note: The Cloud SQL Auth Proxy uses a repository that supports thegcr.io domain but serves images from Artifact Registry. For more information, seeTransition from Container Registry.

   Other OS

   For other operating systems not included here, you cancompile the Cloud SQL Auth Proxy from source.

   You can choose to move the download to somewhere common, such as a location on yourPATH, or your home directory. If you choose to do this, when you start the Cloud SQL Auth Proxy later on in the tutorial, remember to reference your chosen location when usingcloud-sql-proxy commands.

Create backing services

This tutorial uses several Google Cloud services to provide thedatabase, media storage, and secret storage that support the deployed Djangoproject. These services are deployed in a specific region. For efficiency betweenservices, all services should be deployed in the same region.For more information about the closest region to you, seeProducts available by region.

Set up a Cloud SQL for PostgreSQL instance

Django officially supports multiple relational databases, but offers the mostsupport for PostgreSQL. PostgreSQL is supported by Cloud SQL, so thistutorial chooses to use that type of database.

The following section describes the creation of a PostgreSQL instance, database, and database user for the app.

1. Create the PostgreSQL instance:

   Console

   1. In the Google Cloud console, go to theCloud SQL Instances page.

      Go to the Cloud SQL Instances page

   2. ClickCreate Instance.

   3. ClickChoose PostgreSQL.

   4. ForSQL Edition, choose "Enterprise".

   5. ForEdition Preset, choose "Sandbox".

   6. In theInstance ID field, enterINSTANCE_NAME.

   7. Enter a password for the postgres user.

   8. Keep the default values for the other fields.

   9. ClickCreate Instance.

   It takes a few minutes for the instance to be ready for use.

   gcloud

   • Create the PostgreSQL instance:

     gcloudsqlinstancescreateINSTANCE_NAME \--projectPROJECT_ID \--database-versionPOSTGRES_16 \--tierdb-n1-standard-2 \--regionREGION

   Replace the following:

   • INSTANCE_NAME: the Cloud SQL instance name
   • PROJECT_ID: the Google Cloud project ID
   • REGION: theGoogle Cloud region

   It takes a few minutes to create the instance and for it to be ready for use.

2. Within the created instance, create a database:

   Console

   1. Within your instance page, go to theDatabases tab.
   2. ClickCreate database.
   3. In theDatabase Name dialog, enterDATABASE_NAME.
   4. ClickCreate.

   gcloud

   • Create the database within the recently created instance:

     gcloudsqldatabasescreateDATABASE_NAME \--instanceINSTANCE_NAME

     ReplaceDATABASE_NAME with a name for the database inside the instance.

3. Create a database user:

   Note: Users created this way get additional database rights. SeeLimit the database user privileges for an alternative method.

   Console

   1. Within your instance page, go to theUsers tab.
   2. ClickAdd User Account.
   3. In theChoose how to authenticate dialog under "Built-in Authentication":
   4. Enter the usernameDATABASE_USERNAME.
   5. Enter the passwordDATABASE_PASSWORD
   6. ClickAdd.

   gcloud

   • Create the user within the recently created instance:

     gcloudsqluserscreateDATABASE_USERNAME \--instanceINSTANCE_NAME \--passwordDATABASE_PASSWORD

     ReplacePASSWORD with a secure password.

Create a service account

The proxy requires a service account with Editor privileges for yourCloud SQL instance. For more information about service accounts, seetheGoogle Cloud authentication overview.

Configure the service account to have either of the following access scopes:

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. In the Google Cloud console, go to theService accounts page.

   Go to Service accounts

2. Select the project that contains your Cloud SQL instance.
3. ClickCreate service account.
4. In theService account name field, enter a descriptive name for the service account.
5. Change theService account ID to a unique, recognizable value and then clickCreate and continue.
6. Click theSelect a role field and select one of the following roles:
   • Cloud SQL > Cloud SQL Client
   • Cloud SQL > Cloud SQL Editor
   • Cloud SQL > Cloud SQL Admin

   Note: To create a service account with the required permissions, you must haveresourcemanager.projects.setIamPolicy permission. This permission is included in the Project Owner, Project IAM Admin, and Organization Administrator roles.
   You must also have enabled the Cloud SQL Admin API. If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.

7. ClickDone to finish creating the service account.
8. Click the action menu for your new service account and then selectManage keys.
9. Click theAdd key drop-down menu and then clickCreate new key.
10. Confirm that the key type is JSON and then clickCreate.

    The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.

Configure the database settings

Use the following commands to set environment variables for database access.These environment variables are used for local testing.

exportDATABASE_NAME=DATABASE_NAMEexportDATABASE_USER=DATABASE_USERNAMEexportDATABASE_PASSWORD=DATABASE_PASSWORD

setDATABASE_USER=DATABASE_USERNAMEsetDATABASE_PASSWORD=DATABASE_PASSWORD

Set up your GKE configuration

1. This application is represented in a single Kubernetes configuration calledpolls. Inpolls.yaml replace<your-project-id> with yourGoogle Cloud project ID (PROJECT_ID).

2. Run the following command and note the value ofconnectionName:

   gcloudsqlinstancesdescribeINSTANCE_NAME--format"value(connectionName)"

3. In thepolls.yaml file, replace<your-cloudsql-connection-string> withtheconnectionName value.

Run the app on your local computer

With the backing services configured, you can now run the app on your computer. This setup allows for local development, creating a superuser, and applying database migrations.

1. In a separate terminal, start the Cloud SQL Auth Proxy:

   Linux/macOS

   ./cloud-sql-proxyPROJECT_ID:REGION:INSTANCE_NAME

   Windows

   cloud-sql-proxy.exePROJECT_ID:REGION:INSTANCE_NAME

   This step establishes a connection from your local computer to yourCloud SQL instance for local testing purposes. Keep theCloud SQL Auth Proxy running the entire time you test your app locally. Runningthis process in a separate terminal allows you to keep working whilethis process runs.

2. In the original terminal, set the Project ID locally:

   Linux/macOS

   exportGOOGLE_CLOUD_PROJECT=PROJECT_ID

   Windows

   setGOOGLE_CLOUD_PROJECT=PROJECT_ID

3. Run the Django migrations to set up your models and assets:

   pythonmanage.pymakemigrationspythonmanage.pymakemigrationspollspythonmanage.pymigratepythonmanage.pycollectstatic

4. Start the Django web server:

   pythonmanage.pyrunserver8080

5. In your browser, go tohttp://localhost:8080.

   If you are in Cloud Shell, click theWeb Preview button, and selectPreview on port 8080.

   The page displays the following text: "Hello, world. You'reat the polls index." The Django web server running on your computer deliversthe sample app pages.

6. PressCtrl/Cmd+C to stop the local web server.

Use the Django admin console

In order to log into Django's admin console, you need to create asuperuser. Since you have a locally accessible connection to the database, you can run management commands:

1. Create a superuser. You will be prompted to enter a username, email, and password.

   pythonmanage.pycreatesuperuser

2. Start a local web server:

   pythonmanage.pyrunserver

3. In your browser, go tohttp://localhost:8000/admin.

4. Log in to the admin site using the username and password you used whenyou rancreatesuperuser.

1. To initialize GKE, go to theClusters page.

   Go to the Clusters page

   When you use GKE for the first time in a project, youneed to wait for the "Kubernetes Engine is getting ready. This may take aminute or more" message to disappear.

2. Create a GKE cluster:

   gcloudcontainerclusterscreatepolls \--scopes"https://www.googleapis.com/auth/userinfo.email","cloud-platform" \--num-nodes4--zone"us-central1-a"

   If an error message similar toProject is not fully initialized with the default service accountsappears, you might need toinitialize Google Kubernetes Engine.

   Initialize GKE

   If you received an error, go to the Google Cloud console to initializeGKE in your project.

   Go to the Clusters page

   Wait for the "Kubernetes Engine is getting ready. This can take a minute ormore" message to disappear.

   OK

3. After the cluster is created, use thekubectl command-line tool, whichis integrated with thegcloud CLI, to interact with yourGKE cluster. Becausegcloud andkubectl are separatetools, make surekubectl is configured to interact with the right cluster.

   gcloudcontainerclustersget-credentialspolls--zone"us-central1-a"

Set up Cloud SQL

1. You need severalsecrets to enable your GKE app to connect with yourCloud SQL instance. One is required for instance-level access(connection), while the other two are required for database access. For moreinformation about the two levels of access control, seeInstance access control.

   1. To create the secret for instance-level access, provide the location,PATH_TO_CREDENTIAL_FILE, of the JSON service accountkey that you downloaded when you created your service account (seeCreating a service account):

      kubectlcreatesecretgenericcloudsql-oauth-credentials \--from-file=credentials.json=PATH_TO_CREDENTIAL_FILE

   2. To create the secrets for database access, use the SQL database,username, and password defined when you created backing services.SeeSet up a Cloud SQL for PostgreSQL instance:

      kubectlcreatesecretgenericcloudsql \--from-literal=database=DATABASE_NAME \--from-literal=username=DATABASE_USERNAME \--from-literal=password=DATABASE_PASSWORD

2. Retrieve the public Docker image for the Cloud SQL proxy.

   dockerpullb.gcr.io/cloudsql-docker/gce-proxy

3. Build a Docker image, replacing<your-project-id> with your project ID.

   dockerbuild-tgcr.io/PROJECT_ID/polls.

4. Configure Docker to usegcloud as a credential helper, so that you canpush the image toContainer Registry:

   gcloudauthconfigure-docker

5. Push the Docker image. Replace<your-project-id> with your project ID.

   dockerpushgcr.io/PROJECT_ID/polls

   Note: This command requires write access to Cloud Storage. If yourun this tutorial on a Compute Engine instance, youraccess to Cloud Storage might be read-only. To get write access,create a service account anduse the service account to authenticate on your instance.

6. Create the GKE resource:

   kubectlcreate-fpolls.yaml

   Note: If you used different names(other thancloudsql-oauth-credentialsandcloudsql) when creating the secrets in the previous commands, then youneed to update thepolls.yaml file to match those new names.

Deploy the app to GKE

After the resources are created, there are threepolls pods on the cluster.Check the status of your pods:

kubectlgetpods

kubectllogs[YOUR_POD_ID]

kubectlgetservicespolls

django-adminstartprojectmysitepythonmanage.pystartapppolls

The base views, models, and route configurations were copied fromWriting your first Django app (Part 1 andPart 2).

Database configuration

Thesettings.py contains the configuration for your SQL database:

DATABASES={"default":{# If you are using Cloud SQL for MySQL rather than PostgreSQL, set# 'ENGINE': 'django.db.backends.mysql' instead of the following."ENGINE":"django.db.backends.postgresql","NAME":os.getenv("DATABASE_NAME"),"USER":os.getenv("DATABASE_USER"),"PASSWORD":os.getenv("DATABASE_PASSWORD"),"HOST":"127.0.0.1","PORT":"5432",}}

Kubernetes pod configurations

Thepolls.yaml file specifies two Kubernetes resources. The first is theService,which defines a consistent name and internal IP address for the Django web app.The second is anHTTP load balancer with a public-facing external IP address.

# The polls service provides a load-balancing proxy over the polls app# pods. By specifying the type as a 'LoadBalancer', Kubernetes Engine will# create an external HTTP load balancer.# For more information about Services see:#   https://kubernetes.io/docs/concepts/services-networking/service/# For more information about external HTTP load balancing see:#   https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/apiVersion:v1kind:Servicemetadata:name:pollslabels:app:pollsspec:type:LoadBalancerports:-port:80targetPort:8080selector:app:polls

The service provides a network name and IP address, andGKE pods run the app's code behind the service.Thepolls.yaml file specifies adeployment that provides declarative updates for GKE pods. The servicedirects traffic to the deployment by matching the service's selector to thedeployment's label. In this case, the selectorpolls is matched to the labelpolls.

apiVersion:apps/v1kind:Deploymentmetadata:name:pollslabels:app:pollsspec:replicas:3selector:matchLabels:app:pollstemplate:metadata:labels:app:pollsspec:containers:-name:polls-app# Replace  with your project ID or use `make template`image:gcr.io/<your-project-id>/polls# This setting makes nodes pull the docker image every time before# starting the pod. This is useful when debugging, but should be turned# off in production.imagePullPolicy:Alwaysenv:-name:DATABASE_NAMEvalueFrom:secretKeyRef:name:cloudsqlkey:database-name:DATABASE_USERvalueFrom:secretKeyRef:name:cloudsqlkey:username-name:DATABASE_PASSWORDvalueFrom:secretKeyRef:name:cloudsqlkey:passwordports:-containerPort:8080-image:gcr.io/cloudsql-docker/gce-proxy:1.16name:cloudsql-proxycommand:["/cloud_sql_proxy","--dir=/cloudsql","-instances=<your-cloudsql-connection-string>=tcp:5432","-credential_file=/secrets/cloudsql/credentials.json"]volumeMounts:-name:cloudsql-oauth-credentialsmountPath:/secrets/cloudsqlreadOnly:true-name:ssl-certsmountPath:/etc/ssl/certs-name:cloudsqlmountPath:/cloudsqlvolumes:-name:cloudsql-oauth-credentialssecret:secretName:cloudsql-oauth-credentials-name:ssl-certshostPath:path:/etc/ssl/certs-name:cloudsqlemptyDir:{}