Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/docs/guides/menu.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -176,3 +176,5 @@ infrahubctl menu load /path/to/menu.yml

More information on `infrahubctl` command line utility can be found [here]($(base_url)infrahubctl/infrahubctl).
More information on the `menu` subcommand can be found [here]($(base_url)infrahubctl/infrahubctl-menu).

The menu can also be loaded into Infrahub using the git repository integration. To do this, you need to add the menu file to the `.infrahub.yml` details can be seen in the [.infrahub.yml](../topics/infrahub-yml#menus) documentation.
166 changes: 166 additions & 0 deletions docs/docs/guides/object-load.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
---
title: Importing Objects from a file
---

# Object files

An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema. It provides a declarative way to define and manage resources in your Infrahub instance.

Object files work well for models that don't change too often and/or that need to be tracked in Git. Examples include: Groups, tags, Users, etc.

The goal of this guide is to show you how you define and load an object file.

## Loading an example schema into Infrahub

We assume that you have an empty instance of Infrahub started.

Save the following schema into a file on your disk.

The schema contains the following nodes:

- A location hierarchy with a Country and a Site
- A network device with a relation to network interfaces and a site
- A network interface with a relation to a network device

```yaml
---
version: "1.0"
generics:
- name: Generic
namespace: Location
include_in_menu: false
hierarchical: true
attributes:
- name: name
kind: Text
optional: false
unique: true
nodes:
- name: Country
namespace: Location
inherit_from:
- LocationGeneric
parent: ""
children: LocationSite
- name: Site
namespace: Location
inherit_from:
- LocationGeneric
parent: LocationCountry
children: ""
relationships:
- name: devices
kind: Generic
peer: NetworkDevice
cardinality: many
optional: true
- name: Device
namespace: Network
attributes:
- name: name
kind: Text
optional: false
unique: true
relationships:
- name: site
kind: Attribute
cardinality: one
optional: true
peer: LocationSite
- name: interfaces
kind: Component
cardinality: many
optional: true
peer: NetworkInterface
- name: Interface
namespace: Network
attributes:
- name: name
kind: Text
optional: false
relationships:
- name: device
kind: Parent
optional: false
cardinality: one
peer: NetworkDevice
```

Load the schema into Infrahub using the following command

```bash
infrahubctl schema load /path/to/schema.yml
```

In the web interface you will now see that all the nodes defined in the schema are available in the top section of the menu.

## Defining a object file

Our goal is to define data that can be loaded into Infrahub based on the schema we just defined. We will create an object file that defines a Country and a Site.

```yaml
---
apiVersion: infrahub.app/v1
kind: Object
spec:
kind: LocationCountry
data:
- name: United Kingdom
children:
kind: LocationSite
data:
- name: Stonehenge Visitor Centre
- name: Tower of London
- name: Edinburgh Castle
---
apiVersion: infrahub.app/v1
kind: Object
spec:
kind: NetworkDevice
data:
- name: sw01-svc01
site: Stonehenge Visitor Centre
---
apiVersion: infrahub.app/v1
kind: Object
spec:
kind: NetworkInterface
data:
- name: eth0
device: sw01-svc01
- name: eth1
device: sw01-svc01
- name: eth2
device: sw01-svc01
- name: eth3
device: sw01-svc01
- name: eth4
device: sw01-svc01
- name: eth5
device: sw01-svc01
```

> Note that these definitions can be in separate files but for simplicity we have put them all in one file using `---` to separate the different objects.

For a more detailed information on the structure and relationship management within an object file, visit the [SDK Object File]($(base_url)python-sdk/topics/object_file) docs.

## Loading a object file

You can load the object files into Infrahub using `object` subcommand of the `infrahubctl` utility.

Load the objects into Infrahub using the following command

```bash
infrahubctl object load /path/to/objects.yml
```

More information on `infrahubctl` command line utility can be found [here]($(base_url)infrahubctl/infrahubctl).
More information on the `object` subcommand can be found [here]($(base_url)infrahubctl/infrahubctl-object).

Objects can also be loaded into Infrahub using the git repository integration. To do this, you need to add the object file to the `.infrahub.yml` details can be seen in the [.infrahub.yml](../topics/infrahub-yml#objects) documentation.

:::info

Loading objects using git or via the command line will load folders/files in alphabetical order.

:::
36 changes: 36 additions & 0 deletions docs/docs/topics/infrahub-yml.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ An external repository can be used to link the following Infrahub objects to an

- [GraphQL Query](../topics/graphql)
- [Schema](../topics/schema)
- [Menu](../guides/menu)
- [Object File](../guides/object-load)
- [Jinja2 Transform](../topics/transformation#rendered-file-jinja2-plugin)
- [Python Transformation](../topics/transformation#transformpython-python-plugin)
- [Artifact Definition](../topics/artifact)
Expand Down Expand Up @@ -60,6 +62,40 @@ Schemas to be loaded as part of an external repository can be defined in file(s)

Infrahub will attempt to import any schemas defined in `.infrahub.yml` when pulling from the external repository.

## Objects

Objects to be loaded as part of an external repository can be defined in file(s) as described [here]($(base_url)/python-sdk/topics/object_file). The objects must also be explicitly identified in the `.infrahub.yml` file under `objects`.

:::info

The order defined in the `.infrahub.yml` file is maintained. If a folder is defined in the list, the folders/files within the folder are loaded in alphabetical order. This means that if you have a dependency between objects, you must ensure that the dependent object is defined before the object that depends on it.

:::
<details>
<summary>Example</summary>

```yaml
objects:
- objects/locations.yml
- objects/devices
```

</details>

## Menus

Menus to be loaded as part of an external repository can be defined in file(s) as described [here](../guides/menu). The menus must also be explicitly identified in the `.infrahub.yml` file under `menus`.

<details>
<summary>Example</summary>

```yaml
menus:
- menus/base.yml
```

</details>

## Jinja2 transformation {#transform-jinja-2}

Jinja2 Transformations can be defined as described [here](../topics/transformation#rendered-file-jinja2-plugin). To load Jinja2 Transformations into Infrahub from an external repository, you must explicitly define them in the `.infrahub.yml` file. Each Jinja2 Transformations in the `.infrahub.yml` configuration file is defined by the following
Expand Down
1 change: 1 addition & 0 deletions docs/sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ const sidebars: SidebarsConfig = {
'guides/create-schema',
'guides/import-schema',
'guides/menu',
'guides/object-load',
'guides/computed-attributes',
'guides/resource-manager',
'guides/accounts-permissions',
Expand Down