Human-readable specification of Tracing Policy API

* switching to generator html (i.e. single HTML page)
* still work in progress

This commit supports the generation of a human-readable specifition of the
Tracing Policy API from source-code comments.

fixes #2074

Signed-off-by: Christian Hörtnagl <christian2@univie.ac.at>

docs/Dockerfile.hugo

@@ -3,6 +3,71 @@ ARG HUGO_VERSION=0.111.3
 ARG TARGETARCH
 WORKDIR tmp
 RUN curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz | tar xz
+ARG KUBERNETES_VERSION=1.28.8
+RUN curl -L https://github.com/kubernetes/kubernetes/archive/refs/tags/v${KUBERNETES_VERSION}.tar.gz | tar xz && \
+  mv kubernetes-${KUBERNETES_VERSION} kubernetes
+ARG OPENAPI_GENERATOR_VERSION=7.4.0
+RUN curl -L https://github.com/OpenAPITools/openapi-generator/archive/refs/tags/v${OPENAPI_GENERATOR_VERSION}.tar.gz | tar xz && \
+  mv openapi-generator-${OPENAPI_GENERATOR_VERSION} openapi-generator
+
+FROM debian:bookworm AS openapi-spec
+# obtain Tetragon CRDs (see pkg/k8s/Makefile re their generation)
+COPY /pkg/k8s/apis/cilium.io/client/crds/v1alpha1/* /crd/
+# start necessary components of Kubernetes cluster (etcd, kube-apiserver);
+# install Tetragon CRDs;
+# obtain OpenAPI spec for Tetragon from Kubernetes API
+RUN apt-get update -y && \
+  apt-get install -y curl git golang iproute2 jq make rsync && \
+  apt-get clean
+COPY --from=downloader /tmp/kubernetes /kubernetes/
+RUN \
+  test -s /crd/cilium.io_podinfo.yaml && \
+  test -s /crd/cilium.io_tracingpolicies.yaml && \
+  test -s /crd/cilium.io_tracingpoliciesnamespaced.yaml
+WORKDIR /kubernetes
+ARG ETCD_PORT=2382
+ARG API_SECURE_PORT=6444
+ARG KUBECTL_PROXY_PORT=8889
+RUN \
+  hack/install-etcd.sh && \
+  export PATH=/kubernetes/third_party/etcd:$PATH && \
+  export ENABLE_DAEMON=true && \
+  export START_MODE=nokubelet,nokubeproxy && \
+  hack/local-up-cluster.sh && \
+  \
+  export PATH=$PWD/_output/local/go/bin:$PATH && \
+  export KUBECONFIG=/var/run/kubernetes/admin.kubeconfig && \
+  for f in $(ls /crd/*.yaml); do \
+    if ! kubectl create -f $f; then exit 1; fi; \
+  done && \
+  \
+  cert=/var/run/kubernetes/client-admin.crt && \
+  key=/var/run/kubernetes/client-admin.key && \
+  curl -kL --cert $cert --key $key \
+    "https://localhost:$API_SECURE_PORT/openapi/v3" -o /tmp/paths.json && \
+  path=$(cat /tmp/paths.json | \
+    jq -r '.paths."apis/cilium.io/v1alpha1".serverRelativeURL') && \
+  test -n "$path" && \
+  curl --fail-with-body -kL --cert $cert --key $key \
+    "https://localhost:${API_SECURE_PORT}$path" -o /tmp/openapi.json
+# check that OpenAPI spec has been obtained
+RUN test -s /tmp/openapi.json
+
+FROM debian:bookworm AS openapi-documentation
+# compile openapi-generator
+RUN apt-get update -y && \
+  apt-get install -y default-jdk-headless maven && \
+  apt-get clean
+COPY --from=downloader /tmp/openapi-generator /openapi-generator/
+WORKDIR /openapi-generator
+RUN mvn clean install
+# run openapi-generator with OpenAPI spec as input
+COPY --from=openapi-spec /tmp/openapi.json /tmp/
+RUN test -s /tmp/openapi.json
+RUN java -jar /openapi-generator/modules/openapi-generator-cli/target/openapi-generator-cli.jar \
+  generate -g html -i /tmp/openapi.json -o /tmp && false
+# check that HTML page has been created
+RUN test -s /tmp/index.html
 
 # Hugo extended is dynamically linked
 FROM golang:1.20.2@sha256:1724dc3128e2e63f0bc3e055fe4fa478d67f6da4bd95c0e69690f6435f658804
@@ -13,10 +78,23 @@ RUN mkdir -p /var/hugo && \
     chown -R hugo /var/hugo && \
     runuser -u hugo -- git config --global --add safe.directory /src
 COPY --from=downloader /tmp/hugo /usr/local/bin/hugo
+COPY --chown=hugo:hugo /docs/ /src/docs/
+RUN test -d /src/docs/content
+RUN test -s /src/docs/hugo.toml
+# add OpenAPI documentation, also with Hugo front matter
+COPY --from=openapi-documentation --chown=hugo:hugo /tmp/index.html \
+  /src/docs/content/en/docs/reference/tracing-policy-api.md
+RUN test -s /src/docs/content/en/docs/reference/tracing-policy-api.md
+RUN cat > /src/docs/content/en/docs/reference/tracing-policy-api.md <<EOF
+---
+title: Tracing Policy API
+description: This reference is generated from an OpenAPI specification.
+weight: 5
+---
+EOF
 WORKDIR /src
 
 USER hugo:hugo
 EXPOSE 1313
 ENTRYPOINT ["/usr/local/bin/hugo"]
 CMD ["--help"]
-

docs/Makefile

@@ -3,16 +3,19 @@ HUGO_VERSION      = $(shell grep ^HUGO_VERSION ../netlify.toml | tail -n 1 | cut
 CONTAINER_ENGINE ?= docker
 CONTAINER_IMAGE  ?= cilium/tetragon-hugo:v$(HUGO_VERSION)
 # mount the parent folder to get the git history for Docsy to display the "last modified" indicator
-CONTAINER_RUN    ?= "$(CONTAINER_ENGINE)" run --rm --interactive --tty --volume "$(abspath $(CURDIR)/..):/src" --workdir /src/docs
+CONTAINER_RUN    ?= "$(CONTAINER_ENGINE)" run --rm --interactive --tty --workdir /src/docs
 HUGO_DOCKERFILE  ?= Dockerfile.hugo
 
 .PHONY: preview
 preview: image
 	$(CONTAINER_RUN) --cap-drop=ALL --cap-add=AUDIT_WRITE --read-only --mount type=tmpfs,destination=/tmp,tmpfs-mode=01777 -p 1313:1313 $(CONTAINER_IMAGE) server --buildFuture --environment development --bind 0.0.0.0 --destination /tmp/hugo --cleanDestinationDir --noBuildLock
 
 .PHONY: image
-image: ## Build a container image for the preview of the website
-	DOCKER_BUILDKIT=1 $(CONTAINER_ENGINE) build -f ${HUGO_DOCKERFILE} . --network host --tag $(CONTAINER_IMAGE) --build-arg HUGO_VERSION=$(HUGO_VERSION)
+image: ## Build a container image for the preview of the website;
+	# run build in parent directory of Dockerfile in order to include
+	# Tetragon CRDs (in pkg/k8s) in build context and to mount them
+	# in Dockerfile.hugo
+	cd .. && DOCKER_BUILDKIT=1 $(CONTAINER_ENGINE) build -f docs/${HUGO_DOCKERFILE} . --network host --tag $(CONTAINER_IMAGE) --build-arg HUGO_VERSION=$(HUGO_VERSION)
 
 .PHONY: clean
 clean:

docs/hugo.toml

@@ -11,9 +11,6 @@ enableMissingTranslationPlaceholders = true
 
 enableRobotsTXT = true
 
-# Will give values to .Lastmod etc.
-enableGitInfo = true
-
 # Comment out to enable taxonomies in Docsy
 disableKinds = ["taxonomy"]