From 8ff2f6dc124efbaad0d48c7b55aa9e12c8b8ff1a Mon Sep 17 00:00:00 2001 From: jon brookes Date: Tue, 21 Oct 2025 15:53:12 +0100 Subject: [PATCH] Refactor MVK documentation templates; streamline navigation, add new guides, and enhance clarity in prerequisites, configuration, and run instructions for Gcloud setups. --- astro.config.mjs | 32 +---------- src/content/docs/index.mdx | 2 +- .../goals-limitation-design-use-cases.md} | 24 ++++++--- .../docs/mvk/2. infctl/020-quick-start.md | 21 ++++++++ .../docs/mvk/2. infctl/030-configuration.md | 54 +++++++++++++++++++ .../1. Gcloud single node/001-prereques.md | 24 ++++++++- .../1. Gcloud single node/010-configure.md | 10 +++- .../1. Gcloud single node/030-run.md | 10 +++- .../001-prereques.md | 31 +++++++++++ .../010-configure.md | 15 ++++++ .../2. Gcloud 3 node coming soon/030-run.md | 6 +++ 11 files changed, 187 insertions(+), 42 deletions(-) rename src/content/docs/mvk/{intro.md => 1. Introduction/goals-limitation-design-use-cases.md} (71%) create mode 100644 src/content/docs/mvk/2. infctl/020-quick-start.md create mode 100644 src/content/docs/mvk/2. infctl/030-configuration.md create mode 100644 src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md create mode 100644 src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md create mode 100644 src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md diff --git a/astro.config.mjs b/astro.config.mjs index 298bb59..3ea5e88 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -23,41 +23,11 @@ export default defineConfig({ sidebar: [ { label: 'MVK', - items: [ - // Each item here is one entry in the navigation menu. - { label: 'Minimal Viable Kubernetes', slug: 'mvk/intro' }, - ], + autogenerate: { directory: 'mvk' }, }, - { - label: 'infctl', - items: [ - // Each item here is one entry in the navigation menu. - { label: 'Introduction', slug: 'infctl/intro' }, - { label: 'Quick Start Guide', slug: 'infctl/quick-start' }, - { label: 'Configuration', slug: 'infctl/configuration' }, - ], - }, - // { - // label: 'MVK', - // autogenerate: { directory: 'mvk' }, - // }, { label: 'Microlearning', autogenerate: { directory: 'guides' }, - - - - - // items: [ - // { label: 'Local Dev Environment', slug: 'guides/dev-env' }, - // { label: 'Create a Local K3d Instance', slug: 'guides/local-k3d' }, - // { label: 'Initial Pipeline Run', slug: 'guides/infctl-first-run' }, - // { label: 'Create a vagrant 3 node cluster', slug: 'guides/local-vagrant-cluster' }, - // { label: 'Add Longhorn Storage', slug: 'guides/local-vagrant-cluster-storage' }, - // { label: 'Add Ingress', slug: 'guides/local-vagrant-cluster-ingress' }, - - - // ], }, { label: 'MVK Templates', diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index bd4f4e5..e5d04dd 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,7 +8,7 @@ hero: file: ../../assets/mvk.png actions: - text: MVK Guide - link: /mvk/intro/ + link: /mvk/1-introduction/goals-limitation-design-use-cases/ icon: right-arrow - text: infctl and mvk source link: https://codeberg.org/headshed/infctl-cli diff --git a/src/content/docs/mvk/intro.md b/src/content/docs/mvk/1. Introduction/goals-limitation-design-use-cases.md similarity index 71% rename from src/content/docs/mvk/intro.md rename to src/content/docs/mvk/1. Introduction/goals-limitation-design-use-cases.md index 4132b01..b3aec76 100644 --- a/src/content/docs/mvk/intro.md +++ b/src/content/docs/mvk/1. Introduction/goals-limitation-design-use-cases.md @@ -1,17 +1,29 @@ --- -title: MVK Introduction +title: Goals, Limitations, Design, Use Cases description: introducing minimal viable Kubernetes and its guiding principles --- -Kubernetes is complicated +## Goals -Additionally, K8s is designed with cloud in mind. +Minimal Viable Kubernetes has the following goals: -Thus, self hosting options can be limiting. +* CLI friendly and first +* Promotes Infrastructure as Code +* Portablity across cloud and on-prem +* Openness and keeping it simple +* Avoid proprietary lock in + +Kubernetes is complicated. + +K8s is designed with cloud in mind. + +Self hosted options can be limiting. ## Limitations -Out of the box, Kubernetes expects key components of infrastructure to be present. For example, ingress, storage and load balancers. +MVK addresses the limitations of Kubernetes 'out of the box' for self-hosted implementation. + +On its own, Kubernetes expects key components of infrastructure to be present. For example, ingress, storage and load balancers. If any of these are not present, they will need to be supplied in a form that Kubernetes can consume them. @@ -39,7 +51,7 @@ It can also reduce costs, provided that its users are already, or become, famili A greater understanding of k8s results in us all becoming less reliant on others providing this as a service for us. It protects our industry from losing these skills entirely. -**Above all it can gain control over our own digital sovereignty.** +**MVK can help give us control of our digital sovereignty.** diff --git a/src/content/docs/mvk/2. infctl/020-quick-start.md b/src/content/docs/mvk/2. infctl/020-quick-start.md new file mode 100644 index 0000000..b7bad19 --- /dev/null +++ b/src/content/docs/mvk/2. infctl/020-quick-start.md @@ -0,0 +1,21 @@ +--- +title: Quick Start +description: A guide to setting up MVK quickly. +--- + +`infctl` is a command line tool used by MVK to orchestrate code. + +It makes scripted infrastructure as code simpler and easier to run, manage and support. + +You can think of it as a 'simpler pipeline'. + +Install `infctl` command line tool with + +```bash +curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash +``` + +Alternatively, go to [Releases](https://codeberg.org/headshed/infctl-cli/releases) to find a current version for your Operating System, download it and place a copy in your `PATH`. + + + diff --git a/src/content/docs/mvk/2. infctl/030-configuration.md b/src/content/docs/mvk/2. infctl/030-configuration.md new file mode 100644 index 0000000..6e4ff47 --- /dev/null +++ b/src/content/docs/mvk/2. infctl/030-configuration.md @@ -0,0 +1,54 @@ +--- +title: Configuration +description: infctl configuration +--- + +`infctl` uses `json` files for configuration. + +It is designed around the idea of pipelines where each pipeline performs a series of steps. + +A short, 2 step pipeline configuration can look like : + +```json +[ + { + "name": "ensure inf namespace exists", + "function": "k8sNamespaceExists", + "params": ["infctl"], + "retryCount": 0, + "shouldAbort": true + }, + { + "name": "create php configmap", + "function": "RunCommand", + "params": ["./scripts/create_php_configmap_ctl.sh"], + "retryCount": 0, + "shouldAbort": true + } +] +``` + +Each Object is a task. + +Object task records are executed in a `[]` list and in sequence. + +Each task has a `name` to be displayed in logs. + +Each task calls a `Function` that is registered within `infctl` and that accepts `params` string, which are any parameters to be passed to that function, script or executable. The simplest example being `RunCommand` which accepts the path to a script or executable as its `params`. This can be anything but can be as simple as : + +```bash +echo "hello world" + +exit 0 +``` + +So `infctl` is unlimited as to what it can use in its pipeline files to achieve any kind of automation. + +If a task fails ( the script or program that is run returns a non zero value ) it may be re-tried up to `retryCount` times. + +If a task fails the pipeline will stop running unless `shouldAbort` is set to false, in which case, the pipeline will continue to run with the next step item in the list. + + + + + diff --git a/src/content/docs/templates/1. Gcloud single node/001-prereques.md b/src/content/docs/templates/1. Gcloud single node/001-prereques.md index 4f5866f..4cc88ae 100644 --- a/src/content/docs/templates/1. Gcloud single node/001-prereques.md +++ b/src/content/docs/templates/1. Gcloud single node/001-prereques.md @@ -3,5 +3,27 @@ title: Pre-Requisites description: A guide to creating a single Gcloud MVK node. --- -### 1. PREREQS +we need to run this at least once to ensure we have tooling available ... +```bash +cd ${PATH_TO_infctl-cli}/infctl-cli # where we checked out infct-cli to +./gcloud/tf/scripts/pre-flight-checks.sh +``` + +``` +✅ tofu is installed,... + +✅ gcloud is installed,... + +✅ kubectl is installed,... + +✅ envsubst is installed,... + +# ..... + +✅ Pre-flight checks passed. You are ready to proceed 🙂 +``` + +hopefully, we have no errors. + +Follow instructions to install any missing dependencies. \ No newline at end of file diff --git a/src/content/docs/templates/1. Gcloud single node/010-configure.md b/src/content/docs/templates/1. Gcloud single node/010-configure.md index 1f0cb04..cececc1 100644 --- a/src/content/docs/templates/1. Gcloud single node/010-configure.md +++ b/src/content/docs/templates/1. Gcloud single node/010-configure.md @@ -3,5 +3,11 @@ title: Configure description: A guide to creating a single Gcloud MVK node. --- -### 2. CONFIGURE - +```bash +[ -f .env ] || cp -v .env.gcloud-example .env +# edit to include +export PROJECT_NAME="the name of your gcp project, often referred to as the project" +export EMAIL="your email address to identify yourself with letsencrypt" +export APP_DOMAIN_NAME="your domain name for the app, e.g., frgdr.some-domain.com" +export INSTALL_FORGEJO="true" +``` diff --git a/src/content/docs/templates/1. Gcloud single node/030-run.md b/src/content/docs/templates/1. Gcloud single node/030-run.md index 0a2b27b..fe1f16a 100644 --- a/src/content/docs/templates/1. Gcloud single node/030-run.md +++ b/src/content/docs/templates/1. Gcloud single node/030-run.md @@ -3,4 +3,12 @@ title: Run description: A guide to creating a single Gcloud MVK node. --- -### 3. RUN \ No newline at end of file +```bash +# RUN +LOG_FORMAT=none infctl -f ./gcloud/tf/scripts/build-gcloud-k3s-pipeline-wait-dns.json +``` + +At the end of the pipeline we will see an ip address displayed of the VM instance the terraform has created. + +You will need to edit an A-record in your DNS to point your $APP_DOMAIN_NAME + diff --git a/src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md b/src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md new file mode 100644 index 0000000..a08b18e --- /dev/null +++ b/src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md @@ -0,0 +1,31 @@ +--- +title: Pre-Requisites +description: A guide to creating a single Gcloud MVK node. +--- + +### 👷 coming soon ... + +we need to run this at least once to ensure we have tooling available ... + +```bash +cd ${PATH_TO_infctl-cli}/infctl-cli # where we checked out infct-cli to +./gcloud/tf/scripts/pre-flight-checks.sh +``` + +``` +✅ tofu is installed,... + +✅ gcloud is installed,... + +✅ kubectl is installed,... + +✅ envsubst is installed,... + +# ..... + +✅ Pre-flight checks passed. You are ready to proceed 🙂 +``` + +hopefully, we have no errors. + +Follow instructions to install any missing dependencies. \ No newline at end of file diff --git a/src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md b/src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md new file mode 100644 index 0000000..e1da475 --- /dev/null +++ b/src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md @@ -0,0 +1,15 @@ +--- +title: Configure +description: A guide to creating a single Gcloud MVK node. +--- + +### 👷 coming soon ... + +```bash +[ -f .env ] || cp -v .env.gcloud-example .env +# edit to include +export PROJECT_NAME="the name of your gcp project, often referred to as the project" +export EMAIL="your email address to identify yourself with letsencrypt" +export APP_DOMAIN_NAME="your domain name for the app, e.g., frgdr.some-domain.com" +export INSTALL_FORGEJO="true" +``` diff --git a/src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md b/src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md new file mode 100644 index 0000000..0dbeae0 --- /dev/null +++ b/src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md @@ -0,0 +1,6 @@ +--- +title: Run +description: A guide to creating a single Gcloud MVK node. +--- + +### 👷 coming soon ...