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

1. Go to Modules > Select installed module
2. 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

1. Click the node
2. Click the Settings port (top)
3. 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

ConfigRef Pattern

Reference secrets in component settings:

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

# Use ConfigRef:
apiKey:
  configRef:
    name: "api-credentials"
    key: "api-key"

How It Works

┌──────────────────┐      ┌──────────────────┐
│ TinyNode Spec    │ ───▶ │ Kubernetes Secret│
│ configRef: {...} │      │ api-credentials  │
└──────────────────┘      └──────────────────┘
                                   │
                                   ▼
                          ┌──────────────────┐
                          │ Module Runtime   │
                          │ Resolves secret  │
                          └──────────────────┘

Supported References

Type	Source
Secret	Kubernetes Secret
ConfigMap	Kubernetes ConfigMap

Scaling Configuration

Horizontal Pod Autoscaler

Configure automatic scaling:

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

Manual Scaling

Scale via UI:

1. Go to module settings
2. Adjust replica count
3. 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 common-module-v1 tinysystems/common-module \
  -n tinysystems \
  -f values-production.yaml

Next Steps

• Installing Modules - Install modules
• Available Modules - Explore modules
• Cluster Management - Manage clusters