@toa.io/operations 1.0.0-alpha.24 → 1.0.0-alpha.243

package/image/runtime.Dockerfile

@@ -0,0 +1,4 @@
+FROM node:24.14.0-alpine3.22
+
+ARG VERSION
+RUN npm i -g @toa.io/runtime@${VERSION} --omit=dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.24",
+  "version": "1.0.0-alpha.243",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
   "author": {
@@ -16,23 +16,23 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 20.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "types": "types/index.ts",
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/filesystem": "1.0.0-alpha.24",
-    "@toa.io/generic": "1.0.0-alpha.24",
-    "@toa.io/norm": "1.0.0-alpha.24",
-    "@toa.io/yaml": "1.0.0-alpha.24",
+    "@toa.io/filesystem": "1.0.0-alpha.225",
+    "@toa.io/generic": "1.0.0-alpha.225",
+    "@toa.io/norm": "1.0.0-alpha.243",
+    "@toa.io/yaml": "1.0.0-alpha.225",
     "execa": "5.1.1",
     "fs-extra": "11.1.1"
   },
-  "gitHead": "308058561dfc97337a8b9755f357644e7dba8859"
+  "gitHead": "743e8060d35ca750f70487c04aef9698591c5edd"
 }

package/readme.md

@@ -4,6 +4,22 @@
 
 ### Container Registry
 
+Deploy images default to `FROM ghcr.io/toa-io/runtime:<runtime.version>`
+(published with each Toa release). The base image already has `@toa.io/runtime`
+installed; composition/service Dockerfiles only install component dependencies.
+
+To use a custom base image, set `registry.build.image` (or `composition.image`).
+That image must provide the `toa` CLI, or install it via `registry.build.run`:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  build:
+    image: node:24.14.0-alpine3.22
+    run: npm i -g @toa.io/runtime --omit=dev
+```
+
 #### Build Options
 
 ```yaml

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

@@ -1,10 +1,15 @@
 'use strict'
 
 const { addVariables } = require('./variables')
+const { addMounts } = require('./mounts')
 
-function compositions (compositions, variables) {
+function compositions (compositions, dependency) {
   for (const composition of compositions) {
-    addVariables(composition, variables)
+    addVariables(composition, dependency.variables)
+    addMounts(composition, dependency.mounts)
+
+    if (dependency.probe !== undefined && dependency.probe !== false)
+      composition.probe ??= dependency.probe
   }
 }
 

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

@@ -0,0 +1,24 @@
+'use strict'
+
+function addMounts (composition, mounts) {
+  if (mounts === undefined)
+    return
+
+  const used = new Set()
+
+  for (const [key, mount] of Object.entries(mounts)) {
+    if (key !== 'global' && !composition.components?.includes(key))
+      continue
+
+    for (const { name, path, claim } of mount) {
+      if (used.has(name))
+        continue
+
+      composition.mounts ??= []
+      composition.mounts.push({ name, path, claim })
+      used.add(name)
+    }
+  }
+}
+
+exports.addMounts = addMounts

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

@@ -2,9 +2,14 @@
 
 const { addVariables } = require('./variables')
 
-function services (services, variables) {
+function services (services, variables, probe) {
   for (const service of services) {
     addVariables(service, variables)
+
+    if (service.probe === false)
+      delete service.probe
+    else if (service.probe === undefined && probe !== undefined && probe !== false)
+      service.probe = probe
   }
 }
 

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

@@ -1,17 +1,18 @@
 'use strict'
 
-function addVariables (deployment, variables) {
-  const used = new Set()
+function addVariables (composition, variables) {
+  composition.variables ??= []
 
-  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' && !composition.components?.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)
     }
   }

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

@@ -1,6 +1,6 @@
 'use strict'
 
-const get = require('./.describe')
+const desc = require('./.describe')
 
 const describe = (context, compositions, dependency) => {
   const { services } = dependency
@@ -17,11 +17,11 @@ const describe = (context, compositions, dependency) => {
     }
   )
 
-  const components = get.components(compositions)
+  const components = desc.components(compositions)
   const credentials = context.registry?.credentials
 
-  get.compositions(compositions, dependency.variables, context.environment)
-  get.services(services, dependency.variables)
+  desc.compositions(compositions, dependency)
+  desc.services(services, dependency.variables, dependency.probe)
 
   return {
     compositions,

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

@@ -13,14 +13,21 @@ const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Variables} */
   const variables = {}
 
+  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.mounts !== undefined) append(mounts, dependency.mounts)
+    if (dependency.probe !== undefined) probe = dependency.probe
   }
 
-  return { references, services, proxies, variables }
+  return { references, services, proxies, variables, mounts, probe }
 }
 
 const append = (merged, variables) => {

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

@@ -5,6 +5,9 @@ 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
   selector:
     matchLabels:
       toa.io/composition: {{ .name }}
@@ -19,15 +22,82 @@ spec:
       containers:
         - name: {{ .name }}
           image: {{ .image }}
+          {{- 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 .variables }}
           env:
             {{- range .variables }}
             {{- include "env.var" . | indent 12 }}
             {{- end }}
           {{- end }}
+          {{- if .probe }}
+          ports:
+            - containerPort: {{ .probe.port }}
+          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 }}
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 3
+          {{- end }}
+          {{- if .mounts }}
+          volumeMounts:
+            {{- range .mounts }}
+            - name: {{ .name }}
+              mountPath: {{ .path }}
+            {{- end }}
+          {{- end }}
+          lifecycle:
+            preStop:
+              exec:
+                command: [sleep, "5"]
+      terminationGracePeriodSeconds: 45
       {{- if $.Values.credentials }}
       imagePullSecrets:
         - name: {{ $.Values.credentials }}
       {{- end }}
+      {{- if .mounts }}
+      volumes:
+        {{- range .mounts }}
+        - name: {{ .name }}
+          persistentVolumeClaim:
+            claimName: {{ .claim }}
+        {{- end }}
+      {{- end }}
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: ScheduleAnyway
+          labelSelector:
+            matchLabels:
+              toa.io/composition: {{ .name }}
 ---
 {{- end }}

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

@@ -5,6 +5,16 @@ metadata:
   name: extension-{{ required "deployment 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,
+      # otherwise a single pod serves all traffic while the others start up
+      maxUnavailable: 0
+      maxSurge: 50%
   selector:
     matchLabels:
       toa.io/service: extension-{{ .name }}
@@ -16,12 +26,63 @@ spec:
       containers:
         - name: extension-{{ .name }}
           image: {{ .image }}
+          {{- 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 .variables }}
           env:
             {{- range .variables }}
             {{- include "env.var" . | indent 12 }}
             {{- 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 }}
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 3
+          {{- end }}
+          lifecycle:
+            preStop:
+              exec:
+                command: [sleep, "5"]
+      terminationGracePeriodSeconds: 45
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: ScheduleAnyway
+          labelSelector:
+            matchLabels:
+              toa.io/service: extension-{{ .name }}
+{{- if .port }}
 ---
 apiVersion: v1
 kind: Service
@@ -36,9 +97,10 @@ spec:
       protocol: TCP
       port: {{ .port }}
       targetPort: {{ .port }}
----
+{{- end }}
 {{- if .ingress }}
 {{- $service := .name }}
+---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
@@ -64,5 +126,17 @@ spec:
                 port:
                   number: 8000
     {{- end }}
+    {{- if .ingress.default }}
+    - http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: extension-{{ $service }}
+                port:
+                  number: 8000
+    {{- end }}
 {{- end }}
+---
 {{- end }}

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,7 +25,6 @@ compositions:
     replicas: 3
     components:
       - users-users
-# TODO: create component services only if sync binding is being used
 components:
   - todos-tasks
   - todos-stats
@@ -28,7 +34,11 @@ services:
     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:
@@ -41,6 +51,11 @@ services:
         secret:
           name: secret-name
           key: secret-key
+    probe:
+      port: 8000
+      path: /.ready
+      delay: 1
+
 proxies:
   - name: storage-proxy
     target: host.docker.internal

package/src/deployment/composition.js

@@ -10,6 +10,7 @@ class Composition {
     this.name = composition.name
     this.image = image.reference
     this.components = composition.components.map(component)
+    this.resources = composition.resources
   }
 }
 

package/src/deployment/deployment.js

@@ -42,6 +42,7 @@ class Deployment {
 
     if (options.namespace !== undefined) args.push('-n', options.namespace)
     if (options.wait === true) args.push('--wait')
+    if (options.timeout !== undefined) args.push('--timeout', options.timeout)
 
     await this.#process.execute('helm', ['dependency', 'update', this.#target])
     await this.#process.execute('helm', ['upgrade', this.#chart.name, '-i', ...args, this.#target])

package/src/deployment/factory.js

@@ -15,7 +15,6 @@ class Factory {
   #dependencies
   #registry
   #process
-  #extensionComponents = []
 
   constructor (context) {
     this.#context = context
@@ -23,7 +22,7 @@ class Factory {
 
     const imagesFactory = new ImagesFactory(context.name, context.runtime, context.registry)
 
-    this.#registry = new Registry(context.registry, imagesFactory, this.#process)
+    this.#registry = new Registry(context.name, context.registry, imagesFactory, this.#process)
     this.#compositions = context.compositions.map((composition) => this.#composition(composition))
     this.#dependencies = this.#getDependencies()
   }

package/src/deployment/images/composition.Dockerfile

@@ -5,7 +5,6 @@ FROM {{build.image}}
 ENV NODE_ENV=production
 RUN if [ "{{runtime.registry}}" != "" ]; then npm set registry {{runtime.registry}}; fi
 RUN if [ "{{runtime.proxy}}" != "" ]; then npm set proxy {{runtime.proxy}}; fi
-RUN npm i -g @toa.io/runtime@{{runtime.version}} --omit=dev
 
 WORKDIR /composition
 COPY --chown=node:node . /composition
@@ -13,7 +12,8 @@ COPY --chown=node:node . /composition
 {{build.run}}
 
 # run 'npm i' in each component
-RUN for entry in *; do if [ -f "$entry/package.json" ]; then (cd $entry && npm i --omit=dev); fi; done
+RUN --mount=type=cache,target=/root/.npm \
+  for entry in *; do if [ -f "$entry/package.json" ]; then (cd $entry && npm i --omit=dev); fi; done
 
 USER node
 CMD toa compose *

package/src/deployment/images/composition.js

@@ -5,6 +5,7 @@ const fs = require('fs-extra')
 const { createHash } = require('node:crypto')
 
 const { Image } = require('./image')
+const { undef } = require('@toa.io/concise/source/expressions/undefined')
 
 class Composition extends Image {
   dockerfile = join(__dirname, 'composition.Dockerfile')
@@ -37,11 +38,7 @@ class Composition extends Image {
   }
 
   get base () {
-    if (this.#image !== undefined) {
-      return this.#image
-    }
-
-    let image = null
+    let image = this.#image
 
     for (const component of this.#components) {
       const value = component.build?.image
@@ -53,7 +50,20 @@ class Composition extends Image {
       image = value
     }
 
-    return image ?? undefined
+    return image
+  }
+
+  get run () {
+    const commands = []
+
+    for (const component of this.#components) {
+      const run = component.build?.run
+
+      if (run !== undefined)
+        commands.push(run)
+    }
+
+    return commands.join('\n')
   }
 
   async prepare (root) {

package/src/deployment/images/factory.js

@@ -3,9 +3,6 @@
 const { Composition } = require('./composition')
 const { Service } = require('./service')
 
-/**
- * @implements {toa.deployment.images.Factory}
- */
 class Factory {
   /** @type {string} */
   #scope

package/src/deployment/images/image.js

@@ -26,9 +26,7 @@ class Image {
   #registry
   #runtime
   #values = {
-    build: {
-      image: 'node:20.9.0-alpine3.18'
-    }
+    build: {}
   }
 
   constructor (scope, runtime, registry) {
@@ -54,6 +52,8 @@ class Image {
 
   get base () {}
 
+  get run () {}
+
   async prepare (root) {
     if (this.dockerfile === undefined) throw new Error('Dockerfile isn\'t specified')
 
@@ -65,7 +65,7 @@ class Image {
 
     const template = await read(this.dockerfile, 'utf-8')
     const contents = template.replace(/{{(\S{1,32})}}/g, (_, key) => this.#value(key))
-    const ignore = 'Dockerfile'
+    const ignore = ['Dockerfile', '**/node_modules'].join('\r\n')
 
     await write(join(path, 'Dockerfile'), contents)
     await write(join(path, '.dockerignore'), ignore)
@@ -77,13 +77,19 @@ class Image {
 
   #setValues () {
     this.#values.runtime = this.#runtime
-    this.#values.build = overwrite(this.#values.build, this.#registry.build)
+    this.#values.build = overwrite({
+      image: `${RUNTIME_IMAGE}:${this.#runtime.version}`
+    }, this.#registry.build)
 
     const image = this.base
 
-    if (image !== undefined) {
+    if (image !== undefined)
       this.#values.build.image = image
-    }
+
+    const run = this.run
+
+    if (run !== undefined)
+      this.#values.build.run = (this.#values.build.run === undefined ? '' : this.#values.build.run + '\n') + run
 
     if (this.#values.build.arguments !== undefined) this.#values.build.arguments = createArguments(this.#values.build.arguments)
     if (this.#values.build.run !== undefined) this.#values.build.run = createRunCommands(this.#values.build.run)
@@ -121,4 +127,7 @@ function createArguments (variables) {
   return args.join('\n')
 }
 
+const RUNTIME_IMAGE = 'ghcr.io/toa-io/runtime'
+
 exports.Image = Image
+exports.RUNTIME_IMAGE = RUNTIME_IMAGE

package/src/deployment/images/runtime-base.test.js

@@ -0,0 +1,90 @@
+'use strict'
+
+const { join } = require('node:path')
+const { readFile } = require('node:fs/promises')
+const { directory } = require('@toa.io/filesystem')
+
+const { Image, RUNTIME_IMAGE } = require('./image')
+
+const compositionDockerfile = join(__dirname, 'composition.Dockerfile')
+const serviceDockerfile = join(__dirname, 'service.Dockerfile')
+
+class TestImage extends Image {
+  dockerfile
+
+  #name
+  #base
+
+  constructor (runtime, registry, dockerfile, name = 'test', base) {
+    super('acme', runtime, registry)
+
+    this.dockerfile = dockerfile
+    this.#name = name
+    this.#base = base
+  }
+
+  get name () {
+    return this.#name
+  }
+
+  get version () {
+    return 'abcdef12'
+  }
+
+  get base () {
+    return this.#base
+  }
+}
+
+describe('runtime base image', () => {
+  /** @type {string} */
+  let root
+
+  beforeEach(async () => {
+    root = await directory.temp('toa-runtime-base-test')
+  })
+
+  it('should default build.image to version-pinned GHCR runtime image', async () => {
+    const runtime = { version: '1.0.0-alpha.232' }
+    const image = new TestImage(runtime, {}, compositionDockerfile)
+
+    const path = await image.prepare(root)
+    const dockerfile = await readFile(join(path, 'Dockerfile'), 'utf8')
+
+    expect(dockerfile).toContain(`FROM ${RUNTIME_IMAGE}:1.0.0-alpha.232`)
+    expect(dockerfile).not.toMatch(/npm i -g @toa\.io\/runtime/)
+  })
+
+  it('should not install runtime in service Dockerfile template', async () => {
+    const runtime = { version: '1.0.0-alpha.99' }
+    const image = new TestImage(runtime, {}, serviceDockerfile, 'service-test')
+
+    const path = await image.prepare(root)
+    const dockerfile = await readFile(join(path, 'Dockerfile'), 'utf8')
+
+    expect(dockerfile).toContain(`FROM ${RUNTIME_IMAGE}:1.0.0-alpha.99`)
+    expect(dockerfile).not.toMatch(/npm i -g @toa\.io\/runtime/)
+  })
+
+  it('should allow registry.build.image override', async () => {
+    const runtime = { version: '1.0.0-alpha.232' }
+    const registry = { build: { image: 'node:24.14.0-alpine3.22' } }
+    const image = new TestImage(runtime, registry, compositionDockerfile)
+
+    const path = await image.prepare(root)
+    const dockerfile = await readFile(join(path, 'Dockerfile'), 'utf8')
+
+    expect(dockerfile).toContain('FROM node:24.14.0-alpine3.22')
+    expect(dockerfile).not.toContain(RUNTIME_IMAGE)
+  })
+
+  it('should allow composition.image override via base', async () => {
+    const runtime = { version: '1.0.0-alpha.232' }
+    const image = new TestImage(runtime, {}, compositionDockerfile, 'mono', 'custom.example/base:1')
+
+    const path = await image.prepare(root)
+    const dockerfile = await readFile(join(path, 'Dockerfile'), 'utf8')
+
+    expect(dockerfile).toContain('FROM custom.example/base:1')
+  })
+})

package/src/deployment/images/service.Dockerfile

@@ -1,14 +1,14 @@
-FROM node:20.9.0-alpine3.18
+FROM {{build.image}}
 
 ENV NODE_ENV=production
 RUN if [ "{{runtime.registry}}" != "" ]; then npm set registry {{runtime.registry}}; fi
 RUN if [ "{{runtime.proxy}}" != "" ]; then npm set proxy {{runtime.proxy}}; fi
-RUN npm i -g @toa.io/runtime@{{runtime.version}} --omit=dev
 
 WORKDIR /service
 COPY --chown=node:node . /service
 
-RUN npm i --omit=dev
+RUN --mount=type=cache,target=/root/.npm \
+  npm i --omit=dev
 
 USER node
 CMD toa serve .

package/src/deployment/operator.js

@@ -50,6 +50,10 @@ class Operator {
   variables () {
     return this.#deployment.variables()
   }
+
+  tags () {
+    return this.#registry.tags()
+  }
 }
 
 /** @type {toa.deployment.installation.Options} */

package/src/deployment/registry.js

@@ -1,12 +1,14 @@
 'use strict'
 
+const { posix } = require('node:path')
 const workspace = require('./workspace')
-const { newid } = require('@toa.io/generic')
 
 /**
  * @implements {toa.deployment.Registry}
  */
 class Registry {
+  #scope
+
   #registry
 
   #factory
@@ -15,7 +17,11 @@ class Registry {
 
   #images = []
 
-  constructor (registry, factory, process) {
+  /** @type {string | undefined} */
+  #builder
+
+  constructor (scope, registry, factory, process) {
+    this.#scope = scope
     this.#registry = registry
     this.#factory = factory
     this.#process = process
@@ -40,9 +46,8 @@ class Registry {
   async build () {
     await this.prepare()
 
-    for (const image of this.#images) {
+    for (const image of this.#images)
       await this.#build(image)
-    }
   }
 
   async push () {
@@ -51,6 +56,10 @@ class Registry {
     for (const image of this.#images) await this.#push(image)
   }
 
+  tags () {
+    return this.#images.map((image) => image.reference)
+  }
+
   /**
    * @param {'composition' | 'service'} type
    * @param {...any} args
@@ -70,13 +79,17 @@ class Registry {
    * @returns {Promise<void>}
    */
   async #build (image, push = false) {
+    if (await this.exists(image.reference)) {
+      console.log('Image already exists, skipping:', image.reference)
+      return
+    }
+
     const args = ['--context=default', 'buildx', 'build']
 
-    if (push) {
+    if (push)
       args.push('--push')
-    } else {
+    else
       args.push('--load')
-    }
 
     args.push('--tag', image.reference, image.context)
 
@@ -88,14 +101,15 @@ class Registry {
 
     if (multiarch) {
       const platform = this.#registry.platforms.join(',')
-      const builder = await this.#createBuilder()
+      const builder = await this.#ensureBuilder()
 
       args.push('--platform', platform)
       args.push('--builder', builder)
 
-    } else {
+      if (this.#registry.base !== undefined)
+        this.#appendCache(args)
+    } else
       args.push('--builder', 'default')
-    }
 
     args.push('--progress', 'plain')
 
@@ -106,13 +120,43 @@ class Registry {
     await this.#build(image, true)
   }
 
-  async #createBuilder () {
-    const name = `toa-${newid()}`
-    const create = `buildx create --name ${name} --bootstrap --use`.split(' ')
+  async exists (tag) {
+    const args = ['manifest', 'inspect', tag]
+
+    try {
+      await this.#process.execute('docker', args, { silently: true })
+    } catch (error) {
+      console.log(error.message)
+
+      return false
+    }
+
+    return true
+  }
+
+  async #ensureBuilder () {
+    if (this.#builder !== undefined)
+      return this.#builder
+
+    try {
+      await this.#process.execute('docker', ['buildx', 'inspect', BUILDER], { silently: true })
+    } catch {
+      await this.#process.execute('docker', ['buildx', 'create', '--name', BUILDER, '--bootstrap'])
+    }
 
-    await this.#process.execute('docker', create)
+    this.#builder = BUILDER
+
+    return BUILDER
+  }
+
+  /**
+   * @param {string[]} args
+   */
+  #appendCache (args) {
+    const ref = posix.join(this.#registry.base, this.#scope, 'buildcache')
 
-    return name
+    args.push('--cache-from', `type=registry,ref=${ref}`)
+    args.push('--cache-to', `type=registry,ref=${ref},mode=max,image-manifest=true`)
   }
 }
 

package/src/deployment/registry.test.js

@@ -0,0 +1,175 @@
+'use strict'
+
+const { Registry } = require('./registry')
+
+/** @type {toa.operations.Process} */
+let process
+
+/** @type {toa.deployment.images.Factory} */
+let factory
+
+/** @type {toa.deployment.images.Image[]} */
+let images
+
+beforeEach(() => {
+  images = []
+  process = /** @type {toa.operations.Process} */ {
+    execute: jest.fn(async (cmd, args) => {
+      if (args[0] === 'manifest')
+        throw new Error('manifest unknown')
+
+      if (args[0] === 'buildx' && args[1] === 'inspect')
+        throw new Error('builder not found')
+
+      return ''
+    })
+  }
+
+  factory = /** @type {toa.deployment.images.Factory} */ {
+    composition: () => createImage('composition-mono'),
+    service: () => createImage('extension-realtime')
+  }
+})
+
+it('should reuse named builder across images', async () => {
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+  registry.service('.', /** @type {any} */ ({}))
+
+  await registry.build()
+
+  const creates = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === 'buildx' && args[1] === 'create')
+
+  expect(creates).toHaveLength(1)
+  expect(creates[0][1]).toEqual(['buildx', 'create', '--name', 'toa', '--bootstrap'])
+
+  const builds = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === '--context=default' && args[1] === 'buildx' && args[2] === 'build')
+
+  expect(builds).toHaveLength(2)
+
+  for (const [, args] of builds) {
+    expect(args).toContain('--builder')
+    expect(args[args.indexOf('--builder') + 1]).toBe('toa')
+  }
+})
+
+it('should not create builder when it already exists', async () => {
+  process.execute = jest.fn(async (cmd, args) => {
+    if (args[0] === 'manifest')
+      throw new Error('manifest unknown')
+
+    return ''
+  })
+
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.build()
+
+  const creates = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === 'buildx' && args[1] === 'create')
+
+  expect(creates).toHaveLength(0)
+})
+
+it('should add shared registry cache flags when base is set', async () => {
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+  registry.service('.', /** @type {any} */ ({}))
+
+  await registry.build()
+
+  const builds = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === '--context=default' && args[2] === 'build')
+
+  expect(builds).toHaveLength(2)
+
+  for (const [, args] of builds) {
+    expect(args).toContain('--cache-from')
+    expect(args).toContain('type=registry,ref=example.com/reg/acme/buildcache')
+    expect(args).toContain('--cache-to')
+    expect(args).toContain('type=registry,ref=example.com/reg/acme/buildcache,mode=max,image-manifest=true')
+  }
+})
+
+it('should omit cache flags when base is not set', async () => {
+  const registry = createRegistry({ platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.build()
+
+  const builds = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === '--context=default' && args[2] === 'build')
+
+  expect(builds).toHaveLength(1)
+
+  const [, args] = builds[0]
+
+  expect(args).not.toContain('--cache-from')
+  expect(args).not.toContain('--cache-to')
+})
+
+it('should use default builder when platforms is null', async () => {
+  const registry = createRegistry({ base: 'example.com/reg', platforms: null })
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.build()
+
+  const builds = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === '--context=default' && args[2] === 'build')
+
+  expect(builds).toHaveLength(1)
+
+  const [, args] = builds[0]
+
+  expect(args[args.indexOf('--builder') + 1]).toBe('default')
+  expect(args).not.toContain('--cache-from')
+  expect(args).not.toContain('--platform')
+})
+
+it('should skip build when image already exists', async () => {
+  process.execute = jest.fn(async () => '')
+
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.build()
+
+  const builds = process.execute.mock.calls.filter(([, args]) =>
+    args[0] === '--context=default' && args[2] === 'build')
+
+  expect(builds).toHaveLength(0)
+  expect(process.execute).toHaveBeenCalledWith('docker', ['manifest', 'inspect', images[0].reference], { silently: true })
+})
+
+/**
+ * @param {object} [registry]
+ * @returns {Registry}
+ */
+function createRegistry (registry = {}) {
+  return new Registry('acme', registry, factory, process)
+}
+
+/**
+ * @param {string} name
+ * @returns {toa.deployment.images.Image}
+ */
+function createImage (name) {
+  const image = /** @type {toa.deployment.images.Image} */ {
+    reference: `example.com/reg/acme/${name}:abcdef12`,
+    context: `/tmp/${name}`,
+    prepare: jest.fn(async () => `/tmp/${name}`)
+  }
+
+  images.push(image)
+
+  return image
+}

package/types/_deployment/images/image.d.ts

@@ -4,9 +4,11 @@ declare namespace toa.deployment.images {
     readonly reference: string
     readonly context: string
 
-    tag(): void
+    name: string
 
-    prepare(root: string): Promise<string>
+    tag (): void
+
+    prepare (root: string): Promise<string>
   }
 
 }

package/types/_deployment/registry.d.ts

@@ -1,19 +1,21 @@
 import type * as _norm from '@toa.io/norm/types'
 import type * as _dependency from './dependency'
-import type * as _image from "./images/image"
+import type * as _image from './images/image'
 
 declare namespace toa.deployment {
-  
+
   interface Registry {
-    composition(composition: _norm.Composition): _image.Image
+    composition (composition: _norm.Composition): _image.Image
+
+    service (path: string, service: _dependency.Service): _image.Image
 
-    service(path: string, service: _dependency.Service): _image.Image
+    prepare (path: string): Promise<string>
 
-    prepare(path: string): Promise<string>
+    build (): Promise<void>
 
-    build(): Promise<void>
+    push (): Promise<void>
 
-    push(): Promise<void>
+    tags (): string[]
   }
 
 }

package/types/dependency.ts

@@ -0,0 +1,67 @@
+import type { Manifest } from '@toa.io/norm'
+import type { Locator } from '@toa.io/core'
+
+export interface Service {
+  group: string
+  name: string
+  version: string
+  port?: number
+  ingress?: Ingress
+  resources?: Resources
+  variables?: Variable[]
+  components?: string[]
+  probe?: Probe | false
+}
+
+export interface Variable {
+  name: string
+  value?: string
+  secret?: {
+    name: string
+    key: string
+    optional?: boolean
+  }
+}
+
+export interface Instance<T> {
+  locator: Locator
+  manifest: T
+  component: Manifest
+}
+
+export type Instances<T> = Array<Instance<T>>
+
+export type Variables = Record<'global' | string, Variable[]>
+export type Mounts = Record<'global' | string, Mount[]>
+
+export interface Dependency {
+  services?: Service[]
+  variables?: Variables
+  mounts?: Mounts
+  /** Default probe for compositions and services without their own probe. `false` disables. */
+  probe?: Probe | false
+}
+
+interface Ingress {
+  default?: boolean
+  hosts?: string[]
+  class?: string
+  annotations?: object
+}
+
+export interface Probe {
+  port: number
+  path: string
+  delay?: number
+}
+
+interface Mount {
+  name: string
+  path: string
+  claim: string
+}
+
+export interface Resources {
+  cpu: string[]
+  memory: string[]
+}

package/types/dependency.d.ts

@@ -1,32 +0,0 @@
-export type Service = {
-  group: string
-  name: string
-  version: string
-  port: number
-  ingress: Ingress
-  variables: Variable[]
-  components?: string[]
-}
-
-export type Variable = {
-  name: string
-  value?: string
-  secret?: {
-    name: string,
-    key: string
-    optional?: boolean
-  }
-}
-
-export type Variables = Record<'global' | string, Variable[]>
-
-export type Dependency = {
-  services?: Service[]
-  variables?: Variables
-}
-
-type Ingress = {
-  hosts: string[]
-  class?: string
-  annotations?: object
-}