From feb4fdfff5301198ccf4151c6782474fd5ef8fd0 Mon Sep 17 00:00:00 2001 From: Sophia Witt Date: Thu, 29 Jan 2026 17:42:14 -0800 Subject: [PATCH 1/7] feat: add addon docs --- addons/custom-helm-charts.mdx | 134 +++++++++++++++++++++++++++ addons/datastores.mdx | 126 +++++++++++++++++++++++++ addons/managed-addons.mdx | 46 +++++++++ addons/overview.mdx | 86 +++++++++++++++++ addons/storage.mdx | 97 +++++++++++++++++++ addons/third-party-observability.mdx | 53 +++++++++++ mint.json | 11 +++ 7 files changed, 553 insertions(+) create mode 100644 addons/custom-helm-charts.mdx create mode 100644 addons/datastores.mdx create mode 100644 addons/managed-addons.mdx create mode 100644 addons/overview.mdx create mode 100644 addons/storage.mdx create mode 100644 addons/third-party-observability.mdx diff --git a/addons/custom-helm-charts.mdx b/addons/custom-helm-charts.mdx new file mode 100644 index 0000000..490f422 --- /dev/null +++ b/addons/custom-helm-charts.mdx @@ -0,0 +1,134 @@ +--- +title: "Custom Helm Charts" +sidebarTitle: "Custom Helm Charts" +description: "Deploy external Helm charts for components not managed by Porter" +--- + +Sometimes you need to install external charts that are not managed by Porter. You can deploy custom Helm charts either through the Porter dashboard or directly via the Helm CLI. + +--- + +## Deploying via Porter + +Deploy Helm charts through the Porter dashboard for a managed experience with visibility into your deployments. + + + + Navigate to **Add-ons** in your Porter dashboard and select **Helm Chart**. + + + Enter the Helm repository URL and select the chart you want to deploy. + + + Choose the chart version you want to install. + + + Modify any values from the chart's default configuration as needed. + + + Click **Deploy** to install the chart to your cluster. + + + + +Since custom Helm charts install external components into your cluster, they fall outside of Porter's standard support. However, we'll do our best to help you troubleshoot issues. + + +### Managing deployed charts + +Once deployed, you can: +- View the chart status in the Add-ons tab +- Update values and redeploy +- Upgrade to newer chart versions +- Delete the chart when no longer needed + +--- + +## Deploying via Helm CLI + +For more control or CI/CD integration, you can deploy Helm charts directly using the Helm CLI. + +### Prerequisites + +1. Install the [Helm CLI](https://helm.sh/docs/intro/install/) +2. Configure kubectl to connect to your Porter cluster: + ```bash + porter cluster namespace + ``` + +### Deploying a chart + +```bash +# Add the Helm repository +helm repo add +helm repo update + +# Install the chart +helm install / \ + --namespace \ + --values values.yaml +``` + +### Example: Installing NGINX Ingress + +```bash +# Add the ingress-nginx repository +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update + +# Install the chart +helm install my-ingress ingress-nginx/ingress-nginx \ + --namespace ingress \ + --create-namespace +``` + +### Upgrading a release + +```bash +helm upgrade / \ + --namespace \ + --values values.yaml +``` + +### Listing releases + +```bash +helm list --all-namespaces +``` + +### Uninstalling a release + +```bash +helm uninstall --namespace +``` + + +--- + +## Best Practices + +### Use version pinning + +Always specify a chart version to ensure reproducible deployments: + +```bash +helm install my-release repo/chart --version 1.2.3 +``` + +### Store values in version control + +Keep your custom values files in version control alongside your application code: + +```yaml +# values.yaml +replicaCount: 3 +resources: + limits: + cpu: 100m + memory: 128Mi +``` + +### Test in non-production first + +Before deploying to production, test custom charts in a development or staging cluster to verify compatibility with your Porter environment. + diff --git a/addons/datastores.mdx b/addons/datastores.mdx new file mode 100644 index 0000000..f2ad6bd --- /dev/null +++ b/addons/datastores.mdx @@ -0,0 +1,126 @@ +--- +title: "Datastores" +sidebarTitle: "Datastores" +description: "Provision managed databases with automatic networking and security" +--- + +Porter simplifies database provisioning by automatically setting up all networking components between your cluster and Porter-provisioned databases. + + +Datastores are currently supported on **AWS only**. GCP and Azure datastore support is on the roadmap. + + +## Architecture + +Datastores are provisioned in a separate VPC from your cluster VPC. Porter automatically: + +- Peers the datastore VPC to your cluster VPC +- Configures subnets, routing tables, and security groups +- Ensures traffic travels exclusively through private subnets + +This architecture keeps your database secure and accessible only from applications running in your cluster. + +--- + +## Setup + + + + Navigate to **Add-ons** in your Porter dashboard and select the datastore type you want to create (Postgres or Redis). + + + Configure your datastore settings including instance size, storage, and high availability options. + + + Porter creates an environment group with the connection details. Inject this environment group into your applications. + + + Deploy your application. It can now connect to the database using the injected environment variables. + + + +### Connecting from your laptop + +To connect to a datastore from your local machine, use the Porter CLI: + +```bash +porter datastore connect my-datastore +psql -h localhost -p -U -l +``` + + +This requires [Tailscale VPN](/cloud-accounts/tailscale) to be configured for your cluster. + + +--- + +## Postgres + +Postgres datastores can be deployed in different configurations depending on your needs: + +| Configuration | Use Case | Recommended For | +|--------------|----------|-----------------| +| **In-cluster** | Quick setup for development | Dev/staging environments | +| **Single RDS instance (Multi-AZ)** | Standard managed database | Production workloads | +| **Aurora cluster** | Auto-scaling storage with enhanced HA | High-availability production | + +### In-cluster Postgres + +Deploys Postgres as a container within your cluster. This is the fastest way to get started but is **not recommended for production data**. + +### RDS Instance + +Provisions a standard Amazon RDS instance with Multi-AZ deployment for automatic failover. This is the recommended option for most production workloads. + +### Aurora Cluster + +Aurora provides: +- Automatic storage autoscaling +- Enhanced failover capabilities +- High availability settings + +You can create an Aurora datastore with a single instance or with an additional read replica. + +#### Read Replicas + +To enable a read replica, select the **HA toggle** when creating the datastore. + +With read replicas: +- The dashboard displays connection details for both primary and replica +- Modifications automatically failover the primary and promote the replica +- This ensures minimum downtime during operations + +--- + +## Redis + +Redis datastores can be provisioned in different configurations: + +| Configuration | Use Case | Recommended For | +|--------------|----------|-----------------| +| **In-cluster** | Quick setup for development | Dev/staging environments | +| **Elasticache replication group** | Managed cache with automatic failover | Production workloads | + +### In-cluster Redis + +Deploys Redis as a container within your cluster. This is the fastest way to get started but is **not recommended for production data**. + +### Elasticache Replication Group + +Provisions an Amazon Elasticache replication group with: +- Primary and reader replica by default +- Automatic failover if the primary fails +- Minimal downtime during modifications + +--- + +## Compliance + +If the compliance feature is enabled for your project, Porter automatically configures monitoring alarms for RDS and Aurora datastores: + +- CPU utilization alarms +- Memory utilization alarms +- Storage capacity alarms + +These alarms help ensure your databases remain healthy and within operational thresholds. + diff --git a/addons/managed-addons.mdx b/addons/managed-addons.mdx new file mode 100644 index 0000000..22801bb --- /dev/null +++ b/addons/managed-addons.mdx @@ -0,0 +1,46 @@ +--- +title: "Managed Add-ons" +sidebarTitle: "Managed Add-ons" +description: "Pre-configured add-ons managed by Porter" +--- + +Managed add-ons are pre-configured infrastructure components that Porter installs and maintains for you. These add-ons are automatically updated and monitored as part of your cluster. + +## System Add-ons + +Porter automatically installs and manages several system-level add-ons that are essential for cluster operation: + +| Add-on | Purpose | +|--------|---------| +| **Ingress Controller** | Routes external traffic to your services | +| **Certificate Manager** | Automatically provisions and renews TLS certificates | +| **Metrics Server** | Provides resource metrics for autoscaling | +| **Cluster Autoscaler** | Scales node groups based on workload demand | + +These add-ons are managed by Porter and do not require manual configuration. + +## Optional Managed Add-ons + +In addition to system add-ons, Porter offers optional managed add-ons that you can enable for your cluster: + +### Observability Stack + +Porter can deploy a managed observability stack including: +- Prometheus for metrics collection +- Grafana for dashboards and visualization + +### Logging + +Porter can configure centralized logging to aggregate logs from all your applications. + +## Viewing Managed Add-ons + +To view the managed add-ons installed on your cluster: + +1. Navigate to **Infrastructure** in your Porter dashboard +2. System add-ons are managed automatically and visible in the cluster configuration + + +Managed add-ons are updated during [cluster upgrades](/cloud-accounts/cluster-upgrades). Porter tests compatibility before rolling out updates. + + diff --git a/addons/overview.mdx b/addons/overview.mdx new file mode 100644 index 0000000..35570a2 --- /dev/null +++ b/addons/overview.mdx @@ -0,0 +1,86 @@ +--- +title: "Add-ons" +sidebarTitle: "Overview" +description: "Extend your Porter cluster with datastores, monitoring, and more" +--- + +Add-ons extend your Porter cluster with additional infrastructure components like databases, monitoring tools, persistent storage, and custom Helm charts. + +## Available Add-ons + +### Databases + +| Add-on | Description | +|--------|-------------| +| **Postgres** | An object-relational database system | +| **Redis** | An in-memory database that persists on disk | + +[Learn more about Datastores →](/addons/datastores) + +### Monitoring + +| Add-on | Description | +|--------|-------------| +| **Datadog** | Pipe logs, metrics, and APM data from your workloads | +| **New Relic** | Monitor your applications and infrastructure | +| **Grafana** | An open source analytics and monitoring tool | +| **langfuse** | An open source LLM engineering platform | +| **Helicone AI Gateway** | An open source AI gateway for LLM requests | + +[Learn more about Third-party Observability →](/addons/third-party-observability) + +### Logging + +| Add-on | Description | +|--------|-------------| +| **Mezmo** | A popular logging management system | + +### Analytics + +| Add-on | Description | +|--------|-------------| +| **Metabase** | An open source business intelligence tool | +| **Quivr** | Your second brain, empowered by generative AI | +| **n8n** | An open source workflow engine | + +### Storage + +| Add-on | Description | +|--------|-------------| +| **Persistent Disk** | A persistent disk that can be attached to apps for data storage | + +[Learn more about Storage →](/addons/storage) + +### Custom + +| Add-on | Description | +|--------|-------------| +| **Helm Chart** | Install any Helm chart from a public repository | + +[Learn more about Custom Helm Charts →](/addons/custom-helm-charts) + +--- + +## Cloud Provider Support + +| Add-on | AWS | GCP | Azure | +|--------|-----|-----|-------| +| **Datastores (Postgres, Redis)** | ✅ | Coming soon | Coming soon | +| **Monitoring & Analytics** | ✅ | ✅ | ✅ | +| **Custom Helm Charts** | ✅ | ✅ | ✅ | +| **Storage (Persistent Disk)** | ✅ | Coming soon | Coming soon | + +--- + +## Managing Add-ons + +Add-ons are managed through the **Add-ons** tab in your Porter dashboard. From there you can: + +- Create new add-ons +- View and modify existing add-on configurations +- Connect add-ons to your applications via environment groups +- Delete add-ons when no longer needed + + +Deleting an add-on may cause connected applications to lose access to the resource. Ensure you've migrated any data before deleting datastores or storage add-ons. + diff --git a/addons/storage.mdx b/addons/storage.mdx new file mode 100644 index 0000000..7d47cd2 --- /dev/null +++ b/addons/storage.mdx @@ -0,0 +1,97 @@ +--- +title: "Storage" +sidebarTitle: "Storage" +description: "Add persistent storage with shared disks for your applications" +--- + +Porter makes it easy to provision persistent storage that can be shared across multiple services. This is useful for read-intensive applications and workloads with low-latency read requirements. + + +Persistent storage is currently supported on **AWS only** (EFS). GCP and Azure storage support is on the roadmap. + + +--- + +## Persistent Disk (EFS) + +Amazon Elastic File System (EFS) provides a shared filesystem that multiple services can mount simultaneously. Any services mounting the disk can read and write to the same files. + +### Use Cases + +- **Shared file storage**: Multiple services need access to the same files +- **Read-intensive workloads**: Cache frequently accessed data on disk +- **Media processing**: Store uploaded files for processing by multiple workers +- **Machine learning**: Share model files across inference services + +### Setup + + + + Navigate to **Add-ons** in your Porter dashboard and create a **Persistent Disk** add-on. + + + Go to your application's **Services** tab, select the service, and navigate to **Advanced Settings**. + + Enable **Persistent disk**. + + + Enter the name of the persistent disk add-on you created. + + + Deploy your application. The disk will be mounted automatically. + + + +### Accessing the Disk + +Once configured, your service can access the shared disk at: + +``` +/data/efs/ +``` + +All services with the persistent disk enabled will have read and write access to this directory. + +### Example + +If you have two services (`api` and `worker`) both mounting the same persistent disk: + +- `api` writes a file to `/data/efs/api/uploads/image.png` +- `worker` can read the file from `/data/efs/api/uploads/image.png` + +--- + +## Best Practices + +### Use for appropriate workloads + +EFS is optimized for throughput rather than IOPS. It's best suited for: +- Large file reads and writes +- Shared access patterns +- Workloads that can tolerate slightly higher latency than local disk + +For high-IOPS workloads like databases, use [Datastores](/addons/datastores) instead. + +### Monitor storage usage + +Keep track of storage usage to avoid unexpected costs. EFS charges based on the amount of data stored. + +### Plan for data migration + +If you need to move data off EFS, plan your migration strategy before deleting the add-on. + +--- + +## Deleting a Persistent Disk + + +Deleting the persistent disk add-on will remove all mounts to the disk. Any applications will lose access to the files stored on the disk. + + +Before deleting: + +1. Migrate any important data to another storage location +2. Update your services to remove the persistent disk configuration +3. Redeploy affected services +4. Delete the persistent disk add-on + diff --git a/addons/third-party-observability.mdx b/addons/third-party-observability.mdx new file mode 100644 index 0000000..c5e597c --- /dev/null +++ b/addons/third-party-observability.mdx @@ -0,0 +1,53 @@ +--- +title: "Third-party Observability" +sidebarTitle: "Third-party Observability" +description: "Integrate external monitoring and observability platforms" +--- + +Porter integrates with popular observability platforms to provide application-level monitoring, logging, and alerting beyond the built-in cluster observability features. + +## Supported Platforms + + + + Full-stack monitoring with APM, logs, and infrastructure metrics + + + Application performance monitoring and alerting + + + Dashboards and visualization for metrics and logs + + + Open source LLM engineering platform for tracing and analytics + + + Open source AI gateway for LLM request monitoring + + + + +## What You Get + +Integrating a third-party observability platform provides: + +- **Application Performance Monitoring (APM)**: Trace requests across services +- **Log aggregation**: Centralized logging with search and filtering +- **Custom metrics**: Track business and application-specific metrics +- **Alerting**: Get notified when metrics exceed thresholds +- **Dashboards**: Visualize system health and performance trends + +## Comparison with Built-in Observability + +| Feature | Porter Built-in | Third-party Platforms | +|---------|----------------|----------------------| +| Pod status and metrics | ✅ | ✅ | +| Node metrics | ✅ | ✅ | +| Application logs | Basic | Advanced search and filtering | +| Distributed tracing | ❌ | ✅ | +| Custom dashboards | ❌ | ✅ | +| Alerting | ❌ | ✅ | +| Long-term retention | Limited | Configurable | + +For production workloads, we recommend integrating at least one third-party observability platform to get comprehensive visibility into your applications. + diff --git a/mint.json b/mint.json index 3f20507..f550970 100644 --- a/mint.json +++ b/mint.json @@ -116,6 +116,17 @@ } ] }, + { + "group": "Add-ons", + "pages": [ + "addons/overview", + "addons/datastores", + "addons/custom-helm-charts", + "addons/third-party-observability", + "addons/managed-addons", + "addons/storage" + ] + }, { "group": "Command Line Interface (CLI)", "pages": [ From aca2ed59cda2941c08732605bc74ff3915eacb81 Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 17:04:21 -0500 Subject: [PATCH 2/7] Add disaster recovery, and other fixes --- addons/datastores.mdx | 51 ++++++++++++++++++++++++---- addons/overview.mdx | 4 +-- addons/third-party-observability.mdx | 2 +- 3 files changed, 48 insertions(+), 9 deletions(-) diff --git a/addons/datastores.mdx b/addons/datastores.mdx index f2ad6bd..bc532e7 100644 --- a/addons/datastores.mdx +++ b/addons/datastores.mdx @@ -10,13 +10,13 @@ Porter simplifies database provisioning by automatically setting up all networki Datastores are currently supported on **AWS only**. GCP and Azure datastore support is on the roadmap. -## Architecture +## AWS Architecture -Datastores are provisioned in a separate VPC from your cluster VPC. Porter automatically: +Datastores are provisioned in a VPC that is separate from the VPC of your clusters. Porter automatically: - Peers the datastore VPC to your cluster VPC - Configures subnets, routing tables, and security groups -- Ensures traffic travels exclusively through private subnets +- Ensures traffic flows exclusively through private subnets This architecture keeps your database secure and accessible only from applications running in your cluster. @@ -49,7 +49,7 @@ psql -h localhost -p -U -l ``` -This requires [Tailscale VPN](/cloud-accounts/tailscale) to be configured for your cluster. +If your cluster control plane access is set to private, using this command requires [Tailscale VPN](/cloud-accounts/tailscale) to be configured for your cluster. --- @@ -62,7 +62,7 @@ Postgres datastores can be deployed in different configurations depending on you |--------------|----------|-----------------| | **In-cluster** | Quick setup for development | Dev/staging environments | | **Single RDS instance (Multi-AZ)** | Standard managed database | Production workloads | -| **Aurora cluster** | Auto-scaling storage with enhanced HA | High-availability production | +| **Aurora cluster (Multi-AZ)** | Auto-scaling storage and enhanced failover | Production workloads with stringent high-availability requirements | ### In-cluster Postgres @@ -114,6 +114,46 @@ Provisions an Amazon Elasticache replication group with: --- +## Disaster Recovery + +Porter supports some options for disaster recovery of RDS datastores. + +### Restoring from a snapshot + +You can restore a snapshot to a new datastore, and the datastore will be accessible from the applications running in your cluster. This can significantly +reduce the time to recovery during an emergency. + + + + Create a new datastore in the dashboard. In the creation form, click on **"Enable snapshot restore"** + + + Select one of the available snapshots to restore or enter the id manually. Only snapshots in the same region as the database are listed. + + + Create the datastore. This will start the process of restoring the snapshot. + + + +### Cloning an Aurora cluster + +Aurora clusters support cloning an existing cluster using fast-cloning. This process is faster than restoring from a snapshot, and can be used +to recover from an emergency, or to quickly create copies of your database for experiments. + + + + Create a new datastore in the dashboard. In the creation form, click on **"Enable database cloning"** + + + Select one of the existing Aurora clusters or enter the identifier manually. Only clusters in the same region as the selected one are listed. + + + Create the datastore. This will start the process of cloning the cluster. + + + +--- + ## Compliance If the compliance feature is enabled for your project, Porter automatically configures monitoring alarms for RDS and Aurora datastores: @@ -123,4 +163,3 @@ If the compliance feature is enabled for your project, Porter automatically conf - Storage capacity alarms These alarms help ensure your databases remain healthy and within operational thresholds. - diff --git a/addons/overview.mdx b/addons/overview.mdx index 35570a2..51ed7a0 100644 --- a/addons/overview.mdx +++ b/addons/overview.mdx @@ -13,7 +13,7 @@ Add-ons extend your Porter cluster with additional infrastructure components lik | Add-on | Description | |--------|-------------| | **Postgres** | An object-relational database system | -| **Redis** | An in-memory database that persists on disk | +| **Redis** | An in-memory key-value database | [Learn more about Datastores →](/addons/datastores) @@ -24,7 +24,7 @@ Add-ons extend your Porter cluster with additional infrastructure components lik | **Datadog** | Pipe logs, metrics, and APM data from your workloads | | **New Relic** | Monitor your applications and infrastructure | | **Grafana** | An open source analytics and monitoring tool | -| **langfuse** | An open source LLM engineering platform | +| **Langfuse** | An open source LLM engineering platform | | **Helicone AI Gateway** | An open source AI gateway for LLM requests | [Learn more about Third-party Observability →](/addons/third-party-observability) diff --git a/addons/third-party-observability.mdx b/addons/third-party-observability.mdx index c5e597c..30672f9 100644 --- a/addons/third-party-observability.mdx +++ b/addons/third-party-observability.mdx @@ -18,7 +18,7 @@ Porter integrates with popular observability platforms to provide application-le Dashboards and visualization for metrics and logs - + Open source LLM engineering platform for tracing and analytics From 0efdb99129a6a2bcf911a585c25f3e8a00339fec Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 18:17:46 -0500 Subject: [PATCH 3/7] Add datastore configuration chart, roadmap, and monitoring --- addons/datastores.mdx | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/addons/datastores.mdx b/addons/datastores.mdx index bc532e7..67dfc5d 100644 --- a/addons/datastores.mdx +++ b/addons/datastores.mdx @@ -90,6 +90,21 @@ With read replicas: - Modifications automatically failover the primary and promote the replica - This ensures minimum downtime during operations +### Configuration + +The following table outlines the configurable fields and behaviors for each datastore type during creation and updates: + +| Configuration | In-cluster | Standard RDS | Aurora | +| :--- | :--- | :--- | :--- | +| **Connected cluster** | Local (via K8s Service) | External (via VPC Peering) | External (via VPC Peering) | +| **Region** | Matches connected cluster | Matches connected cluster | Matches connected cluster | +| **Database name** | - | User-defined | User-defined | +| **Master username** | - | User-defined | User-defined | +| **Postgres version** | - | Postgres 12-18 | Postgres 12-18 | +| **Instance type** | CPU/RAM Limits | All RDS compatible instances | All Aurora compatible classes, excepts serverless | +| **Allocated storage** | **Fixed** (Cannot be modified) | **Modifiable** (Increase only) | **Managed** (Auto-scales) | +| **Snapshot restore** | - | From RDS snapshot | From Aurora snapshot | +| **Cloning** | - | - | Fast Database Cloning | --- ## Redis @@ -114,6 +129,17 @@ Provisions an Amazon Elasticache replication group with: --- +## Monitoring + +You can monitor the performance of your database from the Porter dashboard. Metrics are available in the "Metrics" tab when opening a datastore. +The metrics that are currently displayed are: + +- CPU utilization +- RAM utilization +- Storage capacity + +--- + ## Disaster Recovery Porter supports some options for disaster recovery of RDS datastores. @@ -163,3 +189,10 @@ If the compliance feature is enabled for your project, Porter automatically conf - Storage capacity alarms These alarms help ensure your databases remain healthy and within operational thresholds. + +## Roadmap + +The following features are not yet supported natively in Porter, but reach out to the support team for help setting them up. + +- Connection pooling +- External access to datastores From 8203b728c96b5c78119f1c1c25764a9aa47ac853 Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 18:28:01 -0500 Subject: [PATCH 4/7] Fix storage mount paths --- addons/storage.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/addons/storage.mdx b/addons/storage.mdx index 7d47cd2..e3db3f8 100644 --- a/addons/storage.mdx +++ b/addons/storage.mdx @@ -54,10 +54,10 @@ All services with the persistent disk enabled will have read and write access to ### Example -If you have two services (`api` and `worker`) both mounting the same persistent disk: +If you have two services (`api` and `worker`) both mounting the same persistent disk 'my-disk': -- `api` writes a file to `/data/efs/api/uploads/image.png` -- `worker` can read the file from `/data/efs/api/uploads/image.png` +- `api` writes a file to `/data/api/my-disk/uploads/image.png` +- `worker` can read the same file from `/data/worker/my-disk/image.png` --- From 9275eb9533b1b5ff5b29c4e5c04aae5b7b588a9b Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 18:41:43 -0500 Subject: [PATCH 5/7] Add custom helm chart instructions, fixes --- addons/custom-helm-charts.mdx | 47 ++++++++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 12 deletions(-) diff --git a/addons/custom-helm-charts.mdx b/addons/custom-helm-charts.mdx index 490f422..a6ca914 100644 --- a/addons/custom-helm-charts.mdx +++ b/addons/custom-helm-charts.mdx @@ -51,10 +51,12 @@ For more control or CI/CD integration, you can deploy Helm charts directly using ### Prerequisites 1. Install the [Helm CLI](https://helm.sh/docs/intro/install/) -2. Configure kubectl to connect to your Porter cluster: +2. Configure kubectl to connect to your Porter cluster. Run: ```bash - porter cluster namespace + porter config set-cluster ``` + And select the cluster from the dropdown. If there is only one + cluster in your project it will be automatically selected. ### Deploying a chart @@ -63,8 +65,8 @@ For more control or CI/CD integration, you can deploy Helm charts directly using helm repo add helm repo update -# Install the chart -helm install / \ +# Install the chart: +porter helm -- install / \ --namespace \ --values values.yaml ``` @@ -73,11 +75,11 @@ helm install / \ ```bash # Add the ingress-nginx repository -helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx -helm repo update +porter helm -- repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +porter helm -- repo update # Install the chart -helm install my-ingress ingress-nginx/ingress-nginx \ +porter helm -- install my-ingress ingress-nginx/ingress-nginx \ --namespace ingress \ --create-namespace ``` @@ -85,7 +87,7 @@ helm install my-ingress ingress-nginx/ingress-nginx \ ### Upgrading a release ```bash -helm upgrade / \ +porter helm -- upgrade / \ --namespace \ --values values.yaml ``` @@ -93,13 +95,13 @@ helm upgrade / \ ### Listing releases ```bash -helm list --all-namespaces +porter helm -- list --all-namespaces ``` ### Uninstalling a release ```bash -helm uninstall --namespace +porter helm -- uninstall --namespace ``` @@ -112,12 +114,23 @@ helm uninstall --namespace Always specify a chart version to ensure reproducible deployments: ```bash -helm install my-release repo/chart --version 1.2.3 +porter helm -- install my-release repo/chart --version 1.2.3 ``` ### Store values in version control -Keep your custom values files in version control alongside your application code: +Keep your custom values files in version control alongside your application code. For example, for the +"custom-chart" helm chart, you can keep the following structure: + +`porter-custom-helm-chart-addons/custom-chart/chart.yaml` + +```yaml +# chart.yaml +chartUrl: https://custom-chart-repo.com +version: 1.0.0 +``` + +`porter-custom-helm-chart-addons/custom-chart/values.yaml` ```yaml # values.yaml @@ -127,6 +140,16 @@ resources: cpu: 100m memory: 128Mi ``` +You can then use these values in CI to install the chart + +```bash +CHART_URL=$(yq e '.chartUrl' porter-custom-helm-chart-addons/custom-chart/chart.yaml) +VERSION=$(yq e '.version' porter-custom-helm-chart-addons/custom-chart/chart.yaml) + +porter helm -- install custom-chart $CHART_URL \ + --version $VERSION \ + --values porter-custom-helm-chart-addons/custom-chart/values.yaml +``` ### Test in non-production first From 21b188d73cf34a0de96be4748e4305baf143a179 Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 18:45:40 -0500 Subject: [PATCH 6/7] Add observability section --- addons/custom-helm-charts.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/addons/custom-helm-charts.mdx b/addons/custom-helm-charts.mdx index a6ca914..6ee897a 100644 --- a/addons/custom-helm-charts.mdx +++ b/addons/custom-helm-charts.mdx @@ -104,6 +104,15 @@ porter helm -- list --all-namespaces porter helm -- uninstall --namespace ``` +--- + +## Observability + +There is limited observability offered for third-party helm chart installations, consisting of logs available in the dashboard. + +For more complex scenarios, you can deploy a **Grafana** addon, which is already configured with the existing observability +stack deployed in the cluster. Grafana makes it possible to explore, query and build dashboard to monitor any charts or +workloads deployed in your cluster. --- From 05d361ed2e65bea7b52ef2976194d28268c33e6f Mon Sep 17 00:00:00 2001 From: Mauricio Araujo Date: Fri, 30 Jan 2026 18:47:50 -0500 Subject: [PATCH 7/7] Remove managed addons section --- addons/managed-addons.mdx | 46 --------------------------------------- mint.json | 1 - 2 files changed, 47 deletions(-) delete mode 100644 addons/managed-addons.mdx diff --git a/addons/managed-addons.mdx b/addons/managed-addons.mdx deleted file mode 100644 index 22801bb..0000000 --- a/addons/managed-addons.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Managed Add-ons" -sidebarTitle: "Managed Add-ons" -description: "Pre-configured add-ons managed by Porter" ---- - -Managed add-ons are pre-configured infrastructure components that Porter installs and maintains for you. These add-ons are automatically updated and monitored as part of your cluster. - -## System Add-ons - -Porter automatically installs and manages several system-level add-ons that are essential for cluster operation: - -| Add-on | Purpose | -|--------|---------| -| **Ingress Controller** | Routes external traffic to your services | -| **Certificate Manager** | Automatically provisions and renews TLS certificates | -| **Metrics Server** | Provides resource metrics for autoscaling | -| **Cluster Autoscaler** | Scales node groups based on workload demand | - -These add-ons are managed by Porter and do not require manual configuration. - -## Optional Managed Add-ons - -In addition to system add-ons, Porter offers optional managed add-ons that you can enable for your cluster: - -### Observability Stack - -Porter can deploy a managed observability stack including: -- Prometheus for metrics collection -- Grafana for dashboards and visualization - -### Logging - -Porter can configure centralized logging to aggregate logs from all your applications. - -## Viewing Managed Add-ons - -To view the managed add-ons installed on your cluster: - -1. Navigate to **Infrastructure** in your Porter dashboard -2. System add-ons are managed automatically and visible in the cluster configuration - - -Managed add-ons are updated during [cluster upgrades](/cloud-accounts/cluster-upgrades). Porter tests compatibility before rolling out updates. - - diff --git a/mint.json b/mint.json index f550970..d7b68c9 100644 --- a/mint.json +++ b/mint.json @@ -123,7 +123,6 @@ "addons/datastores", "addons/custom-helm-charts", "addons/third-party-observability", - "addons/managed-addons", "addons/storage" ] },