Docs

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 Operator pulls releases; nothing connects into the cluster

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-values needs 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.

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

Setting up on an existing Kubernetes cluster with Helm: the values.yaml to keep and the helm install command.
The Helm method in the deployment portal: the values.yaml to keep and the helm install command.

To create a setup link that offers only Kubernetes:

alien onboard customer-2 --allow admin@customer-2.com --platforms kubernetes

In 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

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

The 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 apply creates 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 with kubectl pointed 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.txt

The 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.yaml and 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:

values.yaml
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 release on 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=true to 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 release pins 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, set global.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:

alien.ts
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. /tmp and each path in writablePaths are writable.
  • The process runs as the image's own user, which must not be root. Set runAsUser and runAsGroup to 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-files

A 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 destroy stops before it removes anything and names the steps to take first. A Terraform install from an earlier release gets this check after one terraform apply with the current module.

Chart values

ValueDescription
management.enrollmentCodeThe 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, .keyA 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.tokenA deployment token, for installs from before enrollment codes
management.nameDeployment name shown in the dashboard
infrastructureFrozen resources mapped to the cluster's infrastructure
infrastructureExistingSecretThe same map, from a Secret
runtime.image.selfUpdateFollow the Operator version Alien serves. Default false: a new chart version carries Operator upgrades.
logCollector.enabledCollect 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.imageRegistryPull 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.digestRun the Operator by digest (sha256:...). It wins over the tag and turns off self-update.
runtime.image.pinRun 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.keyOptional 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.enabledTake 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.yaml

Next

On this page