Import a gateway configuration

Import a configuration into a gateway cluster using the Gateway Manager UI or the Platform API. Importing pushes services and resources from a configuration file into a running gateway instance.

Before you begin

• The target gateway must be connected, enabled, and not set to read-only before you can import.
• Your configuration file must be in JSON format if you’re importing through the Platform API. The UI also accepts YAML.
• You must have the gateway:update role to import configurations via the Platform API.

Import via the UI

1. In Gateway Manager, go to the cluster list.
2. Locate the target cluster and select the three-dots overflow menu (⋯) on the cluster row.
3. Select Import Configuration.
4. In the dialog, upload your configuration file or provide the path to the file you want to import.
5. Select Import to apply the configuration.

Gateway Manager confirms a successful import or surfaces an error message if the import fails.

Import via the Platform API

The Platform API exposes import functionality through Gateway Manager. Call the import endpoint from your CI/CD pipeline or automation tooling to import a configuration programmatically.

Endpoint

POST /v1/gateways/:clusterId/configuration/import

Import from inline content

Supply the configuration document directly in the request body using the content source.

1
{
2
  "options": {
3
    "source": "content",
4
    "content": "<yaml-or-json-string>"
5
  }
6
}

Import from a Git repository

Supply a Git source instead of inline content. The gateway clones the repository and imports the specified file.

1
{
2
  "options": {
3
    "source": "git",
4
    "git": {
5
      "url": "git@github.com:<org>/<repo>.git",
6
      "file": "import.yaml",
7
      "reference": "main",
8
      "privateKey": "/path/to/private-key"
9
    }
10
  }
11
}

For HTTPS repositories, use username and password instead of privateKey. The password field supports $GATEWAYSECRET_<alias> references, which the gateway resolves at runtime.

Import options

You can include the following optional flags in the options object:

Response

A successful import returns lists and counts of added, replaced, and skipped resources.

1
{
2
  "added": ["service/Ansible-Example"],
3
  "replaced": [],
4
  "skipped": [],
5
  "summary": {
6
    "added": 1,
7
    "replaced": 0,
8
    "skipped": 0
9
  }
10
}

When you use the check option, the response returns a dry-run diff instead of the standard result.

Error handling

The API returns error messages for the following conditions:

Configuration file format

The following example shows the structure of a valid import file. The file can contain decorators, repositories, and services in any combination.

1
decorators:
2
  - name: ansible-xr
3
    schema:
4
      $id: https://example.com/device.schema.json
5
      $schema: https://json-schema.org/draft/2020-12/schema
6
      properties:
7
        device_type:
8
          description: The type of device
9
          enum:
10
            - ios
11
            - eos
12
            - nxos
13
          type: string
14
        host:
15
          description: The hostname or IP address of the device
16
          type: string
17
      title: Network Device
18
      type: object
19
repositories:
20
  - name: xr-resources
21
    description: XR Resources for testing
22
    url: git@gitlab.com:<org>/xr/resources.git
23
    reference: main
24
    tags:
25
      - cisco
26
      - xr
27
    private-key-name: xr-gitlab-private
28
services:
29
  - name: Ansible-Example
30
    type: ansible-playbook
31
    description: An ansible playbook to say hello-world
32
    playbooks:
33
      - hello-world.yml
34
    working-directory: ./
35
    repository: xr-resources
36
    decorator: ansible-xr
37
    tags:
38
      - xr
39
      - cisco
40
    runtime:
41
      check: true
42
      diff: true
43
      skip-tags: example-tag
44
      inventory:
45
        - ./inventory.ini
46
      verbose-level: 6
47
  - name: Hello-World
48
    type: python-script
49
    description: A simple hello-world script
50
    filename: hello-world.py
51
    working-directory: python-scripts
52
    repository: xr-resources
53
    decorator: my-special-decorator

Related topics

• Export a gateway configuration
• Gateway configuration import and export