@r8s/n8n 0.2.0

package/__tests__/n8n.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect } from 'vitest'
+import { render, jsx } from '@r8s/core'
+import { OperatorContext, SecretContext, RoutingContext } from '@r8s/core/defaults'
+import { runGuardrails, noPlaintextSecrets, validateResource } from '@r8s/core'
+import { operators } from '@r8s/crds'
+import type { r8sElement } from '@r8s/core'
+
+// N8n recipe tests:
+//   1. Operator declarations (deduped via OperatorContext)
+//   2. Rendering: defaults, all props, gateway/ingress adaptation
+//   3. Security: no plaintext credentials in rendered output
+import { N8n } from '../src/index'
+
+/** Render N8n inside a Platform-like secrets backend (OpenBao). */
+function renderN8n(props: Record<string, unknown>): ReturnType<typeof render> {
+  return render(
+    jsx(SecretContext.Provider, {
+      value: { backend: 'openbao', mount: 'kv', path: 'test' },
+      children: jsx(N8n, props as never),
+    })
+  )
+}
+
+/** Render N8n wrapped only in an OperatorContext (no secrets backend). */
+function renderN8nWithContext(operators_: any[], props: Record<string, unknown>): r8sElement {
+  return jsx(OperatorContext.Provider, {
+    value: operators_,
+    children: jsx(N8n, props as never),
+  })
+}
+
+const openbao = { backend: 'openbao', mount: 'kv', path: 'test' }
+
+describe('operator declarations', () => {
+  it('declares the redis operator when queue mode is enabled', () => {
+    const result = renderN8n({
+      host: 'n8n.example.com',
+      queueMode: true,
+      encryptionKeySecretName: 'enc',
+    })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(true)
+  })
+
+  it('does not declare the redis operator without queue mode', () => {
+    const result = renderN8n({ host: 'n8n.example.com' })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(false)
+  })
+
+  it('declares the cnpg operator via the Database recipe', () => {
+    const result = renderN8n({ host: 'n8n.example.com' })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(true)
+  })
+
+  it('deduplicates operators provided via context', () => {
+    const result = render(
+      renderN8nWithContext([operators['redis-operator'](), operators['cnpg']()], {
+        host: 'n8n.example.com',
+        encryptionKeySecretName: 'existing-encryption',
+      })
+    )
+    const names = result.operators.map((op) => op.name)
+    expect(names.filter((n) => n === 'redis-operator')).toHaveLength(1)
+    expect(names.filter((n) => n === 'cnpg')).toHaveLength(1)
+  })
+
+  it('allows version overrides through context operators', () => {
+    const result = render(
+      renderN8nWithContext([operators['redis-operator']('1.0.0')], {
+        host: 'n8n.example.com',
+        queueMode: true,
+        encryptionKeySecretName: 'existing-encryption',
+      })
+    )
+    const redis = result.operators.filter((op) => op.name === 'redis-operator')
+    expect(redis).toHaveLength(1)
+    expect(redis[0].version).toBe('1.0.0')
+  })
+})
+
+describe('rendering defaults', () => {
+  it('renders editor deployment, service, database and endpoint', () => {
+    const result = renderN8n({ host: 'n8n.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('Deployment')
+    expect(kinds).toContain('Service')
+    expect(kinds).toContain('Ingress')
+    expect(kinds).toContain('Cluster')
+  })
+
+  it('renders queue mode with Redis and workers', () => {
+    const result = renderN8n({ host: 'n8n.example.com', queueMode: true, workers: 3 })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('RedisReplication')
+    const deployments = result.resources.filter((r) => r.kind === 'Deployment')
+    expect(deployments.map((d: any) => d.metadata.name)).toContain('n8n-worker')
+    expect(deployments.map((d: any) => d.metadata.name)).toContain('n8n')
+  })
+
+  it('wires the worker to the RedisReplication service and health checks', () => {
+    const result = renderN8n({ host: 'n8n.example.com', queueMode: true })
+    const worker = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'n8n-worker'
+    ) as any
+    const env = worker.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'QUEUE_BULL_REDIS_HOST').value).toBe('n8n-redis')
+    expect(env.find((e: any) => e.name === 'QUEUE_HEALTH_CHECK_ACTIVE').value).toBe('true')
+    const probes = worker.spec.template.spec.containers[0]
+    expect(probes.livenessProbe.httpGet.path).toBe('/healthz')
+  })
+
+  it('throws on multiple editor replicas without queue mode', () => {
+    expect(() => renderN8n({ host: 'n8n.example.com', replicas: 3 })).toThrow(/queue mode/)
+  })
+
+  it('propagates the storage prop to the CNPG cluster', () => {
+    const result = renderN8n({ host: 'n8n.example.com', storage: '30Gi' })
+    const cluster = result.resources.find((r: any) => r.kind === 'Cluster') as any
+    expect(cluster.spec.storage.size).toBe('30Gi')
+  })
+
+  it('renders gateway resources when platform uses gateway routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'gateway', gatewayClassName: 'eg' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(N8n, { host: 'n8n.example.com' }),
+        }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('HTTPRoute')
+  })
+
+  it('renders a valid Ingress when platform uses ingress routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'ingress' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(N8n, { host: 'n8n.example.com' }),
+        }),
+      })
+    )
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress).toBeDefined()
+    expect(ingress.spec.rules[0].host).toBe('n8n.example.com')
+  })
+
+  it('passes resource validation', () => {
+    const result = renderN8n({ host: 'n8n.example.com', queueMode: true })
+    for (const resource of result.resources) {
+      expect(validateResource(resource)).toEqual([])
+    }
+  })
+})
+
+describe('rendering with all props', () => {
+  it('accepts the full prop surface', () => {
+    const result = renderN8n({
+      name: 'automation',
+      namespace: 'automation',
+      version: '1.60.0',
+      host: 'automation.example.com',
+      replicas: 2,
+      queueMode: true,
+      workers: 4,
+      resources: {
+        requests: { memory: '1Gi', cpu: '500m' },
+        limits: { memory: '4Gi', cpu: '2000m' },
+      },
+      tls: { secretName: 'automation-tls', clusterIssuer: 'letsencrypt-prod' },
+    })
+    expect(result.resources.length).toBeGreaterThan(0)
+    const editor = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'automation'
+    ) as any
+    expect(editor.spec.template.spec.containers[0].image).toContain('1.60.0')
+    expect(editor.spec.template.spec.containers[0].resources.limits.memory).toBe('4Gi')
+  })
+})
+
+describe('secrets handling', () => {
+  it('accepts an explicit encryptionKeySecretName without a backend', () => {
+    expect(() =>
+      render(jsx(N8n, { host: 'n8n.example.com', encryptionKeySecretName: 'existing-encryption' }))
+    ).not.toThrow()
+  })
+
+  it('provisions the encryption key through a secrets backend', () => {
+    const result = renderN8n({ host: 'n8n.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('OpenBaoStaticSecret')
+  })
+
+  it('provisions the encryption key through Vault', () => {
+    const result = render(
+      jsx(SecretContext.Provider, {
+        value: { backend: 'vault', mount: 'kv', path: 'apps' },
+        children: jsx(N8n, { host: 'n8n.example.com' }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('VaultStaticSecret')
+  })
+
+  it('wires credentials via secretKeyRef (never plaintext env)', () => {
+    const result = renderN8n({
+      host: 'n8n.example.com',
+      encryptionKeySecretName: 'existing-encryption',
+    })
+    const editor = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'n8n'
+    ) as any
+    const env = editor.spec.template.spec.containers[0].env
+    const encryption = env.find((e: any) => e.name === 'N8N_ENCRYPTION_KEY')
+    const dbPassword = env.find((e: any) => e.name === 'DB_POSTGRESDB_PASSWORD')
+    expect(encryption.valueFrom.secretKeyRef.name).toBe('existing-encryption')
+    expect(dbPassword.valueFrom.secretKeyRef.name).toBe('n8n-db-credentials')
+    expect(encryption.value).toBeUndefined()
+    expect(dbPassword.value).toBeUndefined()
+  })
+
+  it('renders no plaintext credentials anywhere', () => {
+    const result = renderN8n({ host: 'n8n.example.com', queueMode: true })
+    const { passed, errors } = runGuardrails(result.resources as any[], [noPlaintextSecrets])
+    if (!passed) {
+      console.error('Plaintext credential violations:', errors)
+    }
+    expect(passed).toBe(true)
+  })
+})
+
+describe('validation errors', () => {
+  it('throws when no secrets backend and no encryption key secret', () => {
+    expect(() => render(jsx(N8n, { host: 'n8n.example.com' }))).toThrow(/encryption key/)
+  })
+
+  it('throws for unknown secrets backends', () => {
+    expect(() =>
+      render(
+        jsx(SecretContext.Provider, {
+          value: { backend: 'unknown' as never },
+          children: jsx(N8n, { host: 'n8n.example.com' }),
+        })
+      )
+    ).toThrow(/encryption key/)
+  })
+})
+
+describe('secretKeyRef wiring in queue mode', () => {
+  it('worker deployment uses the same credentials secret', () => {
+    const result = renderN8n({
+      host: 'n8n.example.com',
+      queueMode: true,
+      encryptionKeySecretName: 'existing-encryption',
+    })
+    const worker = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'n8n-worker'
+    ) as any
+    expect(worker).toBeDefined()
+    const env = worker.spec.template.spec.containers[0].env
+    const dbPassword = env.find((e: any) => e.name === 'DB_POSTGRESDB_PASSWORD')
+    expect(dbPassword.valueFrom.secretKeyRef.name).toBe('n8n-db-credentials')
+    expect(dbPassword.value).toBeUndefined()
+  })
+})

package/examples/basic.tsx

@@ -0,0 +1,8 @@
+import { Platform } from '@r8s/recipes'
+import { N8n } from '@r8s/n8n'
+
+export default (
+  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+    <N8n name="n8n" host="n8n.example.com" queueMode workers={3} />
+  </Platform>
+)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@r8s/n8n",
+  "version": "0.2.0",
+  "description": "n8n workflow automation — editor, Postgres persistence, Redis queue mode, webhook endpoints",
+  "license": "MIT",
+  "author": "Berget AI AB",
+  "homepage": "https://r8s.berget.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berget-ai/r8s.git",
+    "directory": "packages/n8n"
+  },
+  "bugs": "https://github.com/berget-ai/r8s/issues",
+  "keywords": [
+    "n8n",
+    "automation",
+    "workflows",
+    "integrations"
+  ],
+  "r8s": {
+    "category": "Automation"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "category": "Apps & Automation",
+  "dependencies": {
+    "@r8s/core": "^0.2.0",
+    "@r8s/crds": "^0.2.0",
+    "@r8s/k8s-types": "^0.2.0",
+    "@r8s/recipes": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,284 @@
+import { jsx, Fragment, useContext, declareOperator } from '@r8s/core'
+import { Namespace, OperatorContext, SecretContext } from '@r8s/core/defaults'
+import { operators } from '@r8s/crds'
+import { Database, WebService, Endpoint } from '@r8s/recipes'
+import { RedisReplicationComponent } from '@r8s/crds/redis'
+
+export interface N8nProps {
+  /** Resource name (defaults to 'n8n') */
+  name?: string
+  /** Kubernetes namespace (inherited from Platform context when omitted) */
+  namespace?: string
+  /** Container image tag (defaults to 'latest' — pin a version in production) */
+  version?: string
+  /** Public hostname for the editor and webhooks (required) */
+  host: string
+  /** Number of editor replicas when not running in queue mode (defaults to 1) */
+  replicas?: number
+  /**
+   * Redis-backed queue mode. Adds a Redis master/replica set and a worker
+   * Deployment so webhook ingestion and heavy executions scale independently.
+   */
+  queueMode?: boolean
+  /** Queue worker replicas (defaults to 2, only used with queueMode) */
+  workers?: number
+  /** Storage request for the CNPG Postgres cluster (defaults to '10Gi') */
+  storage?: string
+  /**
+   * Name of an existing Secret containing key `encryptionKey`. n8n
+   * encrypts all workflow credentials with this key — lose it and every
+   * stored credential is unreadable.
+   *
+   * Required unless a secrets backend (openbao/vault) is configured on
+   * the surrounding Platform — the backend then provisions the key
+   * automatically. Plaintext keys are not supported.
+   */
+  encryptionKeySecretName?: string
+  /** Requested editor resources */
+  resources?: {
+    requests?: { cpu?: string; memory?: string }
+    limits?: { cpu?: string; memory?: string }
+  }
+  /** TLS configuration (defaults to letsencrypt-prod cluster issuer) */
+  tls?: {
+    secretName: string
+    clusterIssuer: string
+  }
+}
+
+const OPERATOR_REDIS = 'redis-operator'
+
+/**
+ * n8n — fair-code workflow automation.
+ *
+ * @title N8n
+ * @category Automation
+ *
+ * Composes:
+ * - CNPG Postgres cluster (workflows, executions, stored credentials)
+ * - n8n editor Deployment + Service + Endpoint (webhooks share the host)
+ * - Redis cluster + worker Deployment in queue mode
+ * - Encryption key provisioned through the Platform secrets backend
+ *   (openbao / vault), or referenced from an existing Secret
+ *
+ * Wrap the component in `<Platform secrets={{ backend: 'openbao' }}>` and
+ * the N8N_ENCRYPTION_KEY is provisioned for you. Without a backend you
+ * must point `encryptionKeySecretName` at a pre-created Secret.
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { N8n } from '@r8s/n8n'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+ *     <N8n name="n8n" host="n8n.example.com" queueMode workers={3} />
+ *   </Platform>
+ * )
+ */
+export function N8n(props: N8nProps) {
+  const {
+    name = 'n8n',
+    namespace: namespaceProp,
+    version = 'latest',
+    host,
+    replicas = 1,
+    queueMode = false,
+    workers = 2,
+    storage = '10Gi',
+    encryptionKeySecretName,
+    resources = {
+      requests: { memory: '512Mi', cpu: '250m' },
+      limits: { memory: '2Gi', cpu: '1000m' },
+    },
+    tls = { secretName: `${name}-tls`, clusterIssuer: 'letsencrypt-prod' },
+  } = props
+
+  const sharedOperators = useContext(OperatorContext)
+  const secretProvider = useContext(SecretContext)
+  // Inherit namespace from <Platform> context — mirrors recipes/database.tsx
+  const contextNamespace = useContext(Namespace)
+  const namespace =
+    namespaceProp ?? (contextNamespace !== 'default' ? contextNamespace : undefined) ?? 'default'
+  const resources_: ReturnType<typeof jsx>[] = []
+
+  const dbCredentialsName = `${name}-db-credentials`
+  const encryptionSecretName = encryptionKeySecretName ?? `${name}-encryption-key`
+
+  // --- Secret provisioning -------------------------------------------------
+  // The encryption key is the crown jewel of an n8n install — never render
+  // it as plaintext. With a secrets backend it is provisioned through the
+  // backend (key `encryptionKey`); otherwise reference a pre-created Secret.
+  if (!encryptionKeySecretName) {
+    if (
+      !secretProvider ||
+      (secretProvider.backend !== 'vault' && secretProvider.backend !== 'openbao')
+    ) {
+      throw new Error(
+        `N8n "${name}" requires an encryption key.\n` +
+          `\n` +
+          `n8n encrypts all workflow credentials with N8N_ENCRYPTION_KEY — ` +
+          `it must not be rendered as plaintext.\n` +
+          `\n` +
+          `Fix: configure a secrets backend on the Platform:\n` +
+          `  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'n8n' }}>\n` +
+          `    <N8n name="${name}" host="${host}" />\n` +
+          `  </Platform>\n` +
+          `\n` +
+          `Or reference a pre-created Secret (key: encryptionKey):\n` +
+          `  <N8n name="${name}" host="${host}" encryptionKeySecretName="${name}-encryption-key" />`
+      )
+    }
+
+    const spec = {
+      ...(secretProvider.backend === 'vault'
+        ? { vaultAuthRef: secretProvider.authRef }
+        : { openbaoAuthRef: secretProvider.authRef }),
+      mount: secretProvider.mount,
+      type: 'kv-v2' as const,
+      path: `${secretProvider.path ?? name}/${name}/encryption`,
+      destination: { create: true, name: encryptionSecretName },
+    }
+    resources_.push(
+      secretProvider.backend === 'vault'
+        ? jsx('VaultStaticSecret', {
+            apiVersion: 'secrets.hashicorp.com/v1beta1',
+            kind: 'VaultStaticSecret',
+            metadata: { name: `${name}-encryption`, namespace },
+            spec,
+          })
+        : jsx('OpenBaoStaticSecret', {
+            apiVersion: 'secrets.openbao.org/v1beta1',
+            kind: 'OpenBaoStaticSecret',
+            metadata: { name: `${name}-encryption`, namespace },
+            spec,
+          })
+    )
+  }
+
+  // --- Operators ------------------------------------------------------------
+  if (queueMode && !sharedOperators.some((op) => op.name === OPERATOR_REDIS)) {
+    resources_.push(declareOperator(operators[OPERATOR_REDIS]()))
+  }
+
+  // --- Database (CNPG) — workflows, executions, stored credentials ----------
+  const dbHost = `${name}-rw`
+
+  const sharedEnv = {
+    DB_TYPE: 'postgresdb',
+    DB_POSTGRESDB_HOST: dbHost,
+    DB_POSTGRESDB_PORT: '5432',
+    DB_POSTGRESDB_DATABASE: name,
+    DB_POSTGRESDB_USER: name,
+    N8N_HOST: host,
+    N8N_PORT: '5678',
+    N8N_PROTOCOL: 'https',
+    WEBHOOK_URL: `https://${host}/`,
+    NODE_FUNCTION_ALLOW_BUILTIN: '*',
+    // Binary data must live in Postgres in queue mode — the filesystem
+    // backend is not shared across editors/workers and is unsupported.
+    N8N_DEFAULT_BINARY_DATA_MODE: 'default',
+  }
+
+  const sharedSecrets = {
+    DB_POSTGRESDB_PASSWORD: { secret: dbCredentialsName, key: 'password' },
+    N8N_ENCRYPTION_KEY: { secret: encryptionSecretName, key: 'encryptionKey' },
+  }
+
+  if (queueMode) {
+    Object.assign(sharedEnv, {
+      EXECUTIONS_MODE: 'queue',
+      QUEUE_BULL_REDIS_HOST: `${name}-redis`,
+      QUEUE_BULL_REDIS_PORT: '6379',
+    })
+  }
+
+  if (!queueMode && replicas > 1) {
+    throw new Error(
+      `N8n "${name}" requested replicas={${replicas}} without queue mode.\n` +
+        `\n` +
+        `Multiple main instances without Redis queue mode run every trigger ` +
+        `execution once per replica (duplicated webhooks and schedules).\n` +
+        `\n` +
+        `Fix: enable queue mode:\n` +
+        `  <N8n name="${name}" host="${host}" queueMode workers={${replicas}} />\n` +
+        `\n` +
+        `Or keep a single main instance (workers handle executions in queue mode).`
+    )
+  }
+
+  // Database wraps the editor so credentials stay consistent with the
+  // r8s Database recipe (CNPG dedicated cluster provisions the secret).
+  resources_.push(
+    jsx(Database, {
+      name,
+      namespace,
+      storage,
+      children: (
+        <WebService
+          name={name}
+          namespace={namespace}
+          image={`docker.n8n.io/n8nio/n8n:${version}`}
+          port={5678}
+          replicas={queueMode ? 1 : replicas}
+          resources={resources}
+          probes={{
+            liveness: { path: '/healthz' },
+            readiness: { path: '/healthz', initialDelaySeconds: 15 },
+          }}
+          env={{ ...sharedEnv, ...(queueMode ? {} : { N8N_CONCURRENCY_PRODUCTION_LIMIT: '10' }) }}
+          secrets={sharedSecrets}
+        />
+      ),
+    })
+  )
+
+  // --- Queue mode: Redis + workers ------------------------------------------
+  if (queueMode) {
+    // Bull (n8n's queue backend) speaks plain Redis protocol — use a
+    // master/replica topology, not a Redis cluster (no MOVED-safe client)
+    resources_.push(
+      RedisReplicationComponent({
+        metadata: { name: `${name}-redis`, namespace },
+        spec: {
+          clusterSize: 3,
+          kubernetesConfig: { image: 'redis:7.2-alpine' },
+        },
+      })
+    )
+
+    resources_.push(
+      <WebService
+        name={`${name}-worker`}
+        namespace={namespace}
+        image={`docker.n8n.io/n8nio/n8n:${version}`}
+        port={5678}
+        replicas={workers}
+        command={['n8n', 'worker', '--concurrency=10']}
+        resources={{
+          requests: { memory: '512Mi', cpu: '250m' },
+          limits: { memory: '2Gi', cpu: '2000m' },
+        }}
+        probes={{
+          liveness: { path: '/healthz' },
+          readiness: { path: '/healthz', initialDelaySeconds: 20 },
+        }}
+        env={{ ...sharedEnv, QUEUE_HEALTH_CHECK_ACTIVE: 'true' }}
+        secrets={sharedSecrets}
+      />
+    )
+  }
+
+  // --- Endpoint — webhooks share the editor host -----------------------------
+  resources_.push(
+    <Endpoint
+      name={`${name}-endpoint`}
+      namespace={namespace}
+      host={host}
+      serviceName={name}
+      servicePort={5678}
+      tls={tls}
+    />
+  )
+
+  return jsx(Fragment, { children: resources_ })
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../k8s-types" },
+    { "path": "../crds" },
+    { "path": "../recipes" }
+  ]
+}