-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: start some basic documentation
- Loading branch information
1 parent
50c4ebf
commit 20ae25e
Showing
36 changed files
with
1,597 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.