@toa.io/operations 1.0.0-alpha.34 → 1.0.0-alpha.341

package/src/deployment/chart/values.yaml

@@ -3,9 +3,16 @@ compositions:
   - name: todos
     image: localhost:5000/composition-todos:0.0.0
     replicas: 2
+    mounts:
+      - name: mount-name
+        path: /storage
+        claim: storage-pvc
     components:
       - todos-tasks
       - todos-stats
+    resources:
+      cpu: [100m, 1]
+      memory: [100Mi, 1Gi]
     variables:
       - name: TOA_CONFIGURATION_TODOS_TASKS
         value: foo
@@ -18,17 +25,32 @@ compositions:
     replicas: 3
     components:
       - users-users
-# TODO: create component services only if sync binding is being used
+    # the extensions whose services this composition runs in its own pod
+    services:
+      - '@toa.io/extensions.exposition'
+    # each of those, as its own Service selects it
+    hosted:
+      - exposition-gateway
+    # the ports they bind
+    backends:
+      - port: 8000
+        path: /
 components:
   - todos-tasks
   - todos-stats
   - users-users
 services:
+  # a service a composition runs carries `workload`, and gets no deployment of its own —
+  # its Service and Ingress stay, and select that composition's pods
   - name: resources-gateway
     image: localhost:5000/resources-gateway:0.0.0
     port: 8000
     replicas: 2
+    resources:
+      cpu: [100m, 1]
+      memory: [100Mi, 1Gi]
     ingress:
+      default: true
       hosts: [dummies.toa.io]
       class: alb
       annotations:

package/src/deployment/composition.js

@@ -1,18 +1,20 @@
-'use strict'
-
-class Composition {
+export class Composition {
   name
   image
   /** @type {string[]} */
   components
 
-  constructor (composition, image) {
+  constructor(composition, image) {
     this.name = composition.name
     this.image = image.reference
     this.components = composition.components.map(component)
+    this.resources = composition.resources
+
+    if (composition.replicas !== undefined) this.replicas = composition.replicas
+
+    // the extensions whose services this composition runs, as `TOA_SERVICES` for the process
+    if (composition.services !== undefined) this.services = composition.services
   }
 }
 
 const component = (component) => component.locator.label
-
-exports.Composition = Composition

package/src/deployment/deployment.js

@@ -1,90 +1,230 @@
-'use strict'
+import { join } from 'node:path'
+import { writeFile as write } from 'node:fs/promises'
+import { yaml as jsyaml } from '@toa.io/generic'
+import { cp } from 'node:fs/promises'
+import { shortcuts } from '@toa.io/norm'
 
-const { join } = require('node:path')
-const { writeFile: write } = require('node:fs/promises')
-const { dump } = require('@toa.io/yaml')
-const fs = require('fs-extra')
+import { merge, declare, describe } from './.deployment/index.js'
+import { drain } from './drain.js'
+import * as secrets from './secrets.js'
 
-const { merge, declare, describe } = require('./.deployment')
-
-class Deployment {
+export class Deployment {
   #chart
   #values
+  #keyed
   #process
   #target
 
-  constructor (context, compositions, dependencies, process) {
+  constructor(context, compositions, dependencies, process, image) {
     const dependency = merge(dependencies)
 
     this.#chart = declare(context, dependency)
-    this.#values = describe(context, compositions, dependency)
+    this.#values = describe(context, compositions, dependency, image)
+    this.#keyed = dependency.variables
     this.#process = process
   }
 
-  async export (target) {
+  async export(target) {
+    // a context is read for a local run as well — `toa env` builds one of these and asks it
+    // for variables — and such a context needs no chart and states no version. So this is
+    // asked for where a chart is written, and not where a context is read. Without it Helm
+    // answers `chart.metadata.version is required`, naming nothing, by which point a deploy
+    // has built and pushed every image.
+    if (this.#chart.version === undefined)
+      throw new Error(
+        `Context '${this.#chart.name}' declares no version, which is what its chart is ` +
+          'versioned by. Declare it in context.toa.yaml.'
+      )
+
     const chart = dump(this.#chart)
     const values = dump(this.#values)
 
     await Promise.all([
       write(join(target, 'Chart.yaml'), chart),
       write(join(target, 'values.yaml'), values),
-      fs.copy(TEMPLATES, join(target, 'templates'))
+      cp(TEMPLATES, join(target, 'templates'), { recursive: true })
     ])
 
     this.#target = target
   }
 
-  async install (options) {
+  /**
+   * Refuses a deploy the cluster is not ready for: a secret a workload reads that is not there
+   * leaves its pod uncreated, which is seen only once every image has been built and pushed.
+   *
+   * @param {toa.deployment.installation.Options} options
+   * @returns {Promise<void>}
+   */
+  async verify(options) {
+    const references = secrets.references(this.variables(), this.#values.credentials)
+
+    await secrets.verify(this.#process, references, options)
+  }
+
+  async install(options) {
     if (options.target) this.#target = options.target
-    if (this.#target === undefined) throw new Error('Deployment hasn\'t been exported')
+    if (this.#target === undefined) throw new Error("Deployment hasn't been exported")
 
     const args = []
 
     if (options.namespace !== undefined) args.push('-n', options.namespace)
-    if (options.wait === true) args.push('--wait')
+    // an upgrade waited for and failed — or timed out — is rolled back, rather than left pending:
+    // a pending release refuses every upgrade after it
+    if (options.wait === true) args.push('--wait', '--atomic')
+    if (options.timeout !== undefined) args.push('--timeout', options.timeout)
+
+    await this.#update()
+    await this.#process.execute('helm', [
+      'upgrade',
+      this.#chart.name,
+      '-i',
+      ...args,
+      this.#target
+    ])
 
-    await this.#process.execute('helm', ['dependency', 'update', this.#target])
-    await this.#process.execute('helm', ['upgrade', this.#chart.name, '-i', ...args, this.#target])
+    // ready is not done: the replicas replaced are still draining when helm answers
+    if (options.wait === true) await drain(this.#process, options)
   }
 
-  async template (options) {
-    if (this.#target === undefined) throw new Error('Deployment hasn\'t been exported')
+  async template(options) {
+    if (this.#target === undefined) throw new Error("Deployment hasn't been exported")
 
-    await this.#process.execute('helm', ['dependency', 'update', this.#target], { silently: true })
+    await this.#update({ silently: true })
 
     const args = []
 
     if (options.namespace !== undefined) args.push('-n', options.namespace)
 
-    return await this.#process.execute('helm',
+    return await this.#process.execute(
+      'helm',
       ['template', this.#chart.name, ...args, this.#target],
-      { silently: true })
+      { silently: true }
+    )
+  }
+
+  /**
+   * A chart with no subcharts has nothing to resolve, and the call still reaches out for
+   * the repositories it would have read.
+   *
+   * @param {object} [options]
+   * @returns {Promise<void>}
+   */
+  async #update(options = {}) {
+    if (this.#chart.dependencies.length === 0) return
+
+    await this.#process.execute('helm', ['dependency', 'update', this.#target], options)
+  }
+
+  /**
+   * @param {{ components?: string[], services?: string[] }} [options]
+   * @returns {toa.deployment.dependency.Variable[]}
+   */
+  variables(options = {}) {
+    if (options.components === undefined && options.services === undefined) {
+      const variables = []
+      const used = new Set()
+
+      addVariables(this.#values.compositions, variables, used)
+      addVariables(this.#values.services, variables, used)
+
+      if (this.#values.mono !== undefined)
+        addVariables([this.#values.mono], variables, used)
+
+      return variables
+    }
+
+    return this.#select(options.components, options.services)
   }
 
-  variables () {
+  /**
+   * @param {string[] | undefined} components
+   * @param {string[] | undefined} services
+   * @returns {toa.deployment.dependency.Variable[]}
+   */
+  #select(components, services) {
+    const labels = labelsOf(this.#values, this.#keyed)
+    const keys = new Set(['global'])
+    const selected = []
+
+    for (const token of components ?? []) keys.add(matchComponent(token, labels))
+
+    for (const token of services ?? []) {
+      const service = matchService(token, this.#values.services)
+
+      selected.push(service)
+
+      for (const label of service.components ?? []) keys.add(label)
+    }
+
     const variables = []
     const used = new Set()
 
-    addVariables(this.#values.compositions, variables, used)
-    addVariables(this.#values.services, variables, used)
+    for (const key of keys) append(this.#keyed[key], variables, used)
+
+    for (const service of selected) append(service.variables, variables, used)
 
     return variables
   }
 }
 
-function addVariables (list, variables, used = new Set()) {
-  for (const item of list) {
-    if (item.variables === undefined) continue
+function addVariables(list, variables, used = new Set()) {
+  if (list === undefined) return
 
-    for (const variable of item.variables) {
-      if (used.has(variable.name)) continue
+  for (const item of list) append(item.variables, variables, used)
+}
 
-      variables.push(variable)
-      used.add(variable.name)
-    }
+function append(set, variables, used) {
+  if (set === undefined) return
+
+  for (const variable of set) {
+    if (used.has(variable.name)) continue
+
+    variables.push(variable)
+    used.add(variable.name)
   }
 }
 
-const TEMPLATES = join(__dirname, 'chart/templates')
+function labelsOf(values, keyed) {
+  const labels = new Set(values.components ?? [])
 
-exports.Deployment = Deployment
+  for (const service of values.services ?? [])
+    for (const label of service.components ?? []) labels.add(label)
+
+  for (const key of Object.keys(keyed ?? {})) if (key !== 'global') labels.add(key)
+
+  return labels
+}
+
+function matchComponent(token, labels) {
+  const candidates = [token, token.replaceAll('.', '-').toLowerCase()]
+
+  if (!token.includes('.')) candidates.push('default-' + token.toLowerCase())
+
+  for (const candidate of candidates) if (labels.has(candidate)) return candidate
+
+  throw new Error(`Component '${token}' is not in the context`)
+}
+
+function matchService(token, services) {
+  const resolved = shortcuts.resolve(token)
+
+  const service = (services ?? []).find((service) => {
+    if (service.name === token || service.group === token) return true
+
+    for (const [alias, pkg] of Object.entries(shortcuts.SHORTCUTS))
+      if (resolved === pkg && service.group === alias) return true
+
+    return false
+  })
+
+  if (service === undefined) throw new Error(`Service '${token}' is not in the context`)
+
+  return service
+}
+
+const TEMPLATES = join(import.meta.dirname, 'chart/templates')
+
+function dump(object) {
+  // js-yaml writes plain objects only, and the values carry locators and images
+  return jsyaml.dump(JSON.parse(JSON.stringify(object)), { noRefs: true, lineWidth: -1 })
+}

package/src/deployment/drain.js

@@ -0,0 +1,70 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+
+/**
+ * Waits until no pod of the application is still terminating. `helm --wait` answers once the
+ * replacements are ready, while the replicas they replace are still draining, and a request
+ * made then may land on either.
+ *
+ * @param {toa.operations.Process} process
+ * @param {toa.deployment.installation.Options} options
+ * @returns {Promise<void>}
+ */
+export async function drain(process, options) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT
+  const deadline = Date.now() + duration(timeout)
+  const args = ['get', 'pods', '-o', 'json']
+
+  if (options.namespace !== undefined) args.push('-n', options.namespace)
+
+  let announced = false
+
+  for (;;) {
+    const output = await process.execute('kubectl', args, { silently: true })
+    const pods = JSON.parse(output).items.filter(terminating)
+
+    if (pods.length === 0) return
+
+    if (Date.now() >= deadline)
+      throw new Error(`${pods.length} replaced pod(s) still terminating after ${timeout}`)
+
+    if (!announced) {
+      console.log(`Waiting for ${pods.length} replaced pod(s) to terminate`)
+      announced = true
+    }
+
+    await sleep(INTERVAL)
+  }
+}
+
+/**
+ * A pod of the application on its way out. The chart labels every pod it renders under `toa/`,
+ * and nothing else in the namespace is waited for.
+ */
+const terminating = (pod) =>
+  pod.metadata.deletionTimestamp !== undefined &&
+  Object.keys(pod.metadata.labels ?? {}).some((label) => label.startsWith('toa/'))
+
+/**
+ * A helm duration, `12m` or `1h30m` or `90s`, in milliseconds.
+ *
+ * @param {string} value
+ * @returns {number}
+ */
+export function duration(value) {
+  const matches = value.matchAll(/(\d+)(h|ms|m|s)/g)
+
+  let total = 0
+
+  for (const [, amount, unit] of matches) total += Number(amount) * UNITS[unit]
+
+  if (total === 0) throw new Error(`'${value}' is not a duration`)
+
+  return total
+}
+
+const UNITS = { h: 3_600_000, m: 60_000, s: 1_000, ms: 1 }
+
+/** helm's own default for `--timeout` */
+const DEFAULT_TIMEOUT = '5m'
+
+const INTERVAL = 3_000

package/src/deployment/drain.test.js

@@ -0,0 +1,64 @@
+import { it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { drain, duration } from './drain.js'
+
+/** @type {Array<object[]>} what each poll answers */
+let polls
+
+/** @type {toa.operations.Process} */
+let process
+
+beforeEach(() => {
+  polls = []
+  process = /** @type {toa.operations.Process} */ {
+    execute: mock.fn(async () => JSON.stringify({ items: polls.shift() ?? [] }))
+  }
+})
+
+it('should answer once no pod of the application is terminating', async () => {
+  polls.push([pod('composition-a', true), pod('composition-b')], [pod('composition-b')])
+
+  await drain(process, { namespace: 'acme', timeout: '1m' })
+
+  assert.strictEqual(process.execute.mock.callCount(), 2)
+
+  const [, args, options] = process.execute.mock.calls[0].arguments
+
+  assert.deepStrictEqual(args, ['get', 'pods', '-o', 'json', '-n', 'acme'])
+  assert.deepStrictEqual(options, { silently: true })
+})
+
+it('should not wait for a pod that is not the application', async () => {
+  polls.push([pod('redis-0', true, {})])
+
+  await drain(process, {})
+
+  assert.strictEqual(process.execute.mock.callCount(), 1)
+})
+
+it('should give up at the timeout', async () => {
+  polls.push([pod('composition-a', true)], [pod('composition-a', true)])
+
+  await assert.rejects(drain(process, { timeout: '1ms' }), /still terminating after 1ms/)
+})
+
+it('should read a helm duration', () => {
+  assert.strictEqual(duration('12m'), 720_000)
+  assert.strictEqual(duration('1h30m'), 5_400_000)
+  assert.strictEqual(duration('90s'), 90_000)
+  assert.throws(() => duration('soon'), /not a duration/)
+})
+
+/**
+ * @param {string} name
+ * @param {boolean} [terminating]
+ * @param {object} [labels]
+ */
+function pod(name, terminating = false, labels = { 'toa/composition': 'a' }) {
+  const metadata = { name, labels }
+
+  if (terminating) metadata.deletionTimestamp = '2026-01-01T00:00:00Z'
+
+  return { metadata }
+}