feat: Create new docs for autoscaling + connections

configure/autoscaling.mdx

@@ -4,6 +4,10 @@ title: "Autoscaling"
 
 Porter supports several autoscaling strategies for your web and worker services. This guide covers the available options and when to use each.
 
+<Info>
+For configuration-as-code (porter.yaml) autoscaling settings, see [Autoscaling Configuration](/deploy/configuration-as-code/services/autoscaling).
+</Info>
+
 ## Autoscaling Options
 
 | Method | Best For | Trigger |

deploy/configuration-as-code/reference.mdx

@@ -95,7 +95,7 @@ We recommend defining a Dockerfile over using buildpacks - if you're not sure wh
 </Warning>
 
 <Info>
-For available `builder` and `buildpacks` values, see the [Heroku Buildpacks](https://elements.heroku.com/buildpacks) or [Paketo Builders Reference](https://paketo.io/docs/reference/builders-reference/) documentation. Common builders include `heroku/buildpacks:24` and `paketobuildpacks/builder-jammy-full:latest`.
+For available `builder` and `buildpacks` values, see the [Cloud Native Buildpacks Registry](https://registry.buildpacks.io/) or [Paketo Builders Reference](https://paketo.io/docs/reference/builders-reference/) documentation. Common builders include `heroku/builder:24` and `paketobuildpacks/builder-jammy-full:latest`.
 </Info>
 
 ---
@@ -308,7 +308,7 @@ services:
 
 <Badge shape="pill" color="gray">Optional</Badge>
 
-Configure connections to external cloud services.
+Configure connections to external cloud services. See [Connections Configuration](/deploy/configuration-as-code/services/connections) for full documentation.
 
 ### AWS Role Connection
 
@@ -323,10 +323,6 @@ services:
         role: iam-role-name
 ```
 
-<Info>
-AWS roles must be configured in the Connections tab of your cluster settings.
-</Info>
-
 ### Cloud SQL Connection (GCP)
 
 Connect to Google Cloud SQL instances.
@@ -514,4 +510,6 @@ services:
 - [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration
 - [Job Services](/deploy/configuration-as-code/services/job-service) - Job service configuration
 - [Predeploy Jobs](/deploy/configuration-as-code/services/predeploy) - Pre-deploy job configuration
+- [Autoscaling Configuration](/deploy/configuration-as-code/services/autoscaling) - Autoscaling configuration reference
+- [Connections Configuration](/deploy/configuration-as-code/services/connections) - Cloud connections reference
 - [porter apply](/standard/cli/command-reference/porter-apply) - CLI reference for deployments

deploy/configuration-as-code/services/autoscaling.mdx

@@ -0,0 +1,136 @@
+---
+title: 'Autoscaling Configuration'
+sidebarTitle: 'Autoscaling'
+---
+
+Configure horizontal pod autoscaling to automatically adjust the number of replicas based on resource utilization.
+
+## Field Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable autoscaling |
+| `minInstances` | integer | Minimum number of replicas |
+| `maxInstances` | integer | Maximum number of replicas |
+| `cpuThresholdPercent` | integer | CPU usage threshold (0-100) |
+| `memoryThresholdPercent` | integer | Memory usage threshold (0-100) |
+
+## Basic Configuration
+
+```yaml
+services:
+  - name: api
+    # ...
+    autoscaling:
+      enabled: true
+      minInstances: 2
+      maxInstances: 10
+      cpuThresholdPercent: 80
+      memoryThresholdPercent: 80
+```
+
+<Info>
+When autoscaling is enabled, the `instances` field is ignored. The autoscaler manages replica count automatically.
+</Info>
+
+<Tip>
+For high availability, set `minInstances` to at least 3. See [High Availability Applications](/configure/zero-downtime-deployments#high-availability-applications) for more details.
+</Tip>
+
+## How It Works
+
+When either CPU or memory usage exceeds your configured threshold, Porter automatically adds replicas. When usage drops, replicas are removed (down to your minimum).
+
+### Example: Autoscaling in Action
+
+Consider an API service with this configuration:
+
+```yaml
+autoscaling:
+  enabled: true
+  minInstances: 2
+  maxInstances: 10
+  cpuThresholdPercent: 60
+  memoryThresholdPercent: 80
+```
+
+Here's how the autoscaler responds to changing load:
+
+| Time | Avg CPU | Avg Memory | Replicas | What Happens |
+|------|---------|------------|----------|--------------|
+| t=0 | 30% | 40% | 2 | Baseline: both metrics below thresholds |
+| t=1 | 75% | 50% | 4 | CPU (75%) exceeds 60% threshold → scale up |
+| t=2 | 90% | 60% | 6 | CPU still high → continue scaling up |
+| t=3 | 55% | 85% | 8 | CPU stabilized, but memory (85%) exceeds 80% → scale up |
+| t=4 | 45% | 70% | 8 | Both metrics below thresholds → no change (cooldown period) |
+| t=5 | 40% | 50% | 5 | Sustained low usage → scale down |
+| t=6 | 35% | 45% | 2 | Continue scaling down to minimum |
+
+Key behaviors:
+- **Either metric triggers scaling**: If CPU *or* memory exceeds its threshold, replicas are added
+- **Both must be low to scale down**: Replicas are only removed when both CPU and memory are below their thresholds
+- **Respects bounds**: Replicas never drop below `minInstances` (2) or exceed `maxInstances` (10)
+- **Gradual changes**: The autoscaler adjusts incrementally, not all at once, to avoid oscillation
+
+## Custom Metrics Autoscaling (Prometheus)
+
+Scale based on application-specific metrics like queue length, request latency, or custom business metrics.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `customAutoscaling.prometheusMetricCustomAutoscaling.metricName` | string | Prometheus metric name |
+| `customAutoscaling.prometheusMetricCustomAutoscaling.threshold` | number | Threshold value to trigger scaling |
+| `customAutoscaling.prometheusMetricCustomAutoscaling.query` | string | Custom PromQL query (optional, defaults to metric name) |
+
+```yaml
+services:
+  - name: api
+    # ...
+    autoscaling:
+      enabled: true
+      minInstances: 1
+      maxInstances: 10
+      customAutoscaling:
+        prometheusMetricCustomAutoscaling:
+          metricName: "http_requests_per_second"
+          threshold: 100
+          query: "rate(http_requests_total[5m])"
+```
+
+<Info>
+Custom metrics autoscaling requires Prometheus to be accessible in your cluster. See [Custom Metrics and Autoscaling](/observability/custom-metrics-and-autoscaling) for setup details.
+</Info>
+
+## Temporal Autoscaling
+
+Scale Temporal workflow workers based on task queue depth. Porter monitors your Temporal task queues and automatically adjusts worker count.
+
+<Info>
+Temporal autoscaling requires a Temporal integration to be configured. See [Temporal Autoscaling](/configure/temporal-autoscaling) for setup details.
+</Info>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `temporalAutoscaling.temporalIntegrationId` | string | UUID of the Temporal integration |
+| `temporalAutoscaling.taskQueue` | string | Name of the Temporal task queue to monitor |
+| `temporalAutoscaling.targetQueueSize` | integer | How many queued tasks each replica should handle (e.g., set to 10 with 100 tasks queued → 10 replicas) |
+
+```yaml
+services:
+  - name: temporal-worker
+    # ...
+    autoscaling:
+      enabled: true
+      minInstances: 2
+      maxInstances: 50
+      temporalAutoscaling:
+        temporalIntegrationId: "550e8400-e29b-41d4-a716-446655440000"
+        taskQueue: "my-task-queue"
+        targetQueueSize: 10
+```
+
+## Related Documentation
+
+- [Autoscaling Overview](/configure/autoscaling) - UI-based configuration and concepts
+- [Web Services](/deploy/configuration-as-code/services/web-service) - Web service configuration
+- [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration

deploy/configuration-as-code/services/connections.mdx

@@ -0,0 +1,135 @@
+---
+title: 'Connections Configuration'
+sidebarTitle: 'Connections'
+---
+
+Connect your services to external cloud resources like AWS IAM roles, Google Cloud SQL instances, and persistent disks.
+
+## Connection Types
+
+| Type | Description | Cloud Provider |
+|------|-------------|----------------|
+| `awsRole` | Attach an IAM role for AWS API access | AWS |
+| `cloudSql` | Connect to Google Cloud SQL instances | GCP |
+| `disk` | Attach persistent storage | All |
+
+---
+
+## AWS Role Connection
+
+Attach an IAM role to your service for secure AWS API access without managing credentials.
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Must be `awsRole` |
+| `role` | string | Yes | IAM role name |
+
+### Example
+
+```yaml
+services:
+  - name: api
+    # ...
+    connections:
+      - type: awsRole
+        role: my-app-s3-access
+```
+
+---
+
+## Cloud SQL Connection (GCP)
+
+Connect to Google Cloud SQL instances using the Cloud SQL Auth Proxy for secure database access.
+
+<Info>
+Your GCP Service account must be configured in the Connections tab of your cluster settings before it can be used in `porter.yaml`.
+</Info>
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Must be `cloudSql` |
+| `config.cloudSqlConnectionName` | string | Yes | Cloud SQL instance connection name |
+| `config.cloudSqlDatabasePort` | integer | Yes | Database port (e.g., 5432 for PostgreSQL) |
+| `config.cloudSqlServiceAccount` | string | Yes | GCP service account name |
+
+### Example
+
+```yaml
+services:
+  - name: api
+    # ...
+    connections:
+      - type: cloudSql
+        config:
+          cloudSqlConnectionName: my-project-123456:us-east1:my-instance
+          cloudSqlDatabasePort: 5432
+          cloudSqlServiceAccount: my-service-account
+```
+
+<Info>
+The connection name follows the format `project-id:region:instance-name`. You can find this in the Google Cloud Console under your Cloud SQL instance details.
+</Info>
+
+---
+
+## Persistent Disk Connection
+
+Attach persistent storage to your service for data that needs to survive pod restarts.
+
+<Info>
+Your persistent disk must be created in the Add-Ons tab of Porter before it can be used in `porter.yaml`.
+</Info>
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Must be `disk` |
+| `config.diskName` | string | Yes | Name of the persistent disk |
+
+### Example
+
+```yaml
+services:
+  - name: api
+    # ...
+    connections:
+      - type: disk
+        config:
+          diskName: my-persistent-data
+```
+
+<Warning>
+Persistent disks are tied to specific availability zones. Services using persistent disks cannot be scheduled across multiple zones.
+</Warning>
+
+---
+
+## Multiple Connections
+
+You can attach multiple connections to a single service (but only one of each type of connection):
+
+```yaml
+services:
+  - name: api
+    # ...
+    connections:
+      - type: awsRole
+        role: api-s3-access
+      - type: disk
+        config:
+          diskName: cache-storage
+```
+
+---
+
+## Related Documentation
+
+- [Web Services](/deploy/configuration-as-code/services/web-service) - Web service configuration
+- [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration
+- [Job Services](/deploy/configuration-as-code/services/job-service) - Job service configuration
+- [porter.yaml Reference](/deploy/configuration-as-code/reference) - Complete configuration reference

deploy/configuration-as-code/services/job-service.mdx

@@ -116,31 +116,7 @@ If not specified, jobs may run indefinitely. It's recommended to set a reasonabl
 
 <Badge shape="pill" color="gray">Optional</Badge>
 
-Connect to external cloud services. See [Reference](/deploy/configuration-as-code/reference#connections) for full documentation.
-
-<CodeGroup>
-```yaml AWS Role
-connections:
-  - type: awsRole
-    role: my-iam-role
-```
-
-```yaml Cloud SQL (GCP)
-connections:
-  - type: cloudSql
-    config:
-      cloudSqlConnectionName: project:region:instance
-      cloudSqlDatabasePort: 5432
-      cloudSqlServiceAccount: my-service-account
-```
-
-```yaml Persistent Disk
-connections:
-  - type: disk
-    config:
-      diskName: my-disk
-```
-</CodeGroup>
+Connect to external cloud services. See [Connections Configuration](/deploy/configuration-as-code/services/connections) for full documentation.
 
 ---