From 89509ee07c46579b7ee5135cb5f79f7cc2833f69 Mon Sep 17 00:00:00 2001 From: Fabian Fischer Date: Fri, 23 Jun 2023 15:06:35 +0200 Subject: [PATCH 01/15] Stop running e2e tests and code linter for docs changes Signed-off-by: Fabian Fischer Signed-off-by: Matti Kotsalainen --- .github/workflows/e2e.yml | 2 ++ .github/workflows/lint.yml | 7 ++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index ecfe5d3b6..1620278c2 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -4,6 +4,8 @@ on: pull_request: branches: - master + paths-ignore: + - 'docs/**' jobs: e2e-test: diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 65d48df34..cf11b5da0 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -1,10 +1,15 @@ name: Lint on: - pull_request: {} + pull_request: + paths-ignore: + - 'docs/**' push: branches: - master + paths-ignore: + - 'docs/**' + jobs: lint: From b6ffea0459623cbb30fab48cb448571f3a0ac5b4 Mon Sep 17 00:00:00 2001 From: Fabian Fischer Date: Mon, 26 Jun 2023 15:53:46 +0200 Subject: [PATCH 02/15] Clean up docs makefile Signed-off-by: Fabian Fischer Signed-off-by: Matti Kotsalainen --- Makefile | 2 +- docs/check_orphans.py | 42 ---------- docs/docs.mk | 126 +++++++++--------------------- docs/modules/ROOT/pages/.vale.ini | 6 ++ 4 files changed, 46 insertions(+), 130 deletions(-) delete mode 100644 docs/check_orphans.py diff --git a/Makefile b/Makefile index 24d08c320..8aad85e28 100644 --- a/Makefile +++ b/Makefile @@ -97,7 +97,7 @@ vet: ## Run go vet against code go vet ./... .PHONY: lint -lint: generate fmt vet golangci-lint docs-generate ## Invokes all linting targets +lint: fmt vet golangci-lint ## Invokes all linting targets @echo 'Check for uncommitted changes ...' git diff --exit-code diff --git a/docs/check_orphans.py b/docs/check_orphans.py deleted file mode 100644 index eee32a24f..000000000 --- a/docs/check_orphans.py +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env python3 - -# This script alerts of orphan files in the modules/ROOT/pages directory -# that are not referenced in either ./k8up.adoc or modules/ROOT/nav.adoc. - -from os import listdir -from os.path import isfile, join -import re - -# Opens the input file referenced by its filename, and uses the -# regular expression to filter all included files. It then -# iterates over the list and appends an error if a file in -# the directory is not explicitly referenced in the input. -def check(input, regex): - with open(input, 'r') as file: - contents = file.read() - matches = re.findall(regex, contents) - for f in adoc_files: - if f not in matches: - errors.append('File "{entry}" not in {input}'.format(entry = f, input = input)) - -# Global variables -pages_dir = 'modules/ROOT/pages' -adoc_files = [f for f in listdir(pages_dir) if isfile(join(pages_dir, f))] -errors = [] - -# TODO adapt to special nav structure with partials - -# Perform checks -check('k8up.adoc', r'include::modules/ROOT/pages/(.+)\[\]') -check('modules/ROOT/nav.adoc', r'xref:(.+)\[') - -# Exit with error if some file is orphan -if len(errors) > 0: - for e in errors: - print(e) - exit(1) - -# All is well, bye bye -print('No orphan files in either k8up.adoc or modules/ROOT/nav.adoc') -exit(0) - diff --git a/docs/docs.mk b/docs/docs.mk index 2530d0dae..c34491b6d 100644 --- a/docs/docs.mk +++ b/docs/docs.mk @@ -1,99 +1,51 @@ -clean_targets += docs-clean - -pages := $(shell find . -type f -name '*.adoc') -out_dir := ./_public - -docker_cmd ?= docker -docker_opts ?= --rm --tty --user "$$(id -u)" - -antora_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/antora ghcr.io/vshn/antora:3.1.2.2 -antora_opts ?= --cache-dir=.cache/antora - -asciidoctor_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ asciidoctor/docker-asciidoctor asciidoctor -asciidoctor_pdf_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ ghcr.io/vshn/asciidoctor-pdf:1.39.1 --attribute toclevels=1 -asciidoctor_epub3_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ ghcr.io/vshn/asciidoctor-epub3:1.39.1 --attribute toclevels=1 -asciidoctor_opts ?= --destination-dir=$(out_dir) -asciidoctor_kindle_opts ?= --attribute ebook-format=kf8 - -vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages --workdir /pages ghcr.io/vshn/vale:2.15.5 --minAlertLevel=error . -hunspell_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/spell ghcr.io/vshn/hunspell:1.7.0.2 -d en,vshn -l -H _public/**/**/*.html -htmltest_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/_public:/test wjdp/htmltest:v0.12.0 -preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora ghcr.io/vshn/antora-preview:3.1.2.3 --antora=docs --style=k8up - -docs_usage_dir ?= docs/modules/ROOT/examples/usage - -## CRD API doc generator - -crd_ref_docs_bin ?= $(go_bin)/crd-ref-docs - -$(crd_ref_docs_bin): export GOBIN = $(go_bin) -$(crd_ref_docs_bin): | $(go_bin) - go install github.com/elastic/crd-ref-docs@latest - -## - -.PHONY: docs-all -docs-all: docs-update-usage docs-html docs-pdf ## Generate HTML and PDF docs - -.PHONY: docs-documents -docs-documents: docs-update-usage docs-pdf docs-manpage docs-kindle docs-epub ## Generate downloadable docs - -.PHONY: docs-update-usage -docs-update-usage: ## Generates dumps from `k8up --help`, which are then included as part of the docs - go run $(K8UP_MAIN_GO) --help > "$(docs_usage_dir)/k8up.txt" - go run $(K8UP_MAIN_GO) restic --help > "$(docs_usage_dir)/restic.txt" - go run $(K8UP_MAIN_GO) operator --help > "$(docs_usage_dir)/operator.txt" - -.PHONY: docs-generate-api -docs-generate-api: $(crd_ref_docs_bin) ## Generates API reference documentation - $(crd_ref_docs_bin) --source-path=api/v1 --config=docs/api-gen-config.yaml --renderer=asciidoctor --templates-dir=docs/api-templates --output-path=$(CRD_DOCS_REF_PATH) - -.PHONY: docs-generate -docs-generate: docs-update-usage docs-generate-api - -# This will clean the Antora Artifacts, not the npm artifacts -.PHONY: docs-clean -docs-clean: ## Cleans Antora artifacts - rm -rf $(out_dir) '?' .cache $(crd_ref_docs_bin) +# Determine whether to use podman +# +# podman currently fails when executing in GitHub actions on Ubuntu LTS 20.04, +# so we never use podman if GITHUB_ACTIONS==true. +use_podman := $(shell command -v podman 2>&1 >/dev/null; p="$$?"; \ + if [ "$${GITHUB_ACTIONS}" != "true" ]; then echo "$$p"; else echo 1; fi) + +ifeq ($(use_podman),0) + engine_cmd ?= podman + engine_opts ?= --rm --userns=keep-id +else + engine_cmd ?= docker + engine_opts ?= --rm --user "$$(id -u)" +endif + +use_go := $(shell command -v go 2>&1 >/dev/null; echo "$$?") + +ifeq ($(use_go),0) + go_cmd ?= go +else + go_cmd ?= $(engine_cmd) run $(engine_opts) -e GOCACHE=/k8up/.cache -w /k8up --volume "$${PWD}:/k8up" golang:1.20 go +endif + +orphans_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}:/antora" ghcr.io/vshn/antora-nav-orphans-checker:1.1 -antoraPath /antora/docs +vale_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages --workdir /pages ghcr.io/vshn/vale:2.15.5 --minAlertLevel=error . +preview_cmd ?= $(engine_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora ghcr.io/vshn/antora-preview:3.1.2.3 --antora=docs --style=k8up .PHONY: docs-check docs-check: ## Runs vale against the docs to check style + $(orphans_cmd) $(vale_cmd) -.PHONY: docs-syntax -docs-syntax: docs-html ## Runs hunspell against the docs - $(hunspell_cmd) - -.PHONY: docs-htmltest -docs-htmltest: docs-html docs-pdf docs-epub docs-kindle docs-manpage ## Runs htmltest against the docs - $(htmltest_cmd) - .PHONY: docs-preview docs-preview: ## Start documentation preview at http://localhost:2020 with Live Reload $(preview_cmd) -.PHONY: docs-html-open -docs-html-open: docs-html ## Start documentation preview at http://localhost:2020 with Live Reload and open in browser - $(shell xdg-open _public/index.html) - -.PHONY: docs-html docs-pdf docs-manpage docs-epub docs-kindle -docs-html: $(out_dir)/index.html ## Generate HTML version of documentation with Antora, output at ./_public/ -docs-pdf: $(out_dir)/k8up.pdf ## Generate PDF version of documentation with Antora, output at ./_public/ -docs-manpage: $(out_dir)/k8up.1 ## Generate Manpage version of documentation with Antora, output at ./_public/ -docs-epub: $(out_dir)/k8up.epub ## Generate epub version of documentation with Antora, output at ./_public/ -docs-kindle: $(out_dir)/k8up-kf8.epub ## Generate Kindle version of documentation with Antora, output at ./_public/ - -$(out_dir)/index.html: playbook.yml $(pages) - $(antora_cmd) $(antora_opts) $< - -$(out_dir)/%.1: docs/%.adoc $(pages) - $(asciidoctor_cmd) --backend=manpage --attribute doctype=manpage $(asciidoctor_opts) $< +.PHONY: docs-generate +docs-generate: docs-update-usage docs-generate-api -$(out_dir)/%.pdf: docs/%.adoc $(pages) - $(asciidoctor_pdf_cmd) $(asciidoctor_opts) $< +docs_usage_dir ?= docs/modules/ROOT/examples/usage +.PHONY: docs-update-usage +docs-update-usage: ## Generates dumps from `k8up --help`, which are then included as part of the docs + $(go_cmd) run $(K8UP_MAIN_GO) --help > "$(docs_usage_dir)/k8up.txt" + $(go_cmd) run $(K8UP_MAIN_GO) restic --help > "$(docs_usage_dir)/restic.txt" + $(go_cmd) run $(K8UP_MAIN_GO) operator --help > "$(docs_usage_dir)/operator.txt" -$(out_dir)/%.epub: docs/%.adoc $(pages) - $(asciidoctor_epub3_cmd) $(asciidoctor_opts) $< +## CRD API doc generator +.PHONY: docs-generate-api +docs-generate-api: ## Generates API reference documentation + $(go_cmd) run github.com/elastic/crd-ref-docs@latest --source-path=api/v1 --config=docs/api-gen-config.yaml --renderer=asciidoctor --templates-dir=docs/api-templates --output-path=$(CRD_DOCS_REF_PATH) -$(out_dir)/%-kf8.epub: docs/%.adoc $(pages) - $(asciidoctor_epub3_cmd) $(asciidoctor_kindle_opts) $(asciidoctor_opts) $< diff --git a/docs/modules/ROOT/pages/.vale.ini b/docs/modules/ROOT/pages/.vale.ini index e51957268..686788010 100644 --- a/docs/modules/ROOT/pages/.vale.ini +++ b/docs/modules/ROOT/pages/.vale.ini @@ -4,7 +4,13 @@ MinAlertLevel = warning # suggestion, warning or error # Only check Asciidoc files [*.adoc] BasedOnStyles = Microsoft + Microsoft.GenderBias = warning Microsoft.Contractions = warning Microsoft.Quotes = warning Microsoft.RangeFormat = warning +Microsoft.Avoid = warning + +# Ignore auto-generated references +[references/api-reference.adoc] +BasedOnStyles = "" From e25eb52a3f1f29830296b328002341a1a71ab289 Mon Sep 17 00:00:00 2001 From: Fabian Fischer Date: Wed, 28 Jun 2023 10:03:34 +0200 Subject: [PATCH 03/15] Run docs linter in CI Signed-off-by: Fabian Fischer Signed-off-by: Matti Kotsalainen --- .github/workflows/docs-lint.yml | 35 +++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .github/workflows/docs-lint.yml diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml new file mode 100644 index 000000000..a17b2dda9 --- /dev/null +++ b/.github/workflows/docs-lint.yml @@ -0,0 +1,35 @@ +name: Docs Lint + +on: + pull_request: + paths: + - 'docs/**' + push: + branches: + - master + paths: + - 'docs/**' + + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Determine Go version from go.mod + run: echo "GO_VERSION=$(go mod edit -json | jq -r .Go)" >> $GITHUB_ENV + + - uses: actions/setup-go@v3 + with: + go-version: ${{ env.GO_VERSION }} + + - uses: actions/cache@v3 + with: + path: ~/go/pkg/mod + key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + restore-keys: | + ${{ runner.os }}-go- + + - name: Run linters + run: make docs-check From 904142ebe8661407244ee9f0ea3f7133a95dcaa8 Mon Sep 17 00:00:00 2001 From: Fabian Fischer Date: Wed, 28 Jun 2023 10:21:12 +0200 Subject: [PATCH 04/15] Fix documentation writing style issues We enabled vale linting for documentation on CI. Vale found a couple of issues, that we fix with this commit. Signed-off-by: Fabian Fischer Signed-off-by: Matti Kotsalainen --- docs/modules/ROOT/pages/about/contribution_guide.adoc | 2 +- docs/modules/ROOT/pages/explanations/backup.adoc | 4 ++-- docs/modules/ROOT/pages/explanations/ide.adoc | 4 ++-- docs/modules/ROOT/pages/explanations/missing-docs.adoc | 2 +- .../modules/ROOT/pages/how-tos/application-aware-backups.adoc | 4 ++-- docs/modules/ROOT/pages/how-tos/optimize-schedules.adoc | 2 +- docs/modules/ROOT/pages/references/annotations.adoc | 4 ++-- docs/modules/ROOT/pages/references/object-specifications.adoc | 2 +- .../modules/ROOT/pages/references/schedule-specification.adoc | 4 ++-- docs/modules/ROOT/pages/tutorials/tutorial.adoc | 2 +- 10 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/modules/ROOT/pages/about/contribution_guide.adoc b/docs/modules/ROOT/pages/about/contribution_guide.adoc index 998a70bfa..91a919c5c 100644 --- a/docs/modules/ROOT/pages/about/contribution_guide.adoc +++ b/docs/modules/ROOT/pages/about/contribution_guide.adoc @@ -67,7 +67,7 @@ If you set your `user.name` and `user.email` git configs, you can sign your comm Some K8up contributors might not be familiar with `git`, or have used a web based editor, and thus asking them to `git commit --amend -s` is not the best way forward. In this case, maintainers can update the commits based on clause (c) of the DCO. -The most trivial way for a contributor to allow the maintainer to do this, is to add a DCO signature in a pull requests's comment, or a maintainer can simply note that the change is sufficiently trivial that it does not substantially change the existing contribution - i.e., a spelling change. +The most trivial way for a contributor to allow the maintainer to do this, is to add a DCO signature in a pull requests's comment, or a maintainer can simply note that the change is sufficiently trivial that it does not substantially change the existing contribution - for example a spelling change. When you add someone's DCO, please also add your own to keep a log. diff --git a/docs/modules/ROOT/pages/explanations/backup.adoc b/docs/modules/ROOT/pages/explanations/backup.adoc index 9703a88db..d5b3d269d 100644 --- a/docs/modules/ROOT/pages/explanations/backup.adoc +++ b/docs/modules/ROOT/pages/explanations/backup.adoc @@ -46,7 +46,7 @@ It also works with a variety of database systems and likewise programs that stor The drawback is that it transfers data via `stdout`, which is less efficient. The reason is that Kubernetes has to relay that data from the executed command to K8up. Another drawback is that your `Pod` must provide the tools to execute the command. -If it does not already contain that command – if it's a distro-less container for example – then the next method might be for you. +If it does not already contain that command, for example if it's a distro-less container, then the next method might be for you. Read xref:how-tos/application-aware-backups.adoc[] to learn more about to use this backup method. @@ -63,7 +63,7 @@ You can provide a special image which contains all the commands you need. You can access your `Secrets`. You can connect to services inside or outside the cluster, like a managed database. -The drawback – in contrast to the pure _backup command_ – is that this `Pod` runs in its own context and can't access services which are internal to another _Pod_. +The drawback, in contrast to the pure _backup command_, is that this `Pod` runs in its own context and can't access services which are internal to another _Pod_. You may also need to keep the `PreBackupPod` in sync with your main `Deployment` or with an external dependency. When you update your database in your main `Deployment` for example, you may need to update your `PreBackupPod` as well. diff --git a/docs/modules/ROOT/pages/explanations/ide.adoc b/docs/modules/ROOT/pages/explanations/ide.adoc index 6f9c91351..f36abc130 100644 --- a/docs/modules/ROOT/pages/explanations/ide.adoc +++ b/docs/modules/ROOT/pages/explanations/ide.adoc @@ -14,11 +14,11 @@ Just in order to run the integration tests you will need to do some extra config .. Put `integration` into _Custom tags_ . Now try to run a specific integration test. -You can use all the usual shortcuts to quickly run a test (e.g. kbd:[Ctrl+Shift+D] to debug a specific test method). +You can use all the usual shortcuts to quickly run a test (for example kbd:[Ctrl+Shift+D] to debug a specific test method). If it doesn't work, check the following: . Check that the _Custom tags_ field in _Preferences_ → _Go_ → _Build Tags & Vendoring_ contains to term `integration`. -. Make sure the _Working directory_ of your test's _Run Configuration_ points to the directory where your test lies, e.g. `/home/your_user/projects/k8up/controllers`. +. Make sure the _Working directory_ of your test's _Run Configuration_ points to the directory where your test lies, for example `/home/your_user/projects/k8up/controllers`. . Try to tick _Use all custom build tags_ checkbox in your test's _Run Configuration_. [IMPORTANT] diff --git a/docs/modules/ROOT/pages/explanations/missing-docs.adoc b/docs/modules/ROOT/pages/explanations/missing-docs.adoc index a97bae16a..f2ae967b4 100644 --- a/docs/modules/ROOT/pages/explanations/missing-docs.adoc +++ b/docs/modules/ROOT/pages/explanations/missing-docs.adoc @@ -3,7 +3,7 @@ For the following keywords documentation is missing and will be added over time. This should give you an idea what is included, but currently not documented. -* Describe prune and check jobs and their implications (e.g. locking) +* Describe prune and check jobs and their implications (for example locking) * Webhooks with backup information * Prometheus Metrics of Operator * Prometheus Pushgateway metrics of `k8up restic` diff --git a/docs/modules/ROOT/pages/how-tos/application-aware-backups.adoc b/docs/modules/ROOT/pages/how-tos/application-aware-backups.adoc index 4ea6c8003..9efa3fd94 100644 --- a/docs/modules/ROOT/pages/how-tos/application-aware-backups.adoc +++ b/docs/modules/ROOT/pages/how-tos/application-aware-backups.adoc @@ -18,7 +18,7 @@ template: ---- With this annotation the Operator will trigger that command inside the the container and capture the stdout to a backup. -The command is only executed on one Pod, if there are multiple Pods with the same owner reference (e.g. Deployments, Statefulsets etc). +The command is only executed on one Pod, if there are multiple Pods with the same owner reference (for example Deployments, Statefulsets etc). Tested with: @@ -121,4 +121,4 @@ template: - name: prometheus-exporter ... ----- \ No newline at end of file +---- diff --git a/docs/modules/ROOT/pages/how-tos/optimize-schedules.adoc b/docs/modules/ROOT/pages/how-tos/optimize-schedules.adoc index 29759c849..56a187869 100644 --- a/docs/modules/ROOT/pages/how-tos/optimize-schedules.adoc +++ b/docs/modules/ROOT/pages/how-tos/optimize-schedules.adoc @@ -6,7 +6,7 @@ When you start having hundreds of backup, check, prune or archive schedules it c However, manually trying to balance the schedules to different times is no solution either. Enter smart schedules. -In addition to the standard Cron syntax (e.g. `* */12 * * *`) K8up features stable randomization of schedules. +In addition to the standard Cron syntax (for example `* */12 * * *`) K8up features stable randomization of schedules. Enter a special `-random`-suffixed schedule to your spec in order to let K8up generate a schedule for you. A schedule of `@weekly-random` generates an effective schedule like `52 4 * * 4`. diff --git a/docs/modules/ROOT/pages/references/annotations.adoc b/docs/modules/ROOT/pages/references/annotations.adoc index 4f721120b..b8340fe16 100644 --- a/docs/modules/ROOT/pages/references/annotations.adoc +++ b/docs/modules/ROOT/pages/references/annotations.adoc @@ -19,7 +19,7 @@ See xref:references/operator-config-reference.adoc[Operator Configuration refere |`k8up.io/backupcommand` |If defined, this command is invoked in the context of this `Pod` on the beginning of a backup. -|A string that represents a command (and its arguments) to execute, e.g. `mysqldump -uroot -psecure --all-databases`. +|A string that represents a command (and its arguments) to execute, for example `mysqldump -uroot -psecure --all-databases`. See xref:how-tos/application-aware-backups.adoc[Application Aware Backups] for more information and an example. |`Pod` |`BACKUP_BACKUPCOMMANDANNOTATION` @@ -27,7 +27,7 @@ See xref:references/operator-config-reference.adoc[Operator Configuration refere |`k8up.io/file-extension` |The output of the `k8up.syn.tool/backupcommand` annotation is written to a file in order for it to be backed up. This annotation defines the file extension of that string. -|A string which is valid file-extension on the source system, e.g. `.sql`. +|A string which is valid file-extension on the source system, for example `.sql`. |`Pod` |`BACKUP_FILEEXTENSIONANNOTATION` diff --git a/docs/modules/ROOT/pages/references/object-specifications.adoc b/docs/modules/ROOT/pages/references/object-specifications.adoc index 96928d8dd..c7a6c0ca3 100644 --- a/docs/modules/ROOT/pages/references/object-specifications.adoc +++ b/docs/modules/ROOT/pages/references/object-specifications.adoc @@ -484,6 +484,6 @@ include::example$references/effective-schedule.yaml[] === Settings -* `spec.generatedSchedule`: schedule definition that was translated, e.g. from `@hourly-random` to `4 * * * *`. +* `spec.generatedSchedule`: schedule definition that was translated, for example from `@hourly-random` to `4 * * * *`. * `spec.jobType`: The K8up job type this resource is applicable to. * `spec.scheduleRefs`: A list of `Schedules` for which the generated schedule applies to. diff --git a/docs/modules/ROOT/pages/references/schedule-specification.adoc b/docs/modules/ROOT/pages/references/schedule-specification.adoc index 90352c593..96d7b3428 100644 --- a/docs/modules/ROOT/pages/references/schedule-specification.adoc +++ b/docs/modules/ROOT/pages/references/schedule-specification.adoc @@ -1,7 +1,7 @@ = Schedule Specification K8up comes with its own integrated scheduler and supports more advanced schedule specifications. -The standard Cron syntax (e.g. `0 */12 * * *`) is supported (see https://en.wikipedia.org/wiki/Cron[Wikipedia]) +The standard Cron syntax (for example `0 */12 * * *`) is supported (see https://en.wikipedia.org/wiki/Cron[Wikipedia]) All interpretation and scheduling is done in the machine's local time zone, as provided by the http://www.golang.org/pkg/time[Go time package]. @@ -33,7 +33,7 @@ The following non-standard schedules are supported: |`@every ` |Run once at fixed intervals, starting at the time it's added or K8up is started up. - `` is a string accepted by http://golang.org/pkg/time/#ParseDuration[time.ParseDuration] (e.g. `1h30m`). + `` is a string accepted by http://golang.org/pkg/time/#ParseDuration[`time.ParseDuration`] (for example `1h30m`). | |=== diff --git a/docs/modules/ROOT/pages/tutorials/tutorial.adoc b/docs/modules/ROOT/pages/tutorials/tutorial.adoc index 662cb6df3..cbb491772 100644 --- a/docs/modules/ROOT/pages/tutorials/tutorial.adoc +++ b/docs/modules/ROOT/pages/tutorials/tutorial.adoc @@ -85,7 +85,7 @@ IMPORTANT: On some laptops, running Minikube on battery power severely undermine After finishing all these steps, check that everything is running. Simply launch `k9s` and leave it running in its own terminal window. -Or – of course – you can use the usual `kubectl get pods` to check how your components are doing. +Or you can use the usual `kubectl get pods` to check how your components are doing. The https://asciinema.org/[asciinema] movie below shows all of these steps in real time. From 059138c129499551a266fe83df56d04936dbcb9a Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Thu, 1 Jun 2023 17:22:59 +0200 Subject: [PATCH 05/15] add coc and roadmap links to README Signed-off-by: Tobias Brunner Signed-off-by: Matti Kotsalainen --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 87df9598e..adfd6744c 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,8 @@ To run the end-to-end test (e.g. `make e2e-test`), you additionally need: These are the most common make targets: `build`, `test`, `docker-build`, `run`, `kind-run`. Run `make help` to get an overview over the relevant targets and their intentions. +You can find the project roadmap at [k8up.io](https://k8up.io/k8up/about/roadmap.html). + ### Code Structure K8s consists of two main modules: @@ -133,6 +135,10 @@ make clean There are a number of example configurations in [`config/samples`](config/samples). Apply them using `kubectl apply -f config/samples/somesample.yaml` +### Code of Conduct + +Our code of conduct can be read at [k8up.io](https://k8up.io/k8up/about/code_of_conduct.html). + [build]: https://github.com/k8up-io/k8up/actions?query=workflow%3ATest [releases]: https://github.com/k8up-io/k8up/releases [license]: https://github.com/k8up-io/k8up/blob/master/LICENSE From 8cedd8cf1938f92bec66a054f2c3877e228ad578 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 2 Jun 2023 09:23:45 +0200 Subject: [PATCH 06/15] introduce snyk in the README Signed-off-by: Tobias Brunner Signed-off-by: Matti Kotsalainen --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index adfd6744c..bdff3a62b 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,8 @@ Run `make help` to get an overview over the relevant targets and their intention You can find the project roadmap at [k8up.io](https://k8up.io/k8up/about/roadmap.html). +We use [Snyk](https://snyk.io/test/github/k8up-io/k8up) to test the code regularly for vulnerabilities and other security issues. + ### Code Structure K8s consists of two main modules: From 1a83482129c39616276dcadafc82077c85046b1f Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 2 Jun 2023 09:39:10 +0200 Subject: [PATCH 07/15] mention security vulnerability process Signed-off-by: Tobias Brunner Signed-off-by: Matti Kotsalainen --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index bdff3a62b..7ebf29a9d 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,8 @@ You can find the project roadmap at [k8up.io](https://k8up.io/k8up/about/roadmap We use [Snyk](https://snyk.io/test/github/k8up-io/k8up) to test the code regularly for vulnerabilities and other security issues. +If you find any security issue, please follow our [Vulnerability Reporting](https://k8up.io/k8up/about/vulnerability_reporting.html) process. + ### Code Structure K8s consists of two main modules: From de190f4793322511279a721043b6b1014bbe43bd Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 2 Jun 2023 09:52:05 +0200 Subject: [PATCH 08/15] configure the OpenSSF Scorecard scanning action Signed-off-by: Tobias Brunner Signed-off-by: Matti Kotsalainen --- .github/workflows/scorecard.yml | 72 +++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 73 insertions(+) create mode 100644 .github/workflows/scorecard.yml diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 000000000..c3578fc83 --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,72 @@ +# This workflow uses actions that are not certified by GitHub. They are provided +# by a third-party and are governed by separate terms of service, privacy +# policy, and support documentation. + +name: Scorecard supply-chain security +on: + # For Branch-Protection check. Only the default branch is supported. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection + branch_protection_rule: + # To guarantee Maintained check is occasionally updated. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained + schedule: + - cron: '33 1 * * 6' + push: + branches: [ "master" ] + +# Declare default permissions as read only. +permissions: read-all + +jobs: + analysis: + name: Scorecard analysis + runs-on: ubuntu-latest + permissions: + # Needed to upload the results to code-scanning dashboard. + security-events: write + # Needed to publish results and get a badge (see publish_results below). + id-token: write + # Uncomment the permissions below if installing in a private repository. + # contents: read + # actions: read + + steps: + - name: "Checkout code" + uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0 + with: + persist-credentials: false + + - name: "Run analysis" + uses: ossf/scorecard-action@e38b1902ae4f44df626f11ba0734b14fb91f8f86 # v2.1.2 + with: + results_file: results.sarif + results_format: sarif + # (Optional) "write" PAT token. Uncomment the `repo_token` line below if: + # - you want to enable the Branch-Protection check on a *public* repository, or + # - you are installing Scorecard on a *private* repository + # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat. + # repo_token: ${{ secrets.SCORECARD_TOKEN }} + + # Public repositories: + # - Publish results to OpenSSF REST API for easy access by consumers + # - Allows the repository to include the Scorecard badge. + # - See https://github.com/ossf/scorecard-action#publishing-results. + # For private repositories: + # - `publish_results` will always be set to `false`, regardless + # of the value entered here. + publish_results: true + + # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF + # format to the repository Actions tab. + - name: "Upload artifact" + uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8 # v3.1.0 + with: + name: SARIF file + path: results.sarif + retention-days: 5 + + # Upload the results to GitHub's code scanning dashboard. + - name: "Upload to code-scanning" + uses: github/codeql-action/upload-sarif@17573ee1cc1b9d061760f3a006fc4aac4f944fd5 # v2.2.4 + with: + sarif_file: results.sarif diff --git a/README.md b/README.md index 7ebf29a9d..2d0604647 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![GitHub downloads](https://img.shields.io/github/downloads/k8up-io/k8up/total)][releases] [![License](https://img.shields.io/github/license/k8up-io/k8up)][license] [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5388/badge)](https://bestpractices.coreinfrastructure.org/projects/5388) +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/k8up-io/k8up/badge)](https://api.securityscorecards.dev/projects/github.com/k8up-io/k8up) ![K8up logo](docs/modules/ROOT/assets/images/k8up-logo.svg "K8up") From c504713bb0703048fb50d694913a9e7a8a2af49d Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 2 Jun 2023 10:32:50 +0200 Subject: [PATCH 09/15] add artifact hub badge Signed-off-by: Tobias Brunner Signed-off-by: Matti Kotsalainen --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2d0604647..72477f877 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![License](https://img.shields.io/github/license/k8up-io/k8up)][license] [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5388/badge)](https://bestpractices.coreinfrastructure.org/projects/5388) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/k8up-io/k8up/badge)](https://api.securityscorecards.dev/projects/github.com/k8up-io/k8up) +[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/k8up)](https://artifacthub.io/packages/helm/k8up/k8up) ![K8up logo](docs/modules/ROOT/assets/images/k8up-logo.svg "K8up") From c46c0ae904e3fe74c0dbdf0231e63f5126490598 Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Mon, 31 Jul 2023 14:02:24 +0200 Subject: [PATCH 10/15] Added service account annotations Signed-off-by: Matti Kotsalainen --- charts/k8up/templates/serviceaccount.yaml | 5 +++++ charts/k8up/values.yaml | 2 ++ 2 files changed, 7 insertions(+) diff --git a/charts/k8up/templates/serviceaccount.yaml b/charts/k8up/templates/serviceaccount.yaml index 2fbbfb987..cef36db0a 100644 --- a/charts/k8up/templates/serviceaccount.yaml +++ b/charts/k8up/templates/serviceaccount.yaml @@ -5,4 +5,9 @@ metadata: name: {{ template "k8up.serviceAccountName" . }} labels: {{ include "k8up.labels" . | indent 4 }} +{{- with .Values.serviceAccount.annotations }} +annotations: + {{- toYaml . | nindent 4 }} +{{- end }} + {{- end -}} diff --git a/charts/k8up/values.yaml b/charts/k8up/values.yaml index f4d880253..e1aaf2030 100644 --- a/charts/k8up/values.yaml +++ b/charts/k8up/values.yaml @@ -19,6 +19,8 @@ serviceAccount: # -- The name of the service account to use. # If not set and create is true, a name is generated using the fullname template name: "" + annotations: {} + # -- Extra Labels to add to the service account. k8up: # -- envVars allows the specification of additional environment variables. From 1940cb239758e7c4824dc6d3495986e8b4ceaa44 Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Wed, 2 Aug 2023 09:09:04 +0200 Subject: [PATCH 11/15] Fixed comment Signed-off-by: Matti Kotsalainen --- charts/k8up/values.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/k8up/values.yaml b/charts/k8up/values.yaml index e1aaf2030..2018412b3 100644 --- a/charts/k8up/values.yaml +++ b/charts/k8up/values.yaml @@ -19,8 +19,8 @@ serviceAccount: # -- The name of the service account to use. # If not set and create is true, a name is generated using the fullname template name: "" + # -- Annotations to add to the service account. annotations: {} - # -- Extra Labels to add to the service account. k8up: # -- envVars allows the specification of additional environment variables. From d0a1e362c951f510ade2d6a25f7baacf481b0d1b Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Wed, 2 Aug 2023 09:10:23 +0200 Subject: [PATCH 12/15] README update Signed-off-by: Matti Kotsalainen --- charts/k8up/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/charts/k8up/README.md b/charts/k8up/README.md index 8c264526c..a6369eed7 100644 --- a/charts/k8up/README.md +++ b/charts/k8up/README.md @@ -80,6 +80,7 @@ Document your changes in values.yaml and let `make docs:helm` generate this sect | resources.requests.cpu | string | `"20m"` | CPU request of K8up operator. See [supported units][resource-units]. | | resources.requests.memory | string | `"128Mi"` | Memory request of K8up operator. See [supported units][resource-units]. | | securityContext | object | `{}` | Container security context | +| serviceAccount.annotations | object | `{}` | Annotations to add to the service account. | | serviceAccount.create | bool | `true` | Specifies whether a service account should be created | | serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the fullname template | | tolerations | list | `[]` | | From e8181d361ce26cbdf2289b9fc952d63cca9fdc6f Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Mon, 31 Jul 2023 14:02:24 +0200 Subject: [PATCH 13/15] Added service account annotations Signed-off-by: Matti Kotsalainen --- charts/k8up/templates/serviceaccount.yaml | 5 +++++ charts/k8up/values.yaml | 2 ++ 2 files changed, 7 insertions(+) diff --git a/charts/k8up/templates/serviceaccount.yaml b/charts/k8up/templates/serviceaccount.yaml index 2fbbfb987..cef36db0a 100644 --- a/charts/k8up/templates/serviceaccount.yaml +++ b/charts/k8up/templates/serviceaccount.yaml @@ -5,4 +5,9 @@ metadata: name: {{ template "k8up.serviceAccountName" . }} labels: {{ include "k8up.labels" . | indent 4 }} +{{- with .Values.serviceAccount.annotations }} +annotations: + {{- toYaml . | nindent 4 }} +{{- end }} + {{- end -}} diff --git a/charts/k8up/values.yaml b/charts/k8up/values.yaml index f4d880253..e1aaf2030 100644 --- a/charts/k8up/values.yaml +++ b/charts/k8up/values.yaml @@ -19,6 +19,8 @@ serviceAccount: # -- The name of the service account to use. # If not set and create is true, a name is generated using the fullname template name: "" + annotations: {} + # -- Extra Labels to add to the service account. k8up: # -- envVars allows the specification of additional environment variables. From 0a463e7786fde31893574f346b95b536366ece7e Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Wed, 2 Aug 2023 09:09:04 +0200 Subject: [PATCH 14/15] Fixed comment Signed-off-by: Matti Kotsalainen --- charts/k8up/values.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/k8up/values.yaml b/charts/k8up/values.yaml index e1aaf2030..2018412b3 100644 --- a/charts/k8up/values.yaml +++ b/charts/k8up/values.yaml @@ -19,8 +19,8 @@ serviceAccount: # -- The name of the service account to use. # If not set and create is true, a name is generated using the fullname template name: "" + # -- Annotations to add to the service account. annotations: {} - # -- Extra Labels to add to the service account. k8up: # -- envVars allows the specification of additional environment variables. From 968e19e08aa61804fa0649671f5b6cc2b9cf9b1d Mon Sep 17 00:00:00 2001 From: Matti Kotsalainen Date: Wed, 2 Aug 2023 09:10:23 +0200 Subject: [PATCH 15/15] README update Signed-off-by: Matti Kotsalainen --- charts/k8up/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/charts/k8up/README.md b/charts/k8up/README.md index 8c264526c..a6369eed7 100644 --- a/charts/k8up/README.md +++ b/charts/k8up/README.md @@ -80,6 +80,7 @@ Document your changes in values.yaml and let `make docs:helm` generate this sect | resources.requests.cpu | string | `"20m"` | CPU request of K8up operator. See [supported units][resource-units]. | | resources.requests.memory | string | `"128Mi"` | Memory request of K8up operator. See [supported units][resource-units]. | | securityContext | object | `{}` | Container security context | +| serviceAccount.annotations | object | `{}` | Annotations to add to the service account. | | serviceAccount.create | bool | `true` | Specifies whether a service account should be created | | serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the fullname template | | tolerations | list | `[]` | |