Kubernetes
A Kubernetes deployment runs your stack as pods in one namespace of your customer's cluster, on-prem or in EKS, GKE, or AKS. The customer's admin sets it up once with Helm, and every release after that arrives over outbound HTTPS: nobody runs helm upgrade, and nothing in the cluster accepts inbound connections.
Architecture diagram. Customer cluster (Operator, Your pods) connects outbound to the Alien manager (Releases, Images, Charts), via https 443, outbound.
The Helm chart runs the Operator, a small service that connects out to Alien's manager (the service that holds your releases and deployments) and deploys each release into the namespace. This is pull: a component inside the environment fetches releases, instead of Alien calling in.
A deployment's life has two parts:
- Initial setup: the one-time step the admin runs with their own cluster credentials, using Helm, or Terraform or CloudFormation to create a managed cluster first.
- Ongoing management: everything after. The Operator applies each release, sends logs, and runs commands, without the admin.
How the admin reaches initial setup is your Deployment UX choice: a link you send, a Deploy button in your product, or your own setup screen. What happens in the cluster is the same either way, and this guide follows it from requirements to removal.
What the customer needs
- A cluster, or a cloud account to create one in: EKS on AWS, GKE on Google Cloud, or AKS on Azure.
- Helm 3.8 or later (OCI charts).
--reset-then-reuse-valuesneeds Helm 3.14. - Rights to install the chart into its namespace. Turning on the Remote Operator adds a custom resource definition, which may need cluster-admin approval.
- Outbound HTTPS from the cluster to Alien. Nothing needs to reach into the cluster.
- The infrastructure your frozen resources map to, such as an S3 bucket. See Connect the customer's infrastructure.
Your stack
Target the kubernetes platform. On other platforms, initial setup creates the frozen resources, the ones that hold the customer's data, like a bucket. On Kubernetes, each frozen resource maps to infrastructure the customer already runs, and the admin supplies it during initial setup.
import * as alien from "@alienplatform/core"
// Maps to a bucket the customer already runs, supplied at initial setup.
const files = new alien.Storage("files").build()
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
.cpu(0.5)
.memory("512Mi")
.port(8080)
.link(files)
.permissions("api")
.build()
export default new alien.Stack("acme-files")
.platforms(["kubernetes"])
.add(files, "frozen")
.add(api, "live")
.permissions({
profiles: { api: { files: ["storage/data-read", "storage/data-write"] } },
})
.build()Publish a release with alien release.
Set up
The Helm chart, Terraform modules, and CloudFormation template are setup packages, which Alien builds from your release. The deployment portal, the branded setup page Alien hosts for the admin, hands out the right one.

To create a setup link that offers only Kubernetes:
alien onboard customer-2 --allow admin@customer-2.com --platforms kubernetesIn the portal, the admin reaches Kubernetes from On-prem or from a cloud:
- On-prem, then Compute → Kubernetes: deploy into a cluster they operate, with Helm.
- AWS, Google Cloud, or Azure, then Compute → Amazon EKS, Google Kubernetes Engine, or Azure Kubernetes Service, and a Cluster source: create a new cluster or use an existing one.
Helm on an existing cluster
- Prepare values: save the generated
values.yaml. It holds the deployment's name and a one-hour, one-use enrollment code, never a long-lived token. Keep it for later upgrades: once the Operator has enrolled, an upgrade with the expired code is fine. - Install chart: set the Kubernetes namespace and run the command from a shell with the target cluster's context.
helm install acme-files <chart-from-portal> \
--namespace acme-files --create-namespace \
--values values.yamlThe portal fills in the chart reference and namespace. The Operator starts, registers the deployment, fetches the release, and deploys it. The deployment shows Running in a minute or two.
New EKS, GKE, or AKS cluster
A new EKS cluster is set up with CloudFormation (the default) or Terraform. A new GKE or AKS cluster is set up with Terraform.
- With Install chart automatically (Terraform only),
terraform applycreates the cluster and installs the chart. - With Install chart separately, or after the CloudFormation stack registers, the portal shows Connect your cluster: save
values.yaml, then install the chart withkubectlpointed at the new cluster.
Existing EKS, GKE, or AKS cluster
Terraform only. The admin sets the cluster in the generated main.tf (eks_cluster_name, gke_cluster_name and gke_cluster_location, or aks_cluster_name and aks_cluster_resource_group_name), then runs terraform init && terraform apply with TF_VAR_token set.
When Terraform installs the chart, TF_VAR_token is a setup key from Issue a new setup key in the portal:
- It works for one apply and expires after two hours. Plan and apply with the same key.
- Every later apply, and
terraform destroy, needs a new key. Issuing one makes the previous key stop working. - On EKS, the portal also shows
TF_VAR_management_external_id.
With the deploy CLI
The admin can also install with your deploy CLI, using the setup token from your setup link:
alien-deploy deploy --name customer-2 --platform kubernetes \
--namespace acme-files --token-file setup-token.txtThe CLI installs the chart with a one-hour, one-use enrollment code, never a long-lived token. The Operator trades the code for its own short-lived key on first start.
To change settings later, the admin runs the same command again without a token. The CLI signs in through the installation in the cluster. It runs kubectl exec into the Operator, which hands out a key that lasts 15 minutes and is used for that run only. The CLI never saves it. A newer run replaces the key, and an older run still in progress then stops with a message that a newer update took over.
The admin's kube access is the proof. Anyone allowed pods/exec on the Operator can update or remove this installation, just as they could already delete the namespace. Give that permission only to the cluster's admins. If the CLI can't reach the Operator (no pod, the Operator not enrolled yet, or exec not allowed), it asks for the setup token again with --token-file.
What initial setup creates
- The Operator, in the deployment's namespace. It enrolls with the code in
values.yamland from then on signs in with its own short-lived key, which it renews itself. - Your workloads, which the Operator creates in that namespace from the release.
- A new cluster, only when the admin chose to create one with Terraform or CloudFormation.
Frozen resources aren't created: they map to the customer's infrastructure. See Connect the customer's infrastructure.
Chart versions
Each release gets a new chart version. Alien serves the images and the chart, so you don't need a registry that customers can reach.
Connect the customer's infrastructure
The infrastructure map in the values file binds each frozen resource to something the cluster already has. For storage, that is S3 or any S3-compatible store:
infrastructure:
files:
type: storage
service: s3
bucketName: customer-2-files
# For S3-compatible stores (MinIO, Ceph). Omit these three for Amazon S3
# with the pod's own AWS identity.
endpoint: https://minio.customer-2.internal
accessKeyId: <access-key-id>
secretAccessKey: <secret-access-key>To keep credentials out of values files, store the map as JSON under the key external-bindings.json in a Kubernetes Secret, and set infrastructureExistingSecret to the Secret's name.
How updates arrive
Ongoing management on Kubernetes uses pull: the Operator connects out to Alien and applies what it finds on the deployment's release channel. Nobody runs helm upgrade for a release. See Push, pull, and air-gapped.
- Releases. Every
alien releaseon the deployment's channel reaches the cluster on the Operator's next sync, about every 30 seconds. Use channels and pins to stage rollouts. See Releases. - The Operator. It upgrades with the chart version. Set
runtime.image.selfUpdate=trueto let it follow the version Alien serves. - Images. Pods pull through Alien with a short-lived pull credential that the Operator keeps current in their pull Secret. The cluster needs no credentials for your registry.
alien releasepins each container and daemon image to its digest, so a tag moved later doesn't change what runs. To pull from the customer's own registry instead, setglobal.imageRegistry. - Pod security. Pods run as their images were built unless the container sets a security profile. See Pod security.
- Logs. The Operator collects your containers' logs and OpenTelemetry data and sends them out over the same connection.
- Commands. Commands reach your containers through the Operator.
- Changes that need initial setup again. A release that needs a new frozen Kubernetes object, such as a service account, completes with a normal chart upgrade. A new cloud resource needs the cloud part of initial setup first. See Updating a Helm install.
- Remote Operator. The chart can also run the Remote Operator for operations and access requests. It's off by default. Turning it on may need cluster-admin approval, because it adds a custom resource definition for access requests.
Pod security
.security({ profile: "restricted" }) runs a container under the Kubernetes Pod Security restricted profile:
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
.port(8080)
.security({ profile: "restricted", writablePaths: ["/data"] })
.build()- The pod runs non-root, with seccomp
RuntimeDefault, no capabilities, and no privilege escalation. - The root filesystem is read-only.
/tmpand each path inwritablePathsare writable. - The process runs as the image's own user, which must not be root. Set
runAsUserandrunAsGroupto choose another. - An image Alien builds from source gets user
65532. - A container without
.security()runs as its image was built.
Remove it
Delete the deployment from your side: Delete deployment, or alien deployments delete customer-2/customer-2. The deployment then shows Teardown required until the admin uninstalls the chart:
helm uninstall acme-files --namespace acme-filesA cleanup job removes the workloads the Operator created.
- Persistent volume claims stay unless
runtime.cleanup.onUninstall.deletePersistentVolumeClaims=true. - Infrastructure mapped in
values.yaml, like the bucket, is never touched. - A cluster that initial setup created with Terraform is removed with
terraform destroy, using a new setup key. - While the deployment keeps retained data,
terraform destroystops before it removes anything and names the steps to take first. A Terraform install from an earlier release gets this check after oneterraform applywith the current module.
Chart values
| Value | Description |
|---|---|
management.enrollmentCode | The one-hour, one-use enrollment code from the portal. The Operator ignores it once enrolled, so applying the same values again changes nothing. Needs management.deploymentId and management.audience. |
management.enrollmentCodeSecret.name, .key | A Secret you created that holds the code, instead of enrollmentCode. Set runtime.imagePullSecrets too: the chart can't read the Secret to build the first pull credential. |
management.token | A deployment token, for installs from before enrollment codes |
management.name | Deployment name shown in the dashboard |
infrastructure | Frozen resources mapped to the cluster's infrastructure |
infrastructureExistingSecret | The same map, from a Secret |
runtime.image.selfUpdate | Follow the Operator version Alien serves. Default false: a new chart version carries Operator upgrades. |
logCollector.enabled | Collect container logs. Default false. Set logCollector.mode to podApi (reads selected Pod logs through the Kubernetes API, no DaemonSet) or nodeAgent (a Fluent Bit DaemonSet). |
global.imageRegistry | Pull every image from this registry (host[/path]): the Operator, its hooks and probes, the log collector, and your workloads. Images keep their path, tag, and digest, so mirror them first. For air-gapped sites, alien-deploy sync --registry mirrors them and sets this value. |
runtime.image.digest | Run the Operator by digest (sha256:...). It wins over the tag and turns off self-update. |
runtime.image.pin | Run exactly the runtime.image repository and tag given, for a newer Operator or a hotfix build. Default false: a chart that embeds its own Operator image runs that one. |
runtime.encryption.key | Optional 32-byte hex key for the Operator's stored state. Leave it empty and the Operator creates one in the Secret <release>-operator. A value that differs from the installed key is refused. |
airgapped.enabled | Take releases from sync bundles instead. See Air-gapped. |
helm show values <chart> lists the rest, including resources, scheduling, network policy, and security context.
To change values later:
helm upgrade acme-files <chart-from-portal> \
--namespace acme-files --reset-then-reuse-values --values values.yamlNext
- Push, pull, and air-gapped: how pull and air-gapped deployments get releases
- Bare metal & on-prem: machines without Kubernetes
- Remote Operator: operate the deployment
Azure
A deployment in a customer's Azure subscription: what the admin needs, initial setup with Terraform or the CLI, the managed identity and its role limits, updates, and removal.
Bare metal & on-prem platform
Platform reference for `machines`: what each machine needs, the join command and its flags, the machine agent that pulls releases, offline behavior, and removal.
