operator: Migrate API docs generation tool (#7716)

operator/.bingo/Variables.mk

@@ -29,11 +29,11 @@ $(CONTROLLER_GEN): $(BINGO_DIR)/controller-gen.mod
 	@echo "(re)installing $(GOBIN)/controller-gen-v0.10.0"
 	@cd $(BINGO_DIR) && GOWORK=off $(GO) build -mod=mod -modfile=controller-gen.mod -o=$(GOBIN)/controller-gen-v0.10.0 "sigs.k8s.io/controller-tools/cmd/controller-gen"
 
-GEN_CRD_API_REFERENCE_DOCS := $(GOBIN)/gen-crd-api-reference-docs-v0.4.2
+GEN_CRD_API_REFERENCE_DOCS := $(GOBIN)/gen-crd-api-reference-docs-v0.0.3
 $(GEN_CRD_API_REFERENCE_DOCS): $(BINGO_DIR)/gen-crd-api-reference-docs.mod
 	@# Install binary/ries using Go 1.14+ build command. This is using bwplotka/bingo-controlled, separate go module with pinned dependencies.
-	@echo "(re)installing $(GOBIN)/gen-crd-api-reference-docs-v0.4.2"
-	@cd $(BINGO_DIR) && GOWORK=off $(GO) build -mod=mod -modfile=gen-crd-api-reference-docs.mod -o=$(GOBIN)/gen-crd-api-reference-docs-v0.4.2 "github.com/aminesnow/gen-crd-api-reference-docs"
+	@echo "(re)installing $(GOBIN)/gen-crd-api-reference-docs-v0.0.3"
+	@cd $(BINGO_DIR) && GOWORK=off $(GO) build -mod=mod -modfile=gen-crd-api-reference-docs.mod -o=$(GOBIN)/gen-crd-api-reference-docs-v0.0.3 "github.com/ViaQ/gen-crd-api-reference-docs"
 
 GOFUMPT := $(GOBIN)/gofumpt-v0.4.0
 $(GOFUMPT): $(BINGO_DIR)/gofumpt.mod

operator/.bingo/gen-crd-api-reference-docs.mod

@@ -2,4 +2,4 @@ module _ // Auto generated by https://github.com/bwplotka/bingo. DO NOT EDIT
 
 go 1.19
 
-require github.com/aminesnow/gen-crd-api-reference-docs v0.4.2
+require github.com/ViaQ/gen-crd-api-reference-docs v0.0.3

operator/.bingo/gen-crd-api-reference-docs.sum

@@ -1,14 +1,11 @@
-github.com/aminesnow/gen-crd-api-reference-docs v0.3.1 h1:IaijJi+CTTW5qPMkoGoqWAwfiOWrKg28PX/zpcneVbA=
-github.com/aminesnow/gen-crd-api-reference-docs v0.3.1/go.mod h1:7J+YZ/5vg1ipvcSA6xvG/yf2elOooX76hY+djHUJRKQ=
-github.com/aminesnow/gen-crd-api-reference-docs v0.4.0 h1:E4oz6CT1ZXQ2Bjkge79Fv9PYvc53dyZ+PeAdOgK5CLY=
-github.com/aminesnow/gen-crd-api-reference-docs v0.4.0/go.mod h1:+rKY73OjTIruf1SSjNEX/BQ0giZs7HnDVGRLk6lNVWQ=
-github.com/aminesnow/gen-crd-api-reference-docs v0.4.2 h1:De+lkI8HzPr4wp7wTteKYqvOVKduLmMkDVsHmT4Lg34=
-github.com/aminesnow/gen-crd-api-reference-docs v0.4.2/go.mod h1:1cYMS+Yggurk7ZNmsn9B7IagUhZ9jmLAsThYW/111Q4=
+github.com/ViaQ/gen-crd-api-reference-docs v0.0.2 h1:OVI5SfpuPo/TTANkqiJvNf+qUWE50+DvhbQC12e3ogk=
+github.com/ViaQ/gen-crd-api-reference-docs v0.0.2/go.mod h1:WxpfZG1IGqhtLb0yM4e0Bl7K8VVmg4FAvQkd3x2R660=
+github.com/ViaQ/gen-crd-api-reference-docs v0.0.3 h1:ChSn0sz5GEkVkjart0RlyeHtuI2ahufu3qyvyjksDq0=
+github.com/ViaQ/gen-crd-api-reference-docs v0.0.3/go.mod h1:WxpfZG1IGqhtLb0yM4e0Bl7K8VVmg4FAvQkd3x2R660=
 github.com/go-logr/logr v0.2.0 h1:QvGt2nLcHH0WK9orKa+ppBPAxREcH364nPUedEpK0TY=
 github.com/pkg/errors v0.8.1 h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=
 github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q=
 github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
 k8s.io/gengo v0.0.0-20201203183100-97869a43a9d9 h1:1bLA4Agvs1DILmc+q2Bbcqjx6jOHO7YEFA+G+0aTZoc=
-k8s.io/gengo v0.0.0-20221011193443-fad74ee6edd9 h1:iu3o/SxaHVI7tKPtkGzD3M9IzrE21j+CUKH98NQJ8Ms=
 k8s.io/klog v0.2.0 h1:0ElL0OHzF3N+OhoJTL0uca20SxtYt4X4+bzHeqrB83c=
 k8s.io/klog/v2 v2.2.0 h1:XRvcwJozkgZ1UQJmfMGpvRthQHOvihEhYtDfAaxMz/A=

operator/.bingo/variables.env

@@ -12,7 +12,7 @@ BINGO="${GOBIN}/bingo-v0.7.0"
 
 CONTROLLER_GEN="${GOBIN}/controller-gen-v0.10.0"
 
-GEN_CRD_API_REFERENCE_DOCS="${GOBIN}/gen-crd-api-reference-docs-v0.4.2"
+GEN_CRD_API_REFERENCE_DOCS="${GOBIN}/gen-crd-api-reference-docs-v0.0.3"
 
 GOFUMPT="${GOBIN}/gofumpt-v0.4.0"
 

operator/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## Main
 
+- [7716](https://github.com/grafana/loki/pull/7716) **aminesnow**: Migrate API docs generation tool
 - [7710](https://github.com/grafana/loki/pull/7710) **periklis**: Fix LokiStackController watches for cluster-scoped resources
 - [7682](https://github.com/grafana/loki/pull/7682) **periklis**: Refactor cluster proxy to use configv1.Proxy on OpenShift
 - [7711](https://github.com/grafana/loki/pull/7711) **Red-GV**: Remove default value from replicationFactor field

operator/docs/operator/api.md

@@ -132,6 +132,72 @@ OPASpec
 </tbody>
 </table>
 
+## ClusterProxy { #loki-grafana-com-v1-ClusterProxy }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1-LokiStackSpec">LokiStackSpec</a>)
+</p>
+<div>
+<p>ClusterProxy is the Proxy configuration when the cluster is behind a Proxy.</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>httpProxy</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>HTTPProxy configures the HTTP_PROXY/http_proxy env variable.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>httpsProxy</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>HTTPSProxy configures the HTTPS_PROXY/https_proxy env variable.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>noProxy</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>NoProxy configures the NO_PROXY/no_proxy env variable.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>readVarsFromEnv</code><br/>
+<em>
+bool
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>ReadVarsFromEnv defines a flag to use Operator-lib provides a helper function</p>
+</td>
+</tr>
+</tbody>
+</table>
+
 ## IngestionLimitSpec { #loki-grafana-com-v1-IngestionLimitSpec }
 <p>
 (<em>Appears on:</em><a href="#loki-grafana-com-v1-LimitsTemplateSpec">LimitsTemplateSpec</a>)
@@ -604,7 +670,10 @@ PodStatusMap
 <th>Description</th>
 </tr>
 </thead>
-<tbody><tr><td><p>&#34;FailedComponents&#34;</p></td>
+<tbody><tr><td><p>&#34;FailedCertificateRotation&#34;</p></td>
+<td><p>ReasonFailedCertificateRotation when the reconciler cannot rotate any of the required TLS certificates.</p>
+</td>
+</tr><tr><td><p>&#34;FailedComponents&#34;</p></td>
 <td><p>ReasonFailedComponents when all/some LokiStack components fail to roll out.</p>
 </td>
 </tr><tr><td><p>&#34;InvalidGatewayTenantSecret&#34;</p></td>
@@ -792,6 +861,20 @@ string
 </tr>
 <tr>
 <td>
+<code>proxy</code><br/>
+<em>
+<a href="#loki-grafana-com-v1-ClusterProxy">
+ClusterProxy
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Proxy defines the spec for the object proxy to configure cluster proxy information.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>replicationFactor</code><br/>
 <em>
 int32
@@ -1633,7 +1716,7 @@ uint
 <code>streams</code><br/>
 <em>
 <a href="#loki-grafana-com-v1-RetentionStreamSpec">
-[]*github.com/grafana/loki/operator/apis/loki/v1.RetentionStreamSpec
+[]*RetentionStreamSpec
 </a>
 </em>
 </td>
@@ -1646,6 +1729,9 @@ uint
 </table>
 
 ## RetentionStreamSpec { #loki-grafana-com-v1-RetentionStreamSpec }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1-RetentionLimitSpec">RetentionLimitSpec</a>)
+</p>
 <div>
 <p>RetentionStreamSpec defines a log stream with separate retention time.</p>
 </div>
@@ -2328,6 +2414,9 @@ AlertingRuleStatus
 </table>
 
 ## AlertingRuleGroup { #loki-grafana-com-v1beta1-AlertingRuleGroup }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1beta1-AlertingRuleSpec">AlertingRuleSpec</a>)
+</p>
 <div>
 <p>AlertingRuleGroup defines a group of Loki alerting rules.</p>
 </div>
@@ -2382,7 +2471,7 @@ int32
 <code>rules</code><br/>
 <em>
 <a href="#loki-grafana-com-v1beta1-AlertingRuleGroupSpec">
-[]*github.com/grafana/loki/operator/apis/loki/v1beta1.AlertingRuleGroupSpec
+[]*AlertingRuleGroupSpec
 </a>
 </em>
 </td>
@@ -2394,6 +2483,9 @@ int32
 </table>
 
 ## AlertingRuleGroupSpec { #loki-grafana-com-v1beta1-AlertingRuleGroupSpec }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1beta1-AlertingRuleGroup">AlertingRuleGroup</a>)
+</p>
 <div>
 <p>AlertingRuleGroupSpec defines the spec for a Loki alerting rule.</p>
 </div>
@@ -2503,7 +2595,7 @@ string
 <code>groups</code><br/>
 <em>
 <a href="#loki-grafana-com-v1beta1-AlertingRuleGroup">
-[]*github.com/grafana/loki/operator/apis/loki/v1beta1.AlertingRuleGroup
+[]*AlertingRuleGroup
 </a>
 </em>
 </td>
@@ -4150,6 +4242,9 @@ RecordingRuleStatus
 </table>
 
 ## RecordingRuleGroup { #loki-grafana-com-v1beta1-RecordingRuleGroup }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1beta1-RecordingRuleSpec">RecordingRuleSpec</a>)
+</p>
 <div>
 <p>RecordingRuleGroup defines a group of Loki  recording rules.</p>
 </div>
@@ -4204,7 +4299,7 @@ int32
 <code>rules</code><br/>
 <em>
 <a href="#loki-grafana-com-v1beta1-RecordingRuleGroupSpec">
-[]*github.com/grafana/loki/operator/apis/loki/v1beta1.RecordingRuleGroupSpec
+[]*RecordingRuleGroupSpec
 </a>
 </em>
 </td>
@@ -4216,6 +4311,9 @@ int32
 </table>
 
 ## RecordingRuleGroupSpec { #loki-grafana-com-v1beta1-RecordingRuleGroupSpec }
+<p>
+(<em>Appears on:</em><a href="#loki-grafana-com-v1beta1-RecordingRuleGroup">RecordingRuleGroup</a>)
+</p>
 <div>
 <p>RecordingRuleGroupSpec defines the spec for a Loki recording rule.</p>
 </div>
@@ -4286,7 +4384,7 @@ string
 <code>groups</code><br/>
 <em>
 <a href="#loki-grafana-com-v1beta1-RecordingRuleGroup">
-[]*github.com/grafana/loki/operator/apis/loki/v1beta1.RecordingRuleGroup
+[]*RecordingRuleGroup
 </a>
 </em>
 </td>

operator/docs/operator/feature-gates.md

@@ -18,6 +18,86 @@ This Document contains the types introduced by the Loki Operator to be consumed
 </div>
 <b>Resource Types:</b>
 
+## BuiltInCertManagement { #config-loki-grafana-com-v1-BuiltInCertManagement }
+<p>
+(<em>Appears on:</em><a href="#config-loki-grafana-com-v1-FeatureGates">FeatureGates</a>)
+</p>
+<div>
+<p>BuiltInCertManagement is the configuration for the built-in facility to generate and rotate
+TLS client and serving certificates for all LokiStack services and internal clients except
+for the lokistack-gateway.</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>enabled</code><br/>
+<em>
+bool
+</em>
+</td>
+<td>
+<p>Enabled defines to flag to enable/disable built-in certificate management feature gate.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>caValidity</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>CACertValidity defines the total duration of the CA certificate validity.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>caRefresh</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>CACertRefresh defines the duration of the CA certificate validity until a rotation
+should happen. It can be set up to 80% of CA certificate validity or equal to the
+CA certificate validity. Latter should be used only for rotating only when expired.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>certValidity</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>CertValidity defines the total duration of the validity for all LokiStack certificates.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>certRefresh</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>CertRefresh defines the duration of the certificate validity until a rotation
+should happen. It can be set up to 80% of certificate validity or equal to the
+certificate validity. Latter should be used only for rotating only when expired.
+The refresh is applied to all LokiStack certificates at once.</p>
+</td>
+</tr>
+</tbody>
+</table>
+
 ## FeatureGates { #config-loki-grafana-com-v1-FeatureGates }
 <p>
 (<em>Appears on:</em><a href="#config-loki-grafana-com-v1-ProjectConfig">ProjectConfig</a>)
@@ -104,6 +184,28 @@ suffix <code>-ca-bundle</code>, e.g. <code>lokistack-dev-ca-bundle</code> and th
 </tr>
 <tr>
 <td>
+<code>builtInCertManagement</code><br/>
+<em>
+<a href="#config-loki-grafana-com-v1-BuiltInCertManagement">
+BuiltInCertManagement
+</a>
+</em>
+</td>
+<td>
+<p>BuiltInCertManagement enables the built-in facility for generating and rotating
+TLS client and serving certificates for all LokiStack services and internal clients except
+for the lokistack-gateway, In detail all internal Loki HTTP and GRPC communication is lifted
+to require mTLS. For the lokistack-gateay you need to provide a secret with or use the <code>ServingCertsService</code>
+on OpenShift:
+- <code>tls.crt</code>: The TLS server side certificate.
+- <code>tls.key</code>: The TLS key for server-side encryption.
+In addition each service requires a configmap named as the LokiStack CR with the
+suffix <code>-ca-bundle</code>, e.g. <code>lokistack-dev-ca-bundle</code> and the following data:
+- <code>service-ca.crt</code>: The CA signing the service certificate in <code>tls.crt</code>.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>lokiStackGateway</code><br/>
 <em>
 bool
@@ -235,7 +337,7 @@ bool
 </em>
 </td>
 <td>
-<p>ServingCertsService enables OpenShift service-ca annotations on Services
+<p>ServingCertsService enables OpenShift service-ca annotations on the lokistack-gateway service only
 to use the in-platform CA and generate a TLS cert/key pair per service for
 in-cluster data-in-transit encryption.
 More details: <a href="https://docs.openshift.com/container-platform/latest/security/certificate_types_descriptions/service-ca-certificates.html">https://docs.openshift.com/container-platform/latest/security/certificate_types_descriptions/service-ca-certificates.html</a></p>
@@ -288,6 +390,8 @@ bool
 <td>
 <p>ClusterProxy enables usage of the proxy variables set in the proxy resource.
 More details: <a href="https://docs.openshift.com/container-platform/4.11/networking/enable-cluster-wide-proxy.html#enable-cluster-wide-proxy">https://docs.openshift.com/container-platform/4.11/networking/enable-cluster-wide-proxy.html#enable-cluster-wide-proxy</a></p>
+</td>
+</tr>
 </tbody>
 </table>