Skip to content

Commit 9a26a24

Browse files
dgarrosdgarros
committed
Add docs
1 parent 58a2f49 commit 9a26a24

File tree

2 files changed

+184
-0
lines changed

2 files changed

+184
-0
lines changed

‎docs/docs/python-sdk/topics/object_file.mdx‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: Manage data with Object Files
3+
---
4+
5+
# Manage data with Object filess
6+
7+
## Introduction
8+
9+
An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema.
10+
11+
Object files work well for models that don't change too often and/or that needs to be tracked in Git: Examples: Groups, tags, Users etc ..
12+
Below is an example of an Object file that defines tags (`BuiltinTag`).
13+
14+
```yaml
15+
---
16+
apiVersion: infrahub.app/v1
17+
kind: Object
18+
spec:
19+
kind: BuiltinTag
20+
data:
21+
- name: Blue
22+
- name: Yellow
23+
- name: Red
24+
```
25+
26+
Object files are meant to be used in an idempotent way and as such they would work better for models with a Human Friendly ID (hfid) defined.
27+
28+
## Load Object files into Infrahub
29+
30+
Object files can be loaded into Infrahub using the `infrahub load object` command.
31+
32+
```bash
33+
infrahub object load <path_to_object_file>
34+
```
35+
36+
Multiple object files can be loaded at once by specifying the path to multiple files or by specifying a directory.
37+
38+
The object `object load` command will create/update the objects using an `Upsert` operation. All objects previously loaded will NOT be deleted in the Infrahub instance.
39+
Also, if some objects present in different files are identical are dependent on each other, the `object load` command will NOT calculate the dependencies between the objects and as such it's the reponsability of the users to execute the command in the right order.
40+
41+
### Validate the format of the object facilitates
42+
43+
The object file can be validated using the `infrahub object validate` command.
44+
45+
```bash
46+
infrahub object validate <path_to_object_file>
47+
```
48+
49+
## Object file format
50+
51+
All object files must start with the following format, all other format will be automatically ignored
52+
Each file is intended for one specific top level kind, but one file can include multiple nested objects of any kind.
53+
The kind of the top level object must be defined in spec/kind
54+
55+
```yaml
56+
---
57+
apiVersion: infrahub.app/v1
58+
kind: Object
59+
spec:
60+
kind: <NamespaceName>
61+
data:
62+
- [...]
63+
```
64+
65+
> Multiple documents in a single Yaml file are also supported, each document will be loaded as a separately. Documents are separated by `---`
66+
67+
### Relationship of cardinality One
68+
69+
A relationship of cardinality one can either reference an existing node via its HFID or create a new node if it doesn't exist.
70+
In the example below, both `site` and `primary_ip` are relationship of cardinality one.
71+
72+
```yaml
73+
---
74+
apiVersion: infrahub.app/v1
75+
kind: Object
76+
spec:
77+
kind: InfraDevice
78+
data:
79+
- name: edge01
80+
site: "Paris" # Reference existing node via its HFID
81+
primary_ip: # Nested object, will be created if it doesn't exist
82+
data:
83+
address: "192.168.1.1"
84+
```
85+
86+
87+
### Relationship of cardinality Many
88+
89+
A relationship of cardinality many can reference existing nodes via their HFID or define nested objects
90+
91+
#### Existing nodes referenced by their HFID
92+
93+
Existing nodes can be referenced by their HFID in string format or in list format.
94+
In the example below, both `best_friends` and `tags` are relationship of cardinality many.
95+
96+
> An HFID is composed of a single value, it's possible to use a string instead of a list
97+
98+
```yaml
99+
---
100+
apiVersion: infrahub.app/v1
101+
kind: Object
102+
spec:
103+
kind: TestingPerson
104+
data:
105+
- name: Mike Johnson
106+
height: 175
107+
best_friends: # Relationship of cardinality many that referenced existing nodes based on their HFID
108+
- [Jane Smith, Max]
109+
- [Sarah Williams, Charlie]
110+
tags:
111+
- Veterinarian # Existing Node referenced by its HFID in string format
112+
- [Breeder] # Existing Node referenced by its HFID in list format
113+
```
114+
115+
116+
117+
#### Nested Objects
118+
119+
When defining nested objects, the node will be automatically created if it doesn't exist and if their relationship between the parent object and the nested object it will be automatically inserted.
120+
For example, in the example below, the `owner` of a `TestingDog` doesn't need to be specify because it will be automatically inserted.
121+
122+
For 2 different syntaxes are supported:
123+
- A dictionnary with multiple value under data
124+
- A list of objects
125+
126+
##### Nested objects as a dictionary
127+
128+
In the example below, `tags` is a relationship of cardinality many that is defined as a dictionnary with multiple values under data.
129+
130+
> The kind is optional here because there is only one option possible (not a generic)
131+
132+
```yaml
133+
---
134+
apiVersion: infrahub.app/v1
135+
kind: Object
136+
spec:
137+
kind: TestingPerson
138+
data:
139+
- name: Alex Thompson
140+
tags:
141+
data:
142+
- name: dog-lover
143+
description: "Dog Lover"
144+
- name: veterinarian
145+
description: "Veterinarian"
146+
```
147+
148+
This format works well when all objects are of the same kind and when all objects are using the same properties.
149+
For more complex cases, the list of objects format is more flexible.
150+
151+
##### Nested objects as a list of objects
152+
153+
In the example below, `animals` is a relationship of cardinality many that is defined as a list of objects.
154+
Each object must contains a `data` key and each object can also define a specific `kind`.
155+
156+
> If the kind is not specified, it will be inferred from schema
157+
158+
```yaml
159+
---
160+
apiVersion: infrahub.app/v1
161+
kind: Object
162+
spec:
163+
kind: TestingPerson
164+
data:
165+
- name: Alex Thompson
166+
height: 180
167+
animals:
168+
- kind: TestingDog
169+
data:
170+
name: Max
171+
weight: 25
172+
breed: Golden Retriever
173+
color: "#FFD700"
174+
- kind: TestingCat
175+
data:
176+
name: Mimi
177+
breed: Persian
178+
```
179+
180+
### Support for Metadata
181+
182+
Please stay tuned, the Object file does not support metadata yet, neither on attribute or relationship.
183+

‎docs/sidebars-python-sdk.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const sidebars: SidebarsConfig = {
3131
label: 'Topics',
3232
items: [
3333
'topics/tracking',
34+
'topics/object_file',
3435
],
3536
},
3637
{

0 commit comments

Comments
 (0)