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 cilium#2074

Signed-off-by: Christian Hörtnagl <[email protected]>

docs/Dockerfile.hugo

@@ -3,6 +3,71 @@ ARG HUGO_VERSION=0.124.1
 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: