@toa.io/operations 1.0.0-alpha.318 → 1.0.0-alpha.319

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.319](https://github.com/toa-io/toa/compare/v1.0.0-alpha.318...v1.0.0-alpha.319) (2026-09-27)
+
+### Features
+
+* **operations:** refuse a deploy where the cluster does not hold a secret ([beb7ccf](https://github.com/toa-io/toa/commit/beb7ccf35619494ab9ad6659963969bb4f9603c8))
+
+
 # [1.0.0-alpha.318](https://github.com/toa-io/toa/compare/v1.0.0-alpha.317...v1.0.0-alpha.318) (2026-09-23)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.318",
+  "version": "1.0.0-alpha.319",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -30,9 +30,9 @@
   "dependencies": {
     "@toa.io/generic": "1.0.0-alpha.311",
     "@toa.io/kubernetes": "1.0.0-alpha.301",
-    "@toa.io/norm": "1.0.0-alpha.318",
+    "@toa.io/norm": "1.0.0-alpha.319",
     "oxc-parser": "0.150.0",
     "paseto": "4.0.1"
   },
-  "gitHead": "82895af77cf22e8529925ba97193d73ee2139297"
+  "gitHead": "ee4901f2bc12c33fc2098a62f2af0c29838a2c2c"
 }

package/readme.md

@@ -60,6 +60,23 @@ declared. `evicted@production` states it for one environment.
 
 See [compositions](../documentation/compositions.md#evicted).
 
+## Secrets
+
+A value that must not be in the chart is rendered as a reference to a Kubernetes secret, and the
+secret is the application's to deploy. A deploy reads the namespace it deploys into before it builds
+anything, and refuses where a key a workload would read is not there:
+
+```
+$ toa deploy production
+Secrets are not deployed: toa-mongodb.default/username, toa-mongodb.default/password
+```
+
+Required is what `toa export secrets` lists, less the keys it marks `(optional)`, plus the
+`registry.credentials` secret where a context names one. `toa deploy --dry` reads no cluster, and
+neither does anything else that reads a context: `toa env`, `toa export`, `toa build` and `toa push`.
+
+See [variables and secrets](../documentation/deployment.md#variables-and-secrets).
+
 ## Context
 
 ### Container Registry
@@ -203,6 +220,9 @@ registry:
   credentials: docker-credentials-secret-name
 ```
 
+The secret itself is not Toa's to create, and a deploy that does not find it in the cluster is
+[refused](#secrets).
+
 #### Toa images
 
 Each release publishes `ghcr.io/toa-io/runtime:<version>` and, beside it, `:alpha` or `:latest`.

package/src/deployment/deployment.js

@@ -6,6 +6,7 @@ import { shortcuts } from '@toa.io/norm'
 
 import { merge, declare, describe } from './.deployment/index.js'
 import { drain } from './drain.js'
+import * as secrets from './secrets.js'
 
 export class Deployment {
   #chart
@@ -47,6 +48,19 @@ export class Deployment {
     this.#target = target
   }
 
+  /**
+   * 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")

package/src/deployment/operator.js

@@ -40,6 +40,9 @@ export class Operator {
   async install(options = {}) {
     options = Object.assign({}, OPTIONS, options)
 
+    // nothing is built, pushed or applied where the cluster cannot run what this deploys
+    await this.#deployment.verify(options)
+
     await Promise.all([this.export(), this.push()])
     await this.#registry.alias(this.#environment)
     await this.#deployment.install(options)

package/src/deployment/operator.test.js

@@ -54,6 +54,7 @@ describe('install', () => {
   beforeEach(() => {
     deployment = /** @type {toa.deployment.Deployment} */ {
       export: mock.fn(async () => {}),
+      verify: mock.fn(async () => {}),
       install: mock.fn(async () => {})
     }
     registry = /** @type {toa.deployment.Registry} */ {
@@ -62,6 +63,46 @@ describe('install', () => {
     }
   })
 
+  it('should verify the secrets before anything is built', async () => {
+    const order = []
+
+    deployment.verify = mock.fn(async () => {
+      order.push('verify')
+    })
+    deployment.export = mock.fn(async () => {
+      order.push('export')
+    })
+    registry.push = mock.fn(async () => {
+      order.push('push')
+    })
+
+    operator = new Operator(deployment, registry, 'production')
+
+    await operator.install({ namespace: 'acme' })
+
+    // export and push race each other, and both wait for the cluster to have been read
+    assert.strictEqual(order[0], 'verify')
+    assert.deepStrictEqual(order.slice(1).sort(), ['export', 'push'])
+    assert.deepStrictEqual(deployment.verify.mock.calls[0].arguments, [
+      { wait: false, namespace: 'acme' }
+    ])
+  })
+
+  it('should build nothing where the secrets are not deployed', async () => {
+    deployment.verify = mock.fn(async () => {
+      throw new Error('Secrets are not deployed: toa-mongodb.default/username')
+    })
+
+    operator = new Operator(deployment, registry, 'production')
+
+    await assert.rejects(operator.install(), /Secrets are not deployed/)
+
+    assert.strictEqual(deployment.export.mock.callCount(), 0)
+    assert.strictEqual(registry.push.mock.callCount(), 0)
+    assert.strictEqual(registry.alias.mock.callCount(), 0)
+    assert.strictEqual(deployment.install.mock.callCount(), 0)
+  })
+
   it('should tag the environment after a push', async () => {
     const order = []
 

package/src/deployment/secrets.js

@@ -0,0 +1,92 @@
+/**
+ * What the cluster has to hold for a deployment to run, and the refusal where it does not.
+ *
+ * A pod whose secret is not there is never created, and nothing the chart carries says so: Helm
+ * reports a release, the rollout stalls, and the name of what is missing is in the events of a pod
+ * that does not exist. The cluster answers the question before any of that, for one call.
+ */
+
+/**
+ * Every secret the workloads read, as `<name>/<key>`, and the image pull secret by name alone —
+ * what it holds is the registry's affair, and its absence stops a pod just the same.
+ *
+ * @param {toa.deployment.dependency.Variable[]} variables
+ * @param {string} [credentials] `registry.credentials`
+ * @returns {string[]}
+ */
+export function references(variables, credentials) {
+  /** @type {string[]} */
+  const references = []
+
+  // as the chart renders it: `imagePullSecrets` is there where the name is, and a context
+  // that states the key and no name names no secret
+  if (credentials) references.push(credentials)
+
+  for (const { secret } of variables) {
+    // a key the workload starts without is not one the cluster has to hold
+    if (secret === undefined || secret.optional === true) continue
+
+    const reference = `${secret.name}/${secret.key}`
+
+    if (!references.includes(reference)) references.push(reference)
+  }
+
+  return references
+}
+
+/**
+ * @param {toa.operations.Process} process
+ * @param {string[]} references
+ * @param {toa.deployment.installation.Options} options
+ * @returns {Promise<void>}
+ */
+export async function verify(process, references, options) {
+  if (references.length === 0) return
+
+  const deployed = await read(process, options)
+  const missing = references.filter((reference) => !deployed.has(reference))
+
+  if (missing.length > 0)
+    throw new Error(`Secrets are not deployed: ${missing.join(', ')}`)
+}
+
+/**
+ * What the namespace holds, as the names of its secrets and the `<name>/<key>` of every key in
+ * them. The namespace is read whole: a call per secret would be a process per secret, and the
+ * wrapper for a single one cannot tell a secret that is absent from a cluster that cannot be
+ * reached — which a preflight is the worst place to guess at. Listing asks no permission a
+ * deploy does not already have, Helm keeping its own release state in secrets of this namespace.
+ *
+ * Only the keys are read. What is under them is the cluster's and stays there.
+ *
+ * @param {toa.operations.Process} process
+ * @param {toa.deployment.installation.Options} options
+ * @returns {Promise<Set<string>>}
+ */
+async function read(process, options) {
+  const args = ['get', 'secrets', '-o', TEMPLATE]
+
+  if (options.namespace !== undefined) args.push('-n', options.namespace)
+
+  const output = await process.execute('kubectl', args, { silently: true })
+
+  /** @type {Set<string>} */
+  const deployed = new Set()
+
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+
+    const [name, ...keys] = line.split(' ')
+
+    deployed.add(name)
+
+    for (const key of keys) deployed.add(`${name}/${key}`)
+  }
+
+  return deployed
+}
+
+/** A secret's name and the keys in it, one secret a line. Neither may hold a space. */
+const TEMPLATE =
+  'go-template={{range .items}}{{.metadata.name}}' +
+  '{{range $key, $value := .data}} {{$key}}{{end}}{{"\\n"}}{{end}}'

package/src/deployment/secrets.test.js

@@ -0,0 +1,172 @@
+import { it, describe, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { references, verify } from './secrets.js'
+
+describe('references', () => {
+  it('should reference a secret by name and key', () => {
+    const variables = [
+      { name: 'TOA_CONTEXT', value: 'todos' },
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } },
+      { name: 'PASSWORD', secret: { name: 'toa-mongodb.default', key: 'password' } }
+    ]
+
+    assert.deepStrictEqual(references(variables), [
+      'toa-mongodb.default/username',
+      'toa-mongodb.default/password'
+    ])
+  })
+
+  it('should not reference an optional key', () => {
+    const variables = [
+      { name: 'KEY', secret: { name: 'toa-tokens', key: 'key0', optional: true } },
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } }
+    ]
+
+    assert.deepStrictEqual(references(variables), ['toa-mongodb.default/username'])
+  })
+
+  it('should reference a key read by two workloads once', () => {
+    const secret = { name: 'toa-mongodb.default', key: 'username' }
+
+    assert.deepStrictEqual(references([{ name: 'A', secret }, { name: 'B', secret }]), [
+      'toa-mongodb.default/username'
+    ])
+  })
+
+  it('should reference the image pull secret by name', () => {
+    const variables = [
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } }
+    ]
+
+    assert.deepStrictEqual(references(variables, 'registry-credentials'), [
+      'registry-credentials',
+      'toa-mongodb.default/username'
+    ])
+  })
+
+  it('should reference nothing where nothing is secret', () => {
+    assert.deepStrictEqual(references([{ name: 'TOA_ENV', value: 'production' }]), [])
+  })
+
+  it('should reference no pull secret where a context names none', () => {
+    // as the chart reads it: `credentials: ~` renders no `imagePullSecrets`
+    assert.deepStrictEqual(references([], null), [])
+    assert.deepStrictEqual(references([], ''), [])
+  })
+})
+
+describe('verify', () => {
+  /** @type {string} what `kubectl` answers */
+  let secrets
+
+  /** @type {toa.operations.Process} */
+  let process
+
+  beforeEach(() => {
+    secrets = ''
+    process = /** @type {toa.operations.Process} */ {
+      execute: mock.fn(async () => secrets)
+    }
+  })
+
+  it('should read the namespace deployed into', async () => {
+    secrets = 'toa-mongodb.default password username'
+
+    await verify(process, ['toa-mongodb.default/username'], { namespace: 'acme' })
+
+    const [cmd, args, options] = process.execute.mock.calls[0].arguments
+
+    assert.strictEqual(cmd, 'kubectl')
+    assert.deepStrictEqual(args.slice(0, 2), ['get', 'secrets'])
+    assert.deepStrictEqual(args.slice(-2), ['-n', 'acme'])
+    assert.deepStrictEqual(options, { silently: true })
+  })
+
+  it('should read the current namespace where none is given', async () => {
+    await verify(process, [], {})
+
+    assert.strictEqual(process.execute.mock.callCount(), 0)
+
+    await verify(process, ['toa-mongodb.default/username'], {}).catch(() => {})
+
+    const [, args] = process.execute.mock.calls[0].arguments
+
+    assert.strictEqual(args.includes('-n'), false)
+  })
+
+  it('should name every key that is not deployed', async () => {
+    secrets = 'toa-amqp-context.default password username'
+
+    await assert.rejects(
+      verify(
+        process,
+        [
+          'toa-amqp-context.default/username',
+          'toa-mongodb.default/username',
+          'toa-mongodb.default/password'
+        ],
+        {}
+      ),
+      {
+        message:
+          'Secrets are not deployed: toa-mongodb.default/username, ' +
+          'toa-mongodb.default/password'
+      }
+    )
+  })
+
+  it('should name the key a deployed secret lacks', async () => {
+    secrets = 'toa-mongodb.default username'
+
+    await assert.rejects(
+      verify(process, ['toa-mongodb.default/username', 'toa-mongodb.default/password'], {}),
+      { message: 'Secrets are not deployed: toa-mongodb.default/password' }
+    )
+  })
+
+  it('should name a secret referenced by name alone', async () => {
+    secrets = 'toa-mongodb.default password username'
+
+    await assert.rejects(verify(process, ['registry-credentials'], {}), {
+      message: 'Secrets are not deployed: registry-credentials'
+    })
+
+    secrets = 'registry-credentials .dockerconfigjson'
+
+    await verify(process, ['registry-credentials'], {})
+  })
+
+  it('should pass where the cluster holds every key', async () => {
+    secrets =
+      'default-token\ntoa-amqp-context.default password username\n' +
+      'toa-mongodb.default password username'
+
+    await verify(
+      process,
+      [
+        'toa-amqp-context.default/username',
+        'toa-amqp-context.default/password',
+        'toa-mongodb.default/username',
+        'toa-mongodb.default/password'
+      ],
+      {}
+    )
+  })
+
+  it('should not read the cluster where nothing is secret', async () => {
+    await verify(process, [], { namespace: 'acme' })
+
+    assert.strictEqual(process.execute.mock.callCount(), 0)
+  })
+
+  it('should fail as the error it is where the cluster cannot be read', async () => {
+    process.execute = mock.fn(async () => {
+      throw new Error('Command failed with exit code 1: kubectl get secrets')
+    })
+
+    await assert.rejects(verify(process, ['toa-mongodb.default/username'], {}), {
+      message: /^Command failed/
+    })
+  })
+})

package/types/_deployment/dependency.d.ts

@@ -44,6 +44,8 @@ declare namespace toa.deployment {
       secret?: {
         name: string
         key: string
+        /** The workload starts without it, so the cluster need not hold it. */
+        optional?: boolean
       }
     }
 

package/types/_deployment/deployment.d.ts

@@ -45,6 +45,9 @@ declare namespace toa.deployment {
   interface Deployment {
     export(target: string): Promise<void>
 
+    /** Raises where the cluster does not hold a secret the workloads read. */
+    verify(options: installation.Options): Promise<void>
+
     install(options: installation.Options): Promise<void>
 
     template(options: template.Options): Promise<string>