docs: add Cloud Run sample for Python (#884)

* docs: add Cloud Run sample for Python * chore: remove commented code * chore: add missing copyright header

Author: olavloite

samples/python/cloud-run/.dockerignore

@@ -0,0 +1,7 @@
+Dockerfile
+README.md
+*.pyc
+*.pyo
+*.pyd
+__pycache__
+.pytest_cache

samples/python/cloud-run/Dockerfile

@@ -0,0 +1,49 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Start with a Docker image that includes a JRE. This is needed for PGAdapter.
+FROM eclipse-temurin:17-jre AS jre
+
+# Use the official lightweight Python image.
+# https://hub.docker.com/_/python
+FROM python:3.11-slim
+
+# Copy the JRE into the Pyton image.
+ENV JAVA_HOME=/opt/java/openjdk
+COPY --from=jre $JAVA_HOME $JAVA_HOME
+ENV PATH="${JAVA_HOME}/bin:${PATH}"
+
+# Allow statements and log messages to immediately appear in the logs
+ENV PYTHONUNBUFFERED True
+
+# Copy local code to the container image.
+ENV APP_HOME /app
+WORKDIR $APP_HOME
+COPY . ./
+
+# Install production dependencies.
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Add the latest version of PGAdapter to the container.
+ADD https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz /pgadapter.tar.gz
+RUN mkdir /pgadapter
+RUN tar -xzf /pgadapter.tar.gz -C /pgadapter
+
+# Copy the startup script that will start both PGAdapter and the web service.
+COPY ./startup.sh /startup.sh
+RUN chmod +x /startup.sh
+
+# Set an ENTRYPOINT for the container.
+# The `startup.sh` file will start both PGAdapter and the web service.
+ENTRYPOINT ["/bin/bash", "/startup.sh"]

samples/python/cloud-run/README.md

@@ -0,0 +1,78 @@
+# PGAdapter Cloud Run Sample for Python
+
+This sample application shows how to build and deploy a Python application with PGAdapter to Google Cloud Run.
+
+## Build
+
+First build the Docker image locally and tag it. Replace the `IMAGE_URL` in the script with your own repository.
+Make sure that the repository that you are referencing exists.
+See https://cloud.google.com/artifact-registry/docs/repositories/create-repos for more information on how to set up
+Google Cloud artifact repositories.
+
+```shell
+export IMAGE_URL=my-location-docker.pkg.dev/my-project/my-repository/my-image:latest
+docker build . --tag $IMAGE_URL
+```
+
+Example: `export IMAGE_URL=europe-north1-docker.pkg.dev/my-project/sample-test/pgadapter-sample:latest`
+
+Test the Docker image locally:
+
+```shell
+docker run \
+ -p 8080:8080 \
+ -v /path/to/local_credentials.json:/credentials.json:ro \
+ --env GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \
+ --env SPANNER_PROJECT=my-project \
+ --env SPANNER_INSTANCE=my-instance \
+ --env SPANNER_DATABASE=my-database \
+ $IMAGE_URL
+```
+
+Verify that the connection to Cloud Spanner works correctly by opening a new shell and executing:
+
+```shell
+curl http://localhost:8080
+```
+
+## Deploying to Cloud Run
+
+Push the Docker image to Artifact Registry:
+
+```shell
+gcloud auth configure-docker
+docker push $IMAGE_URL
+```
+
+Then deploy the image as a service on Cloud Run:
+
+```shell
+export SERVICE=my-service
+gcloud run deploy $SERVICE \
+ --image $IMAGE_URL \
+ --update-env-vars SPANNER_PROJECT=my-project,SPANNER_INSTANCE=my-instance,SPANNER_DATABASE=my-database
+```
+
+__NOTE__: This example does not specify any credentials for PGAdapter when it is run on Cloud Run. This means that
+PGAdapter will use the default credentials that is used by Cloud Run. This is by default the default compute engine
+service account. See https://cloud.google.com/run/docs/securing/service-identity for more information on how service
+accounts work on Google Cloud Run.
+
+Test the service (replace URL with your actual service URL):
+
+```shell
+curl https://my-service-xyz.run.app
+```
+
+### Authenticated Cloud Run Service
+
+If your Cloud Run service requires authentication, then first add an IAM binding for your own account and include
+an authentication header with the request:
+
+```shell
+gcloud run services add-iam-policy-binding $SERVICE \
+ --member='user:your-email@gmail.com' \
+ --role='roles/run.invoker'
+curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" https://my-service-xyz.run.app
+```
+

samples/python/cloud-run/main.py

@@ -0,0 +1,32 @@
+import os
+import psycopg
+from flask import Flask
+
+project = os.environ['SPANNER_PROJECT']
+instance = os.environ['SPANNER_INSTANCE']
+database = os.environ['SPANNER_DATABASE']
+app = Flask(__name__)
+
+
+@app.route("/")
+def hello_world():
+ # Connect to Cloud Spanner using psycopg3.
+ # Note that we use the fully qualified database name to connect to the
+ # database, as the Dockerfile startup script starts PGAdapter without a
+ # default project or instance.
+ with psycopg.connect("host=localhost port={port} "
+ "dbname=projects/{project}/instances/{instance}/databases/{database} "
+ "sslmode=disable"
+ .format(port=5432,
+ project=project,
+ instance=instance,
+ database=database)) as conn:
+ conn.autocommit = True
+ with conn.cursor() as cur:
+ cur.execute("select 'Hello world!' as hello")
+ return "Greeting from Cloud Spanner PostgreSQL: {greeting}\n"\
+ .format(greeting=cur.fetchone()[0])
+
+
+if __name__ == "__main__":
+ app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

samples/python/cloud-run/requirements.txt

@@ -0,0 +1,3 @@
+psycopg[binary]~=3.1.9
+Flask==2.1.0
+gunicorn==20.1.0

samples/python/cloud-run/startup.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Run both PGAdapter and the web server when the Docker container is started.
+# Start PGAdapter in plain TCP only mode, that is:
+# 1. Do not specify any credentials. This will make sure PGAdapter picks the credentials from the current environment.
+# You must ensure that the service account that is used by Cloud Run is allowed to access the Cloud Spanner database
+# that your application is using.
+# 2. Do not specify any specific project, instance or database. This will require the application to specify a fully
+# qualified database name when connecting to PGAdapter.
+# 3. Set the Unix domain socket directory to the empty string to disable domain sockets. Domain sockets are not
+# supported on Cloud Run.
+
+# Start PGAdapter in the background.
+java -jar /pgadapter/pgadapter.jar -dir= &
+
+# Run the web service on container startup. Here we use the gunicorn
+# webserver, with one worker process and 8 threads.
+# For environments with multiple CPU cores, increase the number of workers
+# to be equal to the cores available.
+# Timeout is set to 0 to disable the timeouts of the workers to allow Cloud Run to handle instance scaling.
+port="${PORT:-8080}"
+exec gunicorn --bind ":$port" --workers 1 --threads 8 --timeout 0 main:app