Skip to main content

Raw JSON and copy to environment

Every gateway object in the console, a route, a consumer or a global rule among them, has a Raw JSON tab. It shows the whole object as JSON, exactly as the gateway stores it, and lets a role that manages the object edit that JSON directly. The same page offers Copy to environment…, which brings the object into another environment through that environment's own Raw JSON editor.

Who may open it​

ActionWhat the role needs
Open the Raw JSON tabThe view permission of the object's kind in this environment, as the view permission of Routes (routes.view) for a route.
Edit and save in the tabThe manage permission of the same kind. Without it the editor is locked.
Copy to environment…The manage permission of the kind in this environment and in the target environment.

Every built-in role opens the tab. The Environment administrator edits every kind, the Editor every kind but certificates and secrets, and the Viewer none. The server holds the same line: every read of a gateway object needs the kind's view permission, and every write its manage permission. Custom roles lists the permissions each built-in role holds.

What the tab shows​

The editor holds the stored object. The console calls the environment's gateway "the engine", and the messages quoted on this page use that word. The notice above the editor reads: Full engine object as stored. For a certificate it reads: Full engine object as stored, without the private key the engine never returns; saving sends only the fields you change, so the stored key stays.

The notice also says how the text is checked. Where the console holds the schema of the kind, it adds: Validated against the gateway schema as you type. Otherwise it adds: Checked for valid JSON only; no schema is applied here.

Next to the tabs, Format lays the JSON out again and Copy JSON puts it on the clipboard. Format is offered only while you can edit.

A role without the manage permission of the kind sees each secret value as ••••: a key, a password, a certificate's private key. The editor does not mark a masked value as an error, so a locked editor shows no error that its reader could not fix. Users, roles and access and Custom roles say which values are masked and for whom.

The Raw JSON tab of a route: the object as the gateway stores it, in an editor with Format and Copy, and the Save bar below.

Read-only for a Viewer​

A Viewer, and any other role that views the kind without managing it, gets a locked editor. For a route in an environment named Production, its notice reads: Read-only. Your role in Production cannot manage routes. There is no Format and no save bar. The page header has no actions button either, so no copy. The JSON can still be read and copied.

Edit and save​

Type into the editor. It checks the text as you type: the JSON syntax, a key given twice, a plugin the gateway does not offer, and each plugin's configuration against that plugin's schema. Each problem is marked in the gutter at its line.

Once the text differs from the stored object, a bar at the bottom of the page says Unsaved changes, with the number of errors when there are any. Its save button stays unavailable while an error is marked. Cancel asks before it drops your edits. For a route in Production, the question reads: Your edits to the route in Production are dropped. The engine keeps what it has.

A save goes through three checks on the server before anything changes.

  1. The mask. A save that still carries •••• in a secret field is refused, and the answer names the fields. The mask can never overwrite the real value.
  2. The version. The save names the version of the object you opened. When the object changed on the gateway since then, a dialog opens under the title The object changed on the engine. In it you choose Reload or Keep editing.
  3. The gateway's own check. The server asks the gateway whether it would accept the document, without writing it. A refusal is shown in the editor and nothing is written.

Only then is the object written. A certificate is saved by sending the fields you changed, so its stored private key stays as it is.

Every save is written to the environment's audit log in two steps. The row is written as pending before the gateway is called and completed once the gateway answers, with the object before and after and its secret values masked. When the row cannot be written, the save is refused with 503 and the gateway is not called. A refusal by the gateway's check also leaves a failed row.

Copy an object to another environment​

Copying is how a route tested in one environment reaches the next one without retyping it. G8 reads the target, shows what will differ, and hands the object to the target's Raw JSON editor. Nothing is written until you save there.

  1. Open the object in the source environment. At the top right of the page header, open the actions button with three dots, labelled Actions for orders-api for a route of that name. Select Copy to environment…. For a certificate the item is unavailable, and says why: Certificates cannot be copied: the engine never returns the private key. Add the certificate in the target environment with its key.
  2. In the dialog, choose the Target environment. It lists only the environments where your role manages this kind.
  3. When the object holds secrets, Copy secrets too is ticked. Clear it to leave the secrets behind.
  4. Read What will change. G8 reads the target first, so each row says what holds there now.
  5. Select the button named after your target, here Open in Staging for a target environment named Staging. It opens the object's Raw JSON tab there when an object with the same ID exists, or the new-object page of the kind when none does.
  6. Check the editor and save it there.

What is copied​

The object's document is copied whole, with its ID. Its created and updated times are left out, because the gateway sets them. On a new object, the hint under the ID field reads: Kept from the copy. Change it to create a second object instead.

Some fields do not travel, and the dialog names each one.

  • A secret, when you cleared Copy secrets too. Its row reads: Secrets are not copied; set it again in the target.
  • A value the gateway never returns. Its row reads: The engine never returns it; set it again in the target.
  • The objects stored under it, as the credentials of a consumer. They stay in the source, and each one is copied on its own once the parent exists in the target.

What the target needs​

  • Your role there. The manage permission of the kind, or the target is not offered.
  • The objects it refers to. A route that names an upstream, a service or a plugin config needs that object in the target. The dialog names each one the target lacks. Where the gateway enforces the reference, it refuses the save until you copy the missing object first. Where it does not, the save goes through and the reference points at nothing until you do.
  • The parent of a nested object. A credential needs its consumer in the target.
  • Read access to check the references. When your role cannot read a referenced kind in the target, the dialog says the reference was not checked. The gateway answers when you save.

When the target already holds an object with the same ID, the dialog shows the differences line by line, and the copy replaces that object when you save. The save names the version of the object the target page read, so a change made there in the meantime is refused, as with any save. Through the API, that version is sent as If-Match. When the two are identical, there is nothing to save.

What the audit log records​

The dialog only reads, so opening it and choosing a target leaves no row. The save in the target is an ordinary save and leaves the ordinary two-step row in the target environment's audit log. That row also names where the object came from: the source environment, the kind of object and the object's ID. It shows under Details on the row's page. Read through the API, the row carries it as copied_from, the source's slug, kind and ID joined by slashes. The source environment gets no row.

G8 dev