/buildpacks

Builders and buildpacks designed to run on Google Cloud's container platforms

Primary LanguageGoApache License 2.0Apache-2.0

Google Cloud Buildpacks

This repository contains a set of builders and buildpacks designed to run on Google Cloud's container platforms: Cloud Run, GKE, Anthos, App Engine, Cloud Functions, and Compute Engine runing Container-Optimized OS. They are 100% compatible with CNCF Buildbacks.

Quickstart

  1. Install Docker
  2. Install the pack tool (a CLI for running Buildpacks)
  3. Clone the sample apps: 
    git clone https://github.com/GoogleCloudPlatform/buildpack-samples.git
cd buildpack-samples
  4. Pick a sample and build it, for instance with sample-go: 
    cd sample-go
pack build --builder gcr.io/buildpacks/builder sample-go
  5. Run it with docker, like: 
    docker run --rm -p8080:8080 sample-go

See the Usage section for more details.

Concepts

To read more, see Buildpack project documentation.

  • Builder A container image that contains buildpacks and detection order in which builds are executed.
  • Buildpack An executable that "inspects your app source code and formulates a plan to build and run your application".
  • Buildpack Group Several buildpacks which together provide support for a specific language or framework.
  • Run Image The container image that serves as the base for the built application.

Generic Builder and Buildpacks

This is a general purpose builder that creates container images designed to run on most platforms (e.g. Kubernetes / Anthos, Knative / Cloud Run, Container OS, etc), and should be used by the majority of users. The builder attempts to autodetect the language of your source code, and can also build functions compatible with the Google Cloud Function Framework by setting the GOOGLE_FUNCTION_TARGET env var.

The generic builder is hosted at gcr.io/buildpacks/builder.

Supported languages include:

Runtime App Support Function Support
Go 1.10 + ✓ ✓
Node.js 10 + ✓ ✓
Python 3.7 + ✓ ✓
Java 8, 11 ✓
.Net 3 + ✓

App Engine and Cloud Function Builders and Buildpacks

These builders create container images designed to run on Google Cloud's App Engine and Functions services. Most of the buildpacks are identical to those in the generic builder.

Compared to the generic builder, there are two primary differences. First, there are additional buildpacks which add transformations specific to each service. Second, in order to optimize execution speed, each language has a seperate builder.

Usage

The Google Cloud Buildpacks project provides builder images suitable for use with pack, tekton, skaffold, and other tools that support the Buildpacks v3 specification.

Building an application

The following command invokes pack to apply the general builder to build the application in the current directory, and then containerizes the result into a local container image named <app-name>.

pack build <app-name> --builder gcr.io/buildpacks/builder

The application you built can then be executed locally:

docker run --rm -p8080:8080 <app-name>

You can set Cloud Buildpacks as your default:

pack set-default-builder gcr.io/buildpacks/builder

And you can publish the built image to the cloud directly with pack:

pack build <app-name> --publish gcr.io/YOUR_PROJECT_ID/APP_NAME

Extending the run image

If your application requires additional system packages to be installed and available when it runs, you can accomplish this by customizing the run container image.

cat > run.Dockerfile << EOF
FROM gcr.io/buildpacks/gcp/run
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
  imagemagick && \
  apt-get clean && \
  rm -rf /var/lib/apt/lists/*
USER cnb
EOF

docker build -t my-run-image -f run.Dockerfile .

To use the custom run image with pack:

pack build my-app --builder gcr.io/buildpacks/builder --run-image my-run-image

Extending the builder image

If you require certain packages for building your application, create a custom builder image based on the base builder:

cat > builder.Dockerfile << EOF
FROM gcr.io/buildpacks/builder
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
  subversion && \
  apt-get clean && \
  rm -rf /var/lib/apt/lists/*
USER cnb
EOF

docker build -t my-builder-image -f builder.Dockerfile .

To use the custom builder with pack:

pack build my-app --builder my-builder-image

Configuration

Google Cloud Buildpacks support configuration using a set of environment variables that are supported across runtimes.

  • GOOGLE_ENTRYPOINT
    • Specifies the command which is run when the container is executed; equivalent to entrypoint in a Dockerfile.
    • Example: gunicorn -p :8080 main:app for Python. java -jar target/myjar.jar for Java.
  • GOOGLE_FUNCTION_TARGET
    • For use with source code built around the Google Cloud Functions Framework. Specifies the name of the function to be invoked.
    • Example: myFunction will cause the Functions Framework to invoke the function of the same name.
  • GOOGLE_RUNTIME
    • If specified, forces the runtime to opt-in. If the runtime buildpack appears in multiple groups, the first group will be chosen, consistent with the buildpack specification. (only works with buildpacks which install language runtimes).
    • Example: nodejs will cause the nodejs/runtime buildpack to opt-in.
  • GOOGLE_RUNTIME_VERSION
    • If specified, overrides the runtime version to install. (only works with buildpacks which install language runtimes)
    • Example: 13.7.0 for Node.js, 1.14.1 for Go. 11.0.6+10 for Java.
  • GOOGLE_BUILDABLE
    • (only applicable to compiled languages) Specifies path to a buildable unit.
    • Example: ./maindir for Go will build the package rooted at maindir.
  • GOOGLE_DEVMODE
    • Enables the development mode buildpacks. This is used by Skaffold to enable live local development where changes to your source code trigger automatic container rebuilds. To use, install Skaffold and run skaffold dev.
    • Example: true, True, 1 will enable development mode.

Known Limitations

  • General:
    • Caching is project-specific, not cross-project. Dependencies, such as the JDK, cannot be shared across projects and need to be redownloaded on first build.
  • Java:
    • It is not possible to pass arguments to the maven command (for example, a specific Maven profile)
  • Node:
    • Custom build steps (e.g. executing the "build" script of package.json) are not supported.
    • Existing node_modules directory is deleted and dependencies reinstalled using package.json and a lockfile if present.
  • Go

    • (generic builder only) Applications without a go.mod cannot have sub-packages.

    • Go 1.14 triggers a kernel bug in some versions of the Linux kernel (versions other than 5.3.15+, 5.4.2+, or 5.5+). If using an affected version, please set the following in your /etc/docker/daemon.json:

      "default-ulimits": {
    "memlock": {
        "Name": "memlock",
        "Soft": -1,
        "Hard": -1
    }
},

Support

Please note that this project is not an officially supported Google product. Customers of Google Cloud can use standard support channels for help using buildpacks with Google Cloud Products.

Get involved with the community

We welcome contributions! Here's how you can contribute:

License

See LICENSE.