From a Helm chart
A product that ships as a Helm chart, Kustomize overlays, or plain Kubernetes manifests moves onto Alien with the same images. The services in the chart become containers in alien.ts, and they deploy into the customer's AWS, Google Cloud, or Azure account, their Kubernetes cluster, or their Linux servers.
From the repository that has your chart:
Render the chart
Map what the chart renders, not its templates. Use the values real customers use:
helm dependency build ./chart
helm template acme ./chart -f values-customer.yaml > rendered.yaml
# Kustomize
kubectl kustomize overlays/production > rendered.yamlTurn on the bundled subcharts you will replace, such as postgresql.enabled=true, so the rendered env still shows what points at them. Hook Jobs appear in the output with a helm.sh/hook annotation.
An example
A Deployment with a Service and an Ingress, a ConfigMap as env, a Secret the chart generates, and a pre-install hook that migrates the database:
import * as alien from "@alienplatform/core"
const config = alien.inputs({
// Was a Secret the chart generated with randAlphaNum.
sessionSecret: alien.secret({
providedBy: "developer",
required: true,
label: "Session secret",
description: "Signs user sessions.",
generate: { length: 64 },
env: { name: "SESSION_SECRET", targetResources: ["api"] },
}),
})
// Was the postgresql subchart.
const db = new alien.Postgres("db").build()
// Was a Deployment, a Service named api, and an Ingress.
// The pre-install migration hook now runs before the server starts.
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:2.3.0" })
.command(["sh", "-c", "./migrate up && exec ./server"])
.cpu(1)
.memory("2Gi")
.replicas(2)
.port(8080)
.publicEndpoint("app", 8080, "http")
.healthCheck({ path: "/ready", failureThreshold: 10 })
.environment({ LOG_LEVEL: "info" }) // Was a ConfigMap.
.link(db)
.permissions("api")
.build()
export default new alien.Stack("acme")
.inputs(config)
.add(db, "frozen")
.add(api, "live")
.permissions({ profiles: { api: { db: ["postgres/data-access"] } } })
.build()With two replicas, make the migration safe to run twice at once, for example behind a Postgres advisory lock.
Mapping
| Kubernetes | alien.ts |
|---|---|
| Deployment | A Container with an image |
| StatefulSet with a PVC | A Container with .persistentStorage(size, { mountPath }). Set .pool() too, or it gets its own pool of machines. |
| Service and container ports | .port(n). Other containers that link to it read its address from the link binding (ALIEN_<ID>_BINDING, or getInternalUrl()). Don't build the name from the container ID: on Kubernetes it includes the namespace. |
| Ingress, Gateway route | .publicEndpoint(name, port, "http"). Endpoint names are unique across the stack. On AWS each endpoint has its own load balancer, so route several paths through one front service where you can. |
| HTTP readiness or liveness probe | .healthCheck({ path, port, failureThreshold }) |
| Exec or TCP probe | Health checks are HTTP. Serve a small readiness endpoint from a launcher. |
command, args | .command([...]), which replaces the image's entrypoint |
| ConfigMap as env | .environment({...}) |
| ConfigMap or Secret mounted as a file | A thin image built on yours (FROM, COPY), or a file rendered from env at start. On Kubernetes, .kubernetesSecretMount() mounts an existing Secret. |
securityContext | .security({ profile: "restricted", runAsUser, runAsGroup, readOnlyRootFilesystem }) |
| Secret the chart generates | alien.secret({ providedBy: "developer", generate: { length } }) |
| Secret the customer supplies | alien.secret({ providedBy: "deployer" }) |
| Bundled Postgres subchart or operator | alien.Postgres, or the customer's own database on Kubernetes |
| Bundled Redis, RabbitMQ, ClickHouse | A stateful Container with the stock image |
| Pre-install or pre-upgrade hook, init Job | A Container with commands, or idempotent steps at the start of one service's command |
| CronJob | A periodic task in a service, or a Worker with a schedule trigger |
| Init container that waits for a dependency | .link() on that container, and retry on startup |
| Init container that does work | A launcher in a thin image, or a setup step |
| Sidecar | Fold it into the main process, or drop it |
| HorizontalPodAutoscaler | .autoScale({ min, desired, max, targetCpuPercent }) |
resources.requests | .cpu() and .memory() |
emptyDir | .ephemeralStorage(size) |
| nodeSelector, tolerations, instance sizes | A ComputeCluster pool with requirements |
| ServiceAccount, IRSA, Workload Identity | One permission profile per service |
| Role or ClusterRole for the Kubernetes API | The Helm setup package settings, not alien.ts |
imagePullSecrets | docker login before alien release. See Images. |
These have no counterpart, and you can drop them: NetworkPolicy (services in a stack are private unless they have a public endpoint), PodDisruptionBudget, ServiceMonitor, PriorityClass, and namespaces.
Details to check
- Ingress annotations. Body size limits, timeouts, and sticky sessions are set in annotations. Check each against Networking.
fsGroupandrunAsUser. Without them, a volume can be owned by root. A launcher can fix ownership, then start your process as its usual user.- Downward API values such as
POD_NAME. Use the variables in Environment variables instead. - One release per tenant. If you run
helm installonce per customer, each customer becomes one Alien deployment.
Keeping your chart
Some customers must run helm install with your chart in their own cluster. Keep the chart, and add Remote Operator beside it, so you can still see and operate every install.
Next
- Bring an existing app: images, launchers for images that don't use the SDK, and verification.
- Kubernetes: deploying into a customer's cluster, and using their existing databases.
Overview
Move a product that ships with a Helm chart, Docker Compose, ECS, or Terraform onto Alien, so one alien.ts deploys it to every customer.
From Docker Compose
Move a product that ships as a Docker Compose file onto Alien, and see where volumes, healthchecks, depends_on, and one-shot setup services go.