add SAT file docs

docs/sat.md

@@ -1 +1,121 @@
 # SAT file
+
+Manta is compatible with `sat bootprep` file features. 
+Manta extends SAT file features:
+
+## SAT files cannot have configurations only
+
+Currently, the management plane does not track which cluster belongs to each configuration unless a node is booting using an image or a 
+
+The example below won't work
+
+```bash
+cat my_sat_file.yml
+---
+configurations:
+- name: "my-configuration"
+  layers:
+  - name: test_layer
+    playbook: site.yml
+    git:
+      url: https://api-gw-service-nmn.local/vcs/cray/test_layer.git
+      tag: 1.0  # Using git tags
+```
+
+The file neither have a image nor a session_template section, therefore there is no way for manta to track to which cluster this configuration belongs to, therefore, it won't be able to track which user has access to it.
+
+The example below is correct
+
+```bash
+cat my_sat_file.yml
+---
+schema_version: 1.0.2
+configurations:
+- name: "runtime-{{vcluster.name}}-mc-{{default.suffix}}-{{vcluster.version}}"
+  layers:
+  - name: test_layer
+    playbook: site.yml
+    git:
+      url: https://api-gw-service-nmn.local/vcs/cray/test_layer.git
+      tag: {{test_layer.tag}}
+
+session_templates:
+- name: "{{vcluster.name}}-mc-{{default.suffix}}-{{vcluster.version}}.x86_64"
+  ims:
+    is_recipe: false
+    id: dbc5300c-3c98-4384-a7a7-28e628cbff43
+  configuration: "runtime-{{vcluster.name}}-mc-{{default.suffix}}-{{vcluster.version}}"
+  bos_parameters:
+    boot_sets:
+      compute:
+        arch: X86
+        kernel_parameters: ip=dhcp quiet ksocklnd.skip_mr_route_setup=1 cxi_core.disable_default_svc=0 cxi_core.enable_fgfc=1 cxi_core.sct_pid_mask=0xf spire_join_token=${SPIRE_JOIN_TOKEN}
+        node_groups:
+          {{ vcluster.sessiontemplate_group_list }}
+        rootfs_provider_passthrough: "dvs:api-gw-service-nmn.local:300:hsn0,nmn0:0"
+```
+
+## Extra features
+
+### jinja2 templating: 
+
+While sat bootprep templating seems very simple, manta uses the jinja2 engine. One thing to note is to avoid using `-` in variable names since jinja will expand this as a math operator, to avoid this issue, try to use `_` instead.
+
+The example below will fail
+
+template file:
+
+```yaml
+session_templates:
+- name: "my-session-{{ session-version }}" # Won't work. Error when resolving `session-version` because `-` is a math operator. Don't use `-` in variable names
+  ims:
+    id: dbc5300c-3c98-4384-a7a7-28e628cbff43
+  configuration: "my-configuration"
+...
+```
+
+var session file
+
+```yaml
+session-version: 1.0 # Won't work. Variable names should not have `-`
+...
+```
+
+The example below is correct
+
+template file:
+
+```yaml
+session_templates:
+- name: "my-session-{{ session_version }}"
+  ims:
+    id: dbc5300c-3c98-4384-a7a7-28e628cbff43
+  configuration: "my-configuration"
+...
+```
+
+var session file
+
+```yaml
+session_version: 1.0
+...
+```
+
+### git tags
+
+Manta can resolve git tags in configuration layers
+
+```yaml
+---
+configurations:
+- name: "my-configuration"
+  layers:
+  - name: test_layer
+    playbook: site.yml
+    git:
+      url: https://api-gw-service-nmn.local/vcs/cray/test_layer.git
+      tag: 1.0  # Using git tags
+...
+```
+
+In the example above, we are telling manta we want Alps to use the ansible in repo `test_layer` based on git tag `1.0`. As a consequence, Manta will resolve the git tag to its commit id, set this value in the sat file configuration layer and submit the configuration craetion task to Alps management plane.