docs: start some basic documentation

Makefile

@@ -1,26 +1,42 @@
 VERSION=$(shell echo $(shell git describe --abbrev=0 --tags)+$(shell git rev-parse --short=8 HEAD))
 BUILD=$(shell date +%FT%T%z)
+GOCMD=go
 GO_VER=1.22
 GOOS=linux
 GOARCH=amd64
 PKG=github.com/uselagoon/build-deploy-tool
 LDFLAGS=-w -s -X ${PKG}/cmd.bdtVersion=${VERSION} -X ${PKG}/cmd.bdtBuild=${BUILD} -X "${PKG}/cmd.goVersion=${GO_VER}"
 
 test: fmt vet
-	go clean -testcache && go test -v ./...
+	$(GOCMD) clean -testcache && $(GOCMD) test -v ./...
 
 fmt:
-	go fmt ./...
+	$(GOCMD) fmt ./...
 
 vet:
-	go vet ./...
+	$(GOCMD) vet ./...
 
 run: fmt vet
-	go run ./main.go
+	$(GOCMD) run ./main.go
 
 build: fmt vet
-	CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -v
+	CGO_ENABLED=0 $(GOCMD) build -ldflags '${LDFLAGS}' -v
 
 docker-build:
 	DOCKER_BUILDKIT=1 docker build --pull --build-arg GO_VER=${GO_VER} --build-arg VERSION=${VERSION} --build-arg BUILD=${BUILD} --rm -f Dockerfile -t build-deploy-image:local .
 	docker run --entrypoint /bin/bash build-deploy-image:local -c 'build-deploy-tool version'
+
+docs: test
+	$(GOCMD) run main.go --docs
+
+MKDOCS_IMAGE ?= ghcr.io/amazeeio/mkdocs-material
+MKDOCS_SERVE_PORT ?= 8000
+
+.PHONY: docs/serve
+docs/serve:
+	@echo "Starting container to serve documentation"
+	@docker run --rm -it \
+		-p 127.0.0.1:$(MKDOCS_SERVE_PORT):$(MKDOCS_SERVE_PORT) \
+		-v ${PWD}:/docs \
+		--entrypoint sh $(MKDOCS_IMAGE) \
+		-c 'mkdocs serve --dev-addr=0.0.0.0:$(MKDOCS_SERVE_PORT) -f mkdocs.yml'

README.md

@@ -1,3 +1,6 @@
 # Build and Deploy Resource Generator
 
-This is a tool used to help with creating resources for Lagoon builds
+<img src="./docs/lagoon-build-deploy.png" width=100>
+
+This is a tool used with a [Lagoon Build](https://docs.lagoon.sh/concepts-basics/build-and-deploy-process/). It is currently not intended to be used outside of a build process.
+

cmd/root.go

@@ -21,15 +21,28 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
+var docsFlag bool
+
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Use:   "lagoon-build",
 	Short: "A tool to help with generating Lagoon resources for Lagoon builds",
 	Long: `A tool to help with generating Lagoon resources for Lagoon builds
 This tool will read a .lagoon.yml file and also all the required environment variables from
 within a Lagoon build to help with generating the resources`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if docsFlag {
+			err := doc.GenMarkdownTree(cmd, "docs/commands")
+			if err != nil {
+				return err
+			}
+			fmt.Println("Documentation updated")
+		}
+		return nil
+	},
 }
 
 var templateCmd = &cobra.Command{
@@ -99,6 +112,9 @@ func init() {
 	rootCmd.AddCommand(taskCmd)
 	rootCmd.AddCommand(identifyCmd)
 	rootCmd.AddCommand(validateCmd)
+	rootCmd.Flags().BoolVarP(&docsFlag, "docs", "", false, "Generate docs")
+
+	rootCmd.Flags().MarkHidden("docs")
 
 	rootCmd.PersistentFlags().StringP("lagoon-yml", "l", ".lagoon.yml",
 		"The .lagoon.yml file to read")

docs/buildrequirements.md

@@ -1,24 +1,27 @@
-# Build Requirements
-
 Lagoon uses the following information injected into the build pod, and retrieved from files within the git repository to determine how an environment is built.
 
-## Required Files
+# Required Files
+
+These files are **_required_** by a build. 
+
+The `.lagoon.yml` file has a `docker-compose-yaml` field that points to which file should be consumed, and this file is required. Typically it is `docker-compose.yaml`.
+
 * `.lagoon.yml`
 * `docker-compose.yml`
 
-### `.lagoon.yml`
+## `.lagoon.yml`
 See the docs [here](https://docs.lagoon.sh/using-lagoon-the-basics/lagoon-yml/)
 
-### `docker-compose.yml`
+## `docker-compose.yml`
 See the docs [here](https://docs.lagoon.sh/using-lagoon-the-basics/docker-compose-yml/)
 
-## Variables
+# Variables
 
 These are variables that are injected into a build pod by `remote-controller`, some are provided by Lagoon core when a build is created, some are injected into the build from `remote-controller`
 
-### Core provided
+## Core provided
 
-#### Main Variables
+### Main Variables
 * `BUILD_TYPE` can be one of `branch|pullrequest|promote`
 * `PROJECT` is the safed version of the project name
 * `ENVIRONMENT` is the safed version of the environment name
@@ -27,42 +30,41 @@ These are variables that are injected into a build pod by `remote-controller`, s
 * `ACTIVE_ENVIRONMENT` is populated with the current active environment if active/standby is enabled
 * `STANDBY_ENVIRONMENT` is populated with the current standby environment if active/standby is enabled
 
-#### Pullrequest Variables
+### Pullrequest Variables
 * `PR_TITLE`
 * `PR_NUMBER`
 * `PR_HEAD_BRANCH`
 * `PR_HEAD_SHA`
 * `PR_BASE_BRANCH`
 * `PR_BASE_SHA`
 
-####  Promotion Variables
+###  Promotion Variables
 * `PROMOTION_SOURCE_ENVIRONMENT` contains the source environment name if this is a promotion type build
 
-#### Environment Variables
+### Environment Variables
 * `LAGOON_PROJECT_VARIABLES` contains any project specific environment variables
 * `LAGOON_ENVIRONMENT_VARIABLES` contains any environment specific environment variables
 
-### Monitoring Variables
+## Monitoring Variables
 * `MONITORING_ALERTCONTACT`
 * `MONITORING_STATUSPAGEID`
 
-#### Build Variables
+### Build Variables
 * `SOURCE_REPOSITORY` is the git repository
 * `GIT_REF` is the git reference / commit
 * `SUBFOLDER` if the project is in a subfolder, this variable contains the directory to change to
 * `PROJECT_SECRET` is used for backups
 * `KUBERNETES` is the kubernetes cluster name from Lagoon
-* `REGISTRY` is the registry that is passed from Lagoon (will be deprecated)
 
-### Remote provided
+## Remote provided
 
-#### General variables
+### General variables
 These are variables that can influence parts of a build
 
 * `LAGOON_FASTLY_NOCACHE_SERVICE_ID` is a default cache no cache service id that can be consumed
 * `NATIVE_CRON_POD_MINIMUM_FREQUENCY` changes the interval of which cronjobs go from inside cli pods to native k8s cronjobs (default 15m)
 
-### Build Flags
+## Build Flags
 The following are flags provided by `remote-controller` and used to influence build, these also have counterpart variables that omit the `FORCE|DEFAULT` from them that can be used inside of environment variables, `FORCE` flags cannot be overridden.
 
 * `LAGOON_FEATURE_FLAG_FORCE_ROOTLESS_WORKLOAD`
@@ -74,17 +76,24 @@ The following are flags provided by `remote-controller` and used to influence bu
 * `LAGOON_FEATURE_FLAG_FORCE_RWX_TO_RWO`
 * `LAGOON_FEATURE_FLAG_DEFAULT_RWX_TO_RWO`
 
-### Proxy related variables
+!!! info
+    As new features are created, this list can grow. We will try to keep this list updated.
+
+## Proxy related variables
 If proxy has been enabled in `remote-controller`, then these variables will be injected to the buildpod to enabled proxy support
 
 * `HTTP_PROXY / http_proxy`
 * `HTTPS_PROXY / https_proxy`
 * `NO_PROXY / no_proxy`
 
-### API and Remote provided
+!!! info
+    Proxy is typically not provided, consult your Lagoon administrators if this is something you need to be provided to all environments within a `lagoon-remote`.
+
+## API and Remote provided
+
+## Backup related variables
+These are all variables that are provided by either core or remote, for more information see the docs [here](https://docs.lagoon.sh/concepts-advanced/backups/)
 
-### Backup related variables
-These are all variables that are provided by either core or remote 
 * `DEFAULT_BACKUP_SCHEDULE`
 * `MONTHLY_BACKUP_DEFAULT_RETENTION`
 * `WEEKLY_BACKUP_DEFAULT_RETENTION`
@@ -93,4 +102,4 @@ These are all variables that are provided by either core or remote
 * `LAGOON_FEATURE_BACKUP_PROD_SCHEDULE` (remote) / `LAGOON_BACKUP_PROD_SCHEDULE` (API)
 * `LAGOON_FEATURE_BACKUP_DEV_SCHEDULE` (remote) / `LAGOON_BACKUP_DEV_SCHEDULE` (API)
 * `LAGOON_FEATURE_BACKUP_PR_SCHEDULE` (remote) / `LAGOON_BACKUP_PR_SCHEDULE` (API)
-* `K8UP_WEEKLY_RANDOM_FEATURE_FLAG`
+* `K8UP_WEEKLY_RANDOM_FEATURE_FLAG`

docs/buildstages.md

@@ -0,0 +1,104 @@
+When a build pod first starts up, it runs through some checks to ensure that the docker-host it needs to talk to is available. It also establishes a client to use to talk to Kubernetes.
+
+# Git Checkout
+
+Once the setup is complete, the build proceeds to checkout the git repository and any submodules it may have. Any repositories configured as submodules must be allowed to be pulled using the same key as the primary git repository. 
+
+!!! warning
+    This may need the `deploy key` of the project be assigned to a git user, and that user then granted access to the repositories required.
+
+# Kubernetes Setup
+
+This stage ensures that a client can talk to Kubernetes. Also, all builds are configured to talk to a dedicated container registry, in most cases this will be a Harbor that is configured in `lagoon-remote`, checks to ensure this information is present occur here too.
+
+# Initial Environment Setup
+
+This stage saves a copy of the `.lagoon.yml` and `docker-compose.yml` file into the namespace before the build proceeds. This allows administrators to perform debugging if required with a copy of these files to detect potential changes.
+
+# Docker Compose and Lagoon YAML Validations
+
+This stage validates the `.lagoon.yml` and associated `docker-compose.yml` files to ensure they are valid. This step can produce build warnings that describe issues that should be addressed, as warnings indicate that a failure may occur in the future if behaviour changes.
+
+# Variable Configuration
+
+This stage sets up variables used internally during the build to store and process information later during the build.
+
+# Container Registry Login
+
+This stage logs in to the internally provided container registry. As Lagoon also supports [user defined external container registries](https://docs.lagoon.sh/concepts-basics/lagoon-yml/#container-registries), these are also configured and logged in during this step.
+
+# Image Build
+
+This stage is where the images are built. By default `buildkit` is enabled, but this can be disabled by setting the `DOCKER_BUILDKIT=0` as a build scope variable. 
+
+!!! info
+    These images are not tagged and are referenced in Lagoon deployments using the build image `SHA`.
+
+# Pre-Rollout Tasks
+
+This stage runs any pre-rollout tasks that may be configured in the `.lagoon.yml` file. These tasks are treated as a failure item and will result in a build failing if they fail. If you don't want these tasks to fail, you will need to write your tasks in a way to always `exit 0`.
+
+# Service Configuration 1 & 2
+
+These stages proceed to configure autogenerated routes and any DBaaS services.
+
+# Route/Ingress Configuration
+
+This stage calculates and creates any ingress for the environment.
+
+# Route/Ingress Cleanup
+
+This stage calculates any ingress that need to be removed. Currently Lagoon will provide a warning in the build if it detects anything, but will not remove anything.
+
+Setting `LAGOON_FEATURE_FLAG_CLEANUP_REMOVED_LAGOON_ROUTES=enabled` as a global scope variable will ensure that any ingress previously detected will be removed during the next build. A warning will be produced in both situations to inform the user that something has taken place.
+
+# Route/Ingress Certificate Challenges
+
+If the `lagoon-remote` has been configured with cert-manager, and any ingress have certificate challenges that are still pending or failing, this stage will report them in a warning for the user to either confirm if the routes are required, or to ensure DNS is correctly configured.
+
+# Update Configmap
+
+This stage updates the configmap that stores variables from the project or environment in Lagoon, plus any of the variables that are provided by the build, typicaly prefixed with `LAGOON_`.
+
+# Image Push to Registry
+
+This stage pushes any built or pulled through images into the internally configured registry.
+
+!!! info
+    These images are not tagged and are referenced in Lagoon deployments using the build image `SHA`.
+
+# Deprecated Image Warnings
+
+If any images built or pulled contain an image that Lagoon has detected as deprecated, a warning will be shown here to indicate which images have issues. See more information in the docs [here](https://docs.lagoon.sh/docker-images/deprecated-images/).
+
+# Backup Configruation
+
+This stage configures any backup schedules as required. Backups in Lagoon use [k8up](https://k8up.io/).
+
+# Deployment Templating
+
+This stage templates out the deployments, this includes the Kubernetes kinds of `deployment`, `service`, `persistentvolumeclaim`, or any other kinds that may be supported.
+
+# Applying Deployments
+
+This stage actually applies the resources to Kubernetes and waits for the pods to rollout. Any errors here could be due to pods failing to start or schedule. The output of the failure should help indicate why.
+
+# Cronjob Cleanup
+
+This stage ensures that only cronjobs defined in the `.lagoon.yml` are configured by removing any that may have been removed from the `.lagoon.yml` file.
+
+# Post-Rollout tasks
+
+This stage runs any post-rollout tasks that may be configured in the `.lagoon.yml` file. These tasks are treated as a failure item and will result in a build failing if they fail. If you don't want these tasks to fail, you will need to write your tasks in a way to always `exit 0`.
+
+# Build and Deploy
+
+This stage indicates the completion of the build, a copy of the `.lagoon.yml` and `docker-compose.yml` files are saved again here to aid in future debugging if required.
+
+# Insights Gathering
+
+This stage runs after the build has completed, but will only generate warnings if it fails to complete. This is used by Lagoon to generate insights or collect security information about the images that were built and this is then sent to Lagoon. 
+
+!!! info
+    This stage is not enabled by default, it can result in builds taking longer to show as complete. This stage will eventually be moved out of the build process to run externally to the build.
+

docs/commands/lagoon-build.md

@@ -0,0 +1,57 @@
+## lagoon-build
+
+A tool to help with generating Lagoon resources for Lagoon builds
+
+### Synopsis
+
+A tool to help with generating Lagoon resources for Lagoon builds
+This tool will read a .lagoon.yml file and also all the required environment variables from
+within a Lagoon build to help with generating the resources
+
+```
+lagoon-build [flags]
+```
+
+### Options
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+  -h, --help                               help for lagoon-build
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build configuration](lagoon-build_configuration.md)	 - Generate configurations
+* [lagoon-build identify](lagoon-build_identify.md)	 - Identify resources
+* [lagoon-build tasks](lagoon-build_tasks.md)	 - Run tasks
+* [lagoon-build template](lagoon-build_template.md)	 - Generate templates
+* [lagoon-build validate](lagoon-build_validate.md)	 - Validate resources
+* [lagoon-build version](lagoon-build_version.md)	 - Version information
+
+###### Auto generated by spf13/cobra on 4-Oct-2024