alchemy-kubernetes-addons 0.1.1 → 0.1.3

package/README.md

@@ -4,6 +4,24 @@ Composable Kubernetes resources built on Alchemy's public cluster-adapter API.
 They work with any `Kubernetes.ClusterLike`, including Hetzner K3s, Docker K3s,
 EKS, and kubeconfig connections.
 
+## Cloudflare Tunnel ingress
+
+`CloudflareTunnelIngress` installs STRRL's pinned ingress controller, a
+namespace, and a separate scoped Cloudflare token. Supply `cluster`,
+`accountId`, `zoneId`, and a cluster-unique `tunnelName`; optionally supply an
+external Redacted `token`. It returns the chart, namespace, release name, tunnel
+name, and `ingressClassName: "cloudflare-tunnel"`. It never makes that class
+default.
+
+`dependsOn` accepts a non-secret resource dependency, such as a hostname
+admission binding. Helm receives only a Secret reference; Secret revisions
+restart the controller after rotation. The upstream controller can overwrite an
+existing CNAME for a claimed hostname. Check ownership and gate allowed
+hostnames before using it in a shared zone; the
+[Kairos stack](../../examples/kairos-platform/README.md) implements both. Do not
+run ExternalDNS against the same hosts. Remove ingress routes and wait for DNS
+cleanup before uninstalling; the tunnel is retained.
+
 Add the provider beside Alchemy's Kubernetes provider:
 
 ```ts

package/dist/index.d.mts

@@ -28,6 +28,37 @@ declare class KubernetesReadinessError extends Error {
   constructor(message: string, object: KubernetesObjectRef, timedOut: boolean);
 }
 //#endregion
+//#region src/cloudflare-tunnel-ingress.d.ts
+declare const CLOUDFLARE_TUNNEL_CHART = "cloudflare-tunnel-ingress-controller";
+declare const CLOUDFLARE_TUNNEL_REPO = "https://helm.strrl.dev";
+declare const CLOUDFLARE_TUNNEL_VERSION = "0.1.0";
+declare const CLOUDFLARED_VERSION = "2026.7.3-host-metrics.1";
+interface CloudflareTunnelIngressProps {
+  cluster: Input<Kubernetes.ClusterLike>;
+  accountId: string;
+  zoneId: string;
+  tunnelName: string;
+  namespace?: string;
+  releaseName?: string;
+  token?: Input<Redacted.Redacted<string>>;
+  /** Non-secret dependency, e.g. the hostname admission binding revision. */
+  dependsOn?: Input<string>;
+  timeoutSeconds?: number;
+}
+declare const cloudflareTunnelTokenPolicies: (accountId: string, zoneId: string) => Cloudflare.ApiToken.Policy[];
+declare const cloudflareTunnelHelmValues: (releaseName: string, secretName: string, secretRevision: Input<string>, dependsOn?: Input<string>) => Record<string, unknown>;
+/** Install an explicit-class tunnel controller with a separate scoped token.
+ * The upstream controller can overwrite existing CNAMEs: callers must check
+ * hostname ownership and restrict admission before handing it a shared zone.
+ */
+declare const CloudflareTunnelIngress: (id: string, props: CloudflareTunnelIngressProps) => Effect.Effect<{
+  namespace: string;
+  releaseName: string;
+  tunnelName: string;
+  ingressClassName: string;
+  chart: Kubernetes.HelmChart;
+}, import("effect/Cause").UnknownError, Providers | Kubernetes.Providers | Cloudflare.Providers>;
+//#endregion
 //#region src/cloudflare-external-dns.d.ts
 declare const EXTERNAL_DNS_CHART_VERSION = "1.21.1";
 declare const EXTERNAL_DNS_IMAGE = "registry.k8s.io/external-dns/external-dns:v0.21.0@sha256:f53faaf71cb270d1ca9dce6ea0c94bfebf1a18696263487f0fbc74b9bf2bd7ff";
@@ -524,4 +555,4 @@ interface ReadyHelmChartProps extends Omit<Kubernetes.HelmChartProps, "cluster"
 declare const ReadyHelmChart: (id: string, props: ReadyHelmChartProps) => Effect.Effect<Kubernetes.HelmChart, never, Providers | Kubernetes.Providers>;
 declare const providers: () => Layer.Layer<Providers | Provider.Provider<import("alchemy").Random>, never, never>;
 //#endregion
-export { CERT_MANAGER_CHART, CERT_MANAGER_CHART_VERSION, CERT_MANAGER_IMAGE_VERSION, CONTAINER_REGISTRY_CHART, CONTAINER_REGISTRY_CHART_VERSION, CONTAINER_REGISTRY_IMAGE, CertManager, type CertManagerProps, type CertManagerResult, CloudflareAcmeIssuer, type CloudflareAcmeIssuerProps, type CloudflareAcmeIssuerResult, CloudflareExternalDns, type CloudflareExternalDnsPlan, type CloudflareExternalDnsProps, type CloudflareExternalDnsResult, ContainerRegistry, type ContainerRegistryGarbageCollectionProps, type ContainerRegistryIngressProps, type ContainerRegistryProps, type ContainerRegistryPullSecretRef, type ContainerRegistryPullSecretsProps, type ContainerRegistryResult, EXTERNAL_DNS_CHART_VERSION, EXTERNAL_DNS_IMAGE, type KubernetesObjectReadiness, type KubernetesObjectRef, KubernetesReadinessError, LETSENCRYPT_PRODUCTION_URL, LETSENCRYPT_STAGING_URL, OTEL_COLLECTOR_CHART_VERSION, OTEL_COLLECTOR_IMAGE, OtelCollector, type OtelCollectorBasicAuthSecretRef, type OtelCollectorDestination, type OtelCollectorPlan, type OtelCollectorProps, type OtelCollectorResult, type OtelSignal, PARSEABLE_CHART_VERSION, PARSEABLE_IMAGE, Parseable, type ParseableIngressProps, type ParseableOtlpEndpoints, type ParseableProps, type ParseableResult, type ParseableStagingProps, Providers, Readiness, ReadinessProps, ReadinessProvider, ReadyHelmChart, ReadyHelmChartProps, Secret, SecretProps, SecretProvider, certManagerHelmValues, cloudflareAcmeIssuerManifest, cloudflareAcmeIssuerName, cloudflareAcmeIssuerTokenPolicies, containerRegistryDockerConfig, containerRegistryHelmValues, containerRegistryHtpasswd, kubernetesObjectReadiness, parseableHelmValues, planCloudflareExternalDns, planOtelCollector, providers, validateCertManagerProps, validateCloudflareAcmeIssuerProps, validateContainerRegistryProps };
+export { CERT_MANAGER_CHART, CERT_MANAGER_CHART_VERSION, CERT_MANAGER_IMAGE_VERSION, CLOUDFLARED_VERSION, CLOUDFLARE_TUNNEL_CHART, CLOUDFLARE_TUNNEL_REPO, CLOUDFLARE_TUNNEL_VERSION, CONTAINER_REGISTRY_CHART, CONTAINER_REGISTRY_CHART_VERSION, CONTAINER_REGISTRY_IMAGE, CertManager, type CertManagerProps, type CertManagerResult, CloudflareAcmeIssuer, type CloudflareAcmeIssuerProps, type CloudflareAcmeIssuerResult, CloudflareExternalDns, type CloudflareExternalDnsPlan, type CloudflareExternalDnsProps, type CloudflareExternalDnsResult, CloudflareTunnelIngress, type CloudflareTunnelIngressProps, ContainerRegistry, type ContainerRegistryGarbageCollectionProps, type ContainerRegistryIngressProps, type ContainerRegistryProps, type ContainerRegistryPullSecretRef, type ContainerRegistryPullSecretsProps, type ContainerRegistryResult, EXTERNAL_DNS_CHART_VERSION, EXTERNAL_DNS_IMAGE, type KubernetesObjectReadiness, type KubernetesObjectRef, KubernetesReadinessError, LETSENCRYPT_PRODUCTION_URL, LETSENCRYPT_STAGING_URL, OTEL_COLLECTOR_CHART_VERSION, OTEL_COLLECTOR_IMAGE, OtelCollector, type OtelCollectorBasicAuthSecretRef, type OtelCollectorDestination, type OtelCollectorPlan, type OtelCollectorProps, type OtelCollectorResult, type OtelSignal, PARSEABLE_CHART_VERSION, PARSEABLE_IMAGE, Parseable, type ParseableIngressProps, type ParseableOtlpEndpoints, type ParseableProps, type ParseableResult, type ParseableStagingProps, Providers, Readiness, ReadinessProps, ReadinessProvider, ReadyHelmChart, ReadyHelmChartProps, Secret, SecretProps, SecretProvider, certManagerHelmValues, cloudflareAcmeIssuerManifest, cloudflareAcmeIssuerName, cloudflareAcmeIssuerTokenPolicies, cloudflareTunnelHelmValues, cloudflareTunnelTokenPolicies, containerRegistryDockerConfig, containerRegistryHelmValues, containerRegistryHtpasswd, kubernetesObjectReadiness, parseableHelmValues, planCloudflareExternalDns, planOtelCollector, providers, validateCertManagerProps, validateCloudflareAcmeIssuerProps, validateContainerRegistryProps };

package/dist/index.mjs

@@ -10,8 +10,8 @@ import * as Redacted from "effect/Redacted";
 import * as Duration from "effect/Duration";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
-import { createHash } from "node:crypto";
 import * as Cloudflare from "alchemy/Cloudflare";
+import { createHash } from "node:crypto";
 import { encodeBase64, hashSync, truncates } from "bcryptjs";
 //#region src/client.ts
 var KubernetesApiError = class extends Error {
@@ -248,6 +248,119 @@ const waitForObjectsReady = Effect.fn(function* ({ transport, objects, timeoutSe
 	}
 });
 //#endregion
+//#region src/cloudflare-tunnel-ingress.ts
+const CLOUDFLARE_TUNNEL_CHART = "cloudflare-tunnel-ingress-controller";
+const CLOUDFLARE_TUNNEL_REPO = "https://helm.strrl.dev";
+const CLOUDFLARE_TUNNEL_VERSION = "0.1.0";
+const CLOUDFLARED_VERSION = "2026.7.3-host-metrics.1";
+const cloudflareTunnelTokenPolicies = (accountId, zoneId) => [{
+	effect: "allow",
+	permissionGroups: [
+		"Zone Read",
+		"DNS Read",
+		"DNS Write"
+	],
+	resources: { [`com.cloudflare.api.account.zone.${zoneId}`]: "*" }
+}, {
+	effect: "allow",
+	permissionGroups: ["Cloudflare Tunnel Write"],
+	resources: { [`com.cloudflare.api.account.${accountId}`]: "*" }
+}];
+const cloudflareTunnelHelmValues = (releaseName, secretName, secretRevision, dependsOn = "none") => ({
+	fullnameOverride: releaseName,
+	cloudflare: { secretRef: {
+		name: secretName,
+		accountIDKey: "account-id",
+		tunnelNameKey: "tunnel-name",
+		apiTokenKey: "api-token"
+	} },
+	ingressClass: {
+		name: "cloudflare-tunnel",
+		isDefaultClass: false
+	},
+	replicaCount: 1,
+	image: { tag: CLOUDFLARE_TUNNEL_VERSION },
+	podAnnotations: {
+		"alchemy.run/secret-revision": secretRevision,
+		"alchemy.run/dependency": dependsOn
+	},
+	securityContext: {
+		allowPrivilegeEscalation: false,
+		capabilities: { drop: ["ALL"] },
+		readOnlyRootFilesystem: true
+	},
+	cloudflared: {
+		image: { tag: CLOUDFLARED_VERSION },
+		replicaCount: 1,
+		podAntiAffinity: false,
+		resources: {
+			requests: {
+				cpu: "50m",
+				memory: "64Mi"
+			},
+			limits: { memory: "256Mi" }
+		}
+	},
+	serviceMonitor: { create: false }
+});
+/** Install an explicit-class tunnel controller with a separate scoped token.
+* The upstream controller can overwrite existing CNAMEs: callers must check
+* hostname ownership and restrict admission before handing it a shared zone.
+*/
+const CloudflareTunnelIngress = (id, props) => Effect.gen(function* () {
+	const namespaceName = props.namespace ?? "cloudflare-tunnel-system";
+	const releaseName = props.releaseName ?? "cloudflare-tunnel";
+	yield* Effect.try(() => {
+		for (const name of [
+			namespaceName,
+			releaseName,
+			props.tunnelName
+		]) if (!/^[a-z0-9](?:[-a-z0-9]{0,51}[a-z0-9])?$/.test(name)) throw new Error(`Invalid Cloudflare tunnel resource name: ${name}`);
+		for (const value of [props.accountId, props.zoneId]) if (!/^[a-f0-9]{32}$/.test(value)) throw new Error("Cloudflare accountId and zoneId must be 32 hex digits");
+	});
+	const namespace = yield* Kubernetes.Manifest(`${id}Namespace`, {
+		cluster: props.cluster,
+		manifest: {
+			apiVersion: "v1",
+			kind: "Namespace",
+			metadata: { name: namespaceName }
+		}
+	});
+	const token = props.token ?? (yield* Cloudflare.ApiToken.AccountApiToken(`${id}Token`, {
+		accountId: props.accountId,
+		policies: cloudflareTunnelTokenPolicies(props.accountId, props.zoneId)
+	})).value;
+	const secretName = `${releaseName}-credentials`;
+	const secret = yield* Secret(`${id}Credentials`, {
+		cluster: props.cluster,
+		namespace: namespace.name,
+		name: secretName,
+		stringData: {
+			"account-id": props.accountId,
+			"tunnel-name": props.tunnelName,
+			"api-token": token
+		}
+	});
+	const chart = yield* ReadyHelmChart(`${id}Chart`, {
+		cluster: props.cluster,
+		chart: CLOUDFLARE_TUNNEL_CHART,
+		repo: CLOUDFLARE_TUNNEL_REPO,
+		version: CLOUDFLARE_TUNNEL_VERSION,
+		namespace: namespaceName,
+		releaseName,
+		createNamespace: false,
+		timeoutSeconds: props.timeoutSeconds ?? 300,
+		values: cloudflareTunnelHelmValues(releaseName, secretName, Output.map(secret.resourceVersion, (version) => version ?? "created"), props.dependsOn)
+	});
+	return {
+		namespace: namespaceName,
+		releaseName,
+		tunnelName: props.tunnelName,
+		ingressClassName: "cloudflare-tunnel",
+		chart
+	};
+});
+//#endregion
 //#region src/cloudflare-external-dns.ts
 const EXTERNAL_DNS_CHART_VERSION = "1.21.1";
 const EXTERNAL_DNS_IMAGE_REPOSITORY = "registry.k8s.io/external-dns/external-dns";
@@ -1597,4 +1710,4 @@ const ReadyHelmChart = (id, props) => Effect.gen(function* () {
 });
 const providers = () => Layer.effect(Providers, Provider.collection([Secret, Readiness])).pipe(Layer.provide(Layer.mergeAll(SecretProvider(), ReadinessProvider())), Layer.provideMerge(RandomProvider()));
 //#endregion
-export { CERT_MANAGER_CHART, CERT_MANAGER_CHART_VERSION, CERT_MANAGER_IMAGE_VERSION, CONTAINER_REGISTRY_CHART, CONTAINER_REGISTRY_CHART_VERSION, CONTAINER_REGISTRY_IMAGE, CertManager, CloudflareAcmeIssuer, CloudflareExternalDns, ContainerRegistry, EXTERNAL_DNS_CHART_VERSION, EXTERNAL_DNS_IMAGE, KubernetesReadinessError, LETSENCRYPT_PRODUCTION_URL, LETSENCRYPT_STAGING_URL, OTEL_COLLECTOR_CHART_VERSION, OTEL_COLLECTOR_IMAGE, OtelCollector, PARSEABLE_CHART_VERSION, PARSEABLE_IMAGE, Parseable, Providers, Readiness, ReadinessProvider, ReadyHelmChart, Secret, SecretProvider, certManagerHelmValues, cloudflareAcmeIssuerManifest, cloudflareAcmeIssuerName, cloudflareAcmeIssuerTokenPolicies, containerRegistryDockerConfig, containerRegistryHelmValues, containerRegistryHtpasswd, kubernetesObjectReadiness, parseableHelmValues, planCloudflareExternalDns, planOtelCollector, providers, validateCertManagerProps, validateCloudflareAcmeIssuerProps, validateContainerRegistryProps };
+export { CERT_MANAGER_CHART, CERT_MANAGER_CHART_VERSION, CERT_MANAGER_IMAGE_VERSION, CLOUDFLARED_VERSION, CLOUDFLARE_TUNNEL_CHART, CLOUDFLARE_TUNNEL_REPO, CLOUDFLARE_TUNNEL_VERSION, CONTAINER_REGISTRY_CHART, CONTAINER_REGISTRY_CHART_VERSION, CONTAINER_REGISTRY_IMAGE, CertManager, CloudflareAcmeIssuer, CloudflareExternalDns, CloudflareTunnelIngress, ContainerRegistry, EXTERNAL_DNS_CHART_VERSION, EXTERNAL_DNS_IMAGE, KubernetesReadinessError, LETSENCRYPT_PRODUCTION_URL, LETSENCRYPT_STAGING_URL, OTEL_COLLECTOR_CHART_VERSION, OTEL_COLLECTOR_IMAGE, OtelCollector, PARSEABLE_CHART_VERSION, PARSEABLE_IMAGE, Parseable, Providers, Readiness, ReadinessProvider, ReadyHelmChart, Secret, SecretProvider, certManagerHelmValues, cloudflareAcmeIssuerManifest, cloudflareAcmeIssuerName, cloudflareAcmeIssuerTokenPolicies, cloudflareTunnelHelmValues, cloudflareTunnelTokenPolicies, containerRegistryDockerConfig, containerRegistryHelmValues, containerRegistryHtpasswd, kubernetesObjectReadiness, parseableHelmValues, planCloudflareExternalDns, planOtelCollector, providers, validateCertManagerProps, validateCloudflareAcmeIssuerProps, validateContainerRegistryProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy-kubernetes-addons",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Composable Kubernetes add-ons and safe primitives for Alchemy",
   "license": "Apache-2.0",
   "type": "module",