Module Configuration

This guide covers how to configure modules for optimal performance and functionality.

Configuration Levels

Modules can be configured at multiple levels:

+---------------------------------------------------------------------+
| Module Configuration Hierarchy                                      |
+---------------------------------------------------------------------+
|                                                                     |
|  Cluster Level (values.yaml)                                       |
|     +-- Module Level (TinyModule)                                  |
|         +-- Component Level (node settings)                        |
|             +-- Port Level (edge configuration)                    |
|                                                                     |
+---------------------------------------------------------------------+

Module-Level Settings

Access Module Settings

Go to Modules > Select installed module
Click Configure

Common Settings

Replicas

Number of pod instances:

replicaCount: 2

Recommendations:

Development: 1
Staging: 2
Production: 2-5

Resource Limits

CPU and memory allocation:

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Guidelines:

Workload	CPU Request	Memory Request
Light	100m	128Mi
Medium	250m	256Mi
Heavy	500m	512Mi
Intensive	1000m	1Gi

Image Settings

Container image configuration:

image:
  repository: ghcr.io/tiny-systems/common-module
  tag: v1.5.0
  pullPolicy: IfNotPresent

Service Configuration

How the module is exposed:

service:
  type: ClusterIP
  grpcPort: 50051

Advanced Settings

Leader Election

For multi-replica coordination:

leaderElection:
  enabled: true
  leaseDuration: 15s
  renewDeadline: 10s
  retryPeriod: 2s

Metrics

Observability settings:

metrics:
  enabled: true
  port: 8080

Health Probes

Kubernetes health checks:

probes:
  liveness:
    enabled: true
    initialDelaySeconds: 10
    periodSeconds: 10
  readiness:
    enabled: true
    initialDelaySeconds: 5
    periodSeconds: 5

Environment Variables

Setting Environment Variables

Add custom environment variables:

env:
  - name: LOG_LEVEL
    value: "debug"
  - name: API_ENDPOINT
    value: "https://api.example.com"

Using Secrets

Reference Kubernetes secrets:

env:
  - name: API_KEY
    valueFrom:
      secretKeyRef:
        name: api-credentials
        key: api-key
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: password

Creating Secrets

kubectl create secret generic api-credentials \
  --from-literal=api-key=your-api-key \
  -n tinysystems

Component Settings

Node Settings Port

Each component has a settings port for configuration:

# HTTP Server settings
listenAddress: ":8080"
readTimeout: "30s"
writeTimeout: "30s"

Configuring in Flow Editor

Click the node
Click the Settings port (top)
Configure options in the properties panel

Settings Schema

Settings are defined by JSON Schema:

{
  "type": "object",
  "properties": {
    "listenAddress": {
      "type": "string",
      "title": "Listen Address",
      "default": ":8080"
    },
    "timeout": {
      "type": "string",
      "title": "Timeout",
      "default": "30s"
    }
  }
}

Secrets in Components

Secret placeholders

Reference Kubernetes secrets in component settings with whole-string placeholders — never plain text:

# Instead of plain text:
apiKey: "sk-12345"

# Use a placeholder (the whole field, nothing else):
apiKey: "[[secret:api-credentials/api-key]]"

The runtime resolves [[secret:<name>/<key>]] from the module's namespace when settings are delivered, and re-delivers settings on a short TTL so rotated secrets are picked up without a pod restart. Modules declare which secrets they need via SecretRequirements, which pins RBAC to those resource names. Requires secrets.enabled in the operator chart values.

Scaling Configuration

Horizontal Pod Autoscaler

Configure automatic scaling:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

Manual Scaling

Scale via UI:

Go to module settings
Adjust replica count
Click Apply

Or via kubectl:

kubectl scale deployment common-module-v1 \
  --replicas=5 \
  -n tinysystems

Network Configuration

Ingress Settings

For HTTP-exposed modules:

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: api.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: api-tls
      hosts:
        - api.example.com

Service Mesh

If using service mesh (Istio, Linkerd):

podAnnotations:
  sidecar.istio.io/inject: "true"

Storage Configuration

Persistent Storage

For modules requiring persistence:

persistence:
  enabled: true
  storageClass: standard
  size: 10Gi
  accessMode: ReadWriteOnce

Volume Mounts

Mount additional volumes:

volumes:
  - name: config-volume
    configMap:
      name: module-config
volumeMounts:
  - name: config-volume
    mountPath: /etc/config

Configuration Best Practices

1. Start with Defaults

Begin with default settings, then optimize:

# Good starting point
replicaCount: 2
resources:
  requests:
    cpu: 100m
    memory: 128Mi

2. Use Secrets for Sensitive Data

Never hardcode credentials:

# ❌ Bad
env:
  - name: API_KEY
    value: "sk-secret-key"

# ✅ Good
env:
  - name: API_KEY
    valueFrom:
      secretKeyRef:
        name: credentials
        key: api-key

3. Set Resource Limits

Prevent runaway resource usage:

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

4. Configure Health Checks

Ensure proper health monitoring:

probes:
  liveness:
    enabled: true
  readiness:
    enabled: true

5. Document Configuration

Keep track of why settings were chosen:

# Production configuration
# Increased replicas for high availability
replicaCount: 3

# Higher limits for peak traffic
resources:
  limits:
    cpu: 1000m
    memory: 1Gi

Configuration via Helm

Custom values.yaml

Create environment-specific values:

# values-production.yaml
replicaCount: 3

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 1000m
    memory: 1Gi

env:
  - name: LOG_LEVEL
    value: "info"

Apply Configuration

helm upgrade tinysystems-common-module-v1 tinysystems/tinysystems-operator \
  -n tinysystems \
  -f values-production.yaml

Next Steps

Installing Modules - Install modules
Available Modules - Explore modules
Cluster Requirements - Cluster setup