This topic tells you how to use the Tanzu Python Buildpack.
The Tanzu Python Buildpack supports several popular configurations for Python apps.
The Python CNB (Cloud Native Buildpack) allows you to specify a version of CPython 3 (reference implementation of Python 3) to use during deployment. This version can be specified via the BP_CPYTHON_VERSION
environment variable during build. When specifying a version of CPython, you must choose a version that is available within the buildpack. The supported versions can be found in the release notes.
You can set BP_CPYTHON_VERSION
using a platfrom-specific option, or using a project.toml
as shown in the following example:
[build]
[[build.env]]
name = "BP_CPYTHON_VERSION"
value = "3.6.*" # any valid semver constraints (e.g. 3.6.7, 3.*) are acceptable
Specifying a version of CPython is not required. In the case this is not specified, the buildpack will provide the default version, which can be seen in the buildpack.toml
file.
The Tanzu Python Function Buildpack that provides a Python function invoker application for executing functions.
This buildpack will participate if any of the following conditions are met:
BP_FUNCTION
is explicitly set.func.yaml
is detected.The buildpack will do the following if detection passed:
func.yaml
to the launch layer.To get started, create a directory where your function will be defined.
From within this directory, you require a few files to properly detect this as a Python function:
func.py
: This python module will be where we search for a function by default.
func.yaml
.requirements.txt
: This file is required by the Python dependency. It is used to define your function's dependencies. If you do not have any, you still need to provide an empty file.
(Optional) func.yaml
: This is the configuration used to configure your function.
envs
section.BP_FUNCTION
will override the environment variables MODULE_NAME
and FUNCTION_NAME
that you set here.The function handles either HTTP or CloudEvents based on the name and type of the parameters. Only the following arguments are accepted:
name | request type | description | details |
---|---|---|---|
event | CloudEvent | Entire CloudEvent object | event |
data | CloudEvent | Data portion of CloudEvent object | event.data |
payload | CloudEvent | Data portion of CloudEvent object | event.data |
attributes | CloudEvent | All CloudEvent keys and values as dictionary | |
req | HTTP | Entire HTTP request (flask) | request |
request | HTTP | Entire HTTP request (flask) | request |
body | HTTP | Body of HTTP request (flask) | request.get_data() |
headers | HTTP | HTTP request (flask) headers | request.headers |
Environment Variable | Description |
---|---|
$BP_FUNCTION | Configure the function handler. Defaults to func.main. |
The Python invoker has health endpoints exposed by healthz
. By default, the path is found at localhost:8080/healthz/live
or localhost:8080/healthz/ready
.
To quickly start writing your functions, see the functions samples in the Application Accelerator samples repo.
With the Python CNB, there are four options available for package management depending on your application:
You can find specific information for each option in the following sections.
Pip is a popular option for managing third-party application dependencies for Python apps. Including a valid requirements.txt
file at the root of your app source code triggers the Pip installation process by the buildpack. The buildpack will install the application packages and make it available to the app.
The buildpack allows you to configure the version of Pip to be used in the installation process. You can set this using the $BP_PIP_VERSION
variable during build. When specifying a version of Pip, you must choose a version that is available within the buildpack. You can find the supported versions in the release notes.
To use the Python CNB offline, run the following command to vendor Pip packages in your app using miniconda:
cd <pip-app>
pip download -r requirements.txt --no-binary=:none: --dest vendor --platform linux_x86_64 --no-deps
This downloads all dependencies to a directory named vendor
which the buildpack can use to perform offline installation.
Pipenv is another common option for managing dependencies. Including a valid Pipfile
file at the root of your app source code triggers the Pipenv installation process by the buildpack. The buildpack will install the application packages and make it available to the app.
The buildpack allows you to configure the version of Pipenv to be used in the installation process. You can set this using the $BP_PIPENV_VERSION
variable during build. When specifying a version of Pipenv, you must choose a version that is available within the buildpack. You can find the supported versions in the release notes.
The buildpack also takes into consideration the Python version requirement specified by Pipfile.lock
, but BP_CPYTHON_VERSION
takes precedence over this as discussed in Specify a Python Version earlier.
Miniconda is a package management and environment management system supported by the Python buildpack. The buildpack creates or updates a conda environment from an environment.yml
file or a package-list.txt
file located at the root of the app source code.
Configuring the version of miniconda is not supported.
To use the Python CNB offline, follow these steps to vendor Python packages in your app using miniconda:
Be on a Linux machine with a case-sensitive filesystem.
Install conda build tools by running:
conda install conda-build
Change into the directory for your app:
cd <conda-app>
Create environment.yml
file in the root of your app.
Run these commands:
CONDA_PKGS_DIRS=vendor/noarch conda env create -f environment.yml -n <env_name>
conda index vendor
conda list -n <env_name> -e > package-list.txt
Check-in environment.yml
, vendor
, and package-list.txt
as part of your app.
Poetry is a tool to manage both third-party application dependencies and virtual environments. Including a pyproject.toml
file at the root of your app source code triggers the poetry installation process. The buildpack will invoke poetry
to install the application dependencies defined in pyproject.toml
and set up a virtual environment.
The buildpack allows you to configure the version of Poetry to be used in the installation process. You can set this using the $BP_POETRY_VERSION
variable during build. When specifying a version of Poetry, you must choose a version that is available within the buildpack. The supported versions can be found in the release notes.
The Python buildpack includes support for Software Bill of Materials (SBOM). Check out the SBOM documentation for details on how to access the SBOM supplied by the buildpacks.
SBOMs will be generated for applications which leverage Pip
, Pipenv
, or Poetry
.
Currently the Python buildpack has limited support for generating an SBOM for applications which leverage Miniconda
. Specifically, in order to generate an SBOM for a Miniconda
application, applications must vendor their dependencies in addition to defining them via a package-list.txt
file. Miniconda
applications that declare their dependencies via a package-list.txt
file but do not vendor them will result in an empty SBOM. This is due to a limitation in the upstream SBOM generation library (Syft).
This section demonstrates an example using the buildpack on Tanzu Application Platform.
For an example Pip app that can be built by the Python buildpack, see the Paketo samples repository .
Create a workload.yaml
.
The following workload.yaml
builds the Paketo Pip sample App.
---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata:
labels:
app.kubernetes.io/part-of: pip-sample
apps.tanzu.vmware.com/has-tests: "true"
apps.tanzu.vmware.com/workload-type: web
name: pip-sample
spec:
params:
- name: ports
value:
- port: 80
containerPort: 8000 # gunicorn default port
name: http
source:
git:
ref:
branch: main
url: https://github.com/paketo-buildpacks/samples
subPath: python/pip
Where metadata.name
is the application name the workload is a part of, and spec.source.git
points to the remote source code.
Trigger an image build in the my-apps
namespace by running:
tanzu apps workload apply --file workload.yaml --namespace my-apps
After the build completes, you can view the result by running:
tanzu apps workload get pip-sample --namespace my-apps
The Python buildpack is available in both the full
and lite
descriptors of Tanzu Build Service. Use kp image create
to create an image resource. For more information, see the Tanzu Build Service documentation.
For instructions for how to build the sample app using pack, see the README for the Paketo Pip sample app.
watchexec is a tool that can watch files for changes and run a command whenever it detects modifications. The Python buildpack can install this tool in your app container so that you can restart your server process when files in the app's working directory change. This may facilitate a shorter feedback loop for iterating on code changes. This feature may be used in conjunction with a dev orchestrator like Tilt.
BP_LIVE_RELOAD_ENABLED
To enable reloadable processes, set the $BP_LIVE_RELOAD_ENABLED
environment variable at build time. For more details, see the Paketo documentation
Python buildpack users can provide their own CA certificates and have them included in the container root truststore at build-time and runtime by following the instructions outlined in the CA Certificates section of the configuration documentation.
Python buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of the configuration documentation.
Python buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variable Buildpack.
Python buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of the configuration documentation.
The Python CNB sets a few environment variables during the build
and launch
phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.
The PYTHONPATH environment variable is used to add directories where python will look for modules.
CPython
, Pip
and Pipenv
build
and launch
The CPython buildpack sets the PYTHONPATH
value to its installation location, and the Pip, Pipenv buildpack prepends their site-packages
location to it. site-packages
is the target directory where packages are installed to.
The PYTHONUSERBASE environment variable is used to set the user base directory.
Pip Install
and Pipenv Install
build
and launch
The value of PYTHONUSERBASE
is set to the location where these buildpacks install the application packages so that it can be consumed by the app source code.
The Python CNB sets the default start command python
. This starts the Python read-eval-print loop (REPL) at launch.
The Python CNB has support for Procfile that enables users to set custom start commands.