Update documentation and example values

2025-12-22 14:07:22 +00:00
parent 742158d7c9
commit c74d8d16a0
3 changed files with 302 additions and 8 deletions
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ Flow is a distributed workflow automation platform consisting of:
 - Kubernetes 1.25+
 - Helm 3.8+
 - PV provisioner (if using built-in PostgreSQL/RabbitMQ)
+- cert-manager (optional, for internal TLS)

 ## Quick Start

@@ -35,11 +36,17 @@ helm search repo entit/flow --versions
 ### Install the Chart

 ```bash
-# Install with default values
+# Install with default values (uses --namespace flag for installation namespace)
 helm install flow entit/flow \
  --namespace flow \
  --create-namespace

+# Install with explicit namespace configuration
+helm install flow entit/flow \
+  --namespace flow \
+  --create-namespace \
+  --set global.namespace=flow
+
 # Install with custom values file
 helm install flow entit/flow \
  --namespace flow \
@@ -73,6 +80,7 @@ helm install flow entit/flow \

 | Parameter | Description | Default |
 |-----------|-------------|---------|
+| `global.namespace` | Namespace to install all Flow components (uses --namespace if not set) | `""` |
 | `global.imageRegistry` | Container registry for all images | `cr.kn.entit.eu` |
 | `global.imagePullSecrets` | Image pull secrets | `[]` |
 | `global.azureAd.enabled` | Enable Azure AD authentication | `true` |
@@ -80,6 +88,24 @@ helm install flow entit/flow \
 | `global.azureAd.clientId` | Azure AD application client ID | `""` |
 | `global.database.provider` | Database provider (Postgres/SqlServer) | `Postgres` |

+### Namespace Configuration
+
+All Flow components are installed into a single namespace for easy management and cleanup:
+
+```yaml
+global:
+  # Explicit namespace - recommended for production
+  namespace: "flow-production"
+```
+
+If `global.namespace` is not set, the chart uses the namespace from the `helm install --namespace` flag.
+
+**Benefits of single-namespace deployment:**
+- Easy cleanup: `kubectl delete namespace flow` removes everything
+- Simplified RBAC management
+- Clear resource ownership
+- Simplified network policies
+
 ### Service URLs

 All internal services communicate using full Kubernetes FQDN format:
@@ -190,3 +216,144 @@ global:

 redis:
  enabled: false  # Disable built-in Redis
+
+```
+## Security
+
+### Pod Security
+
+The chart enforces secure defaults:
+
+```yaml
+podSecurityContext:
+  fsGroup: 1000
+  runAsNonRoot: true
+
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  allowPrivilegeEscalation: false
+  capabilities:
+    drop:
+      - ALL
+  readOnlyRootFilesystem: true
+```
+
+### Network Policies
+
+Enable network policies for production:
+
+```yaml
+networkPolicy:
+  enabled: true
+```
+
+### Internal TLS (mTLS between Microservices)
+
+Enable encrypted communication between all Flow microservices using cert-manager with self-signed certificates. This is recommended for production environments to ensure data in transit is encrypted within the cluster.
+
+**Prerequisites:**
+- [cert-manager](https://cert-manager.io/) must be installed in your cluster
+
+```bash
+# Install cert-manager if not already installed
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml
+```
+
+**Enable Internal TLS:**
+
+```yaml
+global:
+  # All Flow components will be installed in this namespace
+  namespace: "flow"
+
+tls:
+  # Enable TLS for all internal service communication
+  enabled: true
+  
+  # Additional namespaces for cross-namespace communication (optional)
+  # Certificates will be valid for services in all listed namespaces
+  namespaces: []
+  # Example for multi-namespace deployment:
+  # namespaces:
+  #   - "flow-activities"
+  #   - "flow-infrastructure"
+  
+  certManager:
+    # Use cert-manager to manage certificates
+    enabled: true
+    
+    # Create a self-signed CA for internal certificates
+    createSelfSignedIssuer: true
+    
+    # Certificate settings
+    duration: "2160h"      # 90 days
+    renewBefore: "720h"    # Renew 30 days before expiry
+    
+    # Private key algorithm (ECDSA is faster and more secure)
+    privateKey:
+      algorithm: "ECDSA"
+      size: 256
+    
+    # CA certificate settings
+    ca:
+      duration: "87600h"   # 10 years
+      renewBefore: "8760h" # Renew 1 year before expiry
+      commonName: "Flow Internal CA"
+      organization: "Your Organization"
+  
+  # Minimum TLS version
+  minVersion: "1.2"
+```
+
+**How it works:**
+1. The chart creates a self-signed ClusterIssuer
+2. A CA certificate is generated and stored as a Kubernetes secret
+3. An Issuer is created that uses the CA to sign certificates
+4. Each service gets a certificate valid for:
+   - `<service-name>`
+   - `<release>-<service-name>.<namespace>.svc.cluster.local` (for the installation namespace)
+   - Additional namespaces if configured in `tls.namespaces`
+5. Certificates are automatically rotated before expiry
+
+**Multi-namespace deployment:**
+
+If you need to deploy Flow components across multiple namespaces:
+
+```yaml
+global:
+  namespace: "flow"
+
+tls:
+  enabled: true
+  # Certificates will be valid for services in all these namespaces
+  namespaces:
+    - "flow-activities"
+    - "flow-infrastructure"
+```
+
+**Using an existing issuer:**
+
+If you already have a cert-manager issuer configured (e.g., using Vault or an enterprise CA):
+
+```yaml
+tls:
+  enabled: true
+  
+  certManager:
+    enabled: true
+    createSelfSignedIssuer: false
+    
+    issuerRef:
+      name: "my-existing-issuer"
+      kind: "ClusterIssuer"  # or "Issuer"
+      group: "cert-manager.io"
+```
+
+**Service URLs with TLS:**
+
+When TLS is enabled, service URLs automatically switch to HTTPS:
+- Without TLS: `http://flow-workflow-engine.flow.svc.cluster.local:80`
+- With TLS: `https://flow-workflow-engine.flow.svc.cluster.local:443`
+
+## GitOps Integration
--- a/examples/values-prod.yaml
+++ b/examples/values-prod.yaml
@@ -1,7 +1,12 @@
 # Production environment values
-# Use with: helm install flow ./helm/flow -f ./helm/flow/values-prod.yaml
+# Use with: helm install flow ./helm/flow -f ./helm/flow/values-prod.yaml --namespace flow --create-namespace

 global:
+  # -- Explicit namespace for all Flow components
+  # Recommended for production to ensure consistent resource organization
+  # All resources will be created in this namespace for easy management and cleanup
+  namespace: "flow"
+  
  imageRegistry: "cr.kn.entit.eu"
  imagePullSecrets:
    - flow-registry-credentials
@@ -412,3 +417,42 @@ networkPolicy:
 podDisruptionBudget:
  enabled: true
  minAvailable: 1
+
+# =============================================================================
+# Internal TLS (mTLS between Microservices)
+# =============================================================================
+# Enable encrypted communication between all Flow microservices.
+# Requires cert-manager to be installed in the cluster.
+
+tls:
+  # Enable TLS for all internal service communication
+  enabled: true
+  
+  certManager:
+    # Use cert-manager to automatically manage certificates
+    enabled: true
+    
+    # Create a self-signed CA for internal certificates
+    # Set to false if using an existing issuer (e.g., Vault, enterprise CA)
+    createSelfSignedIssuer: true
+    
+    # Certificate validity duration (90 days)
+    duration: "2160h"
+    
+    # Renew certificates 30 days before expiry
+    renewBefore: "720h"
+    
+    # Use ECDSA for better performance
+    privateKey:
+      algorithm: "ECDSA"
+      size: 256
+    
+    # CA certificate settings
+    ca:
+      duration: "87600h"   # 10 years
+      renewBefore: "8760h" # 1 year
+      commonName: "Flow Internal CA"
+      organization: "Entit AB"
+  
+  # Minimum TLS version
+  minVersion: "1.2"
--- a/examples/values.yaml
+++ b/examples/values.yaml
@@ -3,6 +3,11 @@

 # -- Global configuration shared across all services
 global:
+  # -- Namespace to install all Flow components
+  # This ensures all resources are created in a single namespace for easy management and cleanup
+  # If not set, uses the namespace specified during helm install (--namespace flag)
+  namespace: ""
+  
  # -- Image registry for all Flow services
  imageRegistry: "cr.kn.entit.eu"
  # -- Image pull secrets
@@ -1465,26 +1470,104 @@ auditLogging:
 # =============================================================================
 # TLS Configuration (SOC2/NIS2 Compliance)
 # =============================================================================
+# Internal mTLS between microservices using cert-manager with self-signed CA.
+# Certificates are valid for services within the configured namespace(s).

 tls:
  # -- Enable TLS for internal service communication
  enabled: false
  
-  # -- Use cert-manager for certificate management
+  # -- Namespaces for which certificates should be valid
+  # By default uses the installation namespace (from global.namespace or --namespace flag)
+  # Add additional namespaces if services need to communicate across namespaces
+  namespaces: []
+  # Example:
+  # - "flow"
+  # - "flow-activities"
+  # - "flow-infrastructure"
+  
+  # -- Use cert-manager for automatic certificate management
+  # Requires cert-manager to be installed in the cluster
+  # See: https://cert-manager.io/docs/installation/
  certManager:
-    enabled: false
+    # -- Enable cert-manager integration
+    enabled: true
+    
+    # -- Create a self-signed ClusterIssuer for internal certificates
+    # If false, you must provide an existing issuer via issuerRef
+    createSelfSignedIssuer: true
+    
+    # -- Name of the self-signed CA issuer (created by this chart)
+    selfSignedIssuerName: "{{ .Release.Name }}-selfsigned-issuer"
+    
+    # -- Name of the CA certificate (created by this chart)
+    caCertificateName: "{{ .Release.Name }}-internal-ca"
+    
+    # -- Name of the CA issuer that signs service certificates
+    caIssuerName: "{{ .Release.Name }}-ca-issuer"
+    
+    # -- Reference to an existing issuer (used when createSelfSignedIssuer=false)
    issuerRef:
+      # -- Name of the existing issuer
      name: ""
+      # -- Kind: Issuer or ClusterIssuer
      kind: "ClusterIssuer"
+      # -- Group (usually cert-manager.io)
+      group: "cert-manager.io"
+    
+    # -- Certificate duration (default: 90 days)
+    duration: "2160h"  # 90 days
+    
+    # -- Certificate renewal before expiry (default: 30 days before)
+    renewBefore: "720h"  # 30 days
+    
+    # -- Private key algorithm: RSA, ECDSA, Ed25519
+    privateKey:
+      algorithm: "ECDSA"
+      size: 256  # For ECDSA: 256, 384, or 521. For RSA: 2048, 4096
+    
+    # -- CA certificate settings
+    ca:
+      # -- CA certificate duration (default: 10 years)
+      duration: "87600h"  # 10 years
+      # -- CA renewal before expiry
+      renewBefore: "8760h"  # 1 year
+      # -- CA common name
+      commonName: "Flow Internal CA"
+      # -- CA organization
+      organization: "Entit AB"
  
-  # -- Use existing TLS secret
+  # -- Use existing TLS secret (alternative to cert-manager)
+  # This secret must contain tls.crt, tls.key, and ca.crt
  existingSecret: ""
  
-  # -- Generate self-signed certificates (not recommended for production)
-  selfSigned: false
-  
  # -- Minimum TLS version (1.2 or 1.3)
  minVersion: "1.2"
  
  # -- Cipher suites (leave empty for secure defaults)
+  # Recommended for TLS 1.2: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  cipherSuites: []
+  
+  # -- Additional DNS names to include in all certificates
+  additionalDnsNames: []
+  
+  # -- Service-specific certificate overrides
+  # By default, each service gets a certificate with DNS names for all configured namespaces:
+  #   - <service-name>
+  #   - <release>-<service-name>.<namespace>.svc.cluster.local (for each namespace)
+  services:
+    workflowEngine:
+      # -- Additional DNS names for this service's certificate
+      additionalDnsNames: []
+    activityRegistry:
+      additionalDnsNames: []
+    definitionStore:
+      additionalDnsNames: []
+    workflowLogging:
+      additionalDnsNames: []
+    connectionStore:
+      additionalDnsNames: []
+    tenantRegistry:
+      additionalDnsNames: []
+    frontendWeb:
+      additionalDnsNames: []