From 7d6ae62ba4c735138b2e7ed57a29a7afd2adedc8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 15:20:05 +0000 Subject: [PATCH 1/3] docs: add Mayastor security page covering TLS and future features --- .../advanced-operations/encryption.md | 7 +- .../configuration/rs-rdma.md | 1 + .../configuration/rs-security.md | 211 ++++++++++++++++++ docs/sidebars.ts | 5 + 4 files changed, 223 insertions(+), 1 deletion(-) create mode 100644 docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md diff --git a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption.md b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption.md index dd0fc4520..42be101d2 100644 --- a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption.md +++ b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption.md @@ -123,4 +123,9 @@ kubectl mayastor get block-devices ``` :::note Pool and volume migration is manual and requires careful planning. -::: \ No newline at end of file +::: + +## See Also + +- [Security (TLS / mTLS)](../configuration/rs-security.md) +- [Installation](../../../../quickstart-guide/installation.md) \ No newline at end of file diff --git a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md index 0a74b4810..942c68aae 100644 --- a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md +++ b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md @@ -84,4 +84,5 @@ The table below compares performance metrics for RDMA and TCP under specific wor - [Create StorageClass(s)](../configuration/rs-create-storageclass.md) - [Storage Class Parameters](../configuration/rs-storage-class-parameters.md) - [Topology Parameters](../configuration/rs-topology-parameters.md) +- [Security (TLS / mTLS)](rs-security.md) - [Deploy an Application](../configuration/rs-deployment.md) \ No newline at end of file diff --git a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md new file mode 100644 index 000000000..a93f65f84 --- /dev/null +++ b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md @@ -0,0 +1,211 @@ +--- +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) +- [Enable RDMA](rs-rdma.md) +- [Storage Class Parameters](rs-storage-class-parameters.md) diff --git a/docs/sidebars.ts b/docs/sidebars.ts index fd8013912..4864c879f 100644 --- a/docs/sidebars.ts +++ b/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", From 8e4e142e55dda8fedfa162961baf77d161665ed0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 15:50:39 +0000 Subject: [PATCH 2/3] docs: remove unrelated RDMA link from rs-security See Also --- .../replicated-pv-mayastor/configuration/rs-security.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md index a93f65f84..cf3664b2d 100644 --- a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md +++ b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-security.md @@ -207,5 +207,4 @@ JWT-based authentication for the Mayastor REST API is planned. When available, i - [Installation](../../../../quickstart-guide/installation.md) - [Encryption (Data at Rest)](../advanced-operations/encryption.md) -- [Enable RDMA](rs-rdma.md) - [Storage Class Parameters](rs-storage-class-parameters.md) From ca507d70d3c5c64b4bef05f4606d2220fbb6bfd4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 21 Jul 2026 08:38:40 +0000 Subject: [PATCH 3/3] docs: remove unrelated security link from rs-rdma See Also --- .../replicated-pv-mayastor/configuration/rs-rdma.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md index 942c68aae..0a74b4810 100644 --- a/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md +++ b/docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-rdma.md @@ -84,5 +84,4 @@ The table below compares performance metrics for RDMA and TCP under specific wor - [Create StorageClass(s)](../configuration/rs-create-storageclass.md) - [Storage Class Parameters](../configuration/rs-storage-class-parameters.md) - [Topology Parameters](../configuration/rs-topology-parameters.md) -- [Security (TLS / mTLS)](rs-security.md) - [Deploy an Application](../configuration/rs-deployment.md) \ No newline at end of file