Skip to main content

​
Lattice Setup & Configuration

This guide covers all configuration options for Station Lattice, including config file setup, environment variables, TLS encryption, and NKey authentication.

​
Configuration Methods

Station Lattice can be configured through:
  1. CLI flags (highest priority)
  2. Environment variables
  3. Config file (config.yaml)

​
Config File

Add a lattice section to your config.yaml:
config.yaml
workspace: /path/to/workspace
ai_provider: openai
ai_model: gpt-4o-mini

# Lattice configuration
lattice:
  # Mode: "orchestrator" or "member"
  mode: orchestrator
  
  # Station identity
  station_id: sre-station-prod
  station_name: SRE Production Station
  
  # Orchestrator settings (when mode: orchestrator)
  embedded_nats_port: 4222
  embedded_nats_host: 0.0.0.0
  
  # Member settings (when mode: member)
  nats_urls:
    - nats://orchestrator.example.com:4222
  
  # Presence settings
  heartbeat_interval: 5s
  presence_timeout: 15s
  
  # TLS settings (optional)
  tls:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem
    ca_file: /path/to/ca.pem
  
  # NKey authentication (optional)
  nkey:
    seed_file: /path/to/nkey.seed

​
Environment Variables

All lattice settings can be configured via environment variables:
VariableDescriptionDefault
STN_LATTICE_MODEorchestrator or member-
STN_LATTICE_STATION_IDUnique station identifierauto-generated
STN_LATTICE_STATION_NAMEHuman-readable namehostname
STN_LATTICE_NATS_URLSComma-separated NATS URLs-
STN_LATTICE_NATS_PORTEmbedded NATS port4222
STN_LATTICE_HEARTBEAT_INTERVALHeartbeat frequency5s
STN_LATTICE_TLS_ENABLEDEnable TLSfalse
STN_LATTICE_TLS_CERTTLS certificate path-
STN_LATTICE_TLS_KEYTLS key path-
STN_LATTICE_TLS_CATLS CA certificate path-
STN_LATTICE_NKEY_SEEDNKey seed file path-

​
CLI Flags

# Orchestrator mode
stn serve --orchestration \
  --lattice-port 4222 \
  --lattice-host 0.0.0.0

# Member mode
stn serve --lattice nats://host:4222 \
  --station-id my-station \
  --station-name "My Station"

​
Orchestrator Configuration

​
Basic Setup

orchestrator-config.yaml
workspace: /opt/station/orchestrator

lattice:
  mode: orchestrator
  station_id: orchestrator-main
  station_name: Main Orchestrator
  embedded_nats_port: 4222
  embedded_nats_host: 0.0.0.0

​
JetStream Storage

The orchestrator uses JetStream for persistent storage: 
lattice:
  mode: orchestrator
  jetstream:
    # Storage directory for JetStream data
    store_dir: /var/lib/station/jetstream
    # Max storage size (default: 1GB)
    max_store: 1073741824
    # Max memory (default: 256MB)
    max_mem: 268435456

​
Cluster Mode (High Availability)

For production deployments, run multiple orchestrators in cluster mode:
orchestrator-1.yaml
lattice:
  mode: orchestrator
  cluster:
    enabled: true
    name: station-cluster
    # This node's route address
    host: orchestrator-1.example.com
    port: 6222
    # Other cluster members
    routes:
      - nats://orchestrator-2.example.com:6222
      - nats://orchestrator-3.example.com:6222

​
Member Configuration

​
Basic Setup

member-config.yaml
workspace: /opt/station/member

lattice:
  mode: member
  station_id: sre-station-east
  station_name: SRE Station (US-East)
  nats_urls:
    - nats://orchestrator.example.com:4222

​
Multiple NATS URLs (Failover)

lattice:
  mode: member
  nats_urls:
    - nats://orchestrator-1.example.com:4222
    - nats://orchestrator-2.example.com:4222
    - nats://orchestrator-3.example.com:4222

​
Reconnection Settings

lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  reconnect:
    # Max reconnection attempts (-1 for infinite)
    max_attempts: -1
    # Wait between reconnection attempts
    wait: 2s
    # Max wait time (with jitter)
    max_wait: 30s

​
Security Configuration

​
TLS Encryption

Generate certificates for secure communication: 
# Generate CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.pem \
  -subj "/CN=Station Lattice CA"

# Generate server cert (for orchestrator)
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=orchestrator.example.com"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key \
  -CAcreateserial -out server.pem -days 365

# Generate client cert (for members)
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/CN=member-station"
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key \
  -CAcreateserial -out client.pem -days 365
Configure TLS on orchestrator:
orchestrator-config.yaml
lattice:
  mode: orchestrator
  tls:
    enabled: true
    cert_file: /etc/station/certs/server.pem
    key_file: /etc/station/certs/server.key
    ca_file: /etc/station/certs/ca.pem
    # Require client certificates
    verify_client: true
Configure TLS on member:
member-config.yaml
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  tls:
    enabled: true
    cert_file: /etc/station/certs/client.pem
    key_file: /etc/station/certs/client.key
    ca_file: /etc/station/certs/ca.pem

​
NKey Authentication

NKeys provide secure, passwordless authentication using Ed25519 keys. Generate NKey pairs: 
# Install nk tool
go install github.com/nats-io/nkeys/nk@latest

# Generate operator key (for orchestrator)
nk -gen operator -pubout > operator.pub
nk -gen operator > operator.seed

# Generate account key
nk -gen account -pubout > account.pub
nk -gen account > account.seed

# Generate user keys (for members)
nk -gen user -pubout > member1.pub
nk -gen user > member1.seed
Configure NKey on orchestrator:
orchestrator-config.yaml
lattice:
  mode: orchestrator
  nkey:
    operator_seed: /etc/station/nkeys/operator.seed
    # Allowed user public keys
    authorized_users:
      - UABC123...  # member1.pub content
      - UDEF456...  # member2.pub content
Configure NKey on member:
member-config.yaml
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  nkey:
    seed_file: /etc/station/nkeys/member1.seed

​
Agent Configuration

​
Declaring Capabilities

Agents can declare capabilities for routing:
agent.yaml
name: k8s-health-checker
description: Checks Kubernetes cluster health

# Capabilities for lattice routing
capabilities:
  - kubernetes
  - health-check
  - monitoring

# Tags for filtering
tags:
  environment: production
  region: us-east-1

​
Restricting Remote Access

Control which agents can be invoked remotely:
config.yaml
lattice:
  mode: member
  # Only expose these agents to the mesh
  exposed_agents:
    - k8s-health-checker
    - log-analyzer
  # Or use patterns
  exposed_agent_patterns:
    - "k8s-*"
    - "*-analyzer"

​
Monitoring

​
Health Endpoints

The lattice exposes health information: 
# Check lattice status
curl http://localhost:8080/api/v1/lattice/status

# Response:
{
  "mode": "member",
  "connected": true,
  "station_id": "sre-station-east",
  "orchestrator": "nats://orchestrator.example.com:4222",
  "uptime": "2h15m30s",
  "agents_registered": 5
}

​
Metrics

Lattice exposes Prometheus metrics: 
# Station presence
station_lattice_heartbeats_total{station_id="sre-station"}
station_lattice_presence_status{station_id="sre-station"}

# Agent invocations
station_lattice_invocations_total{agent="k8s-health",status="success"}
station_lattice_invocation_duration_seconds{agent="k8s-health"}

# Work queue
station_lattice_work_items_total{status="pending"}
station_lattice_work_items_total{status="completed"}
station_lattice_work_duration_seconds{agent="log-analyzer"}

​
Troubleshooting

​
Connection Issues

# Test NATS connectivity
nats server check nats://orchestrator.example.com:4222

# Check station logs
stn serve --lattice nats://host:4222 --log-level debug

# Verify TLS
openssl s_client -connect orchestrator.example.com:4222 \
  -cert client.pem -key client.key -CAfile ca.pem

​
Common Errors

ErrorCauseSolution
connection refusedNATS not runningStart orchestrator first
authorization violationInvalid NKeyCheck seed file and authorized users
certificate verify failedTLS mismatchVerify CA chain matches
station not foundNot registeredCheck heartbeat interval