Refactor MVK documentation
templates; streamline navigation, add new guides, and enhance clarity in prerequisites, configuration, and run instructions for Gcloud setups.
This commit is contained in:
jon brookes
parent
cce1c1aa7a
commit
8ff2f6dc12
11 changed files with 187 additions and 42 deletions
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.**
|
||||
|
||||
|
||||
|
||||
21
src/content/docs/mvk/2. infctl/020-quick-start.md
Normal file
21
src/content/docs/mvk/2. infctl/020-quick-start.md
Normal file
|
|
@ -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`.
|
||||
|
||||
|
||||
|
||||
54
src/content/docs/mvk/2. infctl/030-configuration.md
Normal file
54
src/content/docs/mvk/2. infctl/030-configuration.md
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -3,4 +3,12 @@ title: Run
|
|||
description: A guide to creating a single Gcloud MVK node.
|
||||
---
|
||||
|
||||
### 3. RUN
|
||||
```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
|
||||
|
||||
|
|
|
|||
31
src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md
vendored
Normal file
31
src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md
vendored
Normal file
|
|
@ -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.
|
||||
15
src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md
vendored
Normal file
15
src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md
vendored
Normal file
|
|
@ -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"
|
||||
```
|
||||
6
src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md
vendored
Normal file
6
src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md
vendored
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
title: Run
|
||||
description: A guide to creating a single Gcloud MVK node.
|
||||
---
|
||||
|
||||
### 👷 coming soon ...
|
||||
Loading…
Add table
Add a link
Reference in a new issue