@highstate/k8s 0.7.2 → 0.7.3

package/src/deployment.ts

@@ -0,0 +1,210 @@
+import type { k8s } from "@highstate/library"
+import type { HttpRoute } from "./gateway"
+import type { Service } from "./service"
+import {
+  output,
+  type ComponentResourceOptions,
+  Output,
+  type Inputs,
+  ComponentResource,
+  type InputArray,
+  Resource,
+  type Input,
+  type InstanceTerminal,
+  interpolate,
+} from "@highstate/pulumi"
+import { apps, types } from "@pulumi/kubernetes"
+import { omit } from "remeda"
+import { deepmerge } from "deepmerge-ts"
+import { trimIndentation } from "@highstate/contract"
+import { mapMetadata, verifyProvider } from "./shared"
+import { mapContainerToRaw } from "./container"
+import {
+  getPublicWorkloadComponents,
+  publicWorkloadExtraArgs,
+  type PublicWorkloadArgs,
+} from "./workload"
+
+export type DeploymentArgs = Omit<PublicWorkloadArgs, "patch"> & {
+  patch?: Input<k8s.Deployment>
+
+  /**
+   * The shell to use in the terminal.
+   *
+   * By default, `bash` is used.
+   */
+  terminalShell?: string
+} & Omit<Partial<types.input.apps.v1.DeploymentSpec>, "template"> & {
+    template?: {
+      metadata?: types.input.meta.v1.ObjectMeta
+      spec?: Partial<types.input.core.v1.PodSpec>
+    }
+  }
+
+export abstract class Deployment extends ComponentResource {
+  protected constructor(
+    type: string,
+    name: string,
+    private readonly args: Inputs,
+    opts: ComponentResourceOptions,
+
+    /**
+     * The cluster where the deployment is created.
+     */
+    readonly cluster: Output<k8s.Cluster>,
+
+    /**
+     * The metadata of the underlying Kubernetes deployment.
+     */
+    readonly metadata: Output<types.output.meta.v1.ObjectMeta>,
+
+    /**
+     * The spec of the underlying Kubernetes deployment.
+     */
+    readonly spec: Output<types.output.apps.v1.DeploymentSpec>,
+
+    /**
+     * The status of the underlying Kubernetes deployment.
+     */
+    readonly status: Output<types.output.apps.v1.DeploymentStatus>,
+
+    private readonly _service: Output<Service | undefined>,
+    private readonly _httpRoute: Output<HttpRoute | undefined>,
+
+    /**
+     * The resources associated with the deployment.
+     */
+    readonly resources: InputArray<Resource>,
+  ) {
+    super(type, name, args, opts)
+  }
+
+  /**
+   * The Highstate deployment entity.
+   */
+  get entity(): Output<k8s.Deployment> {
+    return output({
+      type: "k8s.deployment",
+      clusterInfo: this.cluster.info,
+      metadata: this.metadata,
+      spec: this.spec,
+      service: this._service.apply(service => service?.entity),
+    })
+  }
+
+  get optionalService(): Output<Service | undefined> {
+    return this._service
+  }
+
+  /**
+   * The service associated with the deployment.
+   */
+  get service(): Output<Service> {
+    return this._service.apply(service => {
+      if (!service) {
+        throw new Error("The service is not available.")
+      }
+
+      return service
+    })
+  }
+
+  /**
+   * The HTTP route associated with the deployment.
+   */
+  get httpRoute(): Output<HttpRoute> {
+    return this._httpRoute.apply(httpRoute => {
+      if (!httpRoute) {
+        throw new Error("The HTTP route is not available.")
+      }
+
+      return httpRoute
+    })
+  }
+
+  /**
+   * The instance terminal to interact with the deployment.
+   */
+  get terminal(): Output<InstanceTerminal> {
+    return output({
+      name: this.metadata.name,
+      title: this.metadata.name,
+      image: "ghcr.io/exeteres/highstate/terminal-kubectl",
+      command: ["script", "-q", "-c", "/enter-container.sh", "/dev/null"],
+      files: {
+        "/kubeconfig": this.cluster.kubeconfig,
+
+        "/enter-container.sh": {
+          mode: 0o755,
+          content: interpolate`
+            #!/bin/bash
+
+            exec kubectl exec -it -n ${this.metadata.namespace} deployment/${this.metadata.name} -- ${this.args.terminalShell ?? "bash"}
+          `.apply(trimIndentation),
+        },
+      },
+      env: {
+        KUBECONFIG: "/kubeconfig",
+      },
+    })
+  }
+
+  static create(name: string, args: DeploymentArgs, opts: ComponentResourceOptions): Deployment {
+    return new CreatedDeployment(name, args, opts)
+  }
+}
+
+class CreatedDeployment extends Deployment {
+  constructor(name: string, args: DeploymentArgs, opts: ComponentResourceOptions) {
+    const { labels, containers, volumes, service, httpRoute } = getPublicWorkloadComponents(
+      name,
+      args,
+      () => this,
+      opts,
+    )
+
+    const deployment = output({ args, containers, volumes }).apply(
+      async ({ args, containers, volumes }) => {
+        await verifyProvider(opts.provider, args.cluster.info)
+
+        return new (args.patch ? apps.v1.DeploymentPatch : apps.v1.Deployment)(
+          name,
+          {
+            metadata: mapMetadata(args.patch?.metadata ?? args, name),
+            spec: deepmerge(
+              {
+                template: {
+                  metadata: !args.patch ? { labels } : undefined,
+                  spec: {
+                    containers: containers.map(container => mapContainerToRaw(container, name)),
+                    volumes,
+                  },
+                },
+                selector: !args.patch ? { matchLabels: labels } : undefined,
+              },
+              omit(args, publicWorkloadExtraArgs),
+            ),
+          },
+          { parent: this, ...opts },
+        )
+      },
+    )
+
+    super(
+      "highstate:k8s:Deployment",
+      name,
+      args,
+      opts,
+
+      output(args.cluster),
+      deployment.metadata,
+      deployment.spec,
+      deployment.status,
+
+      service,
+      httpRoute,
+
+      [deployment],
+    )
+  }
+}

package/src/gateway/backend.ts

@@ -0,0 +1,61 @@
+import { core } from "@pulumi/kubernetes"
+import { type Input, output, Output, type Unwrap } from "@highstate/pulumi"
+import { Service } from "../service"
+
+export interface FullBackendRef {
+  /**
+   * The name of the resource being referenced.
+   */
+  name: Input<string>
+
+  /**
+   * The namespace of the resource being referenced.
+   * May be undefined if the resource is not in a namespace.
+   */
+  namespace?: Input<string | undefined>
+
+  /**
+   * The port of the resource being referenced.
+   */
+  port: Input<number>
+}
+
+export interface ServiceBackendRef {
+  /**
+   * The name of the service being referenced.
+   */
+  service: Input<core.v1.Service>
+
+  /**
+   * The port of the service being referenced.
+   */
+  port: Input<number>
+}
+
+export type BackendRef = FullBackendRef | ServiceBackendRef | Service
+
+export function resolveBackendRef(ref: BackendRef): Output<Unwrap<FullBackendRef>> {
+  if (Service.isInstance(ref)) {
+    return output({
+      name: ref.metadata.name,
+      namespace: ref.metadata.namespace,
+      port: ref.spec.ports[0].port,
+    })
+  }
+
+  if ("service" in ref) {
+    const service = output(ref.service)
+
+    return output({
+      name: service.metadata.name,
+      namespace: service.metadata.namespace,
+      port: ref.port,
+    })
+  }
+
+  return output({
+    name: ref.name,
+    namespace: ref.namespace,
+    port: ref.port,
+  })
+}

package/src/gateway/http-route.ts

@@ -0,0 +1,139 @@
+import {
+  ComponentResource,
+  normalize,
+  output,
+  Output,
+  type ComponentResourceOptions,
+  type Input,
+  type InputArray,
+} from "@highstate/pulumi"
+import { gateway, types } from "@highstate/gateway-api"
+import { map, pipe } from "remeda"
+import { mapMetadata, type CommonArgs } from "../shared"
+import { resolveBackendRef, type BackendRef } from "./backend"
+
+export type HttpRouteArgs = Omit<CommonArgs, "namespace"> & {
+  /**
+   * The gateway to associate with the route.
+   */
+  gateway: Input<gateway.v1.Gateway>
+
+  /**
+   * The alias for `hostnames: [hostname]`.
+   */
+  hostname?: Input<string>
+
+  /**
+   * The rule of the route.
+   */
+  rule?: Input<HttpRouteRuleArgs>
+
+  /**
+   * The rules of the route.
+   */
+  rules?: InputArray<HttpRouteRuleArgs>
+} & Omit<Partial<types.input.gateway.v1.HTTPRouteSpec>, "rules">
+
+export type HttpRouteRuleArgs = Omit<
+  types.input.gateway.v1.HTTPRouteSpecRules,
+  "matches" | "filters" | "backendRefs"
+> & {
+  /**
+   * The conditions of the rule.
+   * Can be specified as string to match on the path.
+   */
+  matches?: InputArray<HttpRouteRuleMatchOptions>
+
+  /**
+   * The condition of the rule.
+   * Can be specified as string to match on the path.
+   */
+  match?: Input<HttpRouteRuleMatchOptions>
+
+  /**
+   * The filters of the rule.
+   */
+  filters?: InputArray<types.input.gateway.v1.HTTPRouteSpecRulesFilters>
+
+  /**
+   * The filter of the rule.
+   */
+  filter?: Input<types.input.gateway.v1.HTTPRouteSpecRulesFilters>
+
+  /**
+   * The service to route to.
+   */
+  backend?: Input<BackendRef>
+}
+
+export type HttpRouteRuleMatchOptions = types.input.gateway.v1.HTTPRouteSpecRulesMatches | string
+
+export class HttpRoute extends ComponentResource {
+  /**
+   * The underlying Kubernetes resource.
+   */
+  public readonly route: Output<gateway.v1.HTTPRoute>
+
+  constructor(name: string, args: HttpRouteArgs, opts?: ComponentResourceOptions) {
+    super("highstate:k8s:HttpRoute", name, args, opts)
+
+    this.route = output({
+      args,
+      gatewayNamespace: output(args.gateway).metadata.namespace,
+    }).apply(({ args, gatewayNamespace }) => {
+      return new gateway.v1.HTTPRoute(
+        name,
+        {
+          metadata: mapMetadata(
+            {
+              ...args,
+              namespace: gatewayNamespace as string,
+            },
+            name,
+          ),
+          spec: {
+            hostnames: normalize(args.hostname, args.hostnames),
+
+            parentRefs: [
+              {
+                name: args.gateway.metadata.name as Output<string>,
+              },
+            ],
+
+            rules: normalize(args.rule, args.rules).map(rule => ({
+              timeouts: rule.timeouts,
+
+              matches: pipe(
+                normalize(rule.match, rule.matches),
+                map(mapHttpRouteRuleMatch),
+                addDefaultPathMatch,
+              ),
+
+              filters: normalize(rule.filter, rule.filters),
+              backendRefs: rule.backend ? [resolveBackendRef(rule.backend)] : undefined,
+            })),
+          } satisfies types.input.gateway.v1.HTTPRouteSpec,
+        },
+        { parent: this, ...opts },
+      )
+    })
+
+    this.registerOutputs({ route: this.route })
+  }
+}
+
+function addDefaultPathMatch(
+  matches: types.input.gateway.v1.HTTPRouteSpecRulesMatches[],
+): types.input.gateway.v1.HTTPRouteSpecRulesMatches[] {
+  return matches.length ? matches : [{ path: { type: "PathPrefix", value: "/" } }]
+}
+
+export function mapHttpRouteRuleMatch(
+  match: HttpRouteRuleMatchOptions,
+): types.input.gateway.v1.HTTPRouteSpecRulesMatches {
+  if (typeof match === "string") {
+    return { path: { type: "PathPrefix", value: match } }
+  }
+
+  return match
+}

package/src/gateway/index.ts

@@ -0,0 +1,2 @@
+export * from "./backend"
+export * from "./http-route"

package/src/helm.ts

@@ -0,0 +1,298 @@
+import type { k8s } from "@highstate/library"
+import { resolve } from "node:path"
+import { mkdir, readFile, unlink } from "node:fs/promises"
+import { toPromise, type InputMap } from "@highstate/pulumi"
+import { core, helm } from "@pulumi/kubernetes"
+import {
+  ComponentResource,
+  output,
+  type ComponentResourceOptions,
+  type Input,
+  type Output,
+} from "@pulumi/pulumi"
+import spawn from "nano-spawn"
+import { sha256 } from "crypto-hash"
+import { omit } from "remeda"
+import { local } from "@pulumi/command"
+import { glob } from "glob"
+import { HttpRoute, type HttpRouteArgs } from "./gateway"
+import { mapNamespaceLikeToNamespaceName, type NamespaceLike } from "./shared"
+import { Service } from "./service"
+
+export type ChartArgs = Omit<
+  helm.v4.ChartArgs,
+  "chart" | "version" | "repositoryOpts" | "namespace"
+> & {
+  /**
+   * The namespace to deploy the chart into.
+   */
+  namespace?: Input<NamespaceLike>
+
+  /**
+   * The custom name of the primary service exposed by the chart.
+   *
+   * By default, it is the same as the chart name.
+   */
+  serviceName?: string
+
+  /**
+   * The manifest of the chart to resolve.
+   */
+  chart: ChartManifest
+
+  /**
+   * The cluster to create the resource in.
+   */
+  cluster: Input<k8s.Cluster>
+
+  /**
+   * The http route args to bind the service to.
+   */
+  httpRoute?: Input<HttpRouteArgs>
+}
+
+export class Chart extends ComponentResource {
+  /**
+   * The underlying Helm chart.
+   */
+  public readonly chart: Output<helm.v4.Chart>
+
+  /**
+   * The HTTP route associated with the deployment.
+   */
+  public readonly httpRoute: Output<HttpRoute | undefined>
+
+  constructor(
+    private readonly name: string,
+    private readonly args: ChartArgs,
+    private readonly opts?: ComponentResourceOptions,
+  ) {
+    super("highstate:k8s:Chart", name, args, opts)
+
+    this.chart = output(args).apply(args => {
+      return new helm.v4.Chart(
+        name,
+        omit(
+          {
+            ...args,
+            chart: resolveHelmChart(args.chart),
+            namespace: args.namespace ? mapNamespaceLikeToNamespaceName(args.namespace) : undefined,
+          },
+          ["httpRoute"],
+        ),
+        { parent: this, ...opts },
+      )
+    })
+
+    this.httpRoute = output(args.httpRoute).apply(httpRoute => {
+      if (!httpRoute) {
+        return undefined
+      }
+
+      return new HttpRoute(
+        name,
+        {
+          ...httpRoute,
+          rule: {
+            backend: this.service,
+          },
+        },
+        { ...opts, parent: this },
+      )
+    })
+
+    this.registerOutputs({ chart: this.chart })
+  }
+
+  get service(): Output<Service> {
+    return this.getServiceOutput(undefined)
+  }
+
+  private readonly services = new Map<string, Service>()
+
+  getServiceOutput(name: string | undefined): Output<Service> {
+    return output({ args: this.args, chart: this.chart }).apply(({ args, chart }) => {
+      const resolvedName = name ?? args.serviceName ?? this.name
+      const existingService = this.services.get(resolvedName)
+
+      if (existingService) {
+        return existingService
+      }
+
+      const service = getChartServiceOutput(chart, resolvedName)
+
+      const wrappedService = Service.wrap(
+        //
+        resolvedName,
+        service,
+        args.cluster.info,
+        { parent: this, ...this.opts },
+      )
+
+      this.services.set(resolvedName, wrappedService)
+      return wrappedService
+    })
+  }
+
+  getService(name?: string): Promise<Service> {
+    return toPromise(this.getServiceOutput(name))
+  }
+}
+
+export type RenderedChartArgs = {
+  /**
+   * The namespace to deploy the chart into.
+   */
+  namespace?: Input<NamespaceLike>
+
+  /**
+   * The manifest of the chart to resolve.
+   */
+  chart: ChartManifest
+
+  /**
+   * The values to pass to the chart.
+   */
+  values?: InputMap<string>
+}
+
+export class RenderedChart extends ComponentResource {
+  /**
+   * The rendered manifest of the Helm chart.
+   */
+  public readonly manifest: Output<string>
+
+  /**
+   * The underlying command used to render the chart.
+   */
+  public readonly command: Output<local.Command>
+
+  constructor(name: string, args: RenderedChartArgs, opts?: ComponentResourceOptions) {
+    super("highstate:k8s:RenderedChart", name, args, opts)
+
+    this.command = output(args).apply(args => {
+      const values = args.values
+        ? Object.entries(args.values).flatMap(([key, value]) => ["--set", `${key}="${value}"`])
+        : []
+
+      return new local.Command(
+        name,
+        {
+          create: output([
+            "helm",
+            "template",
+            resolveHelmChart(args.chart),
+
+            ...(args.namespace
+              ? ["--namespace", mapNamespaceLikeToNamespaceName(args.namespace)]
+              : []),
+
+            ...values,
+          ]).apply(command => command.join(" ")),
+
+          logging: "stderr",
+        },
+        { parent: this, ...opts },
+      )
+    })
+
+    this.manifest = this.command.stdout
+
+    this.registerOutputs({ manifest: this.manifest, command: this.command })
+  }
+}
+
+export type ChartManifest = {
+  repo: string
+  name: string
+  version: string
+  sha256: string
+}
+
+/**
+ * Downloads or reuses the Helm chart according to the charts.json file.
+ * Returns the full path to the chart's .tgz file.
+ *
+ * @param manifest The manifest of the Helm chart.
+ */
+export async function resolveHelmChart(manifest: ChartManifest): Promise<string> {
+  if (!process.env.HIGHSTATE_CACHE_DIR) {
+    throw new Error("Environment variable HIGHSTATE_CACHE_DIR is not set")
+  }
+
+  const chartsDir = resolve(process.env.HIGHSTATE_CACHE_DIR, "charts")
+  await mkdir(chartsDir, { recursive: true })
+
+  const globPattern = `${manifest.name}-*.tgz`
+  const targetFileName = `${manifest.name}-${manifest.version}.tgz`
+
+  // find all matching files
+  const files = await glob(globPattern, { cwd: chartsDir })
+
+  if (files.includes(targetFileName)) {
+    return resolve(chartsDir, targetFileName)
+  }
+
+  // delete old versions
+  for (const file of files) {
+    await unlink(resolve(chartsDir, file))
+  }
+
+  // download the chart
+  await spawn("helm", [
+    "pull",
+    manifest.name,
+    "--version",
+    manifest.version,
+    "--repo",
+    manifest.repo,
+    "--destination",
+    chartsDir,
+  ])
+
+  // check the SHA256
+  const content = await readFile(resolve(chartsDir, targetFileName))
+  const actualSha256 = await sha256(content)
+
+  if (actualSha256 !== manifest.sha256) {
+    throw new Error(`SHA256 mismatch for chart '${manifest.name}'`)
+  }
+
+  return resolve(chartsDir, targetFileName)
+}
+
+/**
+ * Extracts the service with the given name from the chart resources.
+ * Throws an error if the service is not found.
+ *
+ * @param chart The Helm chart.
+ * @param name The name of the service.
+ */
+export function getChartServiceOutput(chart: helm.v4.Chart, name: string): Output<core.v1.Service> {
+  const services = chart.resources.apply(resources => {
+    return resources
+      .filter(r => core.v1.Service.isInstance(r))
+      .map(service => ({ name: service.metadata.name, service }))
+  })
+
+  return output(services).apply(services => {
+    const service = services.find(s => s.name === name)?.service
+
+    if (!service) {
+      throw new Error(`Service with name '${name}' not found in the chart resources`)
+    }
+
+    return service
+  })
+}
+
+/**
+ * Extracts the service with the given name from the chart resources.
+ * Throws an error if the service is not found.
+ *
+ * @param chart The Helm chart.
+ * @param name The name of the service.
+ */
+export function getChartService(chart: helm.v4.Chart, name: string): Promise<core.v1.Service> {
+  return toPromise(getChartServiceOutput(chart, name))
+}