From 265525526c6290a1ab60e9626cda11eca2343b9c Mon Sep 17 00:00:00 2001
From: Leonardo Dorneles <ldornele@redhat.com>
Date: Tue, 16 Jun 2026 23:31:33 -0300
Subject: [PATCH 1/3] HYPERFLEET-1146 - docs: update development env
 configuration

---
 docs/deployment.md  | 56 ++++++++++++++++++++++++++++++++++++++++
 docs/development.md | 63 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 118 insertions(+), 1 deletion(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 81c87d91..db7abccd 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -6,6 +6,20 @@ For running the binary directly on your machine (development, debugging), see th
 
 ---
 
+## ⚠️ Production Security Warning
+
+**IMPORTANT**: Default Helm values are for development. Production requires:
+
+| Setting | Default | Production | Risk if not changed |
+|---------|---------|------------|---------------------|
+| JWT auth | `false` | `true` | ⚠️ Unauthenticated access |
+| TLS | `false` | `true` | ⚠️ Plaintext credentials |
+| Database | Built-in pod | External managed | Data loss on restart |
+
+See [API Operator Guide](api-operator-guide.md) for complete production configuration.
+
+---
+
 ## Prerequisites
 
 Before deploying, ensure you have:
@@ -274,6 +288,37 @@ During upgrade, in case schema changes have occurred in the new version, a DB mi
 helm uninstall hyperfleet-api --namespace hyperfleet-system
 ```
 
+<<<<<<< HEAD
+=======
+## Helm Values
+
+### Key Configuration Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `image.registry` | Container registry | `CHANGE_ME` (must be set explicitly) |
+| `image.repository` | Image repository | `openshift-hyperfleet/hyperfleet-api` |
+| `image.tag` | Image tag | `latest` |
+| `image.pullPolicy` | Image pull policy | `Always` |
+| `config.adapters.required.cluster` | Cluster adapters required for Ready state | `[]` |
+| `config.adapters.required.nodepool` | Nodepool adapters required for Ready state | `[]` |
+| `config.server.jwt.enabled` | Enable JWT authentication | `false` (Helm default; app default is `true`) |
+| `database.postgresql.enabled` | Enable built-in PostgreSQL | `true` |
+| `database.external.enabled` | Use external database | `false` |
+| `database.external.secretName` | Secret containing database credentials | `hyperfleet-db-external` |
+| `serviceMonitor.enabled` | Enable Prometheus Operator ServiceMonitor | `false` |
+| `serviceMonitor.interval` | Metrics scrape interval | `30s` |
+| `serviceMonitor.scrapeTimeout` | Metrics scrape timeout | `10s` |
+| `serviceMonitor.labels` | Additional labels for Prometheus selector | `{}` |
+| `serviceMonitor.namespace` | Namespace for ServiceMonitor (if different) | `""` |
+| `replicaCount` | Number of API replicas | `1` |
+| `resources.limits.cpu` | CPU limit | `500m` |
+| `resources.limits.memory` | Memory limit | `512Mi` |
+| `podDisruptionBudget.enabled` | Enable PodDisruptionBudget | `false` |
+| `podDisruptionBudget.minAvailable` | Minimum available pods during disruption | `1` |
+| `podDisruptionBudget.maxUnavailable` | Maximum unavailable pods during disruption | - |
+
+>>>>>>> 9ec002c (HYPERFLEET-1146 - docs: update development env configuration)
 ### Custom Values File
 
 For repeatable deployments, create a `values.yaml` file:
@@ -452,7 +497,18 @@ Before deploying to production, ensure:
 
 ### Configuration File Security
 
+<<<<<<< HEAD
 The configuration file path — set via `--config` or `HYPERFLEET_CONFIG` — is a trust boundary. The API validates configuration **content** on startup (unknown fields are rejected, required values are enforced, TLS/JWT/timeout settings are checked) and will refuse to start with an invalid configuration. However, **path and permission safety is the operator's responsibility**. The API reads whatever file the process can access at the given path without checking permissions or ownership.
+=======
+- **Environment**: Use default (ProductionEnv) for production deployments; never set `HYPERFLEET_ENV=development`
+- Use external managed database (Cloud SQL, RDS, Azure Database) with automated backups
+- Store all sensitive data in Kubernetes Secrets, never in ConfigMap or values.yaml
+- Enable authentication with `config.server.jwt.enabled=true`
+- Set resource limits and use multiple replicas for high availability
+- Use specific image tags (semantic versioning) instead of `latest`
+- Enable PodDisruptionBudget for zero-downtime during cluster maintenance
+- Configure health probes with appropriate timeouts for your workload
+>>>>>>> 9ec002c (HYPERFLEET-1146 - docs: update development env configuration)
 
 Ensure configuration files are:
 - Owned by the service account running the API (e.g., `root:root` or a dedicated user)
diff --git a/docs/development.md b/docs/development.md
index 455477d0..54a4288b 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -107,7 +107,7 @@ export HYPERFLEET_DATABASE_SSL_MODE=require   # for remote databases
 make run-no-auth
 ```
 
-**Note**: The default runtime environment is `production` (JWT and TLS enabled). The `make run-no-auth` target explicitly disables authentication for local development. If running the binary directly, set `HYPERFLEET_ENV=development` or use `--server-jwt-enabled=false`.
+**Note**: The default runtime environment is `production`. Security features (JWT, TLS) require explicit enablement in Helm values.
 
 The service starts on `localhost:8000` — see [Accessing the API](../README.md#accessing-the-api) for all available endpoints.
 
@@ -451,6 +451,67 @@ make db/setup
 make test-integration
 ```
 
+## Development Environment Configuration
+
+### HYPERFLEET-1146: Development Environment Analysis
+
+**Background**: Prior to HYPERFLEET-1133, the API defaulted to `DevelopmentEnv` (insecure). To protect production deployments, HYPERFLEET-1133 changed the default to `ProductionEnv` (secure by default).
+
+**Analysis Question**: Is `e_development.go` still needed after this change?
+
+**Decision**: **KEEP `e_development.go`** with improved documentation.
+
+**Why keep it**:
+- ✅ **One variable controls multiple settings** — `HYPERFLEET_ENV=development` forces JWT=false, TLS=false, SSL=disable
+- ✅ **Convenient for scripts/CI** — One environment variable vs three separate flags
+- ✅ **Semantic clarity** — "development mode" is clearer than remembering individual flags
+- ✅ **Consistent with tests** — `unit_testing` and `integration_testing` use the same pattern
+- ✅ **Production safe** — `EnvironmentDefault = ProductionEnv` prevents accidental use in production
+
+**How to use**:
+
+```bash
+# Full development mode (JWT/TLS/DB SSL all disabled)
+HYPERFLEET_ENV=development ./bin/hyperfleet-api serve
+
+# JWT-only no-auth (TLS and DB SSL keep their defaults)
+make run-no-auth
+
+# Production mode (JWT/TLS enabled, default)
+./bin/hyperfleet-api serve  # Uses EnvironmentDefault = ProductionEnv
+```
+
+**⚠️ IMPORTANT**: `HYPERFLEET_ENV=development` is for **local development ONLY**. Never use in production. The development environment forces insecure settings:
+- JWT authentication: **disabled**
+- TLS encryption: **disabled**
+- Database SSL: **disabled**
+
+**Production deployments**: Always use `EnvironmentDefault` (production) or explicitly enable security via Helm values:
+```yaml
+config:
+  server:
+    jwt:
+      enabled: true  # Production requires JWT
+    tls:
+      enabled: true  # Production requires TLS
+  database:
+    ssl:
+      mode: verify-full  # Production requires SSL
+```
+
+**Alternative to `HYPERFLEET_ENV=development`**: If you prefer explicit flags over environment-based config, you can pass flags directly:
+
+```bash
+./bin/hyperfleet-api serve \
+  --server-jwt-enabled=false \
+  --server-https-enabled=false \
+  --db-ssl-mode=disable
+```
+
+However, `HYPERFLEET_ENV=development` is recommended for local development as it's simpler and less error-prone.
+
+---
+
 ## Related Documentation
 
 - [Configuration Guide](config.md) — Complete configuration reference

From cedcab3822ac91c22674af2b79e5170159ef0518 Mon Sep 17 00:00:00 2001
From: Leonardo Dorneles <ldornele@redhat.com>
Date: Wed, 17 Jun 2026 00:00:10 -0300
Subject: [PATCH 2/3] HYPERFLEET-1146 - docs: fix deployment.md structure after
 merge

---
 docs/deployment.md | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index db7abccd..3d230835 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -288,8 +288,6 @@ During upgrade, in case schema changes have occurred in the new version, a DB mi
 helm uninstall hyperfleet-api --namespace hyperfleet-system
 ```
 
-<<<<<<< HEAD
-=======
 ## Helm Values
 
 ### Key Configuration Options
@@ -318,7 +316,6 @@ helm uninstall hyperfleet-api --namespace hyperfleet-system
 | `podDisruptionBudget.minAvailable` | Minimum available pods during disruption | `1` |
 | `podDisruptionBudget.maxUnavailable` | Maximum unavailable pods during disruption | - |
 
->>>>>>> 9ec002c (HYPERFLEET-1146 - docs: update development env configuration)
 ### Custom Values File
 
 For repeatable deployments, create a `values.yaml` file:
@@ -495,11 +492,8 @@ Before deploying to production, ensure:
 - [ ] **Disruption**: PodDisruptionBudget enabled (`podDisruptionBudget.enabled=true`)
 - [ ] **Monitoring**: ServiceMonitor enabled if using Prometheus Operator
 
-### Configuration File Security
+## Production Best Practices
 
-<<<<<<< HEAD
-The configuration file path — set via `--config` or `HYPERFLEET_CONFIG` — is a trust boundary. The API validates configuration **content** on startup (unknown fields are rejected, required values are enforced, TLS/JWT/timeout settings are checked) and will refuse to start with an invalid configuration. However, **path and permission safety is the operator's responsibility**. The API reads whatever file the process can access at the given path without checking permissions or ownership.
-=======
 - **Environment**: Use default (ProductionEnv) for production deployments; never set `HYPERFLEET_ENV=development`
 - Use external managed database (Cloud SQL, RDS, Azure Database) with automated backups
 - Store all sensitive data in Kubernetes Secrets, never in ConfigMap or values.yaml
@@ -508,7 +502,10 @@ The configuration file path — set via `--config` or `HYPERFLEET_CONFIG` — is
 - Use specific image tags (semantic versioning) instead of `latest`
 - Enable PodDisruptionBudget for zero-downtime during cluster maintenance
 - Configure health probes with appropriate timeouts for your workload
->>>>>>> 9ec002c (HYPERFLEET-1146 - docs: update development env configuration)
+
+### Configuration File Security
+
+The configuration file path — set via `--config` or `HYPERFLEET_CONFIG` — is a trust boundary. The API validates configuration **content** on startup (unknown fields are rejected, required values are enforced, TLS/JWT/timeout settings are checked) and will refuse to start with an invalid configuration. However, **path and permission safety is the operator's responsibility**. The API reads whatever file the process can access at the given path without checking permissions or ownership.
 
 Ensure configuration files are:
 - Owned by the service account running the API (e.g., `root:root` or a dedicated user)

From 2ab83f81ead8ce87a33b1c33ee42bc4e6a703a8c Mon Sep 17 00:00:00 2001
From: Leonardo Dorneles <ldornele@redhat.com>
Date: Fri, 19 Jun 2026 16:27:26 -0300
Subject: [PATCH 3/3] HYPERFLEET-1146 - docs: address PR feedback

---
 docs/deployment.md  | 19 ++++++++++++-------
 docs/development.md |  4 ++--
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 3d230835..e4d69cf8 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -301,6 +301,8 @@ helm uninstall hyperfleet-api --namespace hyperfleet-system
 | `config.adapters.required.cluster` | Cluster adapters required for Ready state | `[]` |
 | `config.adapters.required.nodepool` | Nodepool adapters required for Ready state | `[]` |
 | `config.server.jwt.enabled` | Enable JWT authentication | `false` (Helm default; app default is `true`) |
+| `config.server.tls.enabled` | Enable TLS on the API listener | `false` |
+| `config.database.ssl.mode` | SSL mode for database connection | `disable` |
 | `database.postgresql.enabled` | Enable built-in PostgreSQL | `true` |
 | `database.external.enabled` | Use external database | `false` |
 | `database.external.secretName` | Secret containing database credentials | `hyperfleet-db-external` |
@@ -495,13 +497,16 @@ Before deploying to production, ensure:
 ## Production Best Practices
 
 - **Environment**: Use default (ProductionEnv) for production deployments; never set `HYPERFLEET_ENV=development`
-- Use external managed database (Cloud SQL, RDS, Azure Database) with automated backups
-- Store all sensitive data in Kubernetes Secrets, never in ConfigMap or values.yaml
-- Enable authentication with `config.server.jwt.enabled=true`
-- Set resource limits and use multiple replicas for high availability
-- Use specific image tags (semantic versioning) instead of `latest`
-- Enable PodDisruptionBudget for zero-downtime during cluster maintenance
-- Configure health probes with appropriate timeouts for your workload
+- **Database**: Use external managed database (Cloud SQL, RDS, Azure Database) with automated backups
+- **Secrets**: Store all sensitive data in Kubernetes Secrets, never in ConfigMap or values.yaml
+- **Authentication**: Enable JWT authentication with `config.server.jwt.enabled=true`
+- **Identity**: Enable identity extraction based on JWT claims or HTTP headers as appropriate
+- **Logging**: Use JSON format (`config.logging.format=json`) and set level to `info` for production
+- **Tracing**: Enable distributed tracing for observability in production environments
+- **Resources**: Set CPU/memory limits and use multiple replicas for high availability
+- **Images**: Use specific image tags (semantic versioning) instead of `latest`
+- **Disruption**: Enable PodDisruptionBudget for zero-downtime during cluster maintenance
+- **Health**: Configure health probes with appropriate timeouts for your workload
 
 ### Configuration File Security
 
diff --git a/docs/development.md b/docs/development.md
index 54a4288b..b343bd4d 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -107,7 +107,7 @@ export HYPERFLEET_DATABASE_SSL_MODE=require   # for remote databases
 make run-no-auth
 ```
 
-**Note**: The default runtime environment is `production`. Security features (JWT, TLS) require explicit enablement in Helm values.
+**Note**: The default runtime environment is `production`. For local development without authentication, use `make run-no-auth` or set `HYPERFLEET_ENV=development` see [Development Environment Configuration](#development-environment-configuration) below).
 
 The service starts on `localhost:8000` — see [Accessing the API](../README.md#accessing-the-api) for all available endpoints.
 
@@ -453,7 +453,7 @@ make test-integration
 
 ## Development Environment Configuration
 
-### HYPERFLEET-1146: Development Environment Analysis
+### Development Environment Analysis
 
 **Background**: Prior to HYPERFLEET-1133, the API defaulted to `DevelopmentEnv` (insecure). To protect production deployments, HYPERFLEET-1133 changed the default to `ProductionEnv` (secure by default).
 
