title | descriptions | layout |
---|---|---|
QuickStart Guide |
Get started using Porter |
single |
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.
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.
Next, you need Porter. Follow the Porter installation instructions.
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.
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
No outputs defined
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
No credentials defined
No parameters defined
No outputs defined
No custom actions defined
No dependencies defined
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 hello.
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.
To see information about an installation, use the porter show
command with the name of the installation.
$ porter show porter-hello
Name: porter-hello
Created: 2021-03-27
Modified: 2021-05-03
Outputs:
-------------------------------------------------------------------------------
Name Type Value
-------------------------------------------------------------------------------
io.cnab.outputs.invocationImageLogs string DEBUG: defaulting action
to CNAB_ACTION (install)
executi...
History:
------------------------------------------------------------------------
Run ID Action Timestamp Status Has Logs
------------------------------------------------------------------------
01F1SVDSQDVKGC0VAABZE9ERQK install 2021-03-27 failed true
01F1SVVRGSWG3FKY2ZATN4XTKC install 2021-03-27 succeeded true
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!
To clean up the resources installed from the bundle, use the porter uninstall
command.
porter uninstall porter-hello
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.