> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # 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 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. 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. ```json { "options": { "source": "content", "content": "" } } ``` ### Import from a Git repository Supply a Git source instead of inline content. The gateway clones the repository and imports the specified file. ```json { "options": { "source": "git", "git": { "url": "git@github.com:/.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_` 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. ```json { "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. ```yaml 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:/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 ``` ## Related topics * [Export a gateway configuration](./export-gateway-configuration) * [Gateway configuration import and export](./import-export)