Import a gateway configuration

Gateway Manager 1.1.1+

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

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

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

If you’re importing a configuration that contains resources that already exist in the cluster, the import won’t override them by default. Use the Force option to overwrite existing resources.

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.

API-based imports only support JSON. To import in YAML, use the Gateway Manager UI.

Endpoint

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

Import from inline content

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

{
  "options": {
    "source": "content",
    "content": "<yaml-or-json-string>"
  }
}

Import from a Git repository

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

{
  "options": {
    "source": "git",
    "git": {
      "url": "git@github.com:<org>/<repo>.git",
      "file": "import.yaml",
      "reference": "main",
      "privateKey": "/path/to/private-key"
    }
  }
}

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:

Option	Type	Description
`force`	boolean	Overwrite existing resources that conflict with the import. Default: `false`.
`validate`	boolean	Parse and validate the configuration without writing any changes. Mutually exclusive with `check`. Default: `false`.
`check`	boolean	Preview what the import would change without writing any changes. Mutually exclusive with `validate`. Default: `false`.

Response

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

{
  "added": ["service/Ansible-Example"],
  "replaced": [],
  "skipped": [],
  "summary": {
    "added": 1,
    "replaced": 0,
    "skipped": 0
  }
}

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:

Condition	Description
Gateway not active	The target gateway isn’t connected, is disabled, or is set to read-only. Resolve the gateway state and retry.
Method does not exist	The connected Itential Gateway version doesn’t support this operation. Update Itential Gateway to a version compatible with your Gateway Manager version.
Invalid configuration	The configuration is missing required fields or contains invalid values. Validate the file and retry.
Permission error	Your credentials don’t have the `gateway:update` role. Contact your platform administrator.
Network failure	The gateway couldn’t be reached during the import. Check connectivity and retry.
Git source error	The repository URL is unreachable, the credentials are invalid, or the specified ref doesn’t exist.

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.

decorators:
  - name: ansible-xr
    schema:
      $id: https://example.com/device.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      properties:
        device_type:
          description: The type of device
          enum:
            - ios
            - eos
            - nxos
          type: string
        host:
          description: The hostname or IP address of the device
          type: string
      title: Network Device
      type: object
repositories:
  - name: xr-resources
    description: XR Resources for testing
    url: git@gitlab.com:<org>/xr/resources.git
    reference: main
    tags:
      - cisco
      - xr
    private-key-name: xr-gitlab-private
services:
  - name: Ansible-Example
    type: ansible-playbook
    description: An ansible playbook to say hello-world
    playbooks:
      - hello-world.yml
    working-directory: ./
    repository: xr-resources
    decorator: ansible-xr
    tags:
      - xr
      - cisco
    runtime:
      check: true
      diff: true
      skip-tags: example-tag
      inventory:
        - ./inventory.ini
      verbose-level: 6
  - name: Hello-World
    type: python-script
    description: A simple hello-world script
    filename: hello-world.py
    working-directory: python-scripts
    repository: xr-resources
    decorator: my-special-decorator