From 364caf22a70237d51f7b0c869e55930bd2b9fef1 Mon Sep 17 00:00:00 2001
From: xenobyte <admin@noreply.suka.moe>
Date: Tue, 16 Dec 2025 01:30:27 +0000
Subject: [PATCH] Add Inventory Scope

---
 Inventory-Scope.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 Inventory-Scope.md

diff --git a/Inventory-Scope.md b/Inventory-Scope.md
new file mode 100644
index 0000000..ea861e0
--- /dev/null
+++ b/Inventory-Scope.md
@@ -0,0 +1,69 @@
+# Inventory Scope
+
+Herein the variables at or in the inventory scope are explained further. We already have the following table [from the overview](https://git.sukaato.moe/admin/skato-ansible/wiki#variable-names-and-their-scopes):
+
+name | type | value validity rule | default value
+---|---|---|---|---
+`fqdn` | `<str>` | fully qualified domain name | none
+`vps_service` | `<dict{<str>:<str\|bool\|list>}>` | valid fields providing data for spinning up new VPS | none
+`groups` | `<dict{$group_name:<dict>}>` | fields/keys that are group names with data configuring that group | none
+`users` | `<dict{$user_name:<dict>}>` | fields/keys that are user names with data configuring that user | none
+`keywords` | `<list[<str>]>` | strings that describe the VPS, useful for applying tags if allowed by API | none
+`custom_vars` | `<dict{<str>:<any>}>` | your own custom variables, though there are some reserved variable names for this namespace | none
+
+> [!NOTE]
+> These variables should be defined either per host or per group, as they may be distinct for each host/group.
+> Consequently, it is preferable to to define these variables in files under `$SKATO_ANSIBLE_ROOT/group_vars` or 
+> `$SKATO_ANSIBLE/host_vars`, each  file having the name of the relevant inventory host or group.
+
+## `fqdn`
+
+The `fqdn` variable, whose name is the acronym for [Fully Qualified Domain Name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name), takes in exactly that as its value: a fully qualified domain name (as a `<str>` data type). This is essentially the [domain name](https://en.wikipedia.org/wiki/Domain_name) associated to the [public](https://en.wikipedia.org/wiki/IP_address#Public_address) [IP address](https://en.wikipedia.org/wiki/IP_address) of your [Virtual Private Server](https://en.wikipedia.org/wiki/Virtual_private_server), or that you entered into a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Resource_records) pointing to the public IP address of that Virtual Private Server. For example, `sukaato.moe` would be the relative [top-level domain](https://en.wikipedia.org/wiki/Top-level_domain) for the [server](https://en.wikipedia.org/wiki/Server) this [Gitea](https://about.gitea.com/) instance is on, `git.sukaato.moe` being a [subdomain](https://en.wikipedia.org/wiki/Subdomain).
+
+Here is an example:
+
+```yaml
+# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
+fqdn: "sukaato.moe"
+```
+
+## `vps_service`
+
+The `vps_service` takes in a dictionary data type as value, that itself has the following fields or keys that have as value particular data types:
+
+key | value type | purpose
+---|---|---
+`exists` | `<bool>` |  determines whether the VPS is to be created
+`password` | `<str>` | the password to be given to the intiial root user
+`api_key` | `<str>` | the API key to take control of your account in order to create the VPS
+`type` | `<str>` | the name or ID of the VPS service being used (so far, only "linode" is possible to use)
+`region` | `<str>` | the geographical region the VPS will be spawned in / make connections from--must follow the convention established by the VPS service
+`ssh_authorized_keys` | `<list[<str>]>` (each item is the content of a public key file) | determines the public keys that that are authorized to access the VPS as `root`
+`root_fate` | `<str>` | if the string states "disposal," this means we do not want to retain SSH or login access to the root account after some necessary initial set-up
+`ssh_private_key_paths` | `<list[<str>]>` | determines the private keys on local machine to be used to access the VPS via SSH as `root`
+`ssh_motd_script_basenames` | `<list[<str>]>`  (each item is a basename of a bash script file in `$SKATO_ANSIBLE_ROOT/roles/bootstrap/files/update-motd.d`) | determines which script files in the aforementioned path are used for SSH MOTD
+`ssh_private_key_path_pref` | `<int>` (corresponds to an index of `ssh_private_key_paths`, so must be less than `len(ssh_private_key_paths)`) | determines the default private key file used to access VPS via SSH as `root`
+
+Here is an example:
+
+```yaml
+# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
+vps_service:
+  exists: true
+  password: "password123"
+  api_key: "sajhnglajgknjwfjioAJGGJP"
+  type: "linode"
+  region: "us-east"
+  ssh_authorized_keys:
+    - "sk-ecdsa-sha2-nistp256@openssh.com AAASAgsflgkjzldoijrta[hjwe[hafWRYASFHzdmvgjheaaWRAFGHn== anon@device"
+  root_fate: "disposal"
+  ssh_private_key_paths:
+    -" ${HOME}/.ssh/id_ecdsa-vps.ppk"
+  ssh_private_key_path_pref: 0
+  ssh_motd_script_basenames:
+    - "00-logo.sh"
+    - "01-data.sh"
+```
+
+> **TBC**
+> This Wiki page remains unfinished. Check back later.
\ No newline at end of file