From 91a79f459ca71e38e33bf329cae62a75863b6f24 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Sun, 5 Nov 2023 20:25:15 -0600 Subject: [PATCH 01/16] refactor: move architecture section --- astro.config.mjs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index a7bc050..a84ca63 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -132,14 +132,14 @@ export default defineConfig({ }, sidebar: [ { label: 'Getting Started', link: '/getting-started' }, - { - label: 'Ingredients', - autogenerate: { directory: 'ingredients' }, - }, { label: 'Architecture', autogenerate: { directory: 'architecture' }, }, + { + label: 'Ingredients', + autogenerate: { directory: 'ingredients' }, + }, ], }), tailwind({ From 70d28cd02b4dc29ab0d039c49134b2d4d10c3797 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Sun, 5 Nov 2023 21:52:25 -0600 Subject: [PATCH 02/16] feat(architecture): add diagram --- src/assets/grlx-arch-dark.webp | 3 +++ src/assets/grlx-arch-light.webp | 3 +++ src/components/ArchitectureImage.astro | 16 ++++++++++++++++ .../architecture/{overview.md => overview.mdx} | 4 ++++ src/custom.css | 4 ++++ 5 files changed, 30 insertions(+) create mode 100644 src/assets/grlx-arch-dark.webp create mode 100644 src/assets/grlx-arch-light.webp create mode 100644 src/components/ArchitectureImage.astro rename src/content/docs/architecture/{overview.md => overview.mdx} (88%) diff --git a/src/assets/grlx-arch-dark.webp b/src/assets/grlx-arch-dark.webp new file mode 100644 index 0000000..0c39050 --- /dev/null +++ b/src/assets/grlx-arch-dark.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c0be79de7cde17b03b1e46ef75edb2baebebd32b0605bad3fcb3a2babe924e6 +size 68258 diff --git a/src/assets/grlx-arch-light.webp b/src/assets/grlx-arch-light.webp new file mode 100644 index 0000000..8e42672 --- /dev/null +++ b/src/assets/grlx-arch-light.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:852c13313142bfb83fefad5bbabd64f5e9f9eba95ef7bf180553dbe140ba2f24 +size 66244 diff --git a/src/components/ArchitectureImage.astro b/src/components/ArchitectureImage.astro new file mode 100644 index 0000000..9f6482d --- /dev/null +++ b/src/components/ArchitectureImage.astro @@ -0,0 +1,16 @@ +--- +import { Image } from 'astro:assets' +import darkArch from "../assets/grlx-arch-dark.webp" +import lightArch from '../assets/grlx-arch-light.webp' +--- + +ADAtomic logo + diff --git a/src/content/docs/architecture/overview.md b/src/content/docs/architecture/overview.mdx similarity index 88% rename from src/content/docs/architecture/overview.md rename to src/content/docs/architecture/overview.mdx index 64d4c26..7738bd5 100644 --- a/src/content/docs/architecture/overview.md +++ b/src/content/docs/architecture/overview.mdx @@ -2,8 +2,12 @@ title: Overview description: A brief description of the grlx architecture --- + +import ArchitectureImage from '../../../components/ArchitectureImage.astro' + At a high level our architecture looks like the following: + We can boil down the `grlx` into three different parts: the farmer, the sprout, and the CLI. ## Farmer diff --git a/src/custom.css b/src/custom.css index 43e37eb..149e979 100644 --- a/src/custom.css +++ b/src/custom.css @@ -3,3 +3,7 @@ --sl-card-border: #454FBF !important; } +[data-theme="light"] .hidden{ + display: none; +} + From d94684af716ef0a09c606dd4fbac0352a5bd09b1 Mon Sep 17 00:00:00 2001 From: "J. Scott Smith" Date: Sun, 5 Nov 2023 20:12:09 -0800 Subject: [PATCH 03/16] updated quick start, details and corrections after testing --- .prettierignore | 1 + src/content/docs/getting-started.mdx | 60 +++++++++++++++++++--------- 2 files changed, 42 insertions(+), 19 deletions(-) create mode 100644 .prettierignore diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..dd08120 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +**/*.mdx diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx index bebf2da..374f7fc 100644 --- a/src/content/docs/getting-started.mdx +++ b/src/content/docs/getting-started.mdx @@ -62,6 +62,9 @@ Install the CLI on your development machine with the correct command for your ar You'll be asked some questions, such as which interface the farmer is listening on, and which ports to use for communication. Set the interface to the domain name or IP address of the farmer. + +If you plan to install the farmer on k3s (see below), then use the IP address of your k3s server, API port 30405, and Bus port 30406. If you plan to locally run the Docker Compose file below, then all of the defaults are good (localhost and default ports). + Once configured, the CLI prints out your administrator public key, which you'll need for the next step! It's recommended you now add `grlx` somewhere in your `$PATH`. @@ -83,7 +86,9 @@ You will then need to install the farmer on the management server. The farmer is Make sure the certificate host name matches the external-facing interface (a domain or IP address) as it will be used for TLS validation! - Deploy the following to your k3s cluster: + Copy the resource YAML below. Replace `PASTE_YOUR_PUBLIC_KEY_HERE` with your admin public key, and `PASTE_YOUR_FARMERINTERFACE_HERE` with the domain name or IP address of the farmer. + + Deploy the farmer, e.g. `kubectl apply -f grlx-farmer.yaml`. This will deploy a single farmer to which you can add many external sprouts. ```yaml apiVersion: v1 kind: Service @@ -122,34 +127,42 @@ You will then need to install the farmer on the management server. The farmer is - name: main image: grlx/farmer:latest env: - - name: CERT_HOSTS - value: "192.168.1.60" - - name: FARMERAPIPORT - value: "5405" - - name: FARMERBUSPORT - value: "5406" - - name: FARMERINTERFACE - value: "0.0.0.0" - - name: ORGANIZATION - value: "Your Organization" - name: ADMIN_PUBKEYS value: "PASTE_YOUR_PUBLIC_KEY_HERE" + - name: CERT_HOSTS + value: "localhost,PASTE_YOUR_FARMERINTERFACE_HERE" + - name: FARMERINTERFACE + value: "0.0.0.0" # do not modify + - name: FARMERORGANIZATION + value: "Your Organization" # change to your org name ports: - name: api containerPort: 5405 - name: bus containerPort: 5406 volumeMounts: - - name: store + - name: cache + mountPath: /var/cache/grlx + - name: config mountPath: /etc/grlx + - name: data + mountPath: /srv/grlx volumes: - - name: store + - name: cache + emptyDir: {} + - name: config + hostPath: + path: /etc/grlx + type: DirectoryOrCreate + - name: data hostPath: path: /srv/grlx type: DirectoryOrCreate ``` + Copy the Docker Compose YAML below. Replace `PASTE_YOUR_PUBLIC_KEY_HERE` with your admin public key, then `docker compose up` to fire up an all-in-one farmer/sprout environment. + ```yaml version: "3" services: @@ -158,15 +171,15 @@ You will then need to install the farmer on the management server. The farmer is image: grlx/farmer:latest hostname: farmer environment: - - ADMIN_PUBKEYS= + - ADMIN_PUBKEYS=PASTE_YOUR_PUBLIC_KEY_HERE - CERT_HOSTS=localhost,farmer - - FarmerInterface=0.0.0.0 + - FARMERINTERFACE=0.0.0.0 volumes: - ./local/farmer:/etc/grlx ports: - "5405:5405" - "5406:5406" - sprout: + sprout: # for testing grlx features only, not for production container_name: sprout image: grlx/sprout:latest hostname: sprout @@ -185,12 +198,19 @@ You will then need to install the farmer on the management server. The farmer is The sprout is the agent that runs on every node you want to manage. It's responsible for executing commands and reporting back to the farmer. ```bash -# or, just run as root instead of sudo -# FARMER_BUS_PORT and FARMER_API_PORT variables are available in case you chose -# to use different ports. +# Be sure to change FARMERINTERFACE to the domain or IP address of the farmer. +# FARMERBUSPORT and FARMERAPIPORT variables are available in case you need +# to use different ports (see k3s note below). curl -L https://bootstrap.grlx.dev/latest/sprout | FARMERINTERFACE=localhost sudo -E bash ``` +NOTE: If you deployed the k3s farmer above, then use: + +```bash +# Be sure to change FARMERINTERFACE to the domain or IP address of the farmer. +curl -L https://bootstrap.grlx.dev/latest/sprout | FARMERBUSPORT=30406 FARMERAPIPORT=30405 FARMERINTERFACE=localhost sudo -E bash +``` + Once the sprout is up and running, return to the CLI. --- @@ -200,6 +220,8 @@ Once the sprout is up and running, return to the CLI. Next, you must accept each sprout's public key and the farmer's TLS certificate. This is done using the `keys` command. Furthermore, using `grlx version`, shows you that you are able to connect to your farmer. ```bash +# You will be asked to download and trust the TLS certificate for +# the farmer, choose Y. grlx version grlx keys accept -A ``` From 073fb07293a883c850e735683beb159b7dc227d1 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Sun, 5 Nov 2023 22:45:09 -0600 Subject: [PATCH 04/16] feat(file): added file.touch --- src/content/docs/ingredients/file.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/content/docs/ingredients/file.md b/src/content/docs/ingredients/file.md index ecd0000..6e7481f 100644 --- a/src/content/docs/ingredients/file.md +++ b/src/content/docs/ingredients/file.md @@ -147,3 +147,20 @@ file.symlink: - name: ~/localbash - target: /usr/bin/bash ``` + +## **file.touch** +Performs a `touch` on a file +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file +| _atime_ | time (RFC339) | no | the access time to set the file to, set to the current time by default +| _mtime_ | time (RFC339) | no | the modified time to set the file to, sets to the current time by default +| _makedirs_ | bool | yes | whether or not to create any provided parent directories, false by default +```yaml +file.touch: + - name: /tmp/parent/new-file + - atime: Mon, 06 Nov 2023 00:00:00 +0000 + - mtime: Mon, 06 Nov 2023 00:00:00 +0000 + - makedirs: true +``` + From ecba814119888b3579906f55f87a098e73ac0e85 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Sun, 5 Nov 2023 22:45:39 -0600 Subject: [PATCH 05/16] fix(css): chagned to correct Discord color --- src/custom.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/custom.css b/src/custom.css index 149e979..39c3006 100644 --- a/src/custom.css +++ b/src/custom.css @@ -1,5 +1,5 @@ .discord-bg .card .icon{ - background-color: #7289da; + background-color: #5865F2; --sl-card-border: #454FBF !important; } From c1b0769c2c8f87603a579cfe6e305ff26d19a508 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 09:45:29 -0600 Subject: [PATCH 06/16] feat: added email to socials --- astro.config.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/astro.config.mjs b/astro.config.mjs index a84ca63..b6dc641 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -129,6 +129,7 @@ export default defineConfig({ github: 'https://github.com/gogrlx/grlx', 'x.com': 'https://x.com/gogrlx', discord: 'https://discord.gg/RNsZ3KWjXm', + email: 'mailto:grlx@adatomic.com?subject=Question' }, sidebar: [ { label: 'Getting Started', link: '/getting-started' }, From 570219b9f92642484d56fa8c9b49a0bc260a8261 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 09:57:04 -0600 Subject: [PATCH 07/16] chore: added csepll for spell checking --- cspell.json | 13 +++++++++++++ flake.nix | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 cspell.json diff --git a/cspell.json b/cspell.json new file mode 100644 index 0000000..c7e2a3c --- /dev/null +++ b/cspell.json @@ -0,0 +1,13 @@ +{ + "version": "0.2", + "language": "en", + "words": [ + "grlx", + "FARMERINTERFACE", + "FARMERORGANIZATION", + "NATS", + "FARMERBUSPORT", + "FARMERAPIPORT", + "PUBKEYS", + ], +} diff --git a/flake.nix b/flake.nix index 84f828a..a198b43 100644 --- a/flake.nix +++ b/flake.nix @@ -23,7 +23,7 @@ # Equivalent to inputs'.nixpkgs.legacyPackages.hello; devShells.default = pkgs.mkShell { - nativeBuildInputs = with pkgs; [ nodejs_18 nodePackages_latest.prettier]; + nativeBuildInputs = with pkgs; [ nodejs_18 nodePackages_latest.prettier nodePackages_latest.cspell ]; }; }; flake = { From 89c13a28739c8df03780916ea68885484b8f07ec Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 10:00:04 -0600 Subject: [PATCH 08/16] fix: spelling updates --- src/content/docs/architecture/overview.mdx | 12 ++++++------ src/content/docs/ingredients/file.md | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/architecture/overview.mdx b/src/content/docs/architecture/overview.mdx index 7738bd5..06838b0 100644 --- a/src/content/docs/architecture/overview.mdx +++ b/src/content/docs/architecture/overview.mdx @@ -5,19 +5,19 @@ description: A brief description of the grlx architecture import ArchitectureImage from '../../../components/ArchitectureImage.astro' -At a high level our architecture looks like the following: +At a high level the grlx architecture looks like the following: We can boil down the `grlx` into three different parts: the farmer, the sprout, and the CLI. ## Farmer - -The farmer is your control server. This has analogs in other similar configuration platforms. In SaltStack, this is your Salt Master, or in Chef, your Chef Server. `grlx` utilizes the farmer for things like authentication, job processing, and [ingredients](/architecture/overview#ingredients). +The farmer is your management server running the `grlx-farmer` binary. The binary can run as a systemd service or be hosted in a container. This has analogs in other similar configuration platforms such as a Salt Master in SaltStack or a Chef Server in Chef. grlx utilizes the farmer for things like authentication, job processing, and [ingredients](/architecture/overview#ingredients). Additionally, the farmer contains is responsible for holding your [recipes](/architecture/overview#recipes). ## Sprout - -The sprout is what the farmer manages. This is similar to a Salt Minion in SaltStack or a Chef Client in Chef. Jobs are received from the farmer over the NATS message bus for actions to be performed on the sprout itself. +The sprout is a managed node running the `grlx-sprout` binary. Sprouts receive commands from the farmer over the NATS message bus. These can be immediate shell commands, or actions that are performed by Ingredients defined in a recipe (e.g. ensure that a file exists, a service is started). Sprouts are similar to a Salt Minion in SaltStack or a Chef Client in Chef. Jobs are received from the farmer over the NATS message bus. Sprouts will then execute the job and report back to the farmer the results of the job. ## CLI +The CLI is a tool used to interact with the farmer and manage sprouts. The CLI is used to accept keys from sprouts and `cook` (run) recipes that are hosted on the farmer. The CLI also contains tools to tail the traffic over the NAT bus, test sprout connections, and run arbitrary commands on sprouts. -## Ingredients +## Recipes +Recipes are the core of grlx and are responsible for handling the configuration of your sprouts. Recipes are written with the `.grlx` extension and are a combination of YAML and Go templates. Recipes are stored on the farmer and are executed by the sprouts. Recipes are responsible for defining the [ingredients](/architecture/overview#ingredients) and in what order they are executed. For more information see the [recipes](/recipes) section. diff --git a/src/content/docs/ingredients/file.md b/src/content/docs/ingredients/file.md index 6e7481f..4ec9256 100644 --- a/src/content/docs/ingredients/file.md +++ b/src/content/docs/ingredients/file.md @@ -12,7 +12,7 @@ Deletes a file or directory #### Example ```yaml file.absent: - name: ~/.config/sytemd/user/backup.service + name: ~/.config/systemd/user/backup.service ``` ## **file.append** @@ -61,7 +61,7 @@ Copies content into a given file #### Example ```yaml file.content: - - name: /srv/ngnix/nginx.conf + - name: /srv/nginx/nginx.conf - makdirs: true - text: | server { @@ -106,7 +106,7 @@ file.directory: - makdirs: false - user: grlx - group: grlx - - dir_moode: 755 + - dir_mode: 755 - recurse: false ``` From 1f61b3e09055aad5afcc3a8f8c89575b40ea97ba Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 11:11:37 -0600 Subject: [PATCH 09/16] feat(cmd): added rest of cmd interface --- src/content/docs/ingredients/cmd.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/content/docs/ingredients/cmd.md b/src/content/docs/ingredients/cmd.md index 3b815a4..e96b8e1 100644 --- a/src/content/docs/ingredients/cmd.md +++ b/src/content/docs/ingredients/cmd.md @@ -10,9 +10,19 @@ Runs shell commands against a sprout |-----------|------|----------|-------------| | _name_ | string | true | the command to run | _runas_ | string | false | user who will run this command +| _path_ | string | false | the path to the binary, this is prepended to the name +| _cwd_ | string | false | the directory to run this command +| _env_ | list | false | environmental variables to set like the following: key1=value1 +| _timeout_ | string | false | set a timeout for the command using [Go Duration](https://pkg.go.dev/time#ParseDuration) ```yaml cmd.run: - name: go version - runas: super-cool-user + - path: /usr/local/bin + - cwd: /tmp + - env: + - GOOS=linux + - GOARCH=arm64 + - timeout: 10s ``` From e2c671f727fdab1d808e4659a63a271db44a4462 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 11:35:02 -0600 Subject: [PATCH 10/16] fix(service): fixed service provider description --- src/content/docs/ingredients/service-providers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ingredients/service-providers.md b/src/content/docs/ingredients/service-providers.md index 108d2aa..5920be4 100644 --- a/src/content/docs/ingredients/service-providers.md +++ b/src/content/docs/ingredients/service-providers.md @@ -2,7 +2,7 @@ title: grlx.ingredients.service.providers description: grlx built-in service providers --- -grlx has a concept of service providers for different ways to interact with a sprout's various services. This uses a provider interface to keep this extensible and provide a standard way to interact with different service managers. The `go` interface for Service Providers looks like the following: +grlx has a concept of service providers for different ways to interact with a sprout's various services. This uses a provider interface to keep this extensible and provide a standard way to interact with different service managers. The Go interface for Service Providers looks like the following: ```go type ServiceProvider interface { Properties() (map[string]interface{}, error) @@ -30,7 +30,7 @@ type ServiceProvider interface { By default, grlx only has a `systemd` provider. ## systemd -The local provider would be how you would use a file from your host system. +The `systemd` provider is #### Example ```yaml service.disabled: From bb6b6551f6f14b7e909b3fc98cad8299eb3352ef Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 11:51:23 -0600 Subject: [PATCH 11/16] fix(getting-started): added uninstall for grlx-farmer --- src/content/docs/getting-started.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx index 374f7fc..a0ffa73 100644 --- a/src/content/docs/getting-started.mdx +++ b/src/content/docs/getting-started.mdx @@ -240,4 +240,7 @@ grlx -T \* cmd run --out json -- uname -a #### Uninstalling -If you ever need to uninstall `grlx` +If you ever need to uninstall the `grlx-farmer`, you can do so with the following commands: +```bash +curl -L https://bootstrap.grlx.dev/latest/farmer | UNINSTALL=true sudo bash +``` From 39f010aa75a59ef4f24f3b3e9da61185f6ee0ed9 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 15:40:53 -0600 Subject: [PATCH 12/16] fix(service): fixed unfinished servicer provider --- src/content/docs/ingredients/service-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ingredients/service-providers.md b/src/content/docs/ingredients/service-providers.md index 5920be4..f6d27be 100644 --- a/src/content/docs/ingredients/service-providers.md +++ b/src/content/docs/ingredients/service-providers.md @@ -30,7 +30,7 @@ type ServiceProvider interface { By default, grlx only has a `systemd` provider. ## systemd -The `systemd` provider is +The [`systemd` provider](/ingredients/service) allows for control over a sprout's `systemd` services. #### Example ```yaml service.disabled: From b2d2029142bb842e10840c04236b54f45c137ad5 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 17:12:04 -0600 Subject: [PATCH 13/16] style: added last updated --- astro.config.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/astro.config.mjs b/astro.config.mjs index b6dc641..fa512ed 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -109,6 +109,7 @@ export default defineConfig({ integrations: [ starlight({ title: 'grlx Docs', + lastUpdated: true, description: 'Documentation for grlx. Fleet configuration management that is low overhead, dependency free, and easy to install.', components: { From 77eb26e770f571ae3190ec22ef3d477bd16427a1 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 17:14:34 -0600 Subject: [PATCH 14/16] fix(file): removed S3 reference --- src/content/docs/ingredients/file-providers.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/content/docs/ingredients/file-providers.md b/src/content/docs/ingredients/file-providers.md index 7540a9e..6b2dbe2 100644 --- a/src/content/docs/ingredients/file-providers.md +++ b/src/content/docs/ingredients/file-providers.md @@ -12,7 +12,7 @@ type FileProvider interface { Verify(context.Context) (bool, error) } ``` -By default, `grlx` has three built-in providers: local, HTTP, and S3. +By default, `grlx` has two built-in providers: local and HTTP. ## Local The local provider would be how you would use a file from your host system. @@ -31,6 +31,3 @@ file.cached: - source: https://go.dev/dl/go1.21.3.src.tar.gz - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488 ``` - -## TODO: S3 -The S3 allows you to get a file from an S3 compatible bucket. From ac7c84b5cc36ebb5c6f6cf35ec505037c7b4d9d7 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 18:12:55 -0600 Subject: [PATCH 15/16] feat(ingredients): add user and group ingredients --- src/content/docs/ingredients/groups.md | 39 ++++++++++++++++++++ src/content/docs/ingredients/user.md | 51 ++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 src/content/docs/ingredients/groups.md create mode 100644 src/content/docs/ingredients/user.md diff --git a/src/content/docs/ingredients/groups.md b/src/content/docs/ingredients/groups.md new file mode 100644 index 0000000..818991f --- /dev/null +++ b/src/content/docs/ingredients/groups.md @@ -0,0 +1,39 @@ +--- +title: grlx.ingredients.group +desc: An overview of grlx.ingredients.group +--- +The group ingredient handles group operations on sprouts. +## **group.absent** +Removes a group +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | no | The name of the group to remove +```yaml +group.absent: + - name: sprout-group +``` + +## **group.exists** +Validates if a group exists +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | The group name to check +```yaml +group.exists: + - name: sprout-group +``` + +## **group.present** +Creates a group if it does not exist +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | The name of the group to create +| _gid_ | int | no | The GID of the group to create +```yaml +group.present: + - name: sprout-group + - gid: 1000 +``` diff --git a/src/content/docs/ingredients/user.md b/src/content/docs/ingredients/user.md new file mode 100644 index 0000000..7475818 --- /dev/null +++ b/src/content/docs/ingredients/user.md @@ -0,0 +1,51 @@ +--- +title: grlx.ingredients.user +desc: An overview of grlx.ingredients.user +--- +The user ingredient handles user operations on sprouts. +## **user.absent** +Removes a user if it exists +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name of the user to be removed +```yaml +user.absent: + - name: super-sprout +``` + +## **user.exists** +Validates if a user exists +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | The username to check +```yaml +user.exists: + - name: sprout-user +``` + +## **user.present** +Creates a new user if it does not exist +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | The username of the user +| _uid_ | int | no | The UID assigned to the user +| _gid_ | int | no | The GID to the user +| _groups_ | list, string | no | A list groups the user is part of +| _shell_ | bool | no | The user login shell, false by default +| _home_ | string | no | The path to the user's home directory if one is required +```yaml +user.present: + - name: sprout-user + - uid: 1000 + - gid: 1000 + - groups: + - wheel + - media + - sudo + - shell: no + - home: /var/sprout-user +``` + From 03ed831ef97f276750fb92aed7d828cf2707f935 Mon Sep 17 00:00:00 2001 From: Ethan Holz Date: Mon, 6 Nov 2023 18:13:30 -0600 Subject: [PATCH 16/16] feat(recipes): added initial recipe overview --- astro.config.mjs | 4 +++ src/content/docs/recipes/overview.md | 46 ++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 src/content/docs/recipes/overview.md diff --git a/astro.config.mjs b/astro.config.mjs index fa512ed..6860216 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -142,6 +142,10 @@ export default defineConfig({ label: 'Ingredients', autogenerate: { directory: 'ingredients' }, }, + { + label: 'Recipes', + autogenerate: { directory: 'recipes' }, + }, ], }), tailwind({ diff --git a/src/content/docs/recipes/overview.md b/src/content/docs/recipes/overview.md new file mode 100644 index 0000000..2d69874 --- /dev/null +++ b/src/content/docs/recipes/overview.md @@ -0,0 +1,46 @@ +--- +title: Overview +description: An overview of grlx recipes +--- +Recipes are the core of grlx functionality, providing a structured way for developers to deploy actions to sprouts. Recipes are a collection of ingredients which can be executed against a sprout. Recipes must be placed on the farmer at `/srv/grlx/recipes/prod` (with support for other non-prod environments in the future). Furthermore, recipes can utilize [Go's builtin templating engine](https://pkg.go.dev/text/template) to provide dynamic functionality for deployment. Below is a simple example of the makeup of a recipe. +```yaml +include: + - .super-sprout-steps +steps: +{{ if props hostname super-sprout }} + install super-sprout: + file.touch: + - name: ~/super-sprout-config + requisites: + - require: super-sprout-steps-completed +{{ else }} + install normal-sprout: + file.touch: + - name: ~/normal-sprout-config +{{ end }} +``` +In this example, an include is created for a `super-sprout-steps.grlx` file. This file would contain a list of steps with a final step `grlx-sprout-steps-completed`. Next we have our list of steps, bounded by Go templates. This template checks the hostname of the sprout and renders the steps to send to the farmer. In this case, if the sprout's hostname is `super-sprout`, then it will render a template that looks like this: +```yaml +include: + - .super-sprout-steps +steps: + install super-sprout: + file.touch: + - name: ~/super-sprout-config + requisites: + - require: super-sprout-steps-completed +``` +If the hostname is anything else, the sprout will run: +```yaml +include: + - .super-sprout-steps +steps: + install normal-sprout: + file.touch: + - name: ~/normal-sprout-config +``` + +It is important to note the requisites listed. This ensures that the step from the include (`super-sprout-steps-completed`) occurs _before_ the `install-super-sprout` step is run. +:::note +Deployment of recipe steps is non-deterministic unless requisites are provided. Otherwise, are steps run as is. If order is important, than order ***must*** be specified. +:::