This topic tells you how to use the Tanzu Python Buildpack.

The Tanzu Python Buildpack supports several popular configurations for Python apps.

Specifying a Python Version

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 may 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.

Building from a Function

The Tanzu Python Function Buildpack that provides a Python function invoker application for executing functions.

Behavior

This buildpack will participate if any of the following conditions are met:

  • A buildpack configuration variable BP_FUNCTION is explicitly set.
  • A file with the name func.yaml is detected.

The buildpack will do the following if detection passed:

  • Request for a Python runtime to be installed to a layer marked build and launch
  • Request for a pip to be installed to a layer marked build
  • Contributes the Python function invoker application to a layer marked launch
  • Contributes environment variables defined in func.yaml to the launch layer
  • Contributes a validation layer which is used to determine if the function is properly defined

Getting Started

To get started you'll need to create a directory where your function will be defined.

From within this directory we 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.
    • If you want to use a different name for the file. See configuration or func.yaml.
    • This file should contain the function to invoke when we receive an event.
    • The function can handle http requests:
  • 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.
  • func.yaml (optional): This is the configuration used to configure your function.
    • The python module and function name can be modified here by defining some environment variables in the envs section.
    • NOTE: The environment variables here (namely MODULE_NAME and FUNCTION_NAME will be overriden by the values specified by BP_FUNCTION)

Accepted Function Parameters

The function handles either HTTP or CloudEvents based on the parameter's name and type. 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

Configuration

Environment Variable Description
$BP_FUNCTION Configure the function handler. Defaults to func.main.

Liveness / Readiness Endpoints

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.

Templates

If you want to quickly start writing your functions, take a look at the functions samples in the [application accelerators samples repo](vmware-tanzu/ application-accelerator-samples).

Package Management Options

With the Python CNB, there are four options available for package management depending on your application:

You can find specific information for each option below.

Package Management with Pip

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 buidpack 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. The supported versions can be found in the release notes.

Vendoring

In order to use the Python CNB offline, you may follow these steps 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.

Package Management with Pipenv

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 buidpack 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. The supported versions can be found 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 this section above.

Using Miniconda

Miniconda is a package management and environment management system supported by the Python buildpack. The builpack will create or update a conda environment from an environment.yml file or a package-list.txt file located at the root of the app source code.

Configuring a version of miniconda is not supported.

Vendoring

In order to use the Python CNB offline, you may follow these steps to vendor python packages in your app using miniconda.

Steps
  1. Be on a Linux machine with a case-sensitive filesystem
  2. Install conda build tools: conda install conda-build
  3. cd <conda-app>
  4. Create environment.yml file in the root of your app
  5. CONDA_PKGS_DIRS=vendor/noarch conda env create -f environment.yml -n <env_name>
  6. conda index vendor
  7. conda list -n <env_name> -e > package-list.txt
  8. Check-in environment.yml, vendor, and package-list.txt as part of your app

Using Poetry

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.

Access the Software Bill of Materials

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).

Example App build

How to use in TAP

This section demonstrate an example of using the buildpack on the Tanzu Application Platform (TAP).

Check out the Paketo samples repository for an example Pip app that can be built by the Python buildpack.

  1. 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.

  1. We'll now trigger an image build in the my-apps namespace by running:
tanzu apps workload apply --file workload.yaml --namespace my-apps
  1. You're done with build! You can view the result with:
tanzu apps workload get pip-sample --namespace my-apps

TBS

The Python buildpack is available in both the full and lite descriptors of TBS. Use kp image create to create an image resource. For more details, see Build Service Documentation

Pack

Please see the README page of Paketo Pip sample app here to see intstructions on building the sample app using pack.

Enable Process Reloading

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.

Using 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

Install a Custom CA Certificate

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 our configuration docs.

Override the Start Process Set by the Buildpack

Python buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of our configuration docs.

Set Environment Variables for App Launch Time

Python buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.

Add Custom Labels to the App Image

Python buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.

Buildpack-Set Environment Variables

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.

PYTHONPATH

The PYTHONPATH environment variable is used to add directories where python will look for modules.

  • Set by: CPython, Pip and Pipenv
  • Phases: 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.

PYTHONUSERBASE

The PYTHONUSERBASE environment variable is used to set the user base directory.

  • Set by: Pip Install and Pipenv Install
  • Phases: build and launch

The value of PYTHONUSERBASE is set to the location where these buildapcks install the application packages so that it can be consumed by the app source code.

Start Command

The Python CNB sets the default start command python. This starts the Python REPL (read-eval-print loop) at launch.

The Python CNB comes with support for Procfile that lets users set custom start commands easily.

check-circle-line exclamation-circle-line close-line
Scroll to top icon