feat: automatically update documentation repository (#610)

Co-authored-by: Moritz Wiesinger <[email protected]>

.github/actions/update-documentation/action.yml

@@ -0,0 +1,83 @@
+name: "Update KLT Docs/Examples"
+description: "Update Keptn Lifecycle Toolkit Documentation and Examples"
+inputs:
+   version:
+     required: true
+     description: "Version of the Keptn Lifecycle Toolkit Documentation to be deployed"
+   doc-repo:
+     required: true
+     description: "Path to the documentation repository"
+     default: "keptn-sandbox/lifecycle-toolkit-docs"
+   examples-repo:
+     required: true
+     description: "Path to the examples repository"
+     default: "keptn-sandbox/lifecycle-toolkit-examples"
+   klt-repo:
+     required: true
+     description: "Path to the klt repository"
+     default: "lifecycle-toolkit"
+   update-main:
+     description: "Update the main version of the documentation"
+     required: true
+     default: "false"
+   target-branch:
+     description: "Target branch for the documentation"
+     default: "dev"
+     required: true
+   token:
+     description: "Token to access the documentation repository"
+     required: true
+
+
+runs:
+  using: "composite"
+
+  steps:
+  - uses: actions/setup-python@v4
+    with:
+      python-version: '3.10'
+
+  - name: Check out documentation
+    uses: actions/checkout@v3
+    with:
+      repository: ${{ inputs.doc-repo }}
+      path: "doc-repo"
+      ref: "main"
+      token: ${{ inputs.token }}
+      fetch-depth: 0
+
+  - name: Check out examples
+    uses: actions/checkout@v3
+    if: inputs.update-main == 'true'
+    with:
+      repository: ${{ inputs.examples-repo }}
+      path: "example-repo"
+      ref: "main"
+      token: ${{ inputs.token }}
+      fetch-depth: 0
+
+  - name: Install dependencies
+    run: pip install -r .github/scripts/doc_update/requirements.txt
+    shell: bash
+
+  - name: Update documentation
+    shell: bash
+    run: python .github/actions/update-documentation/scripts/doc_update/update_docs.py --version ${{ inputs.version }} --klt-docs doc-repo --klt-repo ${{ inputs.klt-repo }} --klt-examples ${{ inputs.examples-repo }} --update-main=${{ inputs.main-version }}
+
+  - name: Commit changes
+    uses: EndBug/add-and-commit@v9
+    with:
+      author_name: "Keptn Sandbox Bot"
+      author_email: "[email protected]"
+      cwd: "doc-repo"
+      message: "Update documentation for version ${{ inputs.version }}"
+      new_branch: ${{ inputs.target-branch }}
+
+  - name: Commit changes to examples
+    uses: EndBug/add-and-commit@v9
+    with:
+      author_name: Keptn Bot
+      author_email: [email protected]
+      cwd: examples-repo
+      message: "Update examples for version ${{ inputs.version }}"
+      new_branch: ${{ inputs.target-branch }}

.github/actions/update-documentation/scripts/requirements.txt

@@ -0,0 +1,3 @@
+dirsync==2.2.5
+pyyaml==5.3.1
+argparse==1.4.0

.github/actions/update-documentation/scripts/update_docs.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+import os
+from dirsync import sync
+import yaml
+import argparse
+
+parser = argparse.ArgumentParser(description="Keptn Documentation Updater")
+parser.add_argument('--version', '-v', help='Keptn LT Version', default="development", required=True, dest='version')
+parser.add_argument('--update-main', '-u', action='store_true', help='Update main version', dest='update_main')
+parser.add_argument('--klt-repo', '-k', help='Keptn LT Repo Path', required=True, dest='klt_repo')
+parser.add_argument('--klt-docs', '-d', help='Keptn LT Docs Repo Path', required=True, dest='klt_docs')
+parser.add_argument('--klt-examples', '-e', help='Keptn LT Examples Repo Path', required=True, dest='klt_examples')
+
+args = parser.parse_args()
+
+klt_repo = args.klt_repo
+klt_docs = args.klt_docs
+klt_examples = args.klt_examples
+version = args.version
+update_main = args.update_main
+
+if klt_docs == "" or klt_repo == "":
+    print("Please provide the path to the Keptn LT and Keptn Docs Repos")
+    exit(1)
+
+# Sync the docs from the KLT repo to the docs folder, sync main-version docs to the root
+sync(klt_repo + '/docs/content/docs', klt_docs + '/content/en/docs-' + version, 'sync', exclude=['^tmp', 'Makefile'], create=True)
+
+# Update the version in the docs
+with open(klt_docs + "/" + 'config.yaml', 'r') as f:
+    config = f.read()
+    data = yaml.safe_load(config)
+
+if "versions" not in data['params']:
+    data['params']['versions'] = []
+
+version_exists = False
+versions = data['params']['versions']
+for v in versions:
+    if v['version'] == version:
+        version_exists = True
+
+if not version_exists:
+    versions.append({'version': version, 'url': '/docs-' + version + '/'})
+
+versions.sort(key=lambda x: (x['version'][0].isdigit(), x['version']), reverse=True)
+
+if update_main:
+    sync(klt_docs + '/content/en/docs-' + version, klt_docs + '/content/en/docs', 'sync', exclude=['^tmp', 'Makefile'], create=True)
+    data['params']['version'] = version
+    sync(klt_repo + '/examples', klt_examples, 'sync', exclude=['^tmp'], create=True)
+
+
+with open(klt_docs + "/" + 'config.yaml', 'w') as file:
+    documents = yaml.dump(data, file)
+

.github/workflows/CI.yaml

@@ -264,3 +264,18 @@ jobs:
       with:
         name: ${{ matrix.config.name }}-manifest
         path: ${{ matrix.config.folder }}/config/rendered/release.yaml
+
+  update-docs:
+    name: Update Documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Update Documentation
+        uses: ./.github/actions/update-documentation
+        if: github.event_name == 'push' && needs.prepare_ci_run.outputs.NON_FORKED_AND_NON_ROBOT_RUN == 'true'
+        with:
+          version: "dev"
+          klt-repo: ${{ github.workspace }}
+          token: ${{ secrets.KEPTN_SANDBOX_BOT_TOKEN }}

.github/workflows/check-links.yaml

@@ -21,6 +21,6 @@ jobs:
           config-file: '.github/mlc_config.json'
           use-verbose-mode: true
           use-quiet-mode: true
-          folder-path: 'examples'
+          folder-path: 'examples,docs'
           file-path: 'README.md'
 

.github/workflows/release.yml

@@ -146,3 +146,20 @@ jobs:
         with:
           tag_name: ${{ needs.release-please.outputs.tag_name }}
           files: manifest.yaml
+
+  update-docs:
+    name: Update Documentation
+    needs:
+    - release-please
+    if: needs.release-please.outputs.releases_created == 'true'
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Update Documentation
+        uses: ./.github/actions/update-documentation
+        with:
+          version: ${{ needs.release-please.outputs.tag_name }}
+          klt-repo: ${{ github.workspace }}
+          token: ${{ secrets.KEPTN_SANDBOX_BOT_TOKEN }}

.gitignore

@@ -35,3 +35,4 @@ manifests/
 
 ## Kubebuilder
 **/kubebuilder
+/docs/tmp/

dashboards/grafana/Makefile

@@ -18,7 +18,7 @@ generate-configmaps:
 	kubectl create configmap grafana-dashboard-keptn-overview -n monitoring --from-file=./grafana_dashboard_overview.json -o yaml --dry-run=client > configmap/grafana-dashboard-keptn-overview.yaml
 	kubectl create configmap grafana-dashboard-keptn-applications -n monitoring --from-file=./grafana_dashboard_applications.json -o yaml --dry-run=client > configmap/grafana-dashboard-keptn-applications.yaml
 	kubectl create configmap grafana-dashboard-keptn-workloads -n monitoring --from-file=./grafana_dashboard_workloads.json -o yaml --dry-run=client > configmap/grafana-dashboard-keptn-workloads.yaml
-	cp configmap/* ../../examples/observability/config/prometheus
+	cp configmap/* ../../examples/support/observability/config/prometheus
 
 .PHONY: import
 import:

docs/Makefile

@@ -0,0 +1,24 @@
+DOCREPO := github.com/keptn-sandbox/lifecycle-toolkit-docs
+TMPDIR := $(CURDIR)/tmp
+VOLUMES := -v $(TMPDIR)/lifecycle-toolkit-docs:/src -v $(CURDIR)/content/docs:/src/content/en/docs
+# renovate: datasource=docker depName=klakegg/hugo
+IMAGE := klakegg/hugo:0.105.0-ext
+
+.PHONY: build server clean htmltest
+
+clone:
+	@rm -rf $(TMPDIR)/lifecycle-toolkit-docs | true
+	@mkdir -p $(TMPDIR)/lifecycle-toolkit-docs
+	@git clone https://$(DOCREPO) $(TMPDIR)/lifecycle-toolkit-docs
+
+build:
+	docker run --rm -it $(VOLUMES) $(IMAGE) -D -v
+
+server:
+	docker run --rm -it $(VOLUMES) -p 1313:1313 $(IMAGE) server -D
+
+clean:
+	docker run --rm -it $(VOLUMES) $(IMAGE) --cleanDestinationDir
+
+htmltest:
+	docker run -v $(CURDIR):/test --rm wjdp/htmltest -s -c .htmltest.yml public

docs/content/404/_index.md

@@ -0,0 +1,3 @@
+---
+title: Page Not Found
+---

docs/content/_index.md

@@ -0,0 +1,37 @@
++++
+title = "Home"
+
++++
+
+{{< blocks/cover title="Welcome to the Keptn Lifecycle Toolkit Documentation" image_anchor="top" height="half" color="primary" >}}
+<div class="mx-auto">
+	<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
+		Docs <i class="fas fa-arrow-alt-circle-right ml-2"></i>
+	</a>
+    <a class="btn btn-lg btn-primary mr-3 mb-4" href="https://github.com/keptn/lifecycle-toolkit/releases">
+		Releases <i class="fab fa-github ml-2 "></i>
+	</a>
+</div>
+{{< /blocks/cover >}}
+
+
+{{% blocks/lead color="white" %}}
+[![Keptn Lifecycle Toolkit in a Nutshell](https://img.youtube.com/vi/K-cvnZ8EtGc/0.jpg)](https://www.youtube.com/watch?v=K-cvnZ8EtGc)
+{{% /blocks/lead %}}
+
+{{< blocks/section color="dark" >}}
+{{% blocks/feature icon="fa-lightbulb" title="Keptn Recordings" %}}
+See Keptn [in Action](https://youtube.com/playlist?list=PL6i801Rjt9DbikPPILz38U1TLMrEjppzZ)
+{{% /blocks/feature %}}
+
+
+{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/keptn/lifecycle-toolkit" %}}
+We do a [Pull Request](https://github.com/keptn/lifecycle-toolkit/pulls) contributions workflow on **GitHub**. New users are always welcome!
+{{% /blocks/feature %}}
+
+
+{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/keptnProject" %}}
+For announcement of latest features etc.
+{{% /blocks/feature %}}
+
+{{< /blocks/section >}}

docs/content/docs/_index.md

@@ -0,0 +1,8 @@
+---
+title: Docs
+linktitle: Docs
+description: Learn how to use Keptn.
+cascade:
+  type: docs
+
+---

docs/content/docs/concepts/_index.md

@@ -0,0 +1,8 @@
+---
+title: Concepts
+description: Learn about underlying concepts of the keptn lifecycle toolkit.
+icon: concepts
+layout: quickstart
+weight: 50
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---

docs/content/docs/concepts/apps/_index.md

@@ -0,0 +1,30 @@
+---
+title: Apps
+description: Learn what Keptn Apps are and how to use them
+icon: concepts
+layout: quickstart
+weight: 10
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+An App contains information about all workloads and checks associated with an application.
+It will use the following structure for the specification of the pre/post deployment and pre/post evaluations checks that should be executed at app level:
+
+```
+apiVersion: lifecycle.keptn.sh/v1alpha2
+kind: KeptnApp
+metadata:
+name: podtato-head
+namespace: podtato-kubectl
+spec:
+version: "1.3"
+workloads:
+- name: podtato-head-left-arm
+version: 0.1.0
+- name: podtato-head-left-leg
+postDeploymentTasks:
+- post-deployment-hello
+preDeploymentEvaluations:    
+- my-prometheus-definition
+```
+While changes in the workload version will affect only workload checks, a change in the app version will also cause a new execution of app level checks.

docs/content/docs/concepts/evaluations/_index.md

@@ -0,0 +1,48 @@
+---
+title: Evaluations
+description: Learn what Keptn Evaluations are and how to use them
+icon: concepts
+layout: quickstart
+weight: 10
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+
+### Keptn Evaluation Definition
+A `KeptnEvaluationDefinition` is a CRD used to define evaluation tasks that can be run by the Keptn Lifecycle Toolkit
+as part of pre- and post-analysis phases of a workload or application.
+
+A Keptn evaluation definition looks like the following:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha2
+kind: KeptnEvaluationDefinition
+metadata:
+  name: my-prometheus-evaluation
+spec:
+  source: prometheus
+  objectives:
+    - name: query-1
+      query: "xxxx"
+      evaluationTarget: <20
+    - name: query-2
+      query: "yyyy"
+      evaluationTarget: >4
+```
+
+
+### Keptn Evaluation Provider
+A `KeptnEvaluationProvider` is a CRD used to define evaluation provider, which will provide data for the
+pre- and post-analysis phases of a workload or application.
+
+A Keptn evaluation provider looks like the following:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha2
+kind: KeptnEvaluationProvider
+metadata:
+  name: prometheus
+spec:
+  targetServer: "http://prometheus-k8s.monitoring.svc.cluster.local:9090"
+  secretName: prometheusLoginCredentials
+```

docs/content/docs/concepts/overview/_index.md

@@ -0,0 +1,7 @@
+---
+title: Overview
+icon: concepts
+layout: quickstart
+weight: 5
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---

docs/content/docs/concepts/overview/how-it-works/_index.md

@@ -0,0 +1,7 @@
+---
+title: How it works
+icon: concepts
+layout: quickstart
+weight: 5
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---

docs/content/docs/concepts/overview/phases/_index.md

@@ -0,0 +1,7 @@
+---
+title: Phases
+icon: concepts
+layout: quickstart
+weight: 10
+hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
+---