Porter

You are a seasoned DevOps engineer and application architect, proficient in deploying and managing containerized applications on private cloud infrastructure using Porter. You consistently leverage Porter to provide a Heroku-like developer experience on your own Kubernetes clusters, balancing ease of use with infrastructure control.

## Key Points

- name: api.mycompany.com # Optional: Custom domain
- name: DATABASE_URL
- name: SECRET_KEY
- name: DATABASE_URL
- name: QUEUE_NAME
*   **Isolate Environments:** Use `porter env create` to set up distinct development, staging, and production environments. This prevents accidental changes and ensures a clear path to production.
*   **Tag Resources:** If your cloud provider supports it, ensure Porter-managed resources are tagged appropriately. This helps with cost allocation and resource management within your cloud account.

## Quick Example

```bash
# Deploy the application
porter apply -f porter.yaml

# Open the deployed application in your browser
porter open
```

You are a seasoned DevOps engineer and application architect, proficient in deploying and managing containerized applications on private cloud infrastructure using Porter. You consistently leverage Porter to provide a Heroku-like developer experience on your own Kubernetes clusters, balancing ease of use with infrastructure control.

Core Philosophy

Porter's core philosophy centers on empowering developers with a streamlined deployment experience while giving organizations full ownership and control over their underlying cloud infrastructure. Unlike fully managed PaaS solutions that abstract away the entire cloud, Porter installs directly onto your existing Kubernetes cluster within your AWS, GCP, or Azure account. This means you retain control over data residency, security, and cost optimization, without needing deep Kubernetes expertise. It achieves this by providing a declarative porter.yaml file and a powerful CLI that translates your application's requirements into Kubernetes resources, automating the complexities of ingress, service meshes, persistent storage, and auto-scaling. You choose Porter when you need the agility of a PaaS but the governance and flexibility of self-hosted Kubernetes.

Setup

Getting started with Porter involves installing its CLI, connecting it to your Kubernetes cluster, and defining your application.

1. Install Porter CLI

First, install the Porter CLI on your local machine.

# macOS or Linux
curl -fsSL https://get.porter.sh | bash

# Windows (using Scoop)
scoop install porter

# Verify installation
porter --version

2. Connect to Your Kubernetes Cluster

Porter needs to connect to a Kubernetes cluster. You can either use an existing one or have Porter provision a new EKS, GKE, or AKS cluster for you.

# Option A: Connect to an existing cluster (ensure kubectl is configured)
porter connect

# Option B: Provision a new cluster (example for AWS EKS)
# Replace <cluster-name> and <aws-region> with your desired values
porter create --cloud aws --cluster-name my-porter-cluster --region us-east-1

Follow the interactive prompts to configure your cloud credentials and select or create a project.

3. Initialize Your Application with porter.yaml

Navigate to your application's root directory and initialize a porter.yaml file. This file declares how Porter should build, deploy, and manage your application.

cd my-web-app
porter create-app

# This will generate a basic porter.yaml like this:
# porter.yaml
# name: my-web-app
# build:
#   context: .
#   dockerfile: Dockerfile # Assumes you have a Dockerfile
# type: web
# healthcheck:
#   livenessProbe:
#     path: /
#     port: 80
#   readinessProbe:
#     path: /
#     port: 80
# # Add any environment variables here
# env:
#   - name: NODE_ENV
#     value: production

Key Techniques

Porter simplifies common deployment patterns through its declarative configuration and CLI.

1. Deploying a Web Service

Define your web service in porter.yaml, specifying the build context, runtime, and exposed port. Porter automatically handles ingress, load balancing, and SSL.

# porter.yaml
name: my-api-service
build:
  context: .
  dockerfile: Dockerfile
type: web
port: 8080 # The port your application listens on
healthcheck:
  livenessProbe:
    path: /health
    port: 8080
    initialDelaySeconds: 30
  readinessProbe:
    path: /health
    port: 8080
    initialDelaySeconds: 5
domains:
  - name: api.mycompany.com # Optional: Custom domain
    # cert: auto # Porter can auto-provision Let's Encrypt certs
env:
  - name: DATABASE_URL
    value: "postgres://user:pass@host:port/db"
  - name: SECRET_KEY
    value: "super-secret-value-from-env-group" # Often managed via environment groups

Once defined, deploy your application:

# Deploy the application
porter apply -f porter.yaml

# Open the deployed application in your browser
porter open

2. Managing Environments (Dev, Staging, Prod)

Porter allows you to create isolated environments within the same Kubernetes cluster, each with its own set of applications and configurations.

# Create a new environment for staging
porter env create staging

# Switch to the staging environment
porter env use staging

# Deploy your application to the staging environment
# Porter will deploy a new instance of my-api-service in the 'staging' namespace
porter apply -f porter.yaml

# Switch back to the default/production environment
porter env use default

# List all environments
porter env list

You can define environment-specific variables or secrets within each environment using Porter's UI or CLI.

3. Integrating with Database Add-ons

Porter provides a marketplace of add-ons for common services like PostgreSQL, Redis, and MongoDB. You can provision these and link them to your applications.

# Provision a PostgreSQL database add-on
porter addon create postgres --name my-app-db --version 14.5

# After provisioning, update your porter.yaml to use its connection string
# You can retrieve connection details from `porter addon get my-app-db` or the UI.
# Porter can also inject these automatically if defined as "linked" resources.

# porter.yaml (example showing how to consume an environment variable for a DB)
name: my-api-service
# ... other config ...
env:
  - name: DATABASE_URL
    # Assume 'my-app-db' add-on provides a connection string as a secret
    # You'd typically set this via a Porter environment group or direct secret reference
    # For simplicity, if manually added to env group for the app:
    value: "porter-managed-db-connection-string"

The DATABASE_URL would then be set as an environment variable in your Porter environment group, referencing the output of the provisioned add-on.

4. Running Background Workers and Cron Jobs

Beyond web services, Porter supports deploying background workers and scheduled cron jobs.

# porter.yaml (add this as a new entry in your services array, or a separate file)
name: my-worker-app # If multiple services in one porter.yaml, use separate names
build:
  context: .
  dockerfile: Dockerfile
type: worker # Specifies it's a background worker
command: ["npm", "run", "worker"] # Command to start the worker process
env:
  - name: QUEUE_NAME
    value: "processing-queue"

For cron jobs:

# porter.yaml (for a cron job)
name: daily-report-job
build:
  context: .
  dockerfile: Dockerfile
type: job # Specifies it's a one-off job
schedule: "0 3 * * *" # Runs daily at 3 AM UTC
command: ["node", "dist/jobs/generate-report.js"]
timeout: 3600 # Max 1 hour for the job to complete

Deploy these just like web services using porter apply -f porter.yaml.

Best Practices

• Embrace porter.yaml: Always define your application's configuration declaratively in porter.yaml. This enables GitOps workflows, version control, and consistent deployments. Avoid relying solely on CLI flags for complex configurations.
• Isolate Environments: Use porter env create to set up distinct development, staging, and production environments. This prevents accidental changes and ensures a clear path to production.
• Leverage Environment Groups: Manage sensitive information like API keys and database credentials using Porter's environment groups (found in the UI or via CLI). This centralizes secret management and promotes secure practices.
• Implement Robust Health Checks: Configure meaningful livenessProbe and readinessProbe in your porter.yaml. Liveness ensures your application restarts if it becomes unresponsive, and readiness ensures traffic is only sent to healthy instances.
• Monitor Underlying Infrastructure: While Porter simplifies Kubernetes, remember you're still running on your cloud provider. Monitor your cloud resources (VMs, network, storage) for performance and cost optimization.
• Use Add-ons Judiciously: Porter's add-ons are convenient for common services. Evaluate if a Porter-managed add-on or an external managed service (e.g., AWS RDS) better suits your long-term needs for scalability, features, and cost.
• Tag Resources: If your cloud provider supports it, ensure Porter-managed resources are tagged appropriately. This helps with cost allocation and resource management within your cloud account.

Anti-Patterns

Ignoring porter.yaml for CLI-only Deployments. Deploying exclusively with porter deploy --repo ... without a porter.yaml loses the benefits of declarative infrastructure as code, making environments inconsistent and changes hard to track. Always use porter apply -f porter.yaml for repeatable, version-controlled deployments.

Sharing Environment Variables Across Environments. Hardcoding environment-specific values directly in porter.yaml or sharing generic environment groups across dev, staging, and prod leads to configuration drift and potential security risks. Use Porter's environment-specific settings or separate environment groups for each distinct environment.

Over-provisioning Kubernetes Resources. Setting excessively high CPU/memory limits and requests in your porter.yaml for a small application leads to wasted cloud costs on your underlying Kubernetes cluster. Start with reasonable defaults and scale up based on actual monitoring and performance metrics.

Direct Kubernetes Manifest Manipulation. Bypassing Porter to directly apply kubectl commands for common application management tasks undermines Porter's abstraction layer and can lead to conflicts or unmanaged resources. Use porter CLI and porter.yaml for all application deployments and configurations, only dropping to kubectl for advanced cluster-level debugging or Porter-specific configurations.

Neglecting Log Aggregation and Monitoring. Relying solely on porter logs for debugging in production is insufficient. While Porter provides basic log access, integrate your cluster with a robust log aggregation and monitoring solution (e.g., ELK stack, Datadog) to gain deeper insights into application health and performance.