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

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

@@ -0,0 +1,195 @@
+{{- if .Values.mono }}
+{{- with .Values.mono }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mono
+spec:
+  replicas: {{ .replicas | default 2 }}
+  progressDeadlineSeconds: 900
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 0
+      maxSurge: 100%
+  selector:
+    matchLabels:
+      toa/composition: mono
+  template:
+    metadata:
+      labels:
+        toa/composition: mono
+        {{- range .components }}
+        toa/component-{{ . }}: "1"
+        {{- end }}
+    spec:
+      containers:
+        - name: mono
+          image: {{ .image }}
+          {{- if or .backends .probe }}
+          ports:
+            {{- range .backends }}
+            - containerPort: {{ .port }}
+            {{- end }}
+            {{- if .probe }}
+            - containerPort: {{ .probe.port }}
+            {{- end }}
+          {{- end }}
+          {{- 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 }}
+            # 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: mono
+          # only this revision's pods: a rollout spreads the new ones, whatever the old ones occupy
+          matchLabelKeys:
+            - pod-template-hash
+{{- if .backends }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mono
+  {{- if .annotations }}
+  annotations:
+{{ toYaml .annotations | indent 4 }}
+  {{- end }}
+spec:
+  type: ClusterIP
+  selector:
+    toa/composition: mono
+  ports:
+    {{- range .backends }}
+    - name: port-{{ .port }}
+      protocol: TCP
+      port: {{ .port }}
+      targetPort: {{ .port }}
+    {{- end }}
+{{- end }}
+{{- if .ingress }}
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: mono
+  {{- if .ingress.annotations }}
+  annotations:
+{{ toYaml .ingress.annotations | indent 4 }}
+  {{- end }}
+spec:
+  {{- if .ingress.class }}
+  ingressClassName: {{ .ingress.class }}
+  {{- end }}
+  {{- $backends := .backends }}
+  rules:
+    {{- range .ingress.hosts }}
+    - host: {{ . }}
+      http:
+        paths:
+          {{- range $backends }}
+          - path: {{ .path }}
+            pathType: Prefix
+            backend:
+              service:
+                name: mono
+                port:
+                  number: {{ .port }}
+          {{- end }}
+    {{- end }}
+    {{- if .ingress.default }}
+    - http:
+        paths:
+          {{- range $backends }}
+          - path: {{ .path }}
+            pathType: Prefix
+            backend:
+              service:
+                name: mono
+                port:
+                  number: {{ .port }}
+          {{- end }}
+    {{- end }}
+{{- end }}
+---
+{{- end }}
+{{- end }}

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

@@ -1,21 +1,52 @@
 {{- range .Values.services }}
+{{- if not .workload }}
 apiVersion: apps/v1
 kind: Deployment
 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, and every
+      # replacement starts at once: the rollout takes one start-up, not one per replica
+      maxUnavailable: 0
+      maxSurge: 100%
   selector:
     matchLabels:
-      toa.io/service: extension-{{ .name }}
+      toa/service: extension-{{ .name }}
   template:
     metadata:
       labels:
-        toa.io/service: extension-{{ .name }}
+        toa/service: extension-{{ .name }}
+        toa/service-{{ .name }}: "1"
     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 }}
@@ -23,31 +54,78 @@ spec:
             {{- end }}
           {{- end }}
           {{- if .probe }}
-          readinessProbe:
+          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 $.Values.map }}
+          volumeMounts:
+            - name: components
+              mountPath: {{ $.Values.map.directory }}
+              readOnly: true
           {{- end }}
+          lifecycle:
+            preStop:
+              exec:
+                command: [sleep, "5"]
+      {{- if $.Values.map }}
+      volumes:
+        - name: components
+          configMap:
+            name: components
+      {{- end }}
+      terminationGracePeriodSeconds: 45
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: ScheduleAnyway
+          labelSelector:
+            matchLabels:
+              toa/service: extension-{{ .name }}
+          # only this revision's pods: a rollout spreads the new ones, whatever the old ones occupy
+          matchLabelKeys:
+            - pod-template-hash
+{{- end }}
+{{- if .port }}
 ---
 apiVersion: v1
 kind: Service
 metadata:
   name: extension-{{ .name }}
+  {{- if .annotations }}
+  annotations:
+{{ toYaml .annotations | indent 4 }}
+  {{- end }}
 spec:
   type: ClusterIP
   selector:
-    toa.io/service: extension-{{ .name }}
+    toa/service-{{ .name }}: "1"
   ports:
     - name: port-{{ .port }}
       protocol: TCP
       port: {{ .port }}
       targetPort: {{ .port }}
----
+{{- end }}
 {{- if .ingress }}
 {{- $service := .name }}
+{{- $port := .port }}
+{{- $path := .ingress.path | default "/" }}
+---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
@@ -65,13 +143,25 @@ spec:
     - host: {{ . }}
       http:
         paths:
-          - path: /
+          - path: {{ $path }}
             pathType: Prefix
             backend:
               service:
                 name: extension-{{ $service }}
                 port:
-                  number: 8000
+                  number: {{ $port }}
+    {{- end }}
+    {{- if .ingress.default }}
+    - http:
+        paths:
+          - path: {{ $path }}
+            pathType: Prefix
+            backend:
+              service:
+                name: extension-{{ $service }}
+                port:
+                  number: {{ $port }}
     {{- 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,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,228 @@
-'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')
+    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 })
+}