feat: add addon docs

addons/custom-helm-charts.mdx

@@ -0,0 +1,166 @@
+---
+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.
+
+<Steps>
+  <Step title="Select Helm Chart addon">
+    Navigate to **Add-ons** in your Porter dashboard and select **Helm Chart**.
+  </Step>
+  <Step title="Configure the chart">
+    Enter the Helm repository URL and select the chart you want to deploy.
+  </Step>
+  <Step title="Select version">
+    Choose the chart version you want to install.
+  </Step>
+  <Step title="Customize values (optional)">
+    Modify any values from the chart's default configuration as needed.
+  </Step>
+  <Step title="Deploy">
+    Click **Deploy** to install the chart to your cluster.
+  </Step>
+</Steps>
+
+<Info>
+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.
+</Info>
+
+### 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. Run:
+   ```bash
+   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
+
+```bash
+# Add the Helm repository
+helm repo add <repo-name> <repo-url>
+helm repo update
+
+# Install the chart:
+porter helm -- install <release-name> <repo-name>/<chart-name> \
+  --namespace <namespace> \
+  --values values.yaml
+```
+
+### Example: Installing NGINX Ingress
+
+```bash
+# Add the ingress-nginx repository
+porter helm -- repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
+porter helm -- repo update
+
+# Install the chart
+porter helm -- install my-ingress ingress-nginx/ingress-nginx \
+  --namespace ingress \
+  --create-namespace
+```
+
+### Upgrading a release
+
+```bash
+porter helm -- upgrade <release-name> <repo-name>/<chart-name> \
+  --namespace <namespace> \
+  --values values.yaml
+```
+
+### Listing releases
+
+```bash
+porter helm -- list --all-namespaces
+```
+
+### Uninstalling a release
+
+```bash
+porter helm -- uninstall <release-name> --namespace <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.
+
+---
+
+## Best Practices
+
+### Use version pinning
+
+Always specify a chart version to ensure reproducible deployments:
+
+```bash
+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. 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
+replicaCount: 3
+resources:
+  limits:
+    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
+
+Before deploying to production, test custom charts in a development or staging cluster to verify compatibility with your Porter environment.
+

addons/datastores.mdx

@@ -0,0 +1,198 @@
+---
+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.
+
+<Info>
+Datastores are currently supported on **AWS only**. GCP and Azure datastore support is on the roadmap.
+</Info>
+
+## AWS Architecture
+
+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 flows exclusively through private subnets
+
+This architecture keeps your database secure and accessible only from applications running in your cluster.
+
+---
+
+## Setup
+
+<Steps>
+  <Step title="Create a datastore">
+    Navigate to **Add-ons** in your Porter dashboard and select the datastore type you want to create (Postgres or Redis).
+  </Step>
+  <Step title="Configure settings">
+    Configure your datastore settings including instance size, storage, and high availability options.
+  </Step>
+  <Step title="Connect to your application">
+    Porter creates an environment group with the connection details. Inject this environment group into your applications.
+  </Step>
+  <Step title="Deploy">
+    Deploy your application. It can now connect to the database using the injected environment variables.
+  </Step>
+</Steps>
+
+### 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 <port> -U <username> -l
+```
+
+<Info>
+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.
+</Info>
+
+---
+
+## 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 (Multi-AZ)** | Auto-scaling storage and enhanced failover | Production workloads with stringent high-availability requirements |
+
+### 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
+
+### 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
+
+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
+
+---
+
+## 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.
+
+### 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.
+
+<Steps>
+  <Step title="Enable">
+  Create a new datastore in the dashboard. In the creation form, click on **"Enable snapshot restore"**
+  </Step>
+  <Step title="Confirm">
+    Select one of the available snapshots to restore or enter the id manually. Only snapshots in the same region as the database are listed.
+  </Step>
+  <Step title="Create">
+    Create the datastore. This will start the process of restoring the snapshot.
+  </Step>
+</Steps>
+
+### 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.
+
+<Steps>
+  <Step title="Enable">
+  Create a new datastore in the dashboard. In the creation form, click on **"Enable database cloning"**
+  </Step>
+  <Step title="Confirm">
+    Select one of the existing Aurora clusters or enter the identifier manually. Only clusters in the same region as the selected one are listed.
+  </Step>
+  <Step title="Create">
+    Create the datastore. This will start the process of cloning the cluster.
+  </Step>
+</Steps>
+
+---
+
+## 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.
+
+## 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