Python + Poetry REST API with FastAPI, hosted on GCP
This template will get you ready to deploy a FastAPI app in Google Cloud with automatic API versioning by major release version and automatic custom domain mapping.
Major tags maintain separate API services in Cloud Run. For example, if my custom domain is
api.k2bd.dev, running the release GitHub action to create version
v2.3.4 will update the
v2 tag and automatically (re)-deploy to the
v2.api.k2bd.dev service with the released code. The
v1 service is unaffected, and there’s no need to keep
v1-compatible code around in the default branch of your repo after bumping to
v1 versions can be pushed separately to update that version using whatever workflow you want that produces a new
v1.*.* semver tag, for example for bugfixes that affect the previous version. This keeps the maintenance cost of the code low while also ensuring old versions of the API are live and available to clients until they’re migrated to the newer versions.
Getting started from the template
- Rename the
- Globally replace (case-sensitive) instances of
GCP_FASTAPI_POETRYwith your project and package name (including later in this list).
- Set your repo up on CodeCov and add a codecov token to your repo under the
- Create a new repo-scoped personal access token and add it as a
DEPLOY_TOKENrepo secret. This is so we can maintain major version tags.
- Change your Cloud Run configuration in
cloudbuild.yamlas appropriate. By default, it will deploy an API that can be invoked with no authentication.
- Configure a Cloud Build trigger in your GCP project to deploy from
cloudbuild.yamlon a new tag that matches the regex
^(v(\d+))$, with a substituion variable
_GCP_FASTAPI_POETRY_API_DOMAINpointing to the (sub)-domain you want to host the API on. Make sure the cloudbuild service account has the required permissions (Cloud Build settings –> enable Cloud Run, Service Accounts, and Cloud Build) and is registered as an owner of your custom domain if required.
LICENSE.mdas appropriate, making sure to retain the original copyright and permissions notices in your distribution according to the MIT license that this template is distributed under.
- Create and test your API. Your app under
gcp_fastapi_poetry.api:appwill be hosted on CloudRun when it’s deployed.
- When you’re ready to release the first version, run the release GitHub action with the “major” option to deploy
v1of your API! (or minor/patch to deploy
- Remove this section from
- Happy hacking!
Like this template?
Install Poetry and
poetry install the project
Note: if Poetry is managing a virtual environment for you, you may need to use
poetry run poe instead of
poe autoformat– Autoformat code
poe lint– Linting
poe test– Run Tests
poe local-server– Run your API locally
Release a new version by manually running the release action on GitHub with a ‘major’, ‘minor’, or ‘patch’ version bump selected. This will create an push a new semver tag of the format
v1.2.3, and also update the appropriate major version tag (
Updating the major version tags will cause Cloud Build to create or update that version’s deployment automatically and host it at e.g.
v1.(your configured domain). You may need to configure your domain’s DNS if you’re creating an endpoint for a new major version and you use an external provider. See the domain mappings page linked here for instructions.