Skip to content

Commit dc269ad

Browse files
minitrigaminitriga
authored
Add menu and object info to docs (#6554)
* Add object and menu repo import to docs * Add more info and a guide doc for object files * fix lint * Add info about file ordering * Add info block * Fix linting
1 parent 35a384b commit dc269ad

File tree

4 files changed

+205
-0
lines changed

4 files changed

+205
-0
lines changed

‎docs/docs/guides/menu.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,3 +176,5 @@ infrahubctl menu load /path/to/menu.yml
176176

177177
More information on `infrahubctl` command line utility can be found [here]($(base_url)infrahubctl/infrahubctl).
178178
More information on the `menu` subcommand can be found [here]($(base_url)infrahubctl/infrahubctl-menu).
179+
180+
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.

‎docs/docs/guides/object-load.mdx‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: Importing Objects from a file
3+
---
4+
5+
# Object files
6+
7+
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.
8+
9+
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.
10+
11+
The goal of this guide is to show you how you define and load an object file.
12+
13+
## Loading an example schema into Infrahub
14+
15+
We assume that you have an empty instance of Infrahub started.
16+
17+
Save the following schema into a file on your disk.
18+
19+
The schema contains the following nodes:
20+
21+
- A location hierarchy with a Country and a Site
22+
- A network device with a relation to network interfaces and a site
23+
- A network interface with a relation to a network device
24+
25+
```yaml
26+
---
27+
version: "1.0"
28+
generics:
29+
- name: Generic
30+
namespace: Location
31+
include_in_menu: false
32+
hierarchical: true
33+
attributes:
34+
- name: name
35+
kind: Text
36+
optional: false
37+
unique: true
38+
nodes:
39+
- name: Country
40+
namespace: Location
41+
inherit_from:
42+
- LocationGeneric
43+
parent: ""
44+
children: LocationSite
45+
- name: Site
46+
namespace: Location
47+
inherit_from:
48+
- LocationGeneric
49+
parent: LocationCountry
50+
children: ""
51+
relationships:
52+
- name: devices
53+
kind: Generic
54+
peer: NetworkDevice
55+
cardinality: many
56+
optional: true
57+
- name: Device
58+
namespace: Network
59+
attributes:
60+
- name: name
61+
kind: Text
62+
optional: false
63+
unique: true
64+
relationships:
65+
- name: site
66+
kind: Attribute
67+
cardinality: one
68+
optional: true
69+
peer: LocationSite
70+
- name: interfaces
71+
kind: Component
72+
cardinality: many
73+
optional: true
74+
peer: NetworkInterface
75+
- name: Interface
76+
namespace: Network
77+
attributes:
78+
- name: name
79+
kind: Text
80+
optional: false
81+
relationships:
82+
- name: device
83+
kind: Parent
84+
optional: false
85+
cardinality: one
86+
peer: NetworkDevice
87+
```
88+
89+
Load the schema into Infrahub using the following command
90+
91+
```bash
92+
infrahubctl schema load /path/to/schema.yml
93+
```
94+
95+
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.
96+
97+
## Defining a object file
98+
99+
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.
100+
101+
```yaml
102+
---
103+
apiVersion: infrahub.app/v1
104+
kind: Object
105+
spec:
106+
kind: LocationCountry
107+
data:
108+
- name: United Kingdom
109+
children:
110+
kind: LocationSite
111+
data:
112+
- name: Stonehenge Visitor Centre
113+
- name: Tower of London
114+
- name: Edinburgh Castle
115+
---
116+
apiVersion: infrahub.app/v1
117+
kind: Object
118+
spec:
119+
kind: NetworkDevice
120+
data:
121+
- name: sw01-svc01
122+
site: Stonehenge Visitor Centre
123+
---
124+
apiVersion: infrahub.app/v1
125+
kind: Object
126+
spec:
127+
kind: NetworkInterface
128+
data:
129+
- name: eth0
130+
device: sw01-svc01
131+
- name: eth1
132+
device: sw01-svc01
133+
- name: eth2
134+
device: sw01-svc01
135+
- name: eth3
136+
device: sw01-svc01
137+
- name: eth4
138+
device: sw01-svc01
139+
- name: eth5
140+
device: sw01-svc01
141+
```
142+
143+
> 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.
144+
145+
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.
146+
147+
## Loading a object file
148+
149+
You can load the object files into Infrahub using `object` subcommand of the `infrahubctl` utility.
150+
151+
Load the objects into Infrahub using the following command
152+
153+
```bash
154+
infrahubctl object load /path/to/objects.yml
155+
```
156+
157+
More information on `infrahubctl` command line utility can be found [here]($(base_url)infrahubctl/infrahubctl).
158+
More information on the `object` subcommand can be found [here]($(base_url)infrahubctl/infrahubctl-object).
159+
160+
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.
161+
162+
:::info
163+
164+
Loading objects using git or via the command line will load folders/files in alphabetical order.
165+
166+
:::

‎docs/docs/topics/infrahub-yml.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ An external repository can be used to link the following Infrahub objects to an
1010

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

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

65+
## Objects
66+
67+
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`.
68+
69+
:::info
70+
71+
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.
72+
73+
:::
74+
<details>
75+
<summary>Example</summary>
76+
77+
```yaml
78+
objects:
79+
- objects/locations.yml
80+
- objects/devices
81+
```
82+
83+
</details>
84+
85+
## Menus
86+
87+
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`.
88+
89+
<details>
90+
<summary>Example</summary>
91+
92+
```yaml
93+
menus:
94+
- menus/base.yml
95+
```
96+
97+
</details>
98+
6399
## Jinja2 transformation {#transform-jinja-2}
64100

65101
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

‎docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ const sidebars: SidebarsConfig = {
6767
'guides/create-schema',
6868
'guides/import-schema',
6969
'guides/menu',
70+
'guides/object-load',
7071
'guides/computed-attributes',
7172
'guides/resource-manager',
7273
'guides/accounts-permissions',

0 commit comments

Comments
 (0)