docs: add Mayastor security page covering TLS for the REST API

docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption.md

@@ -123,4 +123,9 @@ kubectl mayastor get block-devices <node-id>
 ```
 :::note
 Pool and volume migration is manual and requires careful planning.
-:::
+:::
+
+## See Also
+
+- [Security (TLS / mTLS)](../configuration/rs-security.md)
+- [Installation](../../../../quickstart-guide/installation.md)

docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md

@@ -0,0 +1,210 @@
+---
+id: rs-security
+title: Security
+keywords:
+ - OpenEBS Replicated PV Mayastor
+ - Replicated PV Mayastor Security
+ - Security
+ - TLS
+ - mTLS
+ - Mutual TLS
+ - cert-manager
+ - JWT
+ - Encryption in Transit
+ - HTTPS
+description: This guide explains how to secure Replicated PV Mayastor connections using TLS and other security features.
+---
+
+# Security
+
+Replicated PV Mayastor is incrementally adding security across all of its connection layers. The table below summarises the current status and roadmap:
+
+| Connection | Feature | Status |
+|---|---|---|
+| Public / REST API | TLS (HTTPS) | **Available now** |
+| Public / REST API | JWT authentication | Planned |
+| Internal / gRPC | TLS | Planned — no user action required |
+| Internal / etcd | TLS | Planned — user configuration will be required |
+
+All security features are opt-in via Helm values. Plain-text communication remains the default.
+
+---
+
+## TLS for the REST API
+
+When `security.tls.enabled` is set to `true`, the Mayastor REST API is served over HTTPS on port **8080**. When TLS is disabled (the default), the API uses plain HTTP on port **8081**.
+
+### Certificate Engines
+
+Three certificate management strategies are supported, selected via `security.tls.autoGenerated.engine`:
+
+| Engine | Description | Suitable for |
+|---|---|---|
+| `pod` | The server generates a transient self-signed certificate at startup. No Kubernetes Secrets are created. Server-only TLS (mTLS is not supported). | Development / quick evaluation |
+| `helm` | The Helm chart generates a self-signed CA and leaf certificates stored as Kubernetes Secrets. Certificate validity periods are configurable. | Non-production / air-gapped environments |
+| `cert-manager` | cert-manager provisions and rotates certificates automatically. Supports an existing `Issuer` or `ClusterIssuer`. | Production |
+
+### Prerequisites
+
+- **`engine: cert-manager`** — cert-manager must be installed in the cluster before deploying or upgrading Mayastor. See the [cert-manager installation guide](https://cert-manager.io/docs/installation/helm/).
+- **`mutualAuth: true`** — mutual TLS is incompatible with `engine: pod`. Use `engine: helm` or `engine: cert-manager` when enabling mTLS.
+
+### Enabling TLS
+
+#### Option 1: Pod engine (transient certificate)
+
+The simplest way to enable TLS. The server creates a short-lived certificate on startup; no Kubernetes Secrets are involved.
+
+```yaml
+security:
+  tls:
+    enabled: true
+    autoGenerated:
+      enabled: true
+      engine: pod
+```
+
+#### Option 2: Helm-managed self-signed certificates
+
+The chart creates a self-signed CA and leaf certificates as Kubernetes Secrets. Use `caCertDuration` and `certDuration` (in days) to control validity periods.
+
+```yaml
+security:
+  tls:
+    enabled: true
+    autoGenerated:
+      enabled: true
+      engine: helm
+      helm:
+        caCertDuration: 3650  # CA certificate validity in days (default: 3650)
+        certDuration: 365     # Leaf certificate validity in days (default: 365)
+```
+
+#### Option 3: cert-manager (recommended for production)
+
+cert-manager handles certificate issuance and automatic rotation. By default the chart creates a self-signed `ClusterIssuer`; you can point it at an existing issuer instead.
+
+```yaml
+security:
+  tls:
+    enabled: true
+    autoGenerated:
+      enabled: true
+      engine: cert-manager
+      certManager:
+        existingIssuer: ""         # Name of an existing Issuer/ClusterIssuer (optional)
+        existingIssuerKind: ""     # "Issuer" or "ClusterIssuer"
+        keyAlgorithm: RSA
+        keySize: 2048
+        caDuration: "87600h"       # CA certificate duration (default: 87600h / 10 years)
+        duration: "2160h"          # Leaf certificate duration (default: 2160h / 90 days)
+        renewBefore: "360h"        # Renewal window (default: 360h / 15 days)
+```
+
+### Mutual TLS (mTLS)
+
+By default, only the server is authenticated (clients verify the server certificate). Setting `mutualAuth: true` additionally requires every client component to present its own certificate.
+
+:::note
+`mutualAuth: true` is incompatible with `engine: pod`.
+:::
+
+```yaml
+security:
+  tls:
+    enabled: true
+    mutualAuth: true
+    autoGenerated:
+      enabled: true
+      engine: cert-manager   # or helm
+```
+
+When mTLS is enabled, certificates are automatically provisioned for each client: CSI controller, CSI node, callhome, metrics-exporter, diskpool-operator, and the kubectl plugin.
+
+### Bring Your Own Certificates
+
+When `autoGenerated.enabled` is set to `false`, the chart does not create or manage any certificates. Each service must reference a pre-existing Kubernetes Secret that contains `tls.crt`, `tls.key`, and `ca.crt`.
+
+```yaml
+security:
+  tls:
+    enabled: true
+    autoGenerated:
+      enabled: false
+
+apis:
+  rest:
+    security:
+      tls:
+        # Server certificate secret for the REST API
+        existingSecret: "my-api-rest-server-cert"
+        clients:
+          csiController:
+            existingSecret: "my-csi-controller-cert"   # required when mutualAuth is true
+          csiNode:
+            existingSecret: "my-csi-node-cert"
+          callhome:
+            existingSecret: "my-callhome-cert"
+          metricsExporter:
+            existingSecret: "my-metrics-exporter-cert"
+          diskpoolOperator:
+            existingSecret: "my-diskpool-operator-cert"
+          plugin:
+            existingSecret: "my-plugin-cert"
+```
+
+### Per-Service Certificate Overrides
+
+Individual services can override the global `mutualAuth` setting and cert-manager secret names without changing the global defaults. For example, to disable mTLS for the REST API while keeping it enabled globally:
+
+```yaml
+apis:
+  rest:
+    security:
+      tls:
+        mutualAuth: false   # overrides security.tls.mutualAuth for the REST API only
+        certManager:
+          secretName: "custom-api-rest-crt"   # overrides the default secret name
+```
+
+### Verification
+
+After deploying or upgrading with TLS enabled, verify that the REST API pod is listening on the expected port:
+
+```
+kubectl get service -n mayastor | grep api-rest
+```
+
+When TLS is enabled, the service should expose port **8080**. When disabled, it exposes port **8081**.
+
+You can also check the REST API pod logs for confirmation that TLS has been initialised:
+
+```
+kubectl logs -n mayastor -l app=api-rest
+```
+
+---
+
+## Internal gRPC Security (Upcoming)
+
+TLS for the internal gRPC connections between Mayastor components (agent-core, io-engine, and others) is planned for a future release. When available, it will be controlled by the same `security.tls.enabled` flag and **will not require any additional user configuration**.
+
+---
+
+## etcd Security (Upcoming)
+
+Securing communication between Mayastor and etcd is also planned. Unlike the gRPC work, this is expected to require user configuration — for example, supplying TLS credentials via the `etcd.auth` block in Helm values. Details will be added to this page when the feature ships.
+
+---
+
+## Authentication — JWT (Upcoming)
+
+JWT-based authentication for the Mayastor REST API is planned. When available, it will be documented in this section.
+
+---
+
+## See Also
+
+- [Installation](../../../../quickstart-guide/installation.md)
+- [Encryption (Data at Rest)](../advanced-operations/encryption.md)
+- [Storage Class Parameters](rs-storage-class-parameters.md)

docs/sidebars.ts

@@ -503,6 +503,11 @@ const sidebars: SidebarsConfig =
                       id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma",
                       label: "Enable RDMA"
                     },
+                    {
+                      type: "doc",
+                      id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security",
+                      label: "Security"
+                    },
                     {
                       type: "doc",
                       id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-deployment",