Django apps that run on Google Kubernetes Engine (GKE) scale well because they run on the same infrastructure that powers all of Google's products.
This tutorial assumes you are familiar with Django web development. If you are new to Django development, it's a good idea to work through writing your first Django app before continuing. In that tutorial, the app's models represent polls that contain questions, and you can interact with the models by using the Django admin console.
This tutorial requires Python 2.7 or 3.4 or later. You also need to have Docker installed.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Enable the Cloud SQL, and Compute Engine APIs.
- Install and initialize the Cloud SDK.
Downloading and running the app
After you've completed the prerequisites, download and deploy the Django sample app. The following sections guide you through configuring, running, and deploying the app.
Cloning the Django app
The code for the Django sample app is in the
GoogleCloudPlatform/python-docs-samples
repository on GitHub.
You can either download the sample as a ZIP file and extract it or clone the repository to your local machine:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Go to the directory that contains the sample code:
cd python-docs-samples/kubernetes_engine/django_tutorial
Setting up your local environment
When deployed, your app uses the Cloud SQL Proxy that is built in to the App Engine environment to communicate with your Cloud SQL instance. However, to test your app locally, you must install and use a local copy of the proxy in your development environment.
Learn more about the Cloud SQL Proxy.
To perform basic admin tasks on your Cloud SQL instance, you can use the PostgreSQL client.
Installing the Cloud SQL Proxy
Download and install the Cloud SQL Proxy. The Cloud SQL Proxy connects to your Cloud SQL instance when running locally.
Linux 64-bit
- Download the Cloud SQL Auth proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
- Make the Cloud SQL Auth proxy executable:
chmod +x cloud_sql_proxy
Linux 32-bit
- Download the Cloud SQL Auth proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
- Make the Cloud SQL Auth proxy executable:
chmod +x cloud_sql_proxy
macOS 64-bit
- Download the Cloud SQL Auth proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
- Make the Cloud SQL Auth proxy executable:
chmod +x cloud_sql_proxy
macOS 32-bit
- Download the Cloud SQL Auth proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
- Make the Cloud SQL Auth proxy executable:
chmod +x cloud_sql_proxy
Windows 64-bit
Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file tocloud_sql_proxy.exe
.
Windows 32-bit
Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file tocloud_sql_proxy.exe
.
Cloud SQL Auth proxy Docker image
For convenience, the Cloud SQL team maintains several container images that contain the Cloud SQL Auth proxy for use by our customers. For more information about these images, see the Cloud SQL Auth proxy repo on GitHub. You can pull the latest image to your local machine using Docker with the following command:docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1
Other OS
For other operating systems not included here, you can compile the Cloud SQL Auth proxy from source.Creating a Cloud SQL instance
-
Create a Cloud SQL for PostgreSQL instance.
Name the instance
polls-instance
or similar. It can take a few minutes for the instance to be ready. When the instance is ready, it's visible in the instances list. - Use the Cloud SDK to run the following command where
[YOUR_INSTANCE_NAME]
represents the name of your Cloud SQL instance:gcloud sql instances describe [YOUR_INSTANCE_NAME]
In the output, note the value shown for
[CONNECTION_NAME]
.The
[CONNECTION_NAME]
value is in the format[PROJECT_NAME]:[REGION_NAME]:[INSTANCE_NAME]
.
Initializing your Cloud SQL instance
- Start the Cloud SQL Proxy by using the
[CONNECTION_NAME]
value from the previous step:Linux/macOS
./cloud_sql_proxy -instances="[YOUR_INSTANCE_CONNECTION_NAME]"=tcp:5432
Windows
cloud_sql_proxy.exe -instances="[YOUR_INSTANCE_CONNECTION_NAME]"=tcp:5432
Replace
[YOUR_INSTANCE_CONNECTION_NAME]
with the[CONNECTION_NAME]
value that you recorded in the previous step.This step establishes a connection from your local computer to your Cloud SQL instance for local testing purposes. Keep the Cloud SQL Proxy running the entire time you test your app locally.
- Create a Cloud SQL user and database:
Cloud Console
-
Create a
new database by using the Cloud Console
for your Cloud SQL instance
polls-instance
. For example, you can use the namepolls
. -
Create a
new user by using the Cloud Console
for your Cloud SQL instance
polls-instance
.
Postgres client
-
In a separate command-line tab, install the
Postgres client.
sudo apt-get install postgresql
-
Use the Postgres client or similar program to connect to your
instance. When prompted, use the root password you configured.
psql --host 127.0.0.1 --user postgres --password
-
Create the required databases, users, and access permissions in your
Cloud SQL database by using the following commands. Replace
[POSTGRES_USER]
and[POSTGRES_PASSWORD]
with the username and password you want to use.CREATE DATABASE polls; CREATE USER [POSTGRES_USER] WITH PASSWORD '[POSTGRES_PASSWORD]'; GRANT ALL PRIVILEGES ON DATABASE polls TO [POSTGRES_USER]; GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO [POSTGRES_USER];
-
Create a
new database by using the Cloud Console
for your Cloud SQL instance
Creating a service account
The proxy requires a service account with Editor privileges for your Cloud SQL instance. For more information about service accounts, see the Google Cloud authentication overview.
- Go to the Service accounts page of the Google Cloud Console.
- Select the project that contains your Cloud SQL instance.
- Click Create service account.
- In the Create service account dialog, enter a descriptive name for the service account.
- Change the Service account ID to a unique, recognizable value and then click Create.
-
For Role, select one of the following roles, click Continue, and then click
Done:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
- Click the action menu for your new service account and then select Manage keys.
- Click the Add key drop-down menu and then click Create new key.
-
Confirm that the key type is JSON and then click Create.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.
Configuring the database settings
Use the following commands to set environment variables for database access. These environment variables are used for local testing.
Linux/macOS
export DATABASE_USER=<your-database-user> export DATABASE_PASSWORD=<your-database-password>
Windows
set DATABASE_USER=<your-database-user> set DATABASE_PASSWORD=<your-database-password>
Setting up your GKE configuration
This application is represented in a single Kubernetes configuration, called
polls
. Inpolls.yaml
replace<your-project-id>
with your Google Cloud project ID.Run the following command and note the value of
connectionName
:gcloud beta sql instances describe [YOUR_INSTANCE_NAME]
In the
polls.yaml
file, replace<your-cloudsql-connection-string>
with theconnectionName
value.
Running the app on your local computer
To run the Django app on your local computer, set up a Python development environment, including Python, pip, and virtualenv.
Create an isolated Python environment and install dependencies. If your Python 3 installation has a different name, use that in the first command:
virtualenv env source env/bin/activate pip install -r requirements.txt
Run the Django migrations to set up your models:
python manage.py makemigrations python manage.py makemigrations polls python manage.py migrate
Start a local web server:
python manage.py runserver
In your browser, go to http://localhost:8000.
You see a page with the following text: "Hello, world. You're at the polls index." The Django web server running on your computer delivers the sample app pages.
Press
Control+C
to stop the local web server.
Using the Django admin console
Create a superuser. You need to specify a username and password.
python manage.py createsuperuser
Run the main program:
python manage.py runserver
In your browser, go to http://localhost:8000/admin.
Log in to the admin site using the username and password you used when you ran
createsuperuser
.
Deploying the app to GKE
When the app is deployed to Google Cloud, it uses the Gunicorn server. Gunicorn doesn't serve static content, so the app uses Cloud Storage to serve static content.
Collect and upload static resources
Create a Cloud Storage bucket and make it publicly readable. Replace
[YOUR_GCS_BUCKET]
with a bucket name of your choice. For example, you could use your project ID as a bucket name.gsutil mb gs://[YOUR_GCS_BUCKET] gsutil defacl set public-read gs://[YOUR_GCS_BUCKET]
Gather all the static content locally into one folder:
python manage.py collectstatic
Upload the static content to Cloud Storage:
gsutil -m rsync -r ./static gs://[YOUR_GCS_BUCKET]/static
In
mysite/settings.py
, set the value ofSTATIC_URL
to the following URL, replacing[YOUR_GCS_BUCKET]
with your bucket name:http://storage.googleapis.com/[YOUR_GCS_BUCKET]/static/
Set up GKE
To initialize GKE, go to the Clusters page.
When you use GKE for the first time in a project, you need to wait for the "Kubernetes Engine is getting ready. This may take a minute or more" message to disappear.
-
gcloud container clusters create polls \ --scopes "https://www.googleapis.com/auth/userinfo.email","cloud-platform" \ --num-nodes 4 --zone "us-central1-a"
Did you get the error: "Project [PROJECT_ID] is not fully initialized with the default service accounts."?
Initialize GKE
If you received an error, go to the Google Cloud Console to initialize GKE in your project.
Wait for the "Kubernetes Engine is getting ready. This can take a minute or more" message to disappear.
After the cluster is created, use the
kubectl
command-line tool, which is integrated with thegcloud
tool, to interact with your GKE cluster. Becausegcloud
andkubectl
are separate tools, make surekubectl
is configured to interact with the right cluster.gcloud container clusters get-credentials polls --zone "us-central1-a"
Set up Cloud SQL
You need several secrets to enable your GKE app to connect with your Cloud SQL instance. One is required for instance-level access (connection), while the other two are required for database access. For more information about the two levels of access control, see Instance access control.
To create the secret for instance-level access, provide the location (
[PATH_TO_CREDENTIAL_FILE]
) of the JSON service account key you downloaded when you created your service account (see Creating a service account):kubectl create secret generic cloudsql-oauth-credentials --from-file=credentials.json=[PATH_TO_CREDENTIAL_FILE]
To create the secrets for database access, use the SQL
[DATABASE_USERNAME]
and[PASSWORD]
defined in step 2 of Initializing your Cloud SQL instance:kubectl create secret generic cloudsql --from-literal=username=[DATABASE_USERNAME] --from-literal=password=[PASSWORD]
Retrieve the public Docker image for the Cloud SQL proxy.
docker pull b.gcr.io/cloudsql-docker/gce-proxy
Build a Docker image, replacing
<your-project-id>
with your project ID.docker build -t gcr.io/<your-project-id>/polls .
Configure Docker to use
gcloud
as a credential helper, so that you can push the image to Container Registry:gcloud auth configure-docker
Push the Docker image. Replace
<your-project-id>
with your project ID.docker push gcr.io/<your-project-id>/polls
Create the GKE resource:
kubectl create -f polls.yaml
Deploy the app to GKE
After the resources are created, there are three polls
pods on the cluster.
Check the status of your pods:
kubectl get pods
Wait a few minutes for the pod statuses to display as Running
. If the pods
aren't ready or if you see restarts, you can get the logs for a particular pod
to figure out the issue. [YOUR-POD-ID]
is a part of the output returned by the
previous kubectl get pods
command.
kubectl logs [YOUR_POD_ID]
Seeing the app run in Google Cloud
After the pods are ready, you can get the public IP address of the load balancer:
kubectl get services polls
Go to the EXTERNAL-IP
address in your browser to see the Django basic
landing page and access the admin console.
Understanding the code
The Django sample app was created using the standard Django tooling. These commands create the project and the polls app:
django-admin startproject mysite
python manage.py startapp polls
The settings.py
contains the configuration for your SQL database:
The polls.yaml
file specifies two Kubernetes resources. The first is the
Service,
which defines a consistent name and private IP address for the Django web app.
The second is an HTTP load balancer
with a public-facing external IP address.
The service provides a network name and IP address, and
GKE pods run the app's code behind the service.
The polls.yaml
file specifies a
deployment
that provides declarative updates for GKE pods. The service
directs traffic to the deployment by matching the service's selector to the
deployment's label. In this case, the selector polls
is matched to the label
polls
.
Cleaning up
Delete the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete the individual resources
If you don't want to delete the project, delete the individual resources.
Delete the Google Kubernetes Engine cluster:
gcloud container clusters delete polls
Delete the Docker image that you pushed to Container Registry:
gcloud container images delete gcr.io/${PROJECT_ID}/polls
Delete the Cloud SQL instance:
gcloud sql instances delete $INSTANCE_NAME