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.
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
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
For this quickstart we are going to use the hello world bundle which is a bit simpler:
$ porter explain ghcr.io/getporter/examples/porter-hello:v0.2.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 ghcr.io/getporter/examples/porter-hello:v0.2.0
In this example, you are installing the v0.1.0 version of the ghcr.io/getporter/examples/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: ghcr.io/getporter/examples/porter-hello Version: 0.2.0 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
Upgrade using a version tag
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 --version 0.2.0 upgrading porter-hello... executing upgrade action from porter-hello (installation: porter-hello) Upgrade Hello World Upgraded to World 2.0 execution completed successfully!
Upgrade using digest
When working in production environment, we highly recommend you to reference the bundle using its digest instead of tag. We used tags in our docs for simplicity, but tags can be overwritten which results in unexpected outcomes from upgrading an bundle. For deterministic and repeatable deployments, use digests instead of tags to ensure that you deploy exactly what you intended.
$ porter upgrade porter-hello --reference ghcr.io/getporter/examples/porter-hello@sha256:276b44be3f478b4c8d1f99c1925386d45a878a853f22436ece5589f32e9df384 _ upgrading porter-hello... executing upgrade action from porter-hello (installation: porter-hello) Upgrade Hello World Upgraded to World 2.0 execution completed successfully!
If you received an
invalid media type error like below, check that you are referencing the digest for the bundle and not the installer image.
unable to pull bundle: invalid media type "application/vnd.docker.distribution.manifest.v2+json" for bundle manifest
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.