Porter | Back to home

 

QuickStart: Bundles

So you’re interested in learning more about Porter? Great! This guide will walk you through key concepts of managing bundles. You will use the porter CLI to install, upgrade, and uninstall the bundle.

Pre-requisites

Docker is a prerequisite for using Porter. Docker is used to package up the bundle.

If you do not have Docker installed, go ahead and get Docker.

Getting Porter

Next, you need Porter. Follow the Porter installation instructions.

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 --reference 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

For this quickstart we are going to use the hello world bundle which is a bit simpler:

$ porter explain --reference getporter/porter-hello:v0.1.0
Name: HELLO
Description: An example Porter configuration
Version: 0.1.0

Install a Bundle

To install a bundle, you use the porter install command.

porter install porter-hello --reference getporter/porter-hello:v0.1.0

In this example, you are installing the v0.1.0 version of the getporter/porter-hello bundle from its location in the default registry (Docker Hub) and setting the installation name to porter-hello.

List Bundle Installations

To see the list of bundle installations, use the porter list command.

$ porter list
NAME              CREATED          MODIFIED         LAST ACTION   LAST STATUS
porter-hello      21 minutes ago   21 minutes ago   install       succeeded

In this example, it shows the bundle metadata along with the creation time, modification time, the last action that was performed, and the status of the last action.

Show Installation Information

To see information about an installation, use the porter show command with the name of the installation.

$ porter show porter-hello
Name: hello
Bundle: getporter/porter-hello
Version: 0.1.1
Created: 2021-05-24
Modified: 2021-05-24

History:
------------------------------------------------------------------------
  Run ID                      Action   Timestamp   Status     Has Logs
------------------------------------------------------------------------
  01F1SVDSQDVKGC0VAABZE9ERQK  install  2021-03-27  failed     true
  01F1SVVRGSWG3FKY2ZATN4XTKC  install  2021-03-27  succeeded  true

Upgrade the Installation

To upgrade the resources managed by the bundle, use porter upgrade. Most bundles are written such that a specific version of the bundle corresponds to a specific version of an application. So to upgrade the application to a new version you need to specify a newer version of the bundle.

$ porter upgrade porter-hello --reference getporter/porter-hello:v0.1.1
upgrading porter-hello...
executing upgrade action from porter-hello (installation: porter-hello)
Upgrade Hello World
Upgraded to World 2.0
execution completed successfully!

Cleanup

To clean up the resources installed from the bundle, use the porter uninstall command.

porter uninstall porter-hello

Next Steps

In this QuickStart, you learned how to use some of the features of the porter CLI to explain a bundle, install and manage its lifecycle.