Human-readable specification of Tracing Policy API

* still a draft version: I want to see again how this renders with
  in the deploy preview w/ Netlify

* in the final version /tmp/openapi.json, the input to operapi-generator,
  should be obtained life as part of make docs e.g. from a Minikube cluster
  w/ Tetragon

* in the final version docs/content/en/docs/reference/
  {Apis,Models,tracing-policy-api.md} should be git-ignored
  and generated also as part of make docs instead

* HUGO_VERSION was bumped from 0.111.3 to the current version 0.124.1
  because Hugo includes an embedded link render hook to resolve
  Markdown link destinations, which serves here, since 0.123.0.

* The specification is currently rendered as 5th "tile" in the reference
  section of the Tetragon online documentation.

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 <christian2@univie.ac.at>

contrib/openapi-generator/generate.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+set -e
+trap 'echo "error: $0:$LINENO"' ERR
+
+[ $# -eq 1 ]
+input_spec=$1
+
+output_dir=$(dirname $0)/../../docs/content/en/docs/reference
+[ -f $output_dir/_index.md ]
+
+[ -n "$OPENAPI_GENERATOR_HOME" ]
+
+# curr. using names with underlines, because Markdown link destinations
+# must not use fragment identifiers with spaces
+java -jar $OPENAPI_GENERATOR_HOME/modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g markdown \
+  -i $input_spec -o $output_dir \
+  --operation-id-name-mappings \
+"createCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Create_namespaced_tracing_policy",\
+"createCiliumIoV1alpha1TracingPolicy=Create_tracing_policy",\
+"deleteCiliumIoV1alpha1CollectionNamespacedTracingPolicyNamespaced=Delete_collection_of_namespaced_tracing_policies",\
+"deleteCiliumIoV1alpha1CollectionTracingPolicy=Delete_collection_of_tracing_policies",\
+"deleteCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Delete_namespaced_tracing_policy",\
+"deleteCiliumIoV1alpha1TracingPolicy=Delete_tracing_policy",\
+"listCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=List_namespaced_tracing_policies",\
+"listCiliumIoV1alpha1TracingPolicy=List_tracing_policies",\
+"listCiliumIoV1alpha1TracingPolicyNamespacedForAllNamespaces=List_namespaced_tracing_policies_for_all_namespaces",\
+"patchCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Patch_namespaced_tracing_policy",\
+"patchCiliumIoV1alpha1TracingPolicy=Patch_tracing_policy",\
+"replaceCiliumIoV1alpha1NamespacedTracingPolicyNamespaced=Replace_namespaced_tracing_policy",\
+"replaceCiliumIoV1alpha1TracingPolicy=Replace_tracing_policy"
+
+# add Hugo front matter as in surrounding content
+cat > $output_dir/tracing-policy-api.md << EOF
+---
+title: Tracing Policy API
+description: This reference is generated from an OpenAPI specification.
+weight: 5
+---
+
+EOF
+cat $output_dir/README.md >> $output_dir/tracing-policy-api.md
+rm $output_dir/README.md
+
+# some more post-processing of generated Markdown
+sed -Ei \
+  's/^# Documentation .+$/# Documentation for Tracing Policy API/;
+  s/^All URIs are relative to .*$//;
+  s/^\| Class (\| Method \| HTTP request \| Description \|)$/\1/;
+  s/^\|------------ .+$/\| --- \| --- \| --- \|/;
+  s/^(\| )?\*CiliumIoV1alpha1Api\* (\| .*)$/\2/;
+  s/^(\|.+\|.+\|).+$/\1/' \
+  $output_dir/tracing-policy-api.md

docs/Dockerfile.hugo

@@ -1,5 +1,5 @@
 FROM curlimages/curl:8.00.1@sha256:9e886c104cae1072f7874c9c214f77c6758f2e8a477234e32eda5fcbfa41f225 AS downloader
-ARG HUGO_VERSION=0.111.3
+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

docs/content/en/docs/reference/.gitignore

@@ -0,0 +1,2 @@
+/.openapi-generator-ignore
+/.openapi-generator/

docs/content/en/docs/reference/Models/io.cilium.v1alpha1.TracingPolicy.md

@@ -0,0 +1,12 @@
+# io.cilium.v1alpha1.TracingPolicy
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | [optional] [default to null] |
+| **kind** | **String** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+| **metadata** | [**io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta**](io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta.md) | Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata | [default to null] |
+| **spec** | [**io_cilium_v1alpha1_TracingPolicy_spec**](io_cilium_v1alpha1_TracingPolicy_spec.md) |  | [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.cilium.v1alpha1.TracingPolicyList.md

@@ -0,0 +1,12 @@
+# io.cilium.v1alpha1.TracingPolicyList
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | [optional] [default to null] |
+| **items** | [**List**](io.cilium.v1alpha1.TracingPolicy.md) | List of tracingpolicies. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md | [default to null] |
+| **kind** | **String** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+| **metadata** | [**io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta**](io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta.md) | Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.cilium.v1alpha1.TracingPolicyNamespaced.md

@@ -0,0 +1,12 @@
+# io.cilium.v1alpha1.TracingPolicyNamespaced
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | [optional] [default to null] |
+| **kind** | **String** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+| **metadata** | [**io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta**](io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta.md) | Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata | [default to null] |
+| **spec** | [**io_cilium_v1alpha1_TracingPolicy_spec**](io_cilium_v1alpha1_TracingPolicy_spec.md) |  | [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.cilium.v1alpha1.TracingPolicyNamespacedList.md

@@ -0,0 +1,12 @@
+# io.cilium.v1alpha1.TracingPolicyNamespacedList
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | [optional] [default to null] |
+| **items** | [**List**](io.cilium.v1alpha1.TracingPolicyNamespaced.md) | List of tracingpoliciesnamespaced. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md | [default to null] |
+| **kind** | **String** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+| **metadata** | [**io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta**](io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta.md) | Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.k8s.apimachinery.pkg.apis.meta.v1.DeleteOptions.md

@@ -0,0 +1,15 @@
+# io.k8s.apimachinery.pkg.apis.meta.v1.DeleteOptions
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | [optional] [default to null] |
+| **dryRun** | **List** | When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed | [optional] [default to null] |
+| **gracePeriodSeconds** | **Long** | The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. | [optional] [default to null] |
+| **kind** | **String** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | [optional] [default to null] |
+| **orphanDependents** | **Boolean** | Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the \"orphan\" finalizer will be added to/removed from the object's finalizers list. Either this field or PropagationPolicy may be set, but not both. | [optional] [default to null] |
+| **preconditions** | [**io.k8s.apimachinery.pkg.apis.meta.v1.Preconditions**](io.k8s.apimachinery.pkg.apis.meta.v1.Preconditions.md) | Must be fulfilled before a deletion is carried out. If not possible, a 409 Conflict status will be returned. | [optional] [default to null] |
+| **propagationPolicy** | **String** | Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground. | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta.md

@@ -0,0 +1,12 @@
+# io.k8s.apimachinery.pkg.apis.meta.v1.ListMeta
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **continue** | **String** | continue may be set if the user set a limit on the number of items returned, and indicates that the server has more data available. The value is opaque and may be used to issue another request to the endpoint that served this list to retrieve the next set of available objects. Continuing a consistent list may not be possible if the server configuration has changed or more than a few minutes have passed. The resourceVersion field returned when using this continue value will be identical to the value in the first response, unless you have received this token from an error message. | [optional] [default to null] |
+| **remainingItemCount** | **Long** | remainingItemCount is the number of subsequent items in the list which are not included in this list response. If the list request contained label or field selectors, then the number of remaining items is unknown and the field will be left unset and omitted during serialization. If the list is complete (either because it is not chunking or because this is the last chunk), then there are no more remaining items and this field will be left unset and omitted during serialization. Servers older than v1.15 do not set this field. The intended use of the remainingItemCount is *estimating* the size of a collection. Clients should not rely on the remainingItemCount to be set or to be exact. | [optional] [default to null] |
+| **resourceVersion** | **String** | String that identifies the server's internal version of this object that can be used by clients to determine when objects have changed. Value must be treated as opaque by clients and passed unmodified back to the server. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency | [optional] [default to null] |
+| **selfLink** | **String** | Deprecated: selfLink is a legacy read-only field that is no longer populated by the system. | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/en/docs/reference/Models/io.k8s.apimachinery.pkg.apis.meta.v1.ManagedFieldsEntry.md

@@ -0,0 +1,15 @@
+# io.k8s.apimachinery.pkg.apis.meta.v1.ManagedFieldsEntry
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **apiVersion** | **String** | APIVersion defines the version of this resource that this field set applies to. The format is \"group/version\" just like the top-level APIVersion field. It is necessary to track the version of a field set because it cannot be automatically converted. | [optional] [default to null] |
+| **fieldsType** | **String** | FieldsType is the discriminator for the different fields format and version. There is currently only one possible value: \"FieldsV1\" | [optional] [default to null] |
+| **fieldsV1** | [**Object**](.md) | FieldsV1 holds the first JSON version format as described in the "FieldsV1" type. | [optional] [default to null] |
+| **manager** | **String** | Manager is an identifier of the workflow managing these fields. | [optional] [default to null] |
+| **operation** | **String** | Operation is the type of operation which lead to this ManagedFieldsEntry being created. The only valid values for this field are 'Apply' and 'Update'. | [optional] [default to null] |
+| **subresource** | **String** | Subresource is the name of the subresource used to update that object, or empty string if the object was updated through the main resource. The value of this field is used to distinguish between managers, even if they share the same name. For example, a status update will be distinct from a regular update using the same manager name. Note that the APIVersion field is not related to the Subresource field and it always corresponds to the version of the main resource. | [optional] [default to null] |
+| **time** | **Date** | Time is the timestamp of when the ManagedFields entry was added. The timestamp will also be updated if a field is added, the manager changes any of the owned fields value or removes a field. The timestamp does not update when a field is removed from the entry because another manager took it over. | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+