@heynixie/pulumi-k8s 0.0.0-stage → 0.42.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@heynixie/pulumi-k8s</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@heynixie/pulumi-k8s"><img src="https://img.shields.io/npm/v/@heynixie/pulumi-k8s" alt="npm version"></a>
+    <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/architecture/deployment/kubernetes.md#the-pulumi-component">Kubernetes</a> •
+    <a href="../../docs/architecture/deployment/release-pipeline.md">Release pipeline</a>
+  </p>
+</div>
+
+A Pulumi component that runs nixie on Kubernetes.
+
+The component registers nixie's StatefulSet, the web client and the backup job in one namespace, in
+the shape each nixie release ships. Each release of nixie publishes the component at its own
+version, so a deployment takes a change to that shape with a version bump. To start, install the
+package beside your Pulumi SDKs, call `createNixie` with your namespace and images, and point your
+ingress at the two Services it returns.
+
+## Install
+
+The package ships an ES module with its type declarations, so a Pulumi program on Node or on Bun
+loads it. It takes `@pulumi/pulumi` 3 and `@pulumi/kubernetes` 4 as peer dependencies, which your
+program installs.
+
+```bash
+bun add @heynixie/pulumi-k8s
+```
+
+## Features
+
+- **nixie's pod.** One replica on a `ReadWriteOnce` claim, with the configuration, the encrypted
+  secrets and a git-sync container that follows your definitions repo on GitHub.
+- **The web client.** A Deployment that rolls out after nixie and calls its API by the Service.
+- **The backup.** A CronJob that runs your backup script on nixie's volume, on your schedule.
+- **Moving onto it.** Each resource keeps its own Pulumi name and an alias to the stack, so a stack
+  that declared the same resources itself moves onto the component with no replacement.
+
+## Configuration
+
+`createNixie(name, args, opts)` takes the per-deployment values in `args`, and their types in
+[`src/types.ts`](src/types.ts) describe each one. Pass your Kubernetes provider in `opts`.
+
+```ts
+import { createNixie, nixieAPIPort, nixieWebPort } from '@heynixie/pulumi-k8s';
+
+const nixie = createNixie(
+  'nixie',
+  {
+    namespace: 'assistant',
+    image: 'ghcr.io/zgeoff/nixie:<version>@sha256:<digest>',
+    web: { image: 'ghcr.io/zgeoff/nixie-web:<version>@sha256:<digest>' },
+    config: configText,
+    secretsFile: sopsFileText,
+    ageKey: ageKeySecret,
+    definitions: { repository: '<owner>/<repo>', ref: 'live', deployKey: deployKeySecret },
+    storageClassName: 'local-path',
+  },
+  { provider: cluster },
+);
+```
+
+## Documentation
+
+The [Kubernetes architecture](../../docs/architecture/deployment/kubernetes.md) covers the shape.

package/dist/build-backup-pod-spec.d.ts

@@ -0,0 +1,10 @@
+import type { types } from '@pulumi/kubernetes';
+import type { Input } from '@pulumi/pulumi';
+export interface BackupPodInputs {
+    readonly image: Input<string>;
+    readonly claim: string;
+    readonly scriptConfigMap: string;
+    readonly envSecret: string;
+    readonly pullSecret: Input<string>;
+}
+export declare function buildBackupPodSpec(inputs: BackupPodInputs): types.input.core.v1.PodSpec;

package/dist/build-nixie-spec.d.ts

@@ -0,0 +1,22 @@
+import type { types } from '@pulumi/kubernetes';
+import type { Input } from '@pulumi/pulumi';
+export declare const nixieLabels: {
+    app: string;
+};
+export interface NixieSpecInputs {
+    readonly image: Input<string>;
+    readonly serviceName: Input<string>;
+    readonly configMap: Input<string>;
+    readonly secret: Input<string>;
+    readonly definitionsSecret: Input<string>;
+    readonly definitionsRepository: string;
+    readonly definitionsRef: Input<string>;
+    readonly storageClassName: Input<string>;
+}
+export declare function buildNixieSpec(inputs: NixieSpecInputs): types.input.apps.v1.StatefulSetSpec;
+export declare const nixieAPIPort = 8080;
+export declare const nixieSecretsFileKey = "secrets.yaml";
+export declare const nixieAgeKeyKey = "age-key.txt";
+export declare const nixieConfigKey = "config.yaml";
+export declare const definitionsDeployKeyKey = "ssh";
+export declare const definitionsKnownHostsKey = "known_hosts";

package/dist/build-nixie-web-spec.d.ts

@@ -0,0 +1,11 @@
+import type { types } from '@pulumi/kubernetes';
+import type { Input } from '@pulumi/pulumi';
+export declare const nixieWebLabels: {
+    app: string;
+};
+export declare const nixieWebPort = 3000;
+export interface NixieWebSpecInputs {
+    readonly image: Input<string>;
+    readonly apiURL: Input<string>;
+}
+export declare function buildNixieWebSpec(inputs: NixieWebSpecInputs): types.input.apps.v1.DeploymentSpec;

package/dist/build-service-args.d.ts

@@ -0,0 +1,9 @@
+import type { core } from '@pulumi/kubernetes';
+import type { Input } from '@pulumi/pulumi';
+export interface ServiceShape {
+    readonly name: string;
+    readonly namespace: Input<string>;
+    readonly labels: Record<string, string>;
+    readonly port: number;
+}
+export declare function buildServiceArgs(shape: ServiceShape): core.v1.ServiceArgs;

package/dist/create-nixie.d.ts

@@ -0,0 +1,11 @@
+import { apps, core } from '@pulumi/kubernetes';
+import type { ComponentResourceOptions } from '@pulumi/pulumi';
+import { ComponentResource } from '@pulumi/pulumi';
+import type { NixieArgs } from './types.js';
+export interface Nixie {
+    readonly component: ComponentResource;
+    readonly api: core.v1.Service;
+    readonly web: core.v1.Service;
+    readonly statefulSet: apps.v1.StatefulSet;
+}
+export declare function createNixie(name: string, args: NixieArgs, opts?: ComponentResourceOptions): Nixie;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { nixieAPIPort } from './build-nixie-spec.js';
+export { nixieWebPort } from './build-nixie-web-spec.js';
+export { createNixie } from './create-nixie.js';
+export type { Nixie } from './create-nixie.js';
+export type { NixieArgs, NixieBackupArgs, NixieDefinitionsArgs, NixieWebArgs } from './types.js';

package/dist/index.js

@@ -0,0 +1,363 @@
+// src/build-nixie-spec.ts
+var nixieLabels = { app: "nixie" };
+function buildNixieSpec(inputs) {
+  return {
+    replicas: 1,
+    updateStrategy: { type: "RollingUpdate" },
+    podManagementPolicy: "Parallel",
+    serviceName: inputs.serviceName,
+    selector: { matchLabels: nixieLabels },
+    template: {
+      metadata: { labels: nixieLabels },
+      spec: {
+        terminationGracePeriodSeconds: 60,
+        securityContext: {
+          fsGroup: 10001,
+          runAsNonRoot: true,
+          seccompProfile: { type: "RuntimeDefault" }
+        },
+        volumes: [
+          { name: "config", configMap: { name: inputs.configMap } },
+          { name: "secrets", secret: { secretName: inputs.secret, defaultMode: 288 } },
+          {
+            name: "definitions-key",
+            secret: { secretName: inputs.definitionsSecret, defaultMode: 288 }
+          },
+          { name: "definitions", emptyDir: {} },
+          { name: "tmp", emptyDir: {} },
+          { name: "git-sync-tmp", emptyDir: {} }
+        ],
+        containers: [
+          buildNixieContainer(inputs.image),
+          buildGitSyncContainer(inputs.definitionsRepository, inputs.definitionsRef)
+        ]
+      }
+    },
+    volumeClaimTemplates: [
+      {
+        metadata: { name: "data" },
+        spec: {
+          accessModes: ["ReadWriteOnce"],
+          storageClassName: inputs.storageClassName,
+          resources: { requests: { storage: "10Gi" } }
+        }
+      }
+    ]
+  };
+}
+var lockedDown = {
+  allowPrivilegeEscalation: false,
+  readOnlyRootFilesystem: true,
+  capabilities: { drop: ["ALL"] }
+};
+var nixieAPIPort = 8080;
+var nixieSecretsFileKey = "secrets.yaml";
+var nixieAgeKeyKey = "age-key.txt";
+var nixieConfigKey = "config.yaml";
+var definitionsRoot = "/etc/nixie/definitions";
+function buildNixieContainer(image) {
+  return {
+    name: "nixie",
+    image,
+    ports: [{ name: "http", containerPort: nixieAPIPort }],
+    env: [{ name: "SOPS_AGE_KEY_FILE", value: `/etc/nixie/age/${nixieAgeKeyKey}` }],
+    startupProbe: {
+      httpGet: { path: "/health/live", port: nixieAPIPort },
+      periodSeconds: 5,
+      failureThreshold: 60
+    },
+    livenessProbe: {
+      httpGet: { path: "/health/live", port: nixieAPIPort },
+      periodSeconds: 30,
+      failureThreshold: 3
+    },
+    readinessProbe: {
+      httpGet: { path: "/health/ready", port: nixieAPIPort },
+      periodSeconds: 10,
+      timeoutSeconds: 5,
+      failureThreshold: 3
+    },
+    volumeMounts: [
+      { name: "data", mountPath: "/data" },
+      {
+        name: "config",
+        mountPath: `/etc/nixie/${nixieConfigKey}`,
+        subPath: nixieConfigKey,
+        readOnly: true
+      },
+      {
+        name: "secrets",
+        mountPath: `/etc/nixie/${nixieSecretsFileKey}`,
+        subPath: nixieSecretsFileKey,
+        readOnly: true
+      },
+      {
+        name: "secrets",
+        mountPath: `/etc/nixie/age/${nixieAgeKeyKey}`,
+        subPath: nixieAgeKeyKey,
+        readOnly: true
+      },
+      { name: "definitions", mountPath: definitionsRoot, readOnly: true },
+      { name: "tmp", mountPath: "/tmp" }
+    ],
+    securityContext: { ...lockedDown, runAsUser: 10001, runAsGroup: 10001 },
+    resources: { requests: { cpu: "100m", memory: "256Mi" }, limits: { memory: "1Gi" } }
+  };
+}
+var definitionsDeployKeyKey = "ssh";
+var definitionsKnownHostsKey = "known_hosts";
+var gitSyncImage = "registry.k8s.io/git-sync/git-sync:v4.7.1@sha256:c5e1976da735bf0b53979f079a07475d77174c51863cd084e928ff6074480717";
+function buildGitSyncContainer(repository, ref) {
+  return {
+    name: "git-sync",
+    image: gitSyncImage,
+    env: [
+      { name: "GITSYNC_REPO", value: `ssh://git@ssh.github.com:443/${repository}.git` },
+      { name: "GITSYNC_REF", value: ref },
+      { name: "GITSYNC_ROOT", value: definitionsRoot },
+      { name: "GITSYNC_LINK", value: "current" },
+      { name: "GITSYNC_PERIOD", value: "60s" },
+      { name: "GITSYNC_DEPTH", value: "1" },
+      { name: "GITSYNC_SSH_KEY_FILE", value: `/etc/git-secret/${definitionsDeployKeyKey}` },
+      { name: "GITSYNC_SSH_KNOWN_HOSTS", value: "true" },
+      {
+        name: "GITSYNC_SSH_KNOWN_HOSTS_FILE",
+        value: `/etc/git-secret/${definitionsKnownHostsKey}`
+      }
+    ],
+    volumeMounts: [
+      { name: "definitions", mountPath: definitionsRoot },
+      { name: "definitions-key", mountPath: "/etc/git-secret", readOnly: true },
+      { name: "git-sync-tmp", mountPath: "/tmp" }
+    ],
+    securityContext: { ...lockedDown, runAsUser: 65533, runAsGroup: 65533 },
+    resources: { requests: { cpu: "10m", memory: "32Mi" }, limits: { memory: "128Mi" } }
+  };
+}
+// src/build-nixie-web-spec.ts
+var nixieWebLabels = { app: "nixie-web" };
+var nixieWebPort = 3000;
+function buildNixieWebSpec(inputs) {
+  return {
+    replicas: 1,
+    selector: { matchLabels: nixieWebLabels },
+    template: {
+      metadata: { labels: nixieWebLabels },
+      spec: {
+        securityContext: {
+          runAsNonRoot: true,
+          seccompProfile: { type: "RuntimeDefault" }
+        },
+        volumes: [{ name: "tmp", emptyDir: {} }],
+        containers: [
+          {
+            name: "web",
+            image: inputs.image,
+            ports: [{ name: "http", containerPort: nixieWebPort }],
+            env: [
+              { name: "NIXIE_API_URL", value: inputs.apiURL },
+              { name: "PORT", value: String(nixieWebPort) }
+            ],
+            livenessProbe: {
+              httpGet: { path: "/health/live", port: nixieWebPort },
+              periodSeconds: 30,
+              failureThreshold: 3
+            },
+            readinessProbe: {
+              httpGet: { path: "/health/ready", port: nixieWebPort },
+              periodSeconds: 10
+            },
+            volumeMounts: [{ name: "tmp", mountPath: "/tmp" }],
+            securityContext: {
+              allowPrivilegeEscalation: false,
+              readOnlyRootFilesystem: true,
+              capabilities: { drop: ["ALL"] },
+              runAsUser: 1000,
+              runAsGroup: 1000
+            },
+            resources: { requests: { cpu: "20m", memory: "96Mi" }, limits: { memory: "512Mi" } }
+          }
+        ]
+      }
+    }
+  };
+}
+// src/create-nixie.ts
+import { apps, batch, core } from "@pulumi/kubernetes";
+import { ComponentResource, interpolate, rootStackResource, secret } from "@pulumi/pulumi";
+
+// src/build-backup-pod-spec.ts
+function buildBackupPodSpec(inputs) {
+  return {
+    restartPolicy: "OnFailure",
+    securityContext: {
+      runAsNonRoot: true,
+      runAsUser: 10001,
+      runAsGroup: 10001,
+      fsGroup: 10001,
+      seccompProfile: { type: "RuntimeDefault" }
+    },
+    automountServiceAccountToken: false,
+    imagePullSecrets: [{ name: inputs.pullSecret }],
+    containers: [
+      {
+        name: "backup",
+        image: inputs.image,
+        command: ["/bin/sh", "/opt/nixie-backup/backup.sh"],
+        args: ["backup"],
+        env: [
+          { name: "STATE_DIR", value: "/state" },
+          { name: "HOME", value: "/tmp" }
+        ],
+        envFrom: [{ secretRef: { name: inputs.envSecret } }],
+        volumeMounts: [
+          { name: "state", mountPath: "/state" },
+          { name: "script", mountPath: "/opt/nixie-backup", readOnly: true },
+          { name: "tmp", mountPath: "/tmp" }
+        ],
+        resources: { requests: { cpu: "50m", memory: "64Mi" }, limits: { memory: "256Mi" } },
+        securityContext: { allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } }
+      }
+    ],
+    volumes: [
+      { name: "state", persistentVolumeClaim: { claimName: inputs.claim } },
+      { name: "script", configMap: { name: inputs.scriptConfigMap } },
+      { name: "tmp", emptyDir: {} }
+    ]
+  };
+}
+
+// src/build-service-args.ts
+function buildServiceArgs(shape) {
+  return {
+    metadata: {
+      name: shape.name,
+      namespace: shape.namespace,
+      annotations: { "pulumi.com/skipAwait": "true" }
+    },
+    spec: {
+      selector: shape.labels,
+      ports: [{ name: "http", port: shape.port, targetPort: "http" }]
+    }
+  };
+}
+
+// src/create-nixie.ts
+var rolloutTimeouts = { create: "30m", update: "30m" };
+function createNixie(name, args, opts = {}) {
+  const component = new ComponentResource("heynixie:k8s:Nixie", name, {}, opts);
+  const childOptions = {
+    parent: component,
+    aliases: [{ parent: rootStackResource }]
+  };
+  const api = new core.v1.Service("nixie", buildServiceArgs({
+    name: "nixie",
+    namespace: args.namespace,
+    labels: nixieLabels,
+    port: nixieAPIPort
+  }), childOptions);
+  const statefulSet = new apps.v1.StatefulSet("nixie", {
+    metadata: { name: "nixie", namespace: args.namespace },
+    spec: buildNixieSpec({
+      image: args.image,
+      serviceName: api.metadata.name,
+      configMap: createConfig(args, childOptions),
+      secret: createSecrets(args, childOptions),
+      definitionsSecret: createDefinitionsKey(args, childOptions),
+      definitionsRepository: args.definitions.repository,
+      definitionsRef: args.definitions.ref,
+      storageClassName: args.storageClassName
+    })
+  }, { ...childOptions, customTimeouts: rolloutTimeouts });
+  const web = new core.v1.Service("nixie-web", buildServiceArgs({
+    name: "nixie-web",
+    namespace: args.namespace,
+    labels: nixieWebLabels,
+    port: nixieWebPort
+  }), childOptions);
+  createWebDeployment(args, api, {
+    ...childOptions,
+    dependsOn: [statefulSet],
+    customTimeouts: rolloutTimeouts
+  });
+  if (args.backup !== undefined) {
+    createBackupJob(args.namespace, args.backup, statefulSet, childOptions);
+  }
+  return { component, api, web, statefulSet };
+}
+function createConfig(args, opts) {
+  const config = new core.v1.ConfigMap("nixie-config", { metadata: { namespace: args.namespace }, data: { [nixieConfigKey]: args.config } }, opts);
+  return config.metadata.name;
+}
+function createSecrets(args, opts) {
+  const secrets = new core.v1.Secret("nixie-secrets", {
+    metadata: { namespace: args.namespace },
+    stringData: {
+      [nixieSecretsFileKey]: args.secretsFile,
+      [nixieAgeKeyKey]: secret(args.ageKey)
+    }
+  }, opts);
+  return secrets.metadata.name;
+}
+var githubKnownHosts = `[ssh.github.com]:443 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
+`;
+function createDefinitionsKey(args, opts) {
+  const key = new core.v1.Secret("nixie-definitions-key", {
+    metadata: { namespace: args.namespace },
+    stringData: {
+      [definitionsDeployKeyKey]: secret(args.definitions.deployKey).apply((value) => `${value.trimEnd()}
+`),
+      [definitionsKnownHostsKey]: githubKnownHosts
+    }
+  }, opts);
+  return key.metadata.name;
+}
+function createWebDeployment(args, api, opts) {
+  return new apps.v1.Deployment("nixie-web", {
+    metadata: { name: "nixie-web", namespace: args.namespace },
+    spec: buildNixieWebSpec({
+      image: args.web.image,
+      apiURL: interpolate`http://${api.metadata.name}.${args.namespace}.svc.cluster.local:${nixieAPIPort}`
+    })
+  }, opts);
+}
+var backupScriptConfigMap = "nixie-backup-script";
+var backupEnvSecret = "nixie-backup";
+function createBackupJob(namespace, backup, statefulSet, opts) {
+  const env = new core.v1.Secret("nixie-backup", {
+    metadata: { name: backupEnvSecret, namespace },
+    stringData: backup.environment
+  }, opts);
+  const script = new core.v1.ConfigMap("nixie-backup-script", {
+    metadata: { name: backupScriptConfigMap, namespace },
+    data: { "backup.sh": backup.script }
+  }, opts);
+  return new batch.v1.CronJob("nixie-backup", {
+    metadata: { name: "nixie-backup", namespace },
+    spec: {
+      schedule: backup.schedule,
+      timeZone: backup.timeZone,
+      suspend: false,
+      concurrencyPolicy: "Forbid",
+      jobTemplate: {
+        spec: {
+          backoffLimit: 2,
+          template: {
+            spec: buildBackupPodSpec({
+              image: backup.image,
+              claim: "data-nixie-0",
+              scriptConfigMap: backupScriptConfigMap,
+              envSecret: backupEnvSecret,
+              pullSecret: backup.pullSecret
+            })
+          }
+        }
+      }
+    }
+  }, { ...opts, dependsOn: [env, script, statefulSet] });
+}
+export {
+  createNixie,
+  nixieAPIPort,
+  nixieWebPort
+};

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { Input } from '@pulumi/pulumi';
+export interface NixieArgs {
+    readonly namespace: Input<string>;
+    readonly image: Input<string>;
+    readonly config: Input<string>;
+    readonly secretsFile: Input<string>;
+    readonly ageKey: Input<string>;
+    readonly definitions: NixieDefinitionsArgs;
+    readonly storageClassName: Input<string>;
+    readonly web: NixieWebArgs;
+    readonly backup?: NixieBackupArgs;
+}
+export interface NixieWebArgs {
+    readonly image: Input<string>;
+}
+export interface NixieBackupArgs {
+    readonly image: Input<string>;
+    readonly pullSecret: Input<string>;
+    readonly script: Input<string>;
+    readonly schedule: Input<string>;
+    readonly timeZone: Input<string>;
+    readonly environment: Record<string, Input<string>>;
+}
+export interface NixieDefinitionsArgs {
+    readonly repository: string;
+    readonly ref: Input<string>;
+    readonly deployKey: Input<string>;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@heynixie/pulumi-k8s",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.42.0",
+  "description": "A Pulumi component that runs nixie on Kubernetes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/nixie.git",
+    "directory": "deploy/pulumi-k8s"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsrs --noEmit"
+  },
+  "devDependencies": {
+    "@pulumi/kubernetes": "4.34.2",
+    "@pulumi/pulumi": "3.269.0"
+  },
+  "peerDependencies": {
+    "@pulumi/kubernetes": ">=4.34.2 <5",
+    "@pulumi/pulumi": ">=3.268.0 <4"
+  }
+}