pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-21 20:19:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add new blueprint information

Browse Source
This commit is contained in:
Owen
2026-10-20 11:54:02 -04:00
parent e3c52135c2
commit ef6a8b2f3b
1 changed files with 211 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/manage/blueprints.mdx
+211 -5
View File
@@ -217,9 +217,10 @@ public-resources:
full-domain: app.example.com
host-header: app.internal
tls-server-name: app.internal
forward-identity-headers: true
response-headers:
- name: Access-Control-Allow-Origin
value: *
value: "*"
rules:
- action: allow
match: country
@@ -282,6 +283,55 @@ public-resources:
When a resource is targets-only, `name` and `mode` are not required.
### Load Balancing Example
When a resource has more than one target, `load-balancing-strategy` controls how requests are spread across them.
```yaml
public-resources:
app:
name: App
mode: http
full-domain: app.example.com
load-balancing-strategy: hrw
targets:
- site: site-a
hostname: app
port: 8080
method: http
- site: site-b
hostname: app
port: 8080
method: http
```
Strategy values:
- **`wrr`** (default): Round robin. Requests rotate evenly across targets.
- **`p2c`**: Power of two choices. Pangolin picks two random targets and sends the request to the one with fewer active connections.
- **`hrw`**: Client IP hash. The same client IP is consistently routed to the same target.
- **`leasttime`**: Least response time. Requests go to the target with the fastest response time and fewest active connections.
### Identity Headers Example
By default, Pangolin forwards the authenticated user's identity to the backend in the `Remote-User`, `Remote-Email`, `Remote-Name`, `Remote-Role`, and `Remote-User-Id` headers. Set `forward-identity-headers: false` to stop sending them, for example when the backend should not see user details. See [Forwarded Headers](/manage/access-control/forwarded-headers).
```yaml
public-resources:
app:
name: App
mode: http
full-domain: app.example.com
forward-identity-headers: false
auth:
sso-enabled: true
targets:
- site: my-site
hostname: app
port: 8080
method: http
```
### Authentication Example
Authentication is configured inside `auth` and is supported only for HTTP resources.
@@ -307,6 +357,42 @@ public-resources:
- admin@example.com
```
### Mutual TLS (mTLS) **(EE)**
Set `auth.mtls` to require clients to present a TLS client certificate signed by one of the trusted CAs you list. mTLS is only supported on `http` resources, and `ssl` must not be set to `false`.
```yaml
public-resources:
internal-api:
name: Internal API
mode: http
full-domain: api.example.com
auth:
mtls:
enabled: true
ca-certificates:
- |
-----BEGIN CERTIFICATE-----
MIIBszCCAVmgAwIBAgIU...
-----END CERTIFICATE-----
targets:
- site: my-site
hostname: api
port: 8080
method: http
```
- Each `ca-certificates` entry is a PEM-encoded CA certificate. An entry can also be a bundle of several certificates; Pangolin splits it and removes duplicates.
- Only public CA certificates are accepted. An entry that contains a private key is rejected.
- A resource can trust up to 20 CA certificates.
- When `ca-certificates` is set, it replaces the full list of trusted CAs on each apply. When it is omitted, the existing CAs are left as they are.
- `enabled: true` requires at least one entry in `ca-certificates`.
- `mtls` can also be set on a [resource policy](#resource-policy-object-public-policies) so every resource using that policy shares the same trusted CAs.
<Note>
A top-level `mtls` key on the resource is still accepted for backward compatibility. Put it under `auth` in new blueprints.
</Note>
### Maintenance Page **(EE)**
The `maintenance` object lets you present a maintenance page for a public HTTP resource.
@@ -664,24 +750,36 @@ public-resources:
- production
host-header: internal.example.local
tls-server-name: internal.example.local
forward-identity-headers: true
load-balancing-strategy: wrr
request-headers:
- name: X-Env
value: prod
response-headers:
- name: Access-Control-Allow-Origin
value: *
value: "*"
rules:
- action: allow
match: country
value: US
- action: deny
match: region
value: 019
value: "019"
- action: deny
match: method
value: DELETE
auth:
pincode: 123456
sso-enabled: true
whitelist-users:
- admin@example.com
mtls:
enabled: true
ca-certificates:
- |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
maintenance:
enabled: true
type: automatic
@@ -698,6 +796,8 @@ public-resources:
hostname: app
port: 8080
path: /health
healthy-threshold: 2
unhealthy-threshold: 3
```
<Expandable title="Public resource reference">
@@ -907,6 +1007,30 @@ public-resources:
Container label: `pangolin.public-resources.web-app.tls-server-name=internal.example.local`
</ResponseField>
<ResponseField name="forward-identity-headers" type="boolean">
Forwards the authenticated user's identity to the backend in the `Remote-User`, `Remote-Email`, `Remote-Name`, `Remote-Role`, and `Remote-User-Id` headers. Set to `false` to stop sending them. See [Forwarded Headers](/manage/access-control/forwarded-headers).
**Default**: `true`
YAML: `forward-identity-headers: false`
Container label: `pangolin.public-resources.web-app.forward-identity-headers=false`
</ResponseField>
<ResponseField name="load-balancing-strategy" type="string">
How requests are distributed across the resource's targets.
- `wrr`: Round robin. Requests rotate evenly across targets.
- `p2c`: Power of two choices. Pick two random targets and send the request to the one with fewer active connections.
- `hrw`: Client IP hash. The same client IP is consistently routed to the same target.
- `leasttime`: Least response time. Send requests to the target with the fastest response time and fewest active connections.
**Options**: `wrr`, `p2c`, `hrw`, `leasttime`
**Default**: `wrr`
YAML: `load-balancing-strategy: hrw`
Container label: `pangolin.public-resources.web-app.load-balancing-strategy=hrw`
</ResponseField>
<ResponseField name="request-headers" type="array of objects">
Static headers added to proxied requests.
@@ -961,6 +1085,14 @@ public-resources:
Deprecated alias for `request-headers`.
</ResponseField>
<ResponseField name="requestHeaders" type="array of objects" deprecated>
Deprecated alias for `request-headers`.
</ResponseField>
<ResponseField name="responseHeaders" type="array of objects" deprecated>
Deprecated alias for `response-headers`.
</ResponseField>
<ResponseField name="rules" type="array of objects">
Ordered access rules for public resources.
@@ -982,14 +1114,16 @@ public-resources:
<ResponseField name="match" type="string" required>
Match type for the rule.
**Options**: `cidr`, `path`, `ip`, `country`, `asn`, `region`
**Options**: `cidr`, `path`, `ip`, `country`, `country_is_not`, `asn`, `region`, `method`
`country_is_not` matches requests from any country except the one given. `method` matches the request's HTTP method.
YAML: `match: country`
Container label: `pangolin.public-resources.web-app.rules[0].match=country`
</ResponseField>
<ResponseField name="value" type="string" required>
Value to compare against, such as an IP, CIDR, path, two letter country code, ASN, or region.
Value to compare against, such as an IP, CIDR, path, two letter country code, ASN, region, or a comma-separated list of HTTP methods (for example `POST,PUT`).
YAML: `value: US`
Container label: `pangolin.public-resources.web-app.rules[0].value=US`
@@ -1142,9 +1276,38 @@ public-resources:
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="mtls" type="object">
Mutual TLS settings **(EE)**. Requires clients to present a certificate signed by one of the trusted CAs. Only allowed when `mode: http`, and `ssl` must not be `false`. See [Mutual TLS (mTLS)](#mutual-tls-mtls-ee).
YAML: `mtls: { enabled: true, ca-certificates: [...] }`
Container label: `pangolin.public-resources.web-app.auth.mtls.enabled=true`
<Expandable title="mTLS object">
<ResponseField name="enabled" type="boolean">
Turns mTLS on for the resource. Requires at least one entry in `ca-certificates`.
YAML: `enabled: true`
Container label: `pangolin.public-resources.web-app.auth.mtls.enabled=true`
</ResponseField>
<ResponseField name="ca-certificates" type="array of strings">
PEM-encoded CA certificates that client certificates must chain to. An entry may contain a bundle of several certificates. Up to 20 certificates in total. When set, replaces the resource's trusted CAs; when omitted, the existing CAs are kept.
Container labels for arrays must include an index (`[0]`, `[1]`, ...).
YAML: `ca-certificates: ["-----BEGIN CERTIFICATE-----\n..."]`
Container label: `pangolin.public-resources.web-app.auth.mtls.ca-certificates[0]=-----BEGIN CERTIFICATE-----...`
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="mtls" type="object" deprecated>
Deprecated. Use `auth.mtls` instead. Same shape as `auth.mtls`.
</ResponseField>
<ResponseField name="maintenance" type="object">
Maintenance page configuration for public resources **(EE)**.
@@ -1371,6 +1534,20 @@ public-resources:
<ResponseField name="status" type="integer">
Expected HTTP status code.
</ResponseField>
<ResponseField name="healthy-threshold" type="integer">
Number of consecutive successful checks before an unhealthy target is marked healthy again.
**Minimum**: `1`
**Default**: `1`
</ResponseField>
<ResponseField name="unhealthy-threshold" type="integer">
Number of consecutive failed checks before a healthy target is marked unhealthy.
**Minimum**: `1`
**Default**: `1`
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
@@ -1649,6 +1826,8 @@ public-policies:
match: country
value: US
enabled: true
mtls:
enabled: false
```
<Expandable title="Resource policy reference">
@@ -1725,6 +1904,20 @@ public-policies:
<ResponseField name="rules" type="array of rule objects">
Policy rule list using the same rule schema as public resource rules.
</ResponseField>
<ResponseField name="mtls" type="object">
Mutual TLS settings **(EE)** shared by every resource that uses this policy. Same shape as `auth.mtls` on [public resources](#mutual-tls-mtls-ee).
<Expandable title="mTLS object">
<ResponseField name="enabled" type="boolean">
Turns mTLS on for the policy. Requires at least one entry in `ca-certificates`.
</ResponseField>
<ResponseField name="ca-certificates" type="array of strings">
PEM-encoded CA certificates that client certificates must chain to. Up to 20 certificates in total. When set, replaces the policy's trusted CAs; when omitted, the existing CAs are kept.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
@@ -1745,6 +1938,7 @@ public-policies:
10. `alias` values must be unique across private resources in the blueprint.
11. `mode: inference` (public or private) requires `full-domain`, must not have `targets`, and is the only mode that may set `ai-providers`.
12. `ai-budget` entries on a resource must each use a unique `unit`/`period` combination.
13. When `auth.mtls.enabled` is `true`, the resource must use `mode: http`, must not set `ssl: false`, and must list at least one entry in `ca-certificates`. Policies with `mtls.enabled: true` also need at least one CA certificate.
### Common Validation Errors
@@ -1819,3 +2013,15 @@ Each entry in `ai-budget` must use a distinct `unit`/`period` pair, such as one
### "'models' can only be set on a provider with access-mode 'select'"
Set `models` only when the `ai-providers` entry uses `access-mode: select`. Entries using `access-mode: inherit` must leave `models` empty.
### "mTLS is only supported when mode is 'http'"
`auth.mtls` can only be enabled on HTTP public resources.
### "mTLS requires 'ssl' to be enabled"
Remove `ssl: false` from a resource that enables mTLS. Client certificates are checked during the TLS handshake.
### "mTLS requires at least one entry in 'ca-certificates'"
When `mtls.enabled` is `true` on a resource or policy, list at least one PEM-encoded CA certificate in `ca-certificates`.