Skip to content

Commit 9ecb424

Browse files
jackowfishjackowfish
authored
Merge pull request #185 from porter-dev/jack/add-connections+autoscaling
feat: Create new docs for autoscaling + connections
2 parents 970774d + cd044cc commit 9ecb424

8 files changed

Lines changed: 287 additions & 126 deletions

File tree

‎configure/autoscaling.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ title: "Autoscaling"
44

55
Porter supports several autoscaling strategies for your web and worker services. This guide covers the available options and when to use each.
66

7+
<Info>
8+
For configuration-as-code (porter.yaml) autoscaling settings, see [Autoscaling Configuration](/deploy/configuration-as-code/services/autoscaling).
9+
</Info>
10+
711
## Autoscaling Options
812

913
| Method | Best For | Trigger |

‎deploy/configuration-as-code/reference.mdx‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ We recommend defining a Dockerfile over using buildpacks - if you're not sure wh
9595
</Warning>
9696

9797
<Info>
98-
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`.
98+
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`.
9999
</Info>
100100

101101
---
@@ -308,7 +308,7 @@ services:
308308

309309
<Badge shape="pill" color="gray">Optional</Badge>
310310

311-
Configure connections to external cloud services.
311+
Configure connections to external cloud services. See [Connections Configuration](/deploy/configuration-as-code/services/connections) for full documentation.
312312

313313
### AWS Role Connection
314314

@@ -323,10 +323,6 @@ services:
323323
role: iam-role-name
324324
```
325325

326-
<Info>
327-
AWS roles must be configured in the Connections tab of your cluster settings.
328-
</Info>
329-
330326
### Cloud SQL Connection (GCP)
331327

332328
Connect to Google Cloud SQL instances.
@@ -514,4 +510,6 @@ services:
514510
- [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration
515511
- [Job Services](/deploy/configuration-as-code/services/job-service) - Job service configuration
516512
- [Predeploy Jobs](/deploy/configuration-as-code/services/predeploy) - Pre-deploy job configuration
513+
- [Autoscaling Configuration](/deploy/configuration-as-code/services/autoscaling) - Autoscaling configuration reference
514+
- [Connections Configuration](/deploy/configuration-as-code/services/connections) - Cloud connections reference
517515
- [porter apply](/standard/cli/command-reference/porter-apply) - CLI reference for deployments

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

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: 'Autoscaling Configuration'
3+
sidebarTitle: 'Autoscaling'
4+
---
5+
6+
Configure horizontal pod autoscaling to automatically adjust the number of replicas based on resource utilization.
7+
8+
## Field Reference
9+
10+
| Field | Type | Description |
11+
|-------|------|-------------|
12+
| `enabled` | boolean | Enable autoscaling |
13+
| `minInstances` | integer | Minimum number of replicas |
14+
| `maxInstances` | integer | Maximum number of replicas |
15+
| `cpuThresholdPercent` | integer | CPU usage threshold (0-100) |
16+
| `memoryThresholdPercent` | integer | Memory usage threshold (0-100) |
17+
18+
## Basic Configuration
19+
20+
```yaml
21+
services:
22+
- name: api
23+
# ...
24+
autoscaling:
25+
enabled: true
26+
minInstances: 2
27+
maxInstances: 10
28+
cpuThresholdPercent: 80
29+
memoryThresholdPercent: 80
30+
```
31+
32+
<Info>
33+
When autoscaling is enabled, the `instances` field is ignored. The autoscaler manages replica count automatically.
34+
</Info>
35+
36+
<Tip>
37+
For high availability, set `minInstances` to at least 3. See [High Availability Applications](/configure/zero-downtime-deployments#high-availability-applications) for more details.
38+
</Tip>
39+
40+
## How It Works
41+
42+
When either CPU or memory usage exceeds your configured threshold, Porter automatically adds replicas. When usage drops, replicas are removed (down to your minimum).
43+
44+
### Example: Autoscaling in Action
45+
46+
Consider an API service with this configuration:
47+
48+
```yaml
49+
autoscaling:
50+
enabled: true
51+
minInstances: 2
52+
maxInstances: 10
53+
cpuThresholdPercent: 60
54+
memoryThresholdPercent: 80
55+
```
56+
57+
Here's how the autoscaler responds to changing load:
58+
59+
| Time | Avg CPU | Avg Memory | Replicas | What Happens |
60+
|------|---------|------------|----------|--------------|
61+
| t=0 | 30% | 40% | 2 | Baseline: both metrics below thresholds |
62+
| t=1 | 75% | 50% | 4 | CPU (75%) exceeds 60% threshold → scale up |
63+
| t=2 | 90% | 60% | 6 | CPU still high → continue scaling up |
64+
| t=3 | 55% | 85% | 8 | CPU stabilized, but memory (85%) exceeds 80% → scale up |
65+
| t=4 | 45% | 70% | 8 | Both metrics below thresholds → no change (cooldown period) |
66+
| t=5 | 40% | 50% | 5 | Sustained low usage → scale down |
67+
| t=6 | 35% | 45% | 2 | Continue scaling down to minimum |
68+
69+
Key behaviors:
70+
- **Either metric triggers scaling**: If CPU *or* memory exceeds its threshold, replicas are added
71+
- **Both must be low to scale down**: Replicas are only removed when both CPU and memory are below their thresholds
72+
- **Respects bounds**: Replicas never drop below `minInstances` (2) or exceed `maxInstances` (10)
73+
- **Gradual changes**: The autoscaler adjusts incrementally, not all at once, to avoid oscillation
74+
75+
## Custom Metrics Autoscaling (Prometheus)
76+
77+
Scale based on application-specific metrics like queue length, request latency, or custom business metrics.
78+
79+
| Field | Type | Description |
80+
|-------|------|-------------|
81+
| `customAutoscaling.prometheusMetricCustomAutoscaling.metricName` | string | Prometheus metric name |
82+
| `customAutoscaling.prometheusMetricCustomAutoscaling.threshold` | number | Threshold value to trigger scaling |
83+
| `customAutoscaling.prometheusMetricCustomAutoscaling.query` | string | Custom PromQL query (optional, defaults to metric name) |
84+
85+
```yaml
86+
services:
87+
- name: api
88+
# ...
89+
autoscaling:
90+
enabled: true
91+
minInstances: 1
92+
maxInstances: 10
93+
customAutoscaling:
94+
prometheusMetricCustomAutoscaling:
95+
metricName: "http_requests_per_second"
96+
threshold: 100
97+
query: "rate(http_requests_total[5m])"
98+
```
99+
100+
<Info>
101+
Custom metrics autoscaling requires Prometheus to be accessible in your cluster. See [Custom Metrics and Autoscaling](/observability/custom-metrics-and-autoscaling) for setup details.
102+
</Info>
103+
104+
## Temporal Autoscaling
105+
106+
Scale Temporal workflow workers based on task queue depth. Porter monitors your Temporal task queues and automatically adjusts worker count.
107+
108+
<Info>
109+
Temporal autoscaling requires a Temporal integration to be configured. See [Temporal Autoscaling](/configure/temporal-autoscaling) for setup details.
110+
</Info>
111+
112+
| Field | Type | Description |
113+
|-------|------|-------------|
114+
| `temporalAutoscaling.temporalIntegrationId` | string | UUID of the Temporal integration |
115+
| `temporalAutoscaling.taskQueue` | string | Name of the Temporal task queue to monitor |
116+
| `temporalAutoscaling.targetQueueSize` | integer | How many queued tasks each replica should handle (e.g., set to 10 with 100 tasks queued → 10 replicas) |
117+
118+
```yaml
119+
services:
120+
- name: temporal-worker
121+
# ...
122+
autoscaling:
123+
enabled: true
124+
minInstances: 2
125+
maxInstances: 50
126+
temporalAutoscaling:
127+
temporalIntegrationId: "550e8400-e29b-41d4-a716-446655440000"
128+
taskQueue: "my-task-queue"
129+
targetQueueSize: 10
130+
```
131+
132+
## Related Documentation
133+
134+
- [Autoscaling Overview](/configure/autoscaling) - UI-based configuration and concepts
135+
- [Web Services](/deploy/configuration-as-code/services/web-service) - Web service configuration
136+
- [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: 'Connections Configuration'
3+
sidebarTitle: 'Connections'
4+
---
5+
6+
Connect your services to external cloud resources like AWS IAM roles, Google Cloud SQL instances, and persistent disks.
7+
8+
## Connection Types
9+
10+
| Type | Description | Cloud Provider |
11+
|------|-------------|----------------|
12+
| `awsRole` | Attach an IAM role for AWS API access | AWS |
13+
| `cloudSql` | Connect to Google Cloud SQL instances | GCP |
14+
| `disk` | Attach persistent storage | All |
15+
16+
---
17+
18+
## AWS Role Connection
19+
20+
Attach an IAM role to your service for secure AWS API access without managing credentials.
21+
22+
### Field Reference
23+
24+
| Field | Type | Required | Description |
25+
|-------|------|----------|-------------|
26+
| `type` | string | Yes | Must be `awsRole` |
27+
| `role` | string | Yes | IAM role name |
28+
29+
### Example
30+
31+
```yaml
32+
services:
33+
- name: api
34+
# ...
35+
connections:
36+
- type: awsRole
37+
role: my-app-s3-access
38+
```
39+
40+
---
41+
42+
## Cloud SQL Connection (GCP)
43+
44+
Connect to Google Cloud SQL instances using the Cloud SQL Auth Proxy for secure database access.
45+
46+
<Info>
47+
Your GCP Service account must be configured in the Connections tab of your cluster settings before it can be used in `porter.yaml`.
48+
</Info>
49+
50+
### Field Reference
51+
52+
| Field | Type | Required | Description |
53+
|-------|------|----------|-------------|
54+
| `type` | string | Yes | Must be `cloudSql` |
55+
| `config.cloudSqlConnectionName` | string | Yes | Cloud SQL instance connection name |
56+
| `config.cloudSqlDatabasePort` | integer | Yes | Database port (e.g., 5432 for PostgreSQL) |
57+
| `config.cloudSqlServiceAccount` | string | Yes | GCP service account name |
58+
59+
### Example
60+
61+
```yaml
62+
services:
63+
- name: api
64+
# ...
65+
connections:
66+
- type: cloudSql
67+
config:
68+
cloudSqlConnectionName: my-project-123456:us-east1:my-instance
69+
cloudSqlDatabasePort: 5432
70+
cloudSqlServiceAccount: my-service-account
71+
```
72+
73+
<Info>
74+
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.
75+
</Info>
76+
77+
---
78+
79+
## Persistent Disk Connection
80+
81+
Attach persistent storage to your service for data that needs to survive pod restarts.
82+
83+
<Info>
84+
Your persistent disk must be created in the Add-Ons tab of Porter before it can be used in `porter.yaml`.
85+
</Info>
86+
87+
### Field Reference
88+
89+
| Field | Type | Required | Description |
90+
|-------|------|----------|-------------|
91+
| `type` | string | Yes | Must be `disk` |
92+
| `config.diskName` | string | Yes | Name of the persistent disk |
93+
94+
### Example
95+
96+
```yaml
97+
services:
98+
- name: api
99+
# ...
100+
connections:
101+
- type: disk
102+
config:
103+
diskName: my-persistent-data
104+
```
105+
106+
<Warning>
107+
Persistent disks are tied to specific availability zones. Services using persistent disks cannot be scheduled across multiple zones.
108+
</Warning>
109+
110+
---
111+
112+
## Multiple Connections
113+
114+
You can attach multiple connections to a single service (but only one of each type of connection):
115+
116+
```yaml
117+
services:
118+
- name: api
119+
# ...
120+
connections:
121+
- type: awsRole
122+
role: api-s3-access
123+
- type: disk
124+
config:
125+
diskName: cache-storage
126+
```
127+
128+
---
129+
130+
## Related Documentation
131+
132+
- [Web Services](/deploy/configuration-as-code/services/web-service) - Web service configuration
133+
- [Worker Services](/deploy/configuration-as-code/services/worker-service) - Worker service configuration
134+
- [Job Services](/deploy/configuration-as-code/services/job-service) - Job service configuration
135+
- [porter.yaml Reference](/deploy/configuration-as-code/reference) - Complete configuration reference

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

Lines changed: 1 addition & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -116,31 +116,7 @@ If not specified, jobs may run indefinitely. It's recommended to set a reasonabl
116116

117117
<Badge shape="pill" color="gray">Optional</Badge>
118118

119-
Connect to external cloud services. See [Reference](/deploy/configuration-as-code/reference#connections) for full documentation.
120-
121-
<CodeGroup>
122-
```yaml AWS Role
123-
connections:
124-
- type: awsRole
125-
role: my-iam-role
126-
```
127-
128-
```yaml Cloud SQL (GCP)
129-
connections:
130-
- type: cloudSql
131-
config:
132-
cloudSqlConnectionName: project:region:instance
133-
cloudSqlDatabasePort: 5432
134-
cloudSqlServiceAccount: my-service-account
135-
```
136-
137-
```yaml Persistent Disk
138-
connections:
139-
- type: disk
140-
config:
141-
diskName: my-disk
142-
```
143-
</CodeGroup>
119+
Connect to external cloud services. See [Connections Configuration](/deploy/configuration-as-code/services/connections) for full documentation.
144120

145121
---
146122

0 commit comments

Comments
 (0)