DOCSEARCHbyAlgolia
Submit Docs

Lifecycle

repository·main·Indexed 42 days ago

https://github.com/buildpacks/lifecycle

A reference implementation of the Cloud Native Buildpacks (CNB) specification. It provides the orchestration logic for building, running, and rebasing container images, including core phases such as analyzer, detector, restorer, builder, and exporter.

Tokens
11K
Snippets
33
Records
52
Agent score
52%

What's inside Lifecycle

  2. Use Lifecycle for Build, Run, and Rebase operations

    main

    Lifecycle can be used at different granularities depending on whether you want to run individual phases or the entire orchestration.

    Build Operations

    You can run the full build process using the creator command, or execute individual phases manually:

    • analyzer: Reads metadata from the previous image and ensures registry access.
    • detector: Chooses buildpacks (via /bin/detect) and produces a build plan.
    • restorer: Restores layer metadata from the previous image and from the cache, and restores cached layers.
    • builder: Executes buildpacks (via /bin/build).
    • exporter: Creates an image and caches layers.
    • creator: Runs the five phases (analyzer, detector, restorer, builder, and exporter) in order.

    Run Operations

    • launcher: Invokes a chosen process within the container.

    Rebase Operations

    • rebaser: Creates a new image from a previous image using updated base layers.

  3. Verify and download the attached CycloneDX SBOM

    main

    A CycloneDX Software Bill of Materials (SBOM) is attached to the image and signed. You can verify the attachment and then download it using cosign (version 2.0.0+).

    cosign version # must be at least 2.0.0
cosign verify \
  --certificate-identity-regexp "https://github.com/buildpacks/lifecycle/.github/workflows/post-release.yml" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  -a tag=<tag> -attachment sbom \
  buildpacksio/lifecycle:<tag>
cosign download sbom buildpacksio/lifecycle:<tag>

  4. Set up the lifecycle development environment

    main

    To develop on the lifecycle project, you must install the following prerequisites based on your operating system:

    macOS

    • Git: Built-in
    • Go: brew install go
    • jq & yj: brew install jq yj
    • Make/Build Tools: xcode-select --install
    • Docker: Install Docker Desktop

    Windows

    • Git: choco install git -y and set git config --global core.autocrlf false
    • Go: choco install golang -y
    • jq & yj: choco install jq -y and go get github.com/sclevine/yj
    • Make/Build Tools: choco install cygwin make -y and add C:\tools\cygwin\bin to your system PATH
    • Docker: Install Docker Desktop

  5. Run lifecycle development tasks with Make

    main

    The project uses make to automate common development tasks. You can run all tasks at once or execute them individually.

    Run all tasks

    Creates archives for both Linux and Windows at out/.

    make all

    You can specify a custom version for the output archives by prepending LIFECYCLE_VERSION:

    LIFECYCLE_VERSION=1.2.3 make all

    Individual tasks

    TaskCommandDescription
    Testmake testFormats, vets, and runs tests.
    Generate Mocksmake generateGenerates Go mocks.
    Lint/Formatmake format lintFormats and lints code (run after make generate).
    Buildmake buildBuilds binaries to out/linux/lifecycle/ and out/windows/lifecycle/.
    Packagemake packageCreates .tgz archives from the built binaries.
    Cleanmake cleanRemoves the out/ directory.
    # Example: Building with a specific version
$ LIFECYCLE_VERSION=1.2.3 make all

# Example: Running tests
$ make test

# Example: Generating mocks and formatting
$ make generate
$ make format lint

  6. Test GitHub Actions workflows on a fork

    main

    The lifecycle release process uses a chain of GitHub actions (build, draft-release, and post-release). To test changes to these workflows, fork the buildpacks/lifecycle repository and run the release process end-to-end.

    Required Secrets for Forks:

    • DOCKER_PASSWORD (if not using ghcr.io)
    • DOCKER_USERNAME (if not using ghcr.io)

    You can use the tools/test-fork.sh script to update the source code to reflect the state of your fork by providing the registry repository name.

    ./tools/test-fork.sh <registry repo name>

  7. Verify the integrity of the lifecycle image

    main

    The lifecycle images are signed with cosign. To ensure the image has not been tampered with, verify the signature against the official GitHub Actions workflow identity. Ensure you are using cosign version 2.0.0 or later.

    cosign version # must be at least 2.0.0
cosign verify \
  --certificate-identity-regexp "https://github.com/buildpacks/lifecycle/.github/workflows/post-release.yml" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  buildpacksio/lifecycle:<tag>

  8. Configure Lifecycle Environment via Platform API

    main

    The lifecycle behavior is heavily influenced by platform inputs. A critical environment variable is CNB_PLATFORM_API.

    If CNB_PLATFORM_API is unset, the lifecycle will issue a warning and default to a specific version (defined by platform.DefaultPlatformAPI). It is highly recommended to set this variable to ensure stability and avoid breaking changes when the lifecycle tool is upgraded.

    Other inputs that affect the CLI execution include:

    • NoColor: If set, disables color output in the logs.
    • LogLevel: Sets the verbosity of the cmd.DefaultLogger.

  9. Descriptor schema for lifecycle.toml

    main

    The image tool reads a lifecycle.toml file from the provided lifecycle TGZ to extract metadata. The expected structure is:

    [lifecycle]
version = "0.21.20"

[apis.buildpack]
supported = ["v1"]
deprecated = []

[apis.platform]
supported = ["v1"]
deprecated = []

    This data is used to populate the image labels io.buildpacks.lifecycle.apis, io.buildpacks.lifecycle.version, and the legacy io.buildpacks.builder.metadata label.

  10. Skip vendor-specific registry keychains

    main

    If you are building a platform that manages credentials manually, you can prevent the lifecycle from automatically attempting to load vendor-specific keychain implementations. This can improve performance by avoiding unnecessary helper invocations based on the hosting environment or registries being accessed.

    Set the following environment variables to true to skip the respective keychain:

    • CNB_REGISTRY_AUTH_KEYCHAIN_SKIP_AMAZON: Skips the Amazon/AWS ECR credhelper.
    • CNB_REGISTRY_AUTH_KEYCHAIN_SKIP_AZURE: Skips the Microsoft/Azure ACR credhelper.
    # Example: Skip both Amazon and Azure keychains
export CNB_REGISTRY_AUTH_KEYCHAIN_SKIP_AMAZON=true
export CNB_REGISTRY_AUTH_KEYCHAIN_SKIP_AZURE=true

  11. Configure export modes: Remote, Daemon, or Layout

    main

    The exporter command determines how to create the output image based on the flags provided:

    1. Remote Export (Default): If neither --use-daemon nor --use-layout is specified, the exporter communicates directly with remote registries using the provided credentials.
    2. Daemon Export: Using the --use-daemon flag instructs the exporter to use a local Docker daemon to build and manage the image.
    3. Layout Export: Using the --use-layout flag instructs the exporter to write the image to an OCI layout directory specified by --layout-dir.

  12. Use SOURCE_DATE_EPOCH for reproducible builds

    main

    The exporter respects the SOURCE_DATE_EPOCH environment variable to set the creation timestamp of the image. This is useful for achieving reproducible builds. If the variable is set to a valid Unix timestamp, it will be used instead of the current system time.

    export SOURCE_DATE_EPOCH=1694736000
lifecycle exporter my-app:latest ...