Docs

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.

Each cluster's Operator holds one outbound connection to your manager. Releases, logs, and your backend's calls all travel over it.

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:

examples/customer-kubernetes/alien.ts
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 every alien release rolls 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 the api permission profile gives the container read and write access to that bucket and nothing more.
  • The accessToken input is set per customer when you onboard them, and reaches the container as ACCESS_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:

examples/customer-kubernetes/src/main.rs
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:

examples/customer-kubernetes/src/main.rs
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);
examples/customer-kubernetes/src/main.rs
/// 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:

examples/customer-kubernetes/src/main.rs
/// 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:

examples/customer-kubernetes/src/main.rs
/// `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:

RequestSuccessErrors
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 header404 if the file doesn't exist
GET /files?prefix=200 with [{"key", "size", "etag"}]
DELETE /files/{key}204
GET /health200 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:

ToolWhat it does hereInstall
alienYour CLI: releases the service, onboards customers, reads logscurl -fsSL https://alien.dev/install | sh
alien-deploySets up and updates the air-gapped site. A real site's admin runs it; here, you docurl -fsSL https://alien.dev/install | sh -s -- --binary alien-deploy
kind, kubectl, helm 3.14 or laterThe local cluster and the customers' deploymentskind, kubectl, helm
Rust, Zig, and cargo-zigbuildBuild the service for Linuxrustup, then cargo install cargo-zigbuild
jq, opensslRead JSON output and make tokensYour 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 with

Run every command below from this directory.

Create the customers' cluster

./local/cluster.sh up

This creates:

  • A kind cluster called alien-demo (kubectl context kind-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:5001 that 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; done
  • BASE_URL is 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.
  • /data holds 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 whoami

Release the service

alien release

This 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.json

onboard 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: a values.yaml for 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
done

The values file tells the chart where the customer's bucket is:

examples/customer-kubernetes/local/customer-1.yaml
# 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-secret

Each 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 pods

In 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 %1

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

examples/customer-kubernetes/src/main.rs
.route("/health", get(|| async { "ok, v2" }))

Then release:

alien release

Both 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 %1

Read the logs

Each Operator collects its service's logs and sends them to your manager:

alien logs --deployment customer-1/customer-1 --since 15m
2026-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 ready

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

An online machine downloads the signed update. Someone carries the folder in, and alien-deploy sync verifies and applies it.

Each trip has two halves:

  1. Online, on any machine that reaches your manager, alien-deploy sync sends the site's reports and downloads the next update into a folder.
  2. Inside the site, the admin runs alien-deploy sync again. 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.json
  • token is the site's token. It stays on the online machine and can only download this site's updates and send its reports.
  • bundleSigningKey is 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.
  • command is 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:8080

This 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 15m

Ship the next release

cd ..
# change "ok, v2" to "ok, v3" in src/main.rs
alien release
cd airgap && alien-deploy sync

On 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-run shows what an update will change before it applies anything.
  • alien-deploy sync --full includes every image layer, for sites whose reports never come back.
  • alien-deploy rollback returns the site to the release it ran before the last sync. To keep it there, pin it on your side with alien 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.json

Going to production

Run the manager

Run it where customer clusters can reach it over HTTPS:

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

Prompt
Use the alien customer-kubernetes example (github.com/alienplatform/alien/tree/main/examples/customer-kubernetes) as a model. Package the part of my product that must run in customers' Kubernetes clusters as an Alien stack with .platforms(["kubernetes"]): a Container with .port(port), a frozen Storage for the customer's bucket, and a developer secret input for a per-customer access token the service checks on every request. Read https://alien.dev/docs/infrastructure/platforms/kubernetes.md and https://alien.dev/docs/infrastructure/platforms/deployment-models.md first.

Next

On this page