pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-04-18 15:56:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

add new newt config options

Browse Source
This commit is contained in:
miloschwartz
2026-04-03 17:25:22 -04:00
parent b99bfcd9a4
commit 707eda9f88
2 changed files with 80 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
manage/sites/site-provisioning.mdx
View File

@@ -24,14 +24,15 @@ With provisioning keys, you create one long-lived token in Pangolin, embed it in
## How provisioning works
Put the provisioning key in a JSON config file with a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix). Point Newt at that file with `--config-file`, for example:
You can supply the provisioning key in either of two ways:
**1. Config file**
Put the key in a JSON config file in a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix) and point Newt at that file:
```bash
newt --config-file /var/newt.json
```
A minimal file might only set `endpoint` and `provisioningKey` until the exchange completes; afterward the same file holds `id` and `secret` instead of the key. Other Newt options are documented on [Configure Sites](/manage/sites/configure-site).
```json
{
"endpoint": "https://app.pangolin.net",
@@ -39,9 +40,16 @@ A minimal file might only set `endpoint` and `provisioningKey` until the exchang
}
```
When Newt contacts Pangolin and exchanges the provisioning key for a device-specific ID and secret, it updates the same config file: the provisioning key entry is removed and replaced with the new credentials. After a successful provision, the provisioning key is no longer on the host; only the normal site ID and secret remain for future connections.
**2. Command line**
Pass the key with **`--provisioning-key`** instead of storing it in the file. You still use **`--config-file`** so Newt has a path to write and persist settings; see [Configure Sites](/manage/sites/configure-site) for the rest):
From there Newt authenticates over the websocket, optionally applies declarative YAML if you configured a blueprint, then brings the tunnel online. The high-level sequence is summarized below.
```bash
newt --config-file /var/newt.json --endpoint https://app.pangolin.net --provisioning-key 'spk_...'
```
**After the site is provisioned**, Newt writes the new `id` and `secret` into that config file. On later runs, Newt uses those credentials and ignores the provisioning key (CLI flag or file field), because valid ID and secret are already present. If you used `provisioningKey` in JSON, that entry is removed when the file is updated, so the long-lived token is not left on disk.
From there Newt authenticates over the websocket, optionally applies a blueprint if you passed one, then brings the tunnel online. The high-level sequence is summarized below.
<Frame>
<img src="/images/site-provisioning-flow.png" alt="Flow: provision with pre-shared key, exchange for ID and secret, apply YAML, pending approval, admin approves" centered />
@@ -51,7 +59,22 @@ From there Newt authenticates over the websocket, optionally applies declarative
[Pangolin Blueprints](/manage/blueprints) are not required when using provisioning keys. You can provision with the key only and manage resources in the dashboard afterward. Blueprints are optional but convenient when you want resources and settings created automatically from YAML as soon as the site connects.
</Note>
If you do use blueprints together with provisioning keys, you get a repeatable pattern for large fleets: one key (with appropriate limits), a blueprint file or embedded config, and optional environment-specific values so each host gets distinct resource names or domains without maintaining separate YAML per device.
### `--provisioning-blueprint-file` vs `--blueprint-file`
When you run Newt with a provisioning key, you can attach a blueprint YAML file in two different ways:
| Flag | Behavior |
|------|------------|
| **`--blueprint-file`** | **Declarative.** The blueprint is the ongoing source of truth. Newt keeps applying it, and changes you make in the dashboard can be overwritten the next time the blueprint is applied. |
| **`--provisioning-blueprint-file`** | **Imperative (bootstrap only).** The file is applied once, at provisioning time. After that, Newt does not keep reapplying it. You can edit resources in the dashboard and those edits will not be overridden by that YAML on later runs. |
Use **`--provisioning-blueprint-file`** when you want automation to create an initial set of resources (for example from a fleet template) but you intend to manage or tune them in the UI afterward. Use `--blueprint-file` when you want the file to remain authoritative, the same as on a normal site without provisioning keys.
```bash
newt --config-file /var/newt.json --provisioning-blueprint-file /path/to/bootstrap.yaml
```
If you do use blueprints together with provisioning keys, you get a repeatable pattern for large fleets: one key (with appropriate limits), a blueprint file, and optional environment-specific values so each host gets distinct resource names or domains without maintaining separate YAML per device. Pick the flag above based on whether that YAML should keep governing the site or only run at first connect.
### Blueprint example and environment templating
@@ -92,7 +115,13 @@ Use whatever variables match your deployment (for example asset tags or cloud in
### Optional site name (`--name`)
You can pass `--name` to Newt when provisioning so the new site gets a specific name. If you omit it, Pangolin assigns a random animal-based name, which you can change later in the dashboard. Predictable names via `--name` help when your automation or blueprint references the site by a stable label.
You can pass `--name` to Newt when provisioning so the new site gets a specific name. The value supports the same `{{env.VARIABLE_NAME}}` templating as blueprints: placeholders are expanded from the environment where Newt runs before the site is created (for example per-device serials or hostnames).
```bash
newt --config-file /var/newt.json --name '{{env.SERIAL_NUMBER}}-edge'
```
If you omit `--name`, Pangolin assigns a random animal-based name, which you can change later in the dashboard. Explicit or templated names help when your automation or blueprint references the site by a stable label.
## Limits, expiry, and security model