v2: update CRD docs and doc generation

This commit transplants the documentation for the recent redpanda helm chart
update to their relevant place in the Redpanda CRD. In addition, it adds a
configuration for crd-doc-ref to allow developers to review how documentation
changes will be presented in our public docs ahead of merging.

This commit also proactively changes instances of markdown URLs to asciidoc
compatible links and adds a linter to prevent regressions.

Author: chrisseto

.changes/unreleased/chart-redpanda-Added-20250108-153147.yaml

@@ -13,9 +13,9 @@ body: |
 
     ```yaml
     resources:
-    limits: {} # Specified but no cpu or memory values provided
-    requests:
-      cpu: 5 # Only CPU requests
+      limits: {} # Specified but no cpu or memory values provided
+      requests:
+        cpu: 5 # Only CPU requests
     ```
 
     For more details see [redpanda's values.yaml](./charts/redpanda/values.yaml).

.changes/unreleased/operator-Added-20250115-162158.yaml

@@ -0,0 +1,20 @@
+project: operator
+kind: Added
+body: |
+  Added `resources.limits` and `resources.requests` as an alternative method of managing the redpanda container's resources.
+
+    When both `resources.limits` and `resources.requests` are specified, the
+    redpanda container's `resources` will be set to the provided values and all
+    other keys of `resources` will be ignored. Instead, all other values will be
+    inferred from the limits and requests.
+
+    This allows fine grain control of resources. i.e. It is now possible to set
+    CPU requests without setting limits:
+
+    ```yaml
+    resources:
+      limits: {} # Specified but no cpu or memory values provided
+      requests:
+        cpu: 5 # Only CPU requests
+    ```
+time: 2025-01-15T16:21:58.898733-05:00

charts/redpanda/CHANGELOG.md

@@ -19,9 +19,9 @@ and is generated by [Changie](https://github.com/miniscruff/changie).
 
   ```yaml
   resources:
-  limits: {} # Specified but no cpu or memory values provided
-  requests:
-    cpu: 5 # Only CPU requests
+    limits: {} # Specified but no cpu or memory values provided
+    requests:
+      cpu: 5 # Only CPU requests
   ```
 
   For more details see [redpanda's values.yaml](./charts/redpanda/values.yaml).

ci/crd-ref-docs.nix

@@ -0,0 +1,34 @@
+{ buildGoModule
+, fetchFromGitHub
+, lib
+}:
+
+buildGoModule rec {
+  pname = "crd-ref-docs";
+  version = "0.1.0";
+
+  # Don't run tests.
+  doCheck = false;
+  doInstallCheck = false;
+
+  src = fetchFromGitHub {
+    owner = "elastic";
+    repo = pname;
+    rev = "v${version}";
+    hash = "sha256-Vp4HrT6Fj+stj2xasyz7i+UuogsFHeHOT8Ro0HeoGpI=";
+  };
+
+  subPackages = [
+    "."
+    "./config"
+  ];
+
+  vendorHash = "sha256-kNynNSa7xi5BL2oWBq7A2SWtjm1E+CyJd5f0FXkHAII=";
+
+  meta = with lib; {
+    description = "Generates Kubernetes CRD API reference documentation";
+    homepage = "https://github.com/elastic/crd-ref-docs";
+    license = licenses.asl20;
+    mainProgram = "crd-ref-docs";
+  };
+}

ci/overlay.nix

@@ -1,10 +1,11 @@
 { pkgs
 }: (final: prev: {
   applyconfiguration-gen = pkgs.callPackage ./applyconfiguration-gen.nix { };
+  chart-testing = pkgs.callPackage ./chart-testing.nix { };
   controller-gen = pkgs.callPackage ./controller-gen.nix { };
+  crd-ref-docs = pkgs.callPackage ./crd-ref-docs.nix { };
   docker-tag-list = pkgs.callPackage ./docker-tag-list.nix { };
+  helm-3-10-3 = pkgs.callPackage ./helm.nix { };
   kuttl = pkgs.callPackage ./kuttl.nix { };
   setup-envtest = pkgs.callPackage ./setup-envtest.nix { };
-  helm-3-10-3 = pkgs.callPackage ./helm.nix { };
-  chart-testing = pkgs.callPackage ./chart-testing.nix { };
 })

flake.nix

@@ -48,6 +48,7 @@
               pkgs.changie # Changelog manager
               pkgs.chart-testing
               pkgs.controller-gen
+              pkgs.crd-ref-docs # Generates documentation from CRD definitions. Used by our docs but present here to let us control and test the config.yaml
               pkgs.diffutils # Provides `diff`, used by golangci-lint.
               pkgs.docker-client
               pkgs.docker-tag-list

operator/CHANGELOG.md

@@ -16,6 +16,23 @@ and is generated by [Changie](https://github.com/miniscruff/changie).
   * Console
   * Connectors
 
+* Added `resources.limits` and `resources.requests` as an alternative method of managing the redpanda container's resources.
+
+  When both `resources.limits` and `resources.requests` are specified, the
+  redpanda container's `resources` will be set to the provided values and all
+  other keys of `resources` will be ignored. Instead, all other values will be
+  inferred from the limits and requests.
+
+  This allows fine grain control of resources. i.e. It is now possible to set
+  CPU requests without setting limits:
+
+  ```yaml
+  resources:
+    limits: {} # Specified but no cpu or memory values provided
+    requests:
+      cpu: 5 # Only CPU requests
+  ```
+
 ### Changed
 * For any user that is mirroring configurator image (air-gapped environment) and changes entrypoint
   or wraps configurator with additional script the following constraint need to be meet:

operator/api/redpanda/v1alpha2/redpanda_clusterspec_types.go

@@ -497,7 +497,27 @@ type UsageStats struct {
 	ClusterID *string `json:"clusterId,omitempty"`
 }
 
-// Resources configures resource allocation. The default values are for a development environment. Production-level values and other considerations are documented, where those values are different from the default.
+// RedpandaResources encapsulates the calculation of the redpanda container's
+// https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core[corev1.ResourceRequirements]
+// and parameters such as `--memory`, `--reserve-memory`, and `--smp`. This
+// calculation supports two modes:
+//
+//   - Explicit mode (recommended):  Activated when `Limits` and `Requests` are
+//     set. In this mode, the CLI flags are calculated directly based on the
+//     provided `Limits` and `Requests`. This mode ensures predictable resource
+//     allocation and is recommended for production environments. If additional
+//     tuning is required, the CLI flags can be manually overridden using
+//     `statefulset.additionalRedpandaCmdFlags`.
+//
+//   - Legacy mode (default): Used when `Limits` and `Requests` are not set.
+//     In this mode, the container resources and CLI flags are calculated using
+//     built-in default logic, where 80% of the container's memory is allocated
+//     to Redpanda and the rest is reserved for system overhead. Legacy mode is
+//     intended for backward compatibility and less controlled environments.
+//
+// Explicit mode offers better control and aligns with Kubernetes best
+// practices. Legacy mode is a fallback for users who have not defined `Limits`
+// and `Requests`.
 type Resources struct {
 	Limits   *map[corev1.ResourceName]resource.Quantity `json:"limits,omitempty"`
 	Requests *map[corev1.ResourceName]resource.Quantity `json:"requests,omitempty"`
@@ -641,9 +661,8 @@ type PostInstallJob struct {
 	Enabled *bool `json:"enabled,omitempty"`
 	// Applies labels to the job to facilitate identification and selection based on custom criteria.
 	Labels map[string]string `json:"labels,omitempty"`
-
 	// Affinity constraints for scheduling Pods. For details, see the
-	// [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity).
+	// https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity[Kubernetes' documentation].
 	Affinity *corev1.Affinity `json:"affinity,omitempty"`
 	// SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext]
 	// or [PodTemplate.Spec.Containers[*].SecurityContext].
@@ -672,7 +691,7 @@ type PostUpgradeJob struct {
 	BackoffLimit *int32                       `json:"backoffLimit,omitempty"`
 
 	// Affinity constraints for scheduling Pods. For details, see the
-	// [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity).
+	// https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity[Kubernetes' documentation].
 	Affinity *corev1.Affinity `json:"affinity,omitempty"`
 	// SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext]
 	// or [PodTemplate.Spec.Containers[*].SecurityContext].

operator/api/redpanda/v1alpha2/redpanda_types_test.go

@@ -13,7 +13,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"os"
 	"reflect"
+	"regexp"
 	"testing"
 	"time"
 
@@ -276,3 +278,15 @@ func AssertJSONCompat[From, To any](t *rapid.T, cfg rapid.MakeConfig, fn func(*F
 
 	require.JSONEq(t, string(original), string(through), "%s (%T) should have serialized to %s (%T)", through, to, original, from)
 }
+
+func TestNoMarkdownLinks(t *testing.T) {
+	data, err := os.ReadFile("testdata/crd-docs.adoc")
+	require.NoError(t, err)
+
+	re := regexp.MustCompile(`\[(.+)\]\((.+)\)`)
+
+	matches := re.FindAllSubmatch(data, -1)
+	for _, match := range matches {
+		t.Errorf("public CRD docs use Ascii doc but found markdown link: %s\nDid you mean: %s[%s]\n(Or do you need to run task generate?)", match[0], match[2], match[1])
+	}
+}