Run a service in your customers' Kubernetes clusters
This example builds one service that runs in every customer's Kubernetes cluster, including air-gapped sites with no network path to you. Each customer sets it up once with Helm; after that, every alien release reaches their cluster without anyone running helm upgrade.
Architecture diagram. Alien manager manages 2 remote environments: files service (customer-1 · Kubernetes), pull · https 443; files service (customer-2 · Kubernetes), pull · https 443.
What you build:
- A Rust files service that stores data in each customer's own S3-compatible bucket (Amazon S3, MinIO, Ceph).
- Releases that roll out to every connected cluster on their own, with logs flowing back.
- Calls from your backend to any customer's service by name, with no inbound port.
- An air-gapped site that gets the same releases as signed folders carried in by hand.
The whole flow runs on your laptop in about 30 minutes: a local kind cluster plays three customers. Source: examples/customer-kubernetes.
How it works
- The manager runs in your cloud: one container,
ghcr.io/alienplatform/alien-manager, with its state in a volume. It stores releases and images, serves the Helm chart, picks the release each customer runs, collects logs, and forwards your backend's requests. - The Operator runs in each customer's cluster, installed by the chart next to your service. It opens one outbound HTTPS connection to the manager, deploys the right release, sends logs, and carries your requests to the service. Nothing connects in.
- The service is your code.
The customer's admin runs the Helm install once, with their own credentials: the initial setup. Everything after, from new releases to logs, is ongoing management with no admin involved. See Frozen and live.
alien.ts
alien.ts says what the service needs. Alien turns it into the Helm chart customers deploy and the releases you ship:
import * as alien from "@alienplatform/core"
// Set per customer when you onboard them. The service requires it on every
// request, so the application keeps its own authentication end to end.
const inputs = alien.inputs({
accessToken: alien.secret({
providedBy: "developer",
required: true,
label: "Access token",
description: "Token your backend sends in the Authorization header.",
minLength: 32,
env: { name: "ACCESS_TOKEN", targetResources: ["api"] },
}),
})
// The customer's bucket: Amazon S3, MinIO, Ceph or any S3-compatible store.
// The customer's admin names it in the Helm values when they install.
const bucket = new alien.Storage("bucket").build()
const api = new alien.Container("api")
.code({
type: "source",
src: ".",
toolchain: { type: "rust", binaryName: "files" },
})
.cpu(0.5)
.memory("512Mi")
// Reachable inside the customer's cluster only.
.port(8080)
.healthCheck({ path: "/health", method: "GET", timeoutSeconds: 2, failureThreshold: 3 })
.link(bucket)
.permissions("api")
.build()
export default new alien.Stack("files")
.platforms(["kubernetes"])
.inputs(inputs)
.add(bucket, "frozen")
.add(api, "live")
.permissions({
profiles: {
api: { bucket: ["storage/data-read", "storage/data-write"] },
},
})
.build().platforms(["kubernetes"])builds the stack as a Helm chart that installs the Operator and your service.- The bucket is
frozen. It belongs to the customer: their admin names it in the Helm values at initial setup, and your releases never change it. - The container is
live. Alien builds it from this directory with the Rust toolchain, and everyalien releaserolls it out to every cluster. .port(8080)opens the port inside the customer's cluster. Nothing outside it can reach the service..link(bucket)with theapipermission profile gives the container read and write access to that bucket and nothing more.- The
accessTokeninput is set per customer when you onboard them, and reaches the container asACCESS_TOKEN.
The service keeps its own authentication. That's why each customer gets an access token, checked on every request.
The service
src/main.rs never names a storage provider. It asks the Alien bindings for the linked bucket and gets whichever one the customer configured:
let access_token = std::env::var("ACCESS_TOKEN").expect("ACCESS_TOKEN must be set");
let bindings = Bindings::from_env().expect("failed to load bindings");
let storage = bindings
.storage("bucket")
.await
.expect("failed to load the 'bucket' storage binding");
info!(bucket = %storage.get_url(), "bucket ready");The routes sit behind one middleware that checks the bearer token. /health is added after the layer, so the Kubernetes health check doesn't need the token:
let app = Router::new()
.route("/files", get(list))
.route("/files/{*key}", get(download).put(upload).delete(remove))
.route_layer(middleware::from_fn_with_state(state.clone(), authorize))
.route("/health", get(|| async { "ok" }))
.with_state(state);/// Every file route requires `Authorization: Bearer <ACCESS_TOKEN>`.
async fn authorize(State(state): State<AppState>, request: Request, next: Next) -> Response {
let presented = request
.headers()
.get(header::AUTHORIZATION)
.and_then(|v| v.to_str().ok())
.and_then(|v| v.strip_prefix("Bearer "));
if presented != Some(&*state.access_token) {
warn!(path = %request.uri().path(), "rejected request without a valid access token");
return error(StatusCode::UNAUTHORIZED, "missing or invalid access token");
}
next.run(request).await
}Uploads stream. A file up to 8 MiB goes to the bucket in one put; a larger one switches to a multipart upload, so memory stays flat:
/// Objects up to this size are written in one request; larger ones stream as
/// a multipart upload so memory use stays flat.
const SINGLE_PUT_LIMIT: usize = 8 * 1024 * 1024;Uploads also support conditional writes, which let two callers avoid overwriting each other:
/// `If-None-Match: *` creates only; `If-Match: <etag>` replaces only that version.
fn put_mode(headers: &HeaderMap) -> Result<PutMode, Response> {
let header_value = |name| {
headers
.get(name)
.map(|v| v.to_str().map(|s| s.trim_matches('"').to_string()))
.transpose()
.map_err(|_| error(StatusCode::BAD_REQUEST, "invalid precondition header"))
};
if header_value(header::IF_NONE_MATCH)?.as_deref() == Some("*") {
return Ok(PutMode::Create);
}
if let Some(etag) = header_value(header::IF_MATCH)? {
return Ok(PutMode::Update(UpdateVersion {
e_tag: Some(format!("\"{etag}\"")),
version: None,
}));
}
Ok(PutMode::Overwrite)
}The API it serves:
| Request | Success | Errors |
|---|---|---|
PUT /files/{key} | 201 with {"key", "size", "etag"} | 412 if If-None-Match: * and the file exists, if If-Match names an old version, or if a conditional write is over 8 MiB |
GET /files/{key} | 200, streamed body, ETag header | 404 if the file doesn't exist |
GET /files?prefix= | 200 with [{"key", "size", "etag"}] | |
DELETE /files/{key} | 204 | |
GET /health | 200 ok (no token needed) |
Every file route returns 401 with {"error": "missing or invalid access token"} when the token is wrong, and 502 when the bucket itself fails.
The service logs JSON to stdout, which the Operator collects.
Run it on your machine
Install the tools
You need Docker (Docker Desktop, OrbStack, or Docker Engine), and:
| Tool | What it does here | Install |
|---|---|---|
alien | Your CLI: releases the service, onboards customers, reads logs | curl -fsSL https://alien.dev/install | sh |
alien-deploy | Sets up and updates the air-gapped site. A real site's admin runs it; here, you do | curl -fsSL https://alien.dev/install | sh -s -- --binary alien-deploy |
kind, kubectl, helm 3.14 or later | The local cluster and the customers' deployments | kind, kubectl, helm |
Rust, Zig, and cargo-zigbuild | Build the service for Linux | rustup, then cargo install cargo-zigbuild |
jq, openssl | Read JSON output and make tokens | Your package manager |
Clone the repository. The example's Cargo.toml takes its dependency versions from the repository's Cargo workspace, so build it from inside the clone:
git clone https://github.com/alienplatform/alien.git
cd alien/examples/customer-kubernetes
npm install # @alienplatform/core, which alien.ts is written withRun every command below from this directory.
Create the customers' cluster
./local/cluster.sh upThis creates:
- A kind cluster called
alien-demo(kubectl contextkind-alien-demo). - S3-compatible storage inside it, with one bucket per customer:
customer-1-files,customer-2-files,customer-3-files. - A registry at
localhost:5001that plays the air-gapped customer's own registry.
The script also lets the kind nodes pull over plain HTTP from your manager and that registry. Real clusters pull over HTTPS and need none of this.
Every kubectl and helm command below names the context, so none of them touch another cluster in your kubeconfig.
Run your manager
Choose the manager's admin key, then start it:
ADMIN_KEY=ax_admin_$(openssl rand -hex 16)
docker run -d --name alien-manager --network kind -p 127.0.0.1:8080:8080 \
-v alien-manager-data:/data \
-e BASE_URL=http://alien-manager:8080 \
-e ALIEN_ADMIN_TOKEN=$ADMIN_KEY \
ghcr.io/alienplatform/alien-manager
until curl -sf http://localhost:8080/health >/dev/null; do sleep 1; doneBASE_URLis the address customer clusters use to reach the manager. Here it's the container's name on kind's network. In production it's your manager's public HTTPS URL.- Your laptop reaches the same manager at
localhost:8080. /dataholds all of its state: releases, images, deployments, and keys.- Without
ALIEN_ADMIN_TOKEN, the first start generates a key and prints it once (docker logs alien-manager).
Point the CLI at it:
alien login --manager http://localhost:8080 --token $ADMIN_KEY
alien whoamiRelease the service
alien releaseThis builds the container for Linux and pushes the image into your manager, which records the release. You don't need a registry of your own. The first build takes several minutes.
Onboard two customers
Make an access token per customer, then onboard them:
CUSTOMER_1_ACCESS=$(openssl rand -hex 24)
CUSTOMER_2_ACCESS=$(openssl rand -hex 24)
alien onboard customer-1 --platforms kubernetes \
--secret-input accessToken=$CUSTOMER_1_ACCESS --json > customer-1.json
alien onboard customer-2 --platforms kubernetes \
--secret-input accessToken=$CUSTOMER_2_ACCESS --json > customer-2.json
jq . customer-1.jsononboard registers the customer and returns what to send their Kubernetes admin:
token: their cluster's token. The cluster uses it to pull the chart and images from your manager, report status, and send logs, only as this customer.helm.command: the commands the admin runs once.helm.values: avalues.yamlfor their bucket, which the admin fills in.
Without --json, onboard prints the same as ready-to-send instructions.
Set up, as each customer's admin
This is the initial setup each customer's admin runs, once. Two things differ from helm.command: the commands use localhost:8080, where your laptop reaches the manager, and they name the local cluster's context.
for n in 1 2; do
token=$(jq -r .token customer-$n.json)
printf '%s' "$token" |
helm registry login localhost:8080 --insecure --username customer-$n --password-stdin
helm install files oci://localhost:8080/charts/files --plain-http \
--kube-context kind-alien-demo --namespace customer-$n --create-namespace \
--set management.name=customer-$n \
--set-string management.token="$token" \
--values local/customer-$n.yaml \
--wait --timeout 5m
doneThe values file tells the chart where the customer's bucket is:
# What customer-1's admin passes to the chart: where the service keeps its
# files. For Amazon S3 with the pod's own AWS identity, leave out the
# endpoint and keys.
infrastructure:
bucket:
type: storage
service: s3
bucketName: customer-1-files
endpoint: http://s3.storage.svc
accessKeyId: demo-key
secretAccessKey: demo-secretEach helm install starts the Operator. It connects to your manager, fetches the release, and deploys the service. In a minute or two both customers show as running:
alien deployments ls
kubectl --context kind-alien-demo -n customer-1 get podsIn each namespace, files-... is the Operator and api-... is your service. The cluster pulled the chart, the Operator, and your image from your manager alone.
Call a customer's service
The service listens on port 8080 inside each customer's cluster. To try it from your laptop, forward the port and send the customer's access token:
kubectl --context kind-alien-demo -n customer-1 port-forward svc/api 9080:8080 &
curl -s -w '\n' -X PUT --data-binary 'quarterly numbers' \
localhost:9080/files/reports/q3.txt \
-H "Authorization: Bearer $CUSTOMER_1_ACCESS"
curl -s -w '\n' localhost:9080/files/reports/q3.txt \
-H "Authorization: Bearer $CUSTOMER_1_ACCESS"
kill %1The PUT returns 201 with the key, size, and ETag. The GET returns quarterly numbers.
- The service checks its own token. Send customer-2's token to customer-1 and the service answers
401. - Bodies stream in both directions, so large files never sit in memory on the way.
The file is now in customer-1-files, the customer's own bucket.
Ship an update
Change the health route in src/main.rs to report a version:
.route("/health", get(|| async { "ok, v2" }))Then release:
alien releaseBoth Operators pick up the new release on their next check-in and roll it out. Nobody runs helm upgrade:
alien deployments ls # update-pending, then running on the new release
kubectl --context kind-alien-demo -n customer-2 port-forward svc/api 9081:8080 &
curl -s -w '\n' localhost:9081/health # ok, v2
kill %1Read the logs
Each Operator collects its service's logs and sends them to your manager:
alien logs --deployment customer-1/customer-1 --since 15m2026-09-30T08:28:41.543Z INFO api stored file
2026-09-30T08:28:41.599Z WARN api rejected request without a valid access token
2026-09-30T08:30:18.883Z INFO api bucket readyAdd an air-gapped customer
Some sites have no network path to your manager. They still run the same chart and get every release, as signed folders someone carries in on a USB drive, a data diode, or a one-way transfer.
Architecture diagram. Left: Your cloud containing Alien manager, Signs updates. Right: customer-3 site containing Kubernetes containing alien-deploy sync; site registry; api.
Each trip has two halves:
- Online, on any machine that reaches your manager,
alien-deploy syncsends the site's reports and downloads the next update into a folder. - Inside the site, the admin runs
alien-deploy syncagain. It checks the signature, pushes the images to the site's registry, installs or upgrades the chart, waits for the service, and writes a report with status and logs.
Your manager signs every update, and the site checks each one against your key. After the first update, only image layers the site doesn't have are carried. The Operator at the site never connects anywhere.
Onboard the site
CUSTOMER_3_ACCESS=$(openssl rand -hex 24)
alien onboard customer-3 --platforms kubernetes --airgapped \
--secret-input accessToken=$CUSTOMER_3_ACCESS --json > customer-3.json
jq . customer-3.jsontokenis the site's token. It stays on the online machine and can only download this site's updates and send its reports.bundleSigningKeyis your manager's key (ed25519:...). The site trusts updates signed with it. Give it to the admin over a separate channel from the token, so a tampered update can't also carry a forged key.commandis how the admin starts, on the online machine.
Download the first update, online
Use localhost:8080 where the command says http://alien-manager:8080:
mkdir -p airgap && cd airgap
alien-deploy sync --token $(jq -r .token ../customer-3.json) --manager http://localhost:8080This creates customer-3-sync/ with the update in to-site/. The first update carries every image, the chart, and alien-deploy builds for the site, so it's large.
Apply inside the site
The admin runs alien-deploy sync from the directory that holds customer-3-sync/. The first time, they pass the site's registry, their Helm values, and your key:
alien-deploy sync \
--registry localhost:5001/vendor --insecure-registry \
--namespace customer-3 --values ../local/customer-3.yaml \
--kube-context kind-alien-demo \
--trusted-key $(jq -r .bundleSigningKey ../customer-3.json)It verifies the update, pushes the images to localhost:5001, installs the chart, waits for the service, and writes a report into customer-3-sync/from-site/.
It remembers the registry, namespace, values, and context, and the site remembers your key. Later syncs need no options, and an update signed with any other key is refused.
Your laptop reaches both the manager and the cluster, so this run also sent the report back. At a real site, the admin carries the folder out and runs alien-deploy sync online, which sends the report and downloads the next update in the same trip.
alien deployments ls
alien logs --deployment customer-3/customer-3 --since 15mShip the next release
cd ..
# change "ok, v2" to "ok, v3" in src/main.rs
alien release
cd airgap && alien-deploy syncOn your laptop, that one command does both halves. The update is a few megabytes: only the layers that changed.
More alien-deploy commands:
alien-deploy sync --dry-runshows what an update will change before it applies anything.alien-deploy sync --fullincludes every image layer, for sites whose reports never come back.alien-deploy rollbackreturns the site to the release it ran before the last sync. To keep it there, pin it on your side withalien deployments pin customer-3/customer-3 <release>. Otherwise the next trip brings the latest release again.
Clean up
cd ..
docker rm -f alien-manager && docker volume rm alien-manager-data
./local/cluster.sh down
rm -rf airgap customer-1.json customer-2.json customer-3.jsonGoing to production
Run the manager
Run it where customer clusters can reach it over HTTPS:
docker runon a VM behind a TLS proxy.- The Helm chart on your Kubernetes.
- The Terraform module on Amazon ECS.
Set BASE_URL to its public URL and keep /data on a persistent, backed-up volume. Send its telemetry to your OpenTelemetry backend; logs arrive there tagged with alien.deployment_id.
Onboard customers
Run alien onboard and send the admin what it prints: the token, the Helm commands, and the values.yaml for their bucket. Their cluster needs outbound HTTPS to your manager's URL and nothing else.
For Amazon S3 with the pod's own AWS identity, the admin leaves endpoint, accessKeyId, and secretAccessKey out of the values.
Call the services
A customer's service is reachable inside that customer's cluster. Run your own software in the cluster to call it, or put an ingress in front of it that the customer approves. The service checks its own access token on every request, so keep one per customer next to the customer's record.
Air-gapped sites
They need alien-deploy, a container registry of their own, and a way to move a folder in and out.
Stage releases
alien release reaches every connected customer within a minute and each air-gapped site on its next trip. Use channels and pins to stage it. See Rollouts.
Adapt it
Next
Remote tools for an AI agent
Keep the agent loop in your product and run its tool calls in a private Worker next to the customer's files.
Deploy with Flux or Argo CD
Run an Alien deployment in a Kubernetes cluster from Git, with Flux or Argo CD. For your own clusters, and for customers whose platform team installs everything through GitOps.