Porter Documentation
Quickstart
What is a bundle

What is a bundle

Porter Key Concepts

For this quickstart, the main concepts that you will use include:

  • Bundle - A bundle is your application artifact, client tools, configuration and deployment logic packaged together.
  • Installation - An instance of a bundle installed to your system.
  • Tag - A reference to the bundle in an OCI registry that contains the registry, bundle name, and version, e.g. myregistry.com/mybundle:v1.0.
  • Registry - An OCI compliant artifact store. Many Docker registries are now OCI compliant and work with bundles, here’s a list of popular registries have been tested with Porter.

Understand a Bundle

Before using a bundle that you’ve found, you can view information about the bundle with porter explain. Use this command to see:

  • a description of the bundle
  • parameters and credentials used by the bundle
  • custom actions that you can run, for example viewing status or logs
  • outputs generated by the bundle
  • dependencies of the bundle
$ porter explain getporter/wordpress:v0.1.3
Name: wordpress
Description:
Version: 0.1.3

Credentials:
Name         Description   Required   Applies To
kubeconfig                 true       All Actions

Parameters:
Name                 Description   Type     Default               Required   Applies To
namespace                          string                         false      All Actions
wordpress-name                     string   porter-ci-wordpress   false      All Actions
wordpress-password                 string   <nil>                 true       install,upgrade

Actions:
Name   Description   Modifies Installation   Stateless
ping   ping          true                    false

Dependencies:
Alias   Reference
mysql   getporter/mysql:v0.1.3

Looking at a Bundle

When Porter creates a bundle it takes a user provided porter.yaml and generates a CNAB bundle.json that is added to the OCI image that is pushed to your container registry. To keep things easy on the eyes, we will be reviewing a porter.yaml.

schemaVersion: 1.0.0-alpha.1
name: examples/porter-hello
version: 0.2.0
description: "An example Porter configuration"
registry: ghcr.io/getporter

At the beginning of each bundle we specify the bundle schema version, the name of the bundle, the version of the bundle, a description and a registry.

parameters:
  - name: name
    type: string
    default: porter
    path: /cnab/app/foo/name.txt
    source:
      output: name

Parameters are will be used throughout the bundle and can even be set within the bundle! If you’d like to deep dive into parameters, and how they work, that is documented here.

outputs:
  - name: name
    path: /cnab/app/foo/name.txt

Outputs will take any outputs that occurred as a result of a Porter action and can store it in a variable or in a file!

mixins:
  - exec

install:
  - exec:
      description: "Install Hello World"
      command: ./helpers.sh
      arguments:
        - install

upgrade:
  - exec:
      description: "World 2.0"
      command: ./helpers.sh
      arguments:
        - upgrade

uninstall:
  - exec:
      description: "Uninstall Hello World"
      command: ./helpers.sh
      arguments:
        - uninstall

We come across the core of the bundle; mixins and actions. Porter Mixins are extensions that enable structured access to common functionality and integration of common DevOps tools.

Porter actions (install, upgrade, uninstall) are needed for every bundle - and specify the actions Porter will execute on those actions.

Take a peak at the entire porter.yaml file to see it all put together.

What is a bundle (expanded)

A bundle, as defined by the CNAB specification, is a standard packaging format for multi-component distributed applications. It allows packages to target different runtimes and architectures. It empowers application distributors to package applications for deployment on a wide variety of cloud platforms, providers, and services. Furthermore, it provides necessary capabilities for delivering multi-container applications in disconnected (airgapped) environments.

Next Steps

Create your own bundle, or learn more!

Parameters