Update documentation and example values

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

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"

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: []