How a sync works
pgw config sync compares the file with what the tenant has now and builds a plan:
- pgw creates a record that the file has and the tenant lacks.
- pgw updates a record whose fields differ.
- pgw leaves alone a record that the tenant has and the file lacks, unless you pass
--prune.
Before you begin
- The tenant’s API key, in
PGW_API_KEY.pgw bootstrapsaves it in.env. - The secret of each record that the file creates: the APNs key, the Firebase service account, or the SIP password.
Export, edit, and sync
1
Export the tenant
nothing to change.2
Move each secret into a file or an environment variable
The YAML file never holds a secret, so you can commit it. Keep the secret files out of version control.
3
Add a reference to each secret
Name each secret with A record that the sync creates needs its secret, so add every reference before you use the file on a new install. When the file names a secret, pgw compares it with the stored one and shows the field as changed when it differs.
<field>_file and a path, or <field>_env and the name of an environment variable. A relative path starts at the folder of the YAML file. Secret references lists every field.4
Preview the change
+ marks a create, ~ an update, and - a delete. A dry run changes nothing.5
Apply the change
applied.How pgw matches records
The file contains no IDs. pgw recognizes a record by the fields that identify it:
If you change an identifying field, pgw treats the record as a new one. Changing an upstream’s
host creates a second upstream, and with --prune deletes the first, together with its users and devices.
A field that you leave out of the file returns to its default. The exceptions are every secret, a user’s enabled, and an upstream’s Bearer token settings, which always keep their current value when you leave them out.
An unknown key is an error, so pgw rejects a misspelled field instead of ignoring it. The file must hold one YAML document.
Remove records with —prune
With--prune, pgw deletes each app, upstream, and user that the tenant has and the file leaves out, within the sections that the file names:
- A file without the
apps:key leaves every app alone. A file withoutupstreams:leaves every upstream and its users alone. - An upstream without the
users:key keeps its users. - An empty list deletes every record of that kind.
upstreams: []deletes every upstream, andusers: []deletes all of that upstream’s users.
apps: and upstreams:, and it writes users: for each upstream whose users pgw stores. It writes a key that has no records as []. So --prune deletes each record that you remove from an exported file. --prune never deletes the users of a Kamailio upstream.
The plan marks each delete with
-, and shows the number of devices that a deleted app or upstream has. When the plan deletes a record, pgw asks before it applies:
y or yes to apply. If the tenant changes before you answer, pgw applies nothing, and you run the sync again. To delete from a script, see Run a sync in CI.
Secret references
- Give each secret in one form. Setting both is an error.
- A secret written as a value, such as
password:orapns_key_pem:, is an error that names the record and the field. - An unset or empty variable is an error.
- An
_envreference can name aPGW_variable from the.envfile in the folder where you runpgw. A name without thePGW_prefix resolves only from the shell. - pgw reads a key file whole. From a password file, pgw drops one trailing line break.
- A web app without a VAPID key gets a new one when the sync creates it, and keeps it on later syncs. To move a web app to a new tenant with its browser subscriptions, write the key with
pgw app export-vapid-keyand name it invapid_private_key_pem_file. A key that differs from the app’s is an error, because a new key ends every subscription.
What a sync can’t change
- Tenants, API keys, devices, push history, and bans aren’t in the file.
- Users of a Kamailio user source live in Kamailio. A file that lists them is an error.
- An upstream’s
mode,contact_strategy,realm,user_source, andkamailio.use_domainare fixed when the upstream is created. A sync that changes one fails and names the field. To change one, remove the upstream from the file, sync with--prune, add it back with the new value, and sync again. This deletes the upstream’s users and devices.
Next steps
Run a sync in CI
Apply the file from a pipeline after a person approves the plan.
Serve several domains
Learn the rules for the
domains that an upstream in the file lists.