Docs

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:

Bring this chart to Alien
Install the Alien skills: npx skills add alienplatform/skills Use the alien-integration skill to bring our Helm chart to Alien as a whole-product deployment, following https://alien.dev/docs/guide/existing-app/helm.md. Render the chart with helm template and the values customers use (or kubectl kustomize for overlays). Map every Deployment, StatefulSet, Service, Ingress, Job, hook, CronJob, init container, sidecar, ConfigMap, and Secret to alien.ts, and list what you drop and why. Show me the mapping before writing alien.ts. Give every stateful service and setup step a health check that proves it's ready. Verify with alien dev, including a real login and the product's main action. Don't publish a release, create a customer deployment, or apply any infrastructure change without asking.

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.yaml

Turn 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:

alien.ts
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

Kubernetesalien.ts
DeploymentA Container with an image
StatefulSet with a PVCA 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 probeHealth 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 fileA 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 generatesalien.secret({ providedBy: "developer", generate: { length } })
Secret the customer suppliesalien.secret({ providedBy: "deployer" })
Bundled Postgres subchart or operatoralien.Postgres, or the customer's own database on Kubernetes
Bundled Redis, RabbitMQ, ClickHouseA stateful Container with the stock image
Pre-install or pre-upgrade hook, init JobA Container with commands, or idempotent steps at the start of one service's command
CronJobA 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 workA launcher in a thin image, or a setup step
SidecarFold 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 sizesA ComputeCluster pool with requirements
ServiceAccount, IRSA, Workload IdentityOne permission profile per service
Role or ClusterRole for the Kubernetes APIThe Helm setup package settings, not alien.ts
imagePullSecretsdocker 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.
  • fsGroup and runAsUser. 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 install once 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.

On this page