@toa.io/operations 1.0.0-alpha.33 → 1.0.0-alpha.331

package/src/deployment/.deployment/.describe/variables.js

@@ -1,20 +1,16 @@
-'use strict'
+export function addVariables(composition, variables, keys = composition.components) {
+  composition.variables ??= []
 
-function addVariables (deployment, variables) {
-  const used = new Set()
-
-  deployment.variables ??= []
+  const used = new Set(composition.variables.map((variable) => variable.name))
 
   for (const [key, set] of Object.entries(variables)) {
-    if (key !== 'global' && !deployment.components?.includes(key)) continue
+    if (key !== 'global' && !keys?.includes(key)) continue
 
     for (const variable of set) {
       if (used.has(variable.name)) continue
 
-      deployment.variables.push(variable)
+      composition.variables.push(variable)
       used.add(variable.name)
     }
   }
 }
-
-exports.addVariables = addVariables

package/src/deployment/.deployment/declare.js

@@ -1,11 +1,9 @@
-'use strict'
-
 /**
  * @param {toa.norm.Context} context
  * @param {toa.deployment.Dependency} dependency
  * @returns {toa.deployment.Declaration}
  */
-const declare = (context, dependency) => {
+export const declare = (context, dependency) => {
   const { references } = dependency
   const { name, description, version } = context
 
@@ -25,5 +23,3 @@ const DECLARATION = {
   apiVersion: 'v2',
   type: 'application'
 }
-
-exports.declare = declare

package/src/deployment/.deployment/describe.js

@@ -1,8 +1,15 @@
-'use strict'
+import { gzipSync } from 'node:zlib'
+import { map } from '@toa.io/norm'
+import { MAP_DIRECTORY, MAP_FILE } from '@toa.io/definitions'
 
-const get = require('./.describe')
+import * as desc from './.describe/index.js'
+import { addVariables } from './.describe/variables.js'
+import { addMounts } from './.describe/mounts.js'
+import { resources } from './.describe/resources.js'
+import { events } from './.describe/events.js'
+import { fold } from './.describe/fold.js'
 
-const describe = (context, compositions, dependency) => {
+export const describe = (context, compositions, dependency, image) => {
   const { services } = dependency
 
   dependency.variables.global ??= []
@@ -11,24 +18,167 @@ const describe = (context, compositions, dependency) => {
     {
       name: 'TOA_CONTEXT',
       value: context.name
-    }, {
+    },
+    {
       name: 'TOA_ENV',
       value: context.environment
     }
   )
 
-  const components = get.components(compositions)
+  const atomicity = context.atomicity
+
+  if (atomicity?.redis !== undefined) {
+    const addresses = Array.isArray(atomicity.redis) ? atomicity.redis : [atomicity.redis]
+
+    // a lock is taken on `floor(n / 2) + 1` of them, so an even number tolerates no more
+    // losses than the odd number below it, and two tolerate fewer than one does
+    if (addresses.length % 2 === 0)
+      throw new Error(
+        `'atomicity.redis' takes an odd number of addresses, ` +
+          `${addresses.length} given`
+      )
+
+    dependency.variables.global.push({
+      name: 'TOA_ATOMICITY_REDIS',
+      value: addresses.join(' ')
+    })
+  }
+
+  if (atomicity?.interval !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_ATOMICITY_INTERVAL',
+      value: String(atomicity.interval)
+    })
+
+  const outbox = context.outbox
+
+  if (outbox?.interval !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_INTERVAL',
+      value: String(outbox.interval)
+    })
+
+  if (outbox?.batch !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_BATCH',
+      value: String(outbox.batch)
+    })
+
+  if (outbox?.retention !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_RETENTION',
+      value: String(outbox.retention)
+    })
+
+  if (context.inbox?.retention !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_INBOX_RETENTION',
+      value: String(context.inbox.retention)
+    })
+
+  if (context.addressed?.timeout !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_ADDRESSED_TIMEOUT',
+      value: String(context.addressed.timeout)
+    })
+
+  events(context, dependency)
+
   const credentials = context.registry?.credentials
 
-  get.compositions(compositions, dependency.variables, context.environment)
-  get.services(services, dependency.variables)
+  if (image !== undefined) {
+    const mono = unit(context, dependency)
+
+    mono.image = image.reference
+
+    const values = {
+      compositions: [],
+      components: mono.components,
+      services: [],
+      credentials,
+      map: versions(context),
+      mono
+    }
+
+    resources(context, values)
+
+    return values
+  }
+
+  const components = desc.components(compositions)
 
-  return {
+  desc.compositions(compositions, dependency)
+  desc.services(services, dependency.variables, dependency.probe, context.ingress)
+
+  const values = {
     compositions,
     components,
     services,
-    credentials
+    credentials,
+    map: versions(context)
   }
+
+  resources(context, values)
+
+  return values
 }
 
-exports.describe = describe
+function unit(context, dependency) {
+  // an evicted component is deployed by other means, so mono runs it nowhere
+  const components = (context.components ?? [])
+    .filter((component) => component.evicted !== true)
+    .map((component) => component.locator.label)
+
+  const variables = dependency.variables ?? {}
+  const mounts = dependency.mounts ?? {}
+
+  const mono = {
+    replicas: context.mono?.replicas,
+    resources: context.mono?.resources,
+    components,
+    variables: []
+  }
+
+  if (context.ingress !== undefined) mono.ingress = Object.assign({}, context.ingress)
+
+  addVariables(mono, variables, Object.keys(variables))
+  addMounts(mono, dependency.mounts, Object.keys(mounts))
+
+  fold(mono, dependency.services ?? [], dependency)
+
+  // mono is the one workload that fronts every service it runs under a single name,
+  // so it inherits how they are reached as well as what they run
+  for (const service of dependency.services ?? []) {
+    // one Service fronts every backend, so its annotations are the union
+    if (service.annotations !== undefined)
+      mono.annotations = Object.assign(mono.annotations ?? {}, service.annotations)
+
+    if (service.ingress !== undefined) {
+      const { path, hosts, ...ingress } = service.ingress
+
+      mono.ingress = Object.assign(mono.ingress ?? {}, ingress)
+
+      // one Ingress serves every path, so its hosts are the union, not the last word
+      if (hosts !== undefined)
+        mono.ingress.hosts = [...new Set([...(mono.ingress.hosts ?? []), ...hosts])]
+    }
+  }
+
+  return mono
+}
+
+/**
+ * The component map every workload mounts: which version of a component a process asks what that
+ * component provides. Named rather than found, because a ConfigMap mounts as a directory.
+ *
+ * Compressed here rather than in the chart, which renders no gzip, and carried as the bytes it is:
+ * a ConfigMap is capped at a megabyte, and this copy is read by a program. `gzipSync` writes a zero
+ * timestamp, so a deploy that changed nothing renders the same object.
+ *
+ * @param {toa.norm.Context} context
+ */
+function versions(context) {
+  const gzip = gzipSync(Buffer.from(JSON.stringify(map(context)))).toString('base64')
+
+  return { directory: MAP_DIRECTORY, file: MAP_FILE, gzip }
+}

package/src/deployment/.deployment/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { declare } = require('./declare')
-const { describe } = require('./describe')
-const { merge } = require('./merge')
-
-exports.declare = declare
-exports.describe = describe
-exports.merge = merge
+export { declare } from './declare.js'
+export { describe } from './describe.js'
+export { merge } from './merge.js'

package/src/deployment/.deployment/merge.js

@@ -1,6 +1,4 @@
-'use strict'
-
-const merge = (dependencies) => {
+export const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Reference[]} */
   const references = []
 
@@ -13,14 +11,78 @@ const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Variables} */
   const variables = {}
 
+  /** event labels consumed by something other than a component's own receivers */
+  const events = []
+
+  const mounts = {}
+
+  /** @type {toa.deployment.dependency.Probe | false | undefined} */
+  let probe
+
   for (const dependency of dependencies) {
     if (dependency.references !== undefined) references.push(...dependency.references)
     if (dependency.services !== undefined) services.push(...dependency.services)
     if (dependency.proxies !== undefined) proxies.push(...dependency.proxies)
     if (dependency.variables !== undefined) append(variables, dependency.variables)
+    if (dependency.events !== undefined) events.push(...dependency.events)
+    if (dependency.mounts !== undefined) append(mounts, dependency.mounts)
+    if (dependency.probe !== undefined) probe = dependency.probe
   }
 
-  return { references, services, proxies, variables }
+  reserve(services, probe)
+
+  return { references, services, proxies, variables, mounts, events, probe }
+}
+
+/**
+ * A workload that hosts services puts them in one process — `mono`, a composition that
+ * declares them, a local run — so within one a port may be claimed once and only once.
+ * A service deploying on its own is a pod of its own, and shares a port with nobody.
+ */
+const reserve = (services, probe) => {
+  /** @type {Map<string, Map<number, string>>} */
+  const workloads = new Map()
+
+  for (const service of services)
+    // a service several compositions run binds its ports in each of their pods
+    for (const workload of service.workload ?? [service.name]) {
+      let claimed = workloads.get(workload)
+
+      if (claimed === undefined) {
+        claimed = new Map()
+
+        if (probe !== undefined && probe !== false)
+          claimed.set(probe.port, 'the readiness probe')
+
+        workloads.set(workload, claimed)
+      }
+
+      for (const [port, claimant] of ports(service)) {
+        const conflicting = claimed.get(port)
+
+        if (conflicting !== undefined)
+          throw new Error(
+            `Port ${port} is claimed by both ${conflicting} and ${claimant}` +
+              (service.workload === undefined ? '' : ` in '${workload}'`)
+          )
+
+        claimed.set(port, claimant)
+      }
+    }
+}
+
+function* ports(service) {
+  // every service reaching here is named the way it is deployed, `<group>-<name>`
+  const name = `'${service.name}'`
+
+  if (service.port !== undefined) yield [service.port, name]
+
+  if (
+    service.probe !== undefined &&
+    service.probe !== false &&
+    service.probe.port !== service.port
+  )
+    yield [service.probe.port, `the readiness probe of ${name}`]
 }
 
 const append = (merged, variables) => {
@@ -30,5 +92,3 @@ const append = (merged, variables) => {
     merged[component].push(...vars)
   }
 }
-
-exports.merge = merge

package/src/deployment/.deployment/merge.test.js

@@ -0,0 +1,133 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { merge } from './merge.js'
+
+// a service is named the way it is deployed by the time it reaches `merge`
+const service = (name, extra = {}) => ({
+  group: 'group',
+  name: `group-${name}`,
+  version: '0',
+  ...extra
+})
+
+it('should merge services of all dependencies', () => {
+  const merged = merge([
+    { services: [service('one', { port: 8000 })] },
+    { services: [service('two', { port: 8001 })] }
+  ])
+
+  assert.strictEqual(merged.services.length, 2)
+})
+
+/*
+ * A workload that hosts services puts them in one process, so a port is claimed once
+ * within one. Services in separate pods share nothing.
+ */
+describe('port reservation', () => {
+  const hosted = (name, extra = {}) => service(name, { workload: ['mono'], ...extra })
+
+  it('should reject two services of one workload claiming one port', () => {
+    const dependencies = [
+      { services: [hosted('one', { port: 8000 })] },
+      { services: [hosted('two', { port: 8000 })] }
+    ]
+
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and 'group-two' in 'mono'/.test(
+          error.message
+        )
+    )
+  })
+
+  it('should allow two workloads to claim one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge'] })] },
+      { services: [service('two', { port: 8000, workload: ['inner'] })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should reserve the ports of a service in every workload running it', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge', 'inner'] })] },
+      { services: [service('two', { port: 8000, workload: ['inner'] })] }
+    ]
+
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and 'group-two' in 'inner'/.test(
+          error.message
+        )
+    )
+  })
+
+  it('should allow two services deployed on their own to claim one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000 })] },
+      { services: [service('two', { port: 8000 })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should reject a service claiming the port of the readiness probe', () => {
+    const dependencies = [
+      { probe: { path: '/.ready', port: 8001 } },
+      { services: [service('one', { port: 8001 })] }
+    ]
+
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8001 is claimed by both the readiness probe and 'group-one'/.test(
+          error.message
+        )
+    )
+  })
+
+  it('should reject a probe claiming the port of another service of the workload', () => {
+    const dependencies = [
+      { services: [hosted('one', { port: 8000 })] },
+      {
+        services: [hosted('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })]
+      }
+    ]
+
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two' in 'mono'/.test(
+          error.message
+        )
+    )
+  })
+
+  it('should allow a service to probe its own port', () => {
+    const dependencies = [
+      {
+        services: [service('one', { port: 8000, probe: { path: '/.ready', port: 8000 } })]
+      }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should ignore services without a port', () => {
+    const dependencies = [{ services: [service('one'), service('two')] }]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should ignore a disabled probe', () => {
+    const dependencies = [
+      { probe: false, services: [service('one', { port: 8000, probe: false })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+})

package/src/deployment/chart/templates/components.configmap.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.map }}
+# What every component of the context provides, by the version this deployment runs of it.
+# Mounted rather than rendered into a workload's environment: a variable would replace every pod
+# of the context on every deployment, and a pod that came up between two of them could not be
+# told. Carried gzipped, because what is read here is read by a program and a ConfigMap is capped
+# at a megabyte: `kubectl exec <pod> -- zcat {{ .Values.map.directory }}/{{ .Values.map.file }}`.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: components
+binaryData:
+  {{ .Values.map.file }}: {{ .Values.map.gzip | quote }}
+{{- end }}

package/src/deployment/chart/templates/components.yaml

@@ -6,11 +6,12 @@ metadata:
 spec:
   type: ClusterIP
   selector:
-    {{ . }}: "1"
+    toa/component-{{ . }}: "1"
   ports:
+    # what a streamed call is dialled at; see documentation/ports.md
     - name: http-binding
       protocol: TCP
-      port: 3000
-      targetPort: 3000
+      port: 8005
+      targetPort: 8005
 ---
 {{- end }}

package/src/deployment/chart/templates/compositions.yaml

@@ -5,29 +5,134 @@ metadata:
   name: composition-{{ required "composition name is required" .name }}
 spec:
   replicas: {{ .replicas | default 2 }}
+  # A backstop for stuck rollouts only. Must stay above the `helm upgrade --timeout`
+  # the deploy runs with, so a slow but progressing rollout is not marked failed.
+  progressDeadlineSeconds: 900
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      # a replacement must pass readiness before a running replica is taken out, and every
+      # replacement starts at once: the rollout takes one start-up, not one per replica
+      maxUnavailable: 0
+      maxSurge: 100%
   selector:
     matchLabels:
-      toa.io/composition: {{ .name }}
+      toa/composition: {{ .name }}
   template:
     metadata:
       labels:
-        toa.io/composition: {{ .name }}
+        toa/composition: {{ .name }}
         {{- range .components }}
-        {{ . }}: "1"
+        toa/component-{{ . }}: "1"
+        {{- end }}
+        {{- range .hosted }}
+        toa/service-{{ . }}: "1"
         {{- end }}
     spec:
       containers:
         - name: {{ .name }}
           image: {{ .image }}
-          {{- if .variables }}
+          {{- if .resources }}
+          resources:
+            {{- if or .resources.cpu .resources.memory }}
+            requests:
+              {{- if .resources.cpu }}
+              cpu: {{ index .resources.cpu 0 }}
+              {{- end }}
+              {{- if .resources.memory }}
+              memory: {{ index .resources.memory 0 }}
+              {{- end }}
+            limits:
+              {{- if .resources.cpu }}
+              cpu: {{ index .resources.cpu 1 }}
+              {{- end }}
+              {{- if .resources.memory }}
+              memory: {{ index .resources.memory 1 }}
+              {{- end }}
+            {{- end }}
+          {{- end }}          
+          {{- if or .variables .services }}
           env:
+            {{- if .services }}
+            - name: TOA_SERVICES
+              value: {{ join " " .services | quote }}
+            {{- end }}
             {{- range .variables }}
             {{- include "env.var" . | indent 12 }}
             {{- end }}
           {{- end }}
+          {{- if or .backends .probe }}
+          ports:
+            {{- range .backends }}
+            - containerPort: {{ .port }}
+            {{- end }}
+            {{- if .probe }}
+            - containerPort: {{ .probe.port }}
+            {{- end }}
+          {{- end }}
+          {{- if .probe }}
+          startupProbe:
+            httpGet:
+              path: {{ .probe.path }}
+              port: {{ .probe.port }}
+            {{- if .probe.delay }}
+            initialDelaySeconds: {{ .probe.delay }}
+            {{- end }}
+            periodSeconds: 2
+            timeoutSeconds: 3
+            failureThreshold: 150
+          readinessProbe:
+            httpGet:
+              path: {{ .probe.path }}
+              port: {{ .probe.port }}
+            # a replica is ready when it says so, not at the next tick of a slow clock
+            periodSeconds: 2
+            timeoutSeconds: 3
+            failureThreshold: 5
+          {{- end }}
+          {{- if or .mounts $.Values.map }}
+          volumeMounts:
+            {{- range .mounts }}
+            - name: {{ .name }}
+              mountPath: {{ .path }}
+            {{- end }}
+            {{- if $.Values.map }}
+            - name: components
+              mountPath: {{ $.Values.map.directory }}
+              readOnly: true
+            {{- end }}
+          {{- end }}
+          lifecycle:
+            preStop:
+              exec:
+                command: [sleep, "5"]
+      terminationGracePeriodSeconds: 45
       {{- if $.Values.credentials }}
       imagePullSecrets:
         - name: {{ $.Values.credentials }}
       {{- end }}
+      {{- if or .mounts $.Values.map }}
+      volumes:
+        {{- range .mounts }}
+        - name: {{ .name }}
+          persistentVolumeClaim:
+            claimName: {{ .claim }}
+        {{- end }}
+        {{- if $.Values.map }}
+        - name: components
+          configMap:
+            name: components
+        {{- end }}
+      {{- end }}
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: ScheduleAnyway
+          labelSelector:
+            matchLabels:
+              toa/composition: {{ .name }}
+          # only this revision's pods: a rollout spreads the new ones, whatever the old ones occupy
+          matchLabelKeys:
+            - pod-template-hash
 ---
 {{- end }}