Add Role Scope
124
Role-Scope.md
Normal file
124
Role-Scope.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Role 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
|
||||
---|---|---
|
||||
`software` | `<dict{<str>:<dict>}>` | valid fields providing data for software installations
|
||||
`config` | `<dict{$software_name:<dict>}>` | software name fields providing data for configuring that software
|
||||
|
||||
> [!NOTE]
|
||||
> These variables' values should be defined in either a `main.yml` under the `bootstrap` role's `vars` directory, or in an arbitrarily named YAML file under a `main` subdirectory of the `bootstrap` role's `vars` directory. In fact, the latter is preferred, with the filename being `software.yml`.
|
||||
|
||||
## `software`
|
||||
|
||||
The `software` takes a dictionary value that includes the following fields/keys:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`pkgs` | `<dict{$corresponding_handler_name:<dict>}>` | determines what packages to install that are accessible via the VPS's native package management system
|
||||
`snaps` | `<dict{$corresponding_handler_name}:<dict>>` | determines what software to install that are accessible via the VPS's newly installed snapd package service
|
||||
`containers` | `<dict{$corresponding_handler_name}:<dict>>` | determines what images to download from a container registry onto the VPS
|
||||
`links` | `<dict{$corresponding_handler_name}:<dict>>` | determines what links to pull or download from to build given software in the VPS (e.g., a git repo link, source archive, package file, script, etc.)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The key/field of each of these keys'/fields' dictionary value must be a name that corresponds to the `listen` name given to a handler in the `bootstrap` role that handles the details of the software configuration process, and that is notified after the software had been installed. Handlers in a role are found under the `handlers` directory of that role's directory.
|
||||
|
||||
Since each of these themselves take dictionary data types as their value, those having conventional/valid fields/keys, it is necessary to go through each one's dictionary field/keys separately.
|
||||
|
||||
### `pkgs`
|
||||
|
||||
This `pkgs` key or field of `software` takes in a dictionary comprised of the following keys/fields:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`$corresponding_handler_name` | `<dict{<str>:<dict>}>`| determines the package to be installed by the VPS's package manager
|
||||
|
||||
The dictionary taken by `$corresponding_handler_name` has at least a field/key of `name`, that itself takes in a dictionary value with field/key named after the package manager for whom the package name it takes as value applies, e.g.:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`name` | `<dict{$package_manager_name:<str>}>` | determines the name to be searched for finding the package under the given package manager to be installed by it
|
||||
|
||||
Here is an example of how one would write a package entry under `pkgs` in `software`:
|
||||
|
||||
```yaml
|
||||
software:
|
||||
pkgs:
|
||||
php-lang:
|
||||
name:
|
||||
apt: "php"
|
||||
```
|
||||
|
||||
### `snaps`
|
||||
|
||||
This `snaps` key or field of `software` takes in a dictionary comprised of the following keys/fields:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`$corresponding_handler_name` | `<dict{<str>:<dict>}>`| determines the package to be installed by the VPS's package manager
|
||||
|
||||
The dictionary taken by `$corresponding_handler_name` has the following keys/fields:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`name` | `<str>` | determines the name to be searched for finding the snap
|
||||
`channel` | `<str>` | determines the channel the snap name is being searched in/through
|
||||
`opts` | `<list[<str>]>` | determines some configuration options to set on snap installation
|
||||
|
||||
> [!IMPORTANT]
|
||||
> For `opts` in particular, each string must have a valid syntax that corresponds to that accepted by the `options` field for the Ansible `community.general.snap` module. For more, see [this](https://docs.ansible.com/projects/ansible/latest/collections/community/general/snap_module.html#parameter-options).
|
||||
|
||||
Here is an example of how one would write a snap entry under `snaps` in `software`:
|
||||
|
||||
```yaml
|
||||
snaps:
|
||||
nextcloud:
|
||||
name: "nextcloud"
|
||||
channel: ~
|
||||
opts:
|
||||
- "nextcloud:php.memory-limit=512M"
|
||||
- "nextcloud:nextcloud.cron-interval=10m"
|
||||
- "nextcloud:http.compression=true"
|
||||
- "nextcloud:ports.http=81"
|
||||
```
|
||||
|
||||
### `containers`
|
||||
|
||||
> [!NOTE]
|
||||
> No `containers`' value validity rules have been declared yet, as it is highly recommended to instead use Compose files for image installation and container management. As of right now, this field or key essentially does nothing. An example Compose file can be found in [this repo](https://git.sukaato.moe/admin/skato-compose/src/branch/main/compose.yml).
|
||||
|
||||
### `links`
|
||||
|
||||
This `links` key or field of `software` takes in a dictionary comprised of the following keys/fields:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`$corresponding_handler_name` | `<dict{<str>:<dict>}>`| determines the network resource to be pulled for software building or installation on the VPS
|
||||
|
||||
The dictionary taken by `$corresponding_handler_name` has the following keys/fields:
|
||||
|
||||
key | value type | purpose
|
||||
---|---|---
|
||||
`name` | `<str>` | determines the name to be conventionally used for this software
|
||||
`src` | `<str>` (a URI/URL to a package file, installation script, source archive, git repo, etc.) | determines the network location of the software or software-related resource
|
||||
`branch` | `<str>`(branch name or path to the preferred software version) | specifies the relevant files for the software build or installation
|
||||
`version` | `<str>` (version name) | specifies the version name of the software version to be installed or built
|
||||
`output` | `<str>` (path to a resulting file or name of or reference to a desired state) | determines either what the software build/installation will output, or what result to track to confirm successful build/installation
|
||||
|
||||
Here is an example of how one would write a link entry under `links` in `software`:
|
||||
|
||||
```yaml
|
||||
links:
|
||||
quartz:
|
||||
name: "quartz"
|
||||
src: "https://github.com/jackyzha0/quartz.git"
|
||||
branch: "v4"
|
||||
version: ~
|
||||
output: ~
|
||||
```
|
||||
|
||||
## `config`
|
||||
|
||||
> **TBC**
|
||||
> This page of the documentation is still a work in progress. Revisit later.
|
||||
Reference in New Issue
Block a user