diff --git a/astro.config.mjs b/astro.config.mjs index cc60e23..a1e43c1 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,11 +1,13 @@ // @ts-check import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; +import starlightHeadingBadges from 'starlight-heading-badges' // https://astro.build/config export default defineConfig({ integrations: [ starlight({ + plugins: [starlightHeadingBadges()], title: 'MinimalViableK8s', social: [{ icon: 'github', label: 'GitHub', href: 'https://codeberg.org/headshed/infctl-cli' }], head: [ diff --git a/package.json b/package.json index 5414587..b375153 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "dependencies": { "@astrojs/starlight": "^0.34.5", "astro": "^5.6.1", - "sharp": "^0.34.2" + "sharp": "^0.34.2", + "starlight-heading-badges": "^0.6.0" } } \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2f74755..e9e78e0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -17,6 +17,9 @@ importers: sharp: specifier: ^0.34.2 version: 0.34.3 + starlight-heading-badges: + specifier: ^0.6.0 + version: 0.6.0(@astrojs/starlight@0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2))) packages: @@ -1608,6 +1611,12 @@ packages: space-separated-tokens@2.0.2: resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==} + starlight-heading-badges@0.6.0: + resolution: {integrity: sha512-YYYImb6ov842k62A6UNecj2elhoA8NPj6CnVlLFpe9Qa8C4xgWQw5NlqKfJrQgJFWeMj0uKnVqKQfv2eSGX8HQ==} + engines: {node: '>=18'} + peerDependencies: + '@astrojs/starlight': '>=0.32.0' + stream-replace-string@2.0.0: resolution: {integrity: sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==} @@ -4062,6 +4071,16 @@ snapshots: space-separated-tokens@2.0.2: {} + starlight-heading-badges@0.6.0(@astrojs/starlight@0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2))): + dependencies: + '@astrojs/markdown-remark': 6.3.6 + '@astrojs/starlight': 0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2)) + github-slugger: 2.0.0 + mdast-util-directive: 3.1.0 + unist-util-visit: 5.0.0 + transitivePeerDependencies: + - supports-color + stream-replace-string@2.0.0: {} string-width@4.2.3: diff --git a/src/content/docs/guides/001-dev-env.md b/src/content/docs/guides/001-dev-env.md index be4cc15..dc2e3ae 100644 --- a/src/content/docs/guides/001-dev-env.md +++ b/src/content/docs/guides/001-dev-env.md @@ -1,14 +1,16 @@ --- -title: Local Dev Environment +title: Pre requisites for development description: A guide to checking a local environment. --- +MVK will help create a working kubernetes environment but requires some tooling. Running a test script will help to check your current environment and avoid failures later on. + ## Pre Flight Checks Run `dev-pre-flight-checks.sh` command line tool with ```bash -curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash +curl -sL https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash ``` Alternatively, download https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh locally, check over what it does, `chmod +x dev-pre-flight-checks.sh` and run `./dev-pre-flight-checks.` diff --git a/src/content/docs/guides/k3d/003-local-k3d.md b/src/content/docs/guides/k3d/003-local-k3d.md index 7aad14e..39bcdc7 100644 --- a/src/content/docs/guides/k3d/003-local-k3d.md +++ b/src/content/docs/guides/k3d/003-local-k3d.md @@ -1,8 +1,10 @@ --- -title: Create a Local K3d Instance +title: K3d single instance description: A guide to creating an initial local k3d instance. --- +###### Use case :badge[development]{variant=success} + clone the `infctl-cli` repo in order to have local access to its scripts, files and manifests to use later on. Where you put this is up to you but we will work on the assumption that this will be in `$HOME/projects` : diff --git a/src/content/docs/guides/k3d/004-infctl-first-run.md b/src/content/docs/guides/k3d/004-infctl-first-run.md index 01f4be6..c946a9c 100644 --- a/src/content/docs/guides/k3d/004-infctl-first-run.md +++ b/src/content/docs/guides/k3d/004-infctl-first-run.md @@ -3,7 +3,7 @@ title: Initial Pipeline Run description: A guide to running infctl for the first time. --- -having already cloned the `infctl-cli` see [Create a local k3d instance](/guides/local-k3d/) change directory to where this code repository was checked out on your system. +having already cloned the `infctl-cli` see [K3d single instance](/guides/k3d/003-local-k3d/) change directory to where this code repository was checked out on your system. If necessary, re-run `scripts/create_k3d_cluster.sh` to create a new local cluster or just use one created earlier if you chose not to delete it. diff --git a/src/content/docs/guides/k3d/009-development-releases.md b/src/content/docs/guides/k3d/009-development-releases.md new file mode 100644 index 0000000..60ba614 --- /dev/null +++ b/src/content/docs/guides/k3d/009-development-releases.md @@ -0,0 +1,43 @@ +--- +title: Operational consideration +description: Thinking about security and service management early on. +--- + +When we create code and infrastructure for development, it is in preparation for production. + +Breaks in development workflow ultimately delay releases to production. So adequate testing of our code helps ensure that others working with us do not have bad experiences. + +## Continuity + +Continuity of the development workflow is frequently underpinned by + +* applying secure coding practices to ensure we are not leaking secure data or opening our applications to be exploited by bad actors +* adding feature tests to prove critical functionality is maintained +* employing health and ping checks to ensure availability in deployments +* creating anonymized test data that is functionally representative of that in live + +The above headlines are not exhaustive and, depending on our use case, may well become longer. + +This can be summarized as a 'shift left' of security and testing practice into early stages of the software development lifecycle. + +## Configuration + +From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains : + +```json +{ + "log_format": "", + "deployment_file": "", + "deployment_type": "", + "deployment_mode": "json" +} +``` + +So unless we edit this file, the default `deployment_type` is that of `development`. + +It signifies that we have applied the above working practice. + +Our code and pipelines can be documented, version controlled and checked from development through to production readiness. + + + diff --git a/src/content/docs/guides/vagrant/005-local-vagrant-cluster.md b/src/content/docs/guides/vagrant/005-local-vagrant-cluster.md index f739543..fc86f1b 100644 --- a/src/content/docs/guides/vagrant/005-local-vagrant-cluster.md +++ b/src/content/docs/guides/vagrant/005-local-vagrant-cluster.md @@ -1,8 +1,10 @@ --- -title: Create a vagrant 3 node cluster +title: 3 node cluster description: A guide to creating a virtualized local k3s instance. --- +###### Use case :badge[development]{variant=success} :badge[pre-production]{variant=caution} + # Prerequisites MVK on vagrant represents a 'real' 3 node VM in the cloud but running on a local, self-hosted environment. diff --git a/src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md b/src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md index 67d8aaa..688318e 100644 --- a/src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md +++ b/src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md @@ -3,7 +3,6 @@ title: Smoke test the cluster description: Basic smoke tests --- -# Smoke test the cluster ... If all has gone well, a cluster will now be running on your local system comprising of 3 nodes and a workstation. @@ -37,4 +36,9 @@ vm2 Ready control-plane,etcd,master 4h11m v1.33.3+k3s1 vm3 Ready control-plane,etcd,master 4h10m v1.33.3+k3s1 ``` + + + + + If you have got this far, congratulation you have a locally hosted k3s cluster running in 3 virtual machines and a workstation that can be used to manage it using `kubectl` and `ansible`. \ No newline at end of file diff --git a/src/content/docs/guides/vagrant/016-local-vagrant-cluster-ingress-smoke-test.md b/src/content/docs/guides/vagrant/016-local-vagrant-cluster-ingress-smoke-test.md deleted file mode 100644 index 1ac1bb7..0000000 --- a/src/content/docs/guides/vagrant/016-local-vagrant-cluster-ingress-smoke-test.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Smoke Test Ingress -description: Simple test for ingress. ---- - -## Smoke test ingress - -If all has gone well, we should now be able to get the service for `traefik` and see an external IP address and type of `LoadBalancer` : - -```bash -kubectl -n traefik get svc -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -traefik LoadBalancer 10.43.5.252 192.168.56.230 80:32066/TCP,443:32410/TCP 16s -``` - -Here the address of `192.168.56.230` is available to use to ingress route our services, pods and Kubernetes hosted apps on both plain text port 89 and over TLS https on port 443. - -We will be able next to assign a certificate to this 2nd port such that `traefik` will be able to serve URL's on that port to our pods and apps. - -Initially this will use a self signed certificate but we will be able to crate our own CA and have a secure connection without browser warnings on our local, vagrant mks cluster environment. \ No newline at end of file diff --git a/src/content/docs/guides/vagrant/020-security.md b/src/content/docs/guides/vagrant/020-security.md new file mode 100644 index 0000000..2633000 --- /dev/null +++ b/src/content/docs/guides/vagrant/020-security.md @@ -0,0 +1,35 @@ +--- +title: Operational consideration +description: using production like infra for securing our apps +--- + +Running infrastructure on Vagrant is not generally intended for production use. More frequently, localized development and testing may be achieved using `k3d` and other containerized k8s environments. + +## Production grade + +However it is possible and useful to develop and test applications that are already running on near to production grade infrastructure. + +We can test and prove deployments to be able to + +* be tested in a safer environment +* able to cope with service interruptions due to a failing node +* work with ingress + +Single containerized k8s stacks lack their fully virtualized counterparts physical attributes such as CPU, memory, storage and networks. + +## Configuration + +From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains : + +```json +{ + "log_format": "", + "deployment_file": "", + "deployment_type": "", + "deployment_mode": "json" +} +``` + +We would logically change `deployment_type` to be `pre-production` for pipelines that have reached this stage. + +It is then obvious that our code has reached a stage that has been tested close to production. \ No newline at end of file diff --git a/src/content/docs/infctl/intro.md b/src/content/docs/infctl/intro.md index 40bd52b..1b64a56 100644 --- a/src/content/docs/infctl/intro.md +++ b/src/content/docs/infctl/intro.md @@ -7,7 +7,7 @@ Kubernetes is complicated, so getting started can be a pain. There are many tools out there to create a development Kubernetes environment. -`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to it being extended into production and beyond. +`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to its use being extended to production and beyond. diff --git a/src/content/docs/mvk/intro.md b/src/content/docs/mvk/intro.md index 524e970..4132b01 100644 --- a/src/content/docs/mvk/intro.md +++ b/src/content/docs/mvk/intro.md @@ -1,37 +1,45 @@ --- -title: Minimal Viable Kubernetes Intro +title: MVK Introduction description: introducing minimal viable Kubernetes and its guiding principles --- -Kubernetes is complicated but additional to this it is designed with cloud compute in mind. +Kubernetes is complicated + +Additionally, K8s is designed with cloud in mind. Thus, self hosting options can be limiting. -Out of the box, Kubernetes expects key ingredients of infrastructure to be present. For example, ingress, storage and load balancers. +## Limitations + +Out of the box, 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. -Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can quickly become messy. +Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can become time consuming. -Knowing what to create in 'dev' as opposed to 'prod` may introduce inconsistent configurations and can result in adding technical debt. +## Opinionated by design + +Knowing what to create in **development** as opposed to **production** may introduce inconsistency and technical debt. Production environments can also become complex, difficult to manage, even over engineered. -Responding to these challenging scenarios, Minimal Viable Kubernetes (MVK) provides tooling and design patterns aimed toward solving these issues. +Responding to these challenging scenarios, MVK provides tooling and design patterns aimed toward solving these issues. MVK helps create a minimal K8s setup and one which is a viable implementation of Kubernetes. Initially this may be used for test and development work, but extending this into production is also its goal. +## Use cases + Typical use cases of MVK are aimed toward entirely self hosted environments. This may be outside of any managed Kubernetes or cloud platform, which are often as not proprietary in their design and provisioning of k8s. The goals of MVK are to increase portability and reduce 'vendor lock in'. It can also reduce costs, provided that its users are already, or become, familiar with Kubernetes and its day to day operational and management. -*We think that **everyone** should know more about Kubernetes*. +> We think that **everyone** should know more about Kubernetes. 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 help us to gain control over our digital sovereignty.** +**Above all it can gain control over our own digital sovereignty.**