DOCSEARCHbyAlgolia
Submit Docs

Porter Documentation

repository·main·Indexed 23 days ago

https://github.com/getporter/porter

Porter is a tool for packaging applications and their deployment logic into single-command installers following the Cloud Native Application Bundle (CNAB) specification. It utilizes mixins for platform support (including Kubernetes, Helm, AWS, Azure, and Docker) and plugins for external secret and data management. The tool provides a CLI for building, linting, publishing, and archiving bundles, as well as a Porter agent for environments with mounted configuration volumes.

Tokens
195K
Snippets
505
Records
889
Agent score
78%

What's inside Porter

  1. What is Porter?

    main
    Porter is a deployment tool that glues together command-line tools, configuration files, secrets, bash scripts, and applications into a single, versioned bundle. These bundles are distributed as standard OCI registries or plain .tgz files. This allows users to install applications without needing deep knowledge of the underlying deployment process or tech stack.

  3. Summary of Porter Mixin Commands

    main

    When developing a Porter mixin, you must implement specific commands to ensure compatibility with the Porter lifecycle. Commands are categorized into Required (must be implemented or Porter will refuse to load the mixin) and Optional (recommended for better user experience).

    CommandRequirementContextPurpose
    buildRequiredLocal machine (porter build)Generates Dockerfile lines via stdout based on stdin config.
    schemaRequiredVarious (porter schema, build, run)Returns a JSON Schema for manifest validation and autocomplete.
    installRequiredInside bundle image (porter run)Performs installation; writes outputs to /cnab/app/porter/outputs/.
    upgradeRequiredInside bundle image (porter run)Performs upgrades; writes outputs to /cnab/app/porter/outputs/.
    uninstallRequiredInside bundle image (porter run)Performs uninstallation.
    versionRequiredLocal machine (porter build, mixins list)Returns mixin version info (supports --output json or plaintext).
    invokeOptionalInside bundle image (porter run)Handles custom actions defined in the bundle.

  5. Understand Porter core concepts and components

    main

    Porter is composed of several key abstractions used to define and manage infrastructure and application lifecycles. To build with Porter, you should understand the following core concepts:

    • Bundles: The primary unit of deployment in Porter.
    • Parameters: Variables used to customize bundle behavior.
    • Configuration: Settings that define how a bundle operates.
    • Credentials: Securely managed secrets and access keys required by bundles.
    • Desired State: The definition of how your infrastructure or application should look.
    • Bundle Images: The containerized environments where bundles execute.
    • Mixins: Reusable logic that can be shared across multiple bundles.
    • Plugins: Extensible components that add specific capabilities to the Porter ecosystem.
    • Mixins vs Plugins: Understanding the distinction between shared logic (Mixins) and extended functionality (Plugins).

  7. What is a Cloud Native Application Bundle (CNAB)?

    main

    A Cloud Native Application Bundle (CNAB) is an open-source packaging and distribution specification designed to manage distributed applications using a single installable file.

    It solves the gap between application code and the various tools (Terraform, Helm, bash scripts, etc.) required to deploy it. Instead of requiring users to manually install specific CLI versions or manage environment variables, a CNAB bundle abstracts these requirements into a single unit.

    Key components of a bundle include:

    • Application Images: The standard container images used by your application.
    • The Invocation Image (The Installer): A container that includes all necessary tools (e.g., Helm, Terraform), configuration, metadata, and the logic (scripts) to perform install, upgrade, and uninstall actions.
    • The Bundle Descriptor (bundle.json): A file containing the content digests for the invocation and application images, as well as definitions for accepted credentials, parameters, and expected outputs.

  8. What is a Porter Bundle and CNAB?

    main

    Porter is an implementation of the Cloud Native Application Bundle (CNAB) specification. A bundle acts as a "cloud installer" that packages an application along with its required infrastructure, binaries, and scripts into a single, distributable artifact (typically an OCI image).

    Key characteristics of bundles:

    • Self-contained: Includes everything from application charts (e.g., Helm) to client binaries (e.g., kubectl, terraform, gcloud) and installation scripts.
    • Infrastructure-aware: Can handle provisioning underlying resources (like an Azure MySQL database) and passing those credentials into the application installation steps.
    • Distributable: Bundles can be stored in any OCI-compliant registry (like DockerHub) and used in air-gapped networks.
    • Standardized: Porter builds CNAB-compliant bundles, allowing for interoperability with other CNAB-compliant tools.

  9. What is a Bundle and CNAB?

    main
    A Bundle is a packaging format for multi-component distributed applications based on the CNAB (Cloud Native Application Bundle) specification. A bundle contains everything required to install, upgrade, and uninstall an application, including the logic and tooling needed to manage its lifecycle. CNAB provides an open specification for packaging and distributing these applications consistently across different environments.

  10. What is a Porter Mixin

    main

    A Porter bundle consists of the Porter runtime and a porter.yaml manifest. While the runtime executes the bundle actions, the actual functionality (e.g., installing a Helm chart, running a bash command) is provided by mixins.

    How Mixins work:

    1. The Porter runtime reads a step definition from porter.yaml.
    2. Porter passes the relevant YAML section of that step to the mixin via standard input (stdin).
    3. The mixin processes the YAML and performs the action.
    4. The mixin writes any desired outputs to standard output (stdout) and returns control to the Porter runtime.
    mixins:
  - exec

name: hello
version: 0.1.0
registry: getporter

install:
  - exec:
      description: "Say Hello"
      command: bash
      flags:
        c: echo Hello World

  11. What is Porter and how do bundles work?

    main

    Porter is an implementation of the Cloud Native Application Bundle (CNAB) specification. It is used to create installers called bundles.

    A bundle packages together the logic required to install an application along with its necessary infrastructure and configuration. This allows you to provide a consistent installation experience to other teams or customers without requiring them to understand the underlying deployment tools or complex internal processes.

  12. What is a Porter bundle and how is it defined?

    main

    In Porter, a bundle is the unit of authoring and building. A bundle is defined by a porter.yaml manifest, which specifies the following components:

    • Parameters: Used to customize the bundle.
    • Credentials: Used to authenticate to services and resources.
    • Outputs: The results generated by the bundle.
    • Mixins: Tools installed into the bundle to facilitate interaction with external services (e.g., Kubernetes).
    • Actions: Steps to execute for specific lifecycle events like install, upgrade, or uninstall.