Porter Documentation Organization

This document outlines a new structure for the porter docs website (https://porter.sh/docs). It identifies how the navigation should be grouped and what content we should include.

Goals:

• Have a consistent doc structure where we can keep adding items without exploding the nav menu
• Right now we focus heavily on reference pages. We need more concept and task pages.
• ? If something is reference/concept/task focused should it be in a a separate location? I was thinking of grouping by doc type, and then use the next steps on each page to cross link to relevant things. For example the concept page for parameters would also link to a task page for parameters, and the reference.

Getting Started

• Install Porter
• Install Porter Operator
• Install Porter Extension for VS Code
• Examples
• FAQ
  We need to redo the FAQ. It focuses on questions that are no longer relevant

QuickStart

This is a series of tutorials that will cover the basics of Porter. It's not exhaustive and will link to task tutorials to keep learning.

• Overview of Porter use cases
• Run a bundle
• with parameters
  • define
  • create parameter set, explain how they are helpful for team mgmt
  • set with flag, parameter sets
  • show what parameters were used when it last run
• with credentials
  • define
  • credential set, how to use for different individuals on a team
  • note that you can't see them from previous runs
  • set with credential set
• Run a custom action
• Use bundle outputs
• Next Steps:
  • QuickStart - Create a bundle
  • Concepts - What is a bundle

Contribute

• New Contributor Guide
• New Contributor Tutorial
• Contributing Guide
• Make a Proposal
• Community Meetings (interacting? encourage ways to give feedback)

Tasks

Break down tasks into groups based on role:

• end-user - someone running bundles
• admin - someone setting up an environment for shared use
• bundle author - creates and publishes bundles
• developers - creates and publishes mixins and plugins

End-Users

Set up Porter Environment

• Setup Storage Plugin
• Setup Secret Plugin

Manage Bundles

• re-link quickstart tutorials here

Understanding a bundle

• explain - how to use a bundle
• inspect - what is included in the bundle

Installation Lifecycle

• Install
• Upgrade
• Custom Actions
• Uninstall

Credential and Parameter Sets

• Secrets
• Reusing credentials (e.g. your cloud credentials)

Porter Operator

• Install
• Manage with OLM or bundles
• QuickStart
  • install the operator on a k8s cluster with k8s plugin
  • make a version of the whalesay bundle for k8s
  • run it with a parameter, message
  • view the logs
  • upgrade it
  • uninstall it
• Agent Config
• RBAC and Permissions

Authors

Setup your environment

• VS Code
• Install Mixins

Create a bundle

• run create, publish it somewhere, and install it

Author the bundles

• authoring bundles
• mixins
  • what does a mixin do? building blocks for authoring bundles, adapt between imperative cli usage and needs of a bundle.
  • default mixins shipped with porter
  • finding mixins
  • using a mixin with vs code's autocomplete
• using the exec mixin (best practice)

Validate your bundle

• Lint

Build your bundle

• CI pipeline with –version and –registry
• Best practices for porter in a ci pipeline

Publish your bundle

• Publish to a registry
• Managing application and bundle versions

Using Porter with Terraform

• remote backend
• local state storage
• initFile

Developers

Create a Mixin

• what can a mixin do?
• skeletor for Go
• use skeletor
• install a cli (whalesay)
• expose the cli
• add a custom command
• use mixin locally

Develop a Plugin

• what can a plugin do?
• plugin interfaces
• no skeletor so who is a good one to copy?

Distribute a Mixin/Plugin

• build requirements
• binary matrix
• how the URLs work
• atom feed vs github releses
• test out using the release

Promote your Mixin/Plugin

• how to list on packages repo so people can search for it
• listing on our website
• We are open to guest blog posts
• tweet and mention our twitter for a retweet
• email the mailing list
• porter channel in slack

Administrators

Using Porter with Kubernetes

Using Porter in a CI Pipeline

Porter Operator

• install
• quickstart
• Share credential and parameter sets
• Share porter configuration
• Customize porter agent
  • use a special agent or installation account
  • bump up the volume size
• Pointing porter at the cluster datastore

Concepts

CNAB Specification

• copy whatever I want from deislabs
• porter is an implementation
• purpose of spec is to be able to run bundles regardless of how it was made
• other implementations (internal at companies such as DataDog), duffle archived.

Bundles

• What they can contain and do?
  • types of bundles
  • who would use them
  • advantages of using a bundle even when using just a single tool like terraform or helm
• Actions (lifecycle)
• Parameters and Credentials
• Secrets Plugins
• Dependencies

Distribution

• Registry
• (eventually notary)

Installations

• Installation
• Lifecycle
• Run
• Logs
• Storage Plugins

Porter's Architecture

• plugins
• mixins
• drivers (build drivers, execution drivers)
• security (secret plugin, what data is available where, storage format)
• configuration

Porter Operator

• Infra as Code
• Git Ops
• not running one-off unaudited commands in production
• easier for a team to manage
• namespaces

Reference

• Configuration
• Published Artifacts
  • binaries
  • images
• CNAB Specification
• Porter Commands
  • overview page that links to resources
  • porter starting page
• File Formats
• Operator CRDs
• Logos
• Go Library
• Version Strategy

Troubleshooting