Deploy with Flux or Argo CD
This example installs an Alien deployment in a Kubernetes cluster from a Git repository, with Flux or Argo CD. You commit one file. Flux or Argo CD installs the Helm chart Alien builds from your alien.ts, and your releases reach the cluster from then on.
Use it in two cases:
- Your own clusters. You already deploy your internal services with Flux or Argo CD, and you want the Alien stack you run for yourself to be deployed the same way.
- A customer's cluster. Their platform team accepts only Kubernetes-native installs and applies everything through their own Flux or Argo CD.
Both cases use the same chart and the same file. The only difference is who commits it.
How it fits together
Architecture diagram. Left: Your cloud containing Your manager, Releases, Helm chart, images. Right: Kubernetes cluster containing Flux or Argo CD; Namespace containing Operator; Your pods.
Three parts, each with one job:
- Your manager holds your releases, images and Helm charts. It is the Alien service you already publish releases to.
- Flux or Argo CD installs the chart in the cluster and keeps it at the version Git names.
- The Alien Operator is a small service the chart runs in the cluster. It connects out to your manager over HTTPS, rolls out each release, sends logs, and runs commands. Nothing connects into the cluster.
So the Operator stays, and it works with your GitOps tool, not instead of it. Flux or Argo CD owns what is installed. The Operator owns rolling out your releases inside it.
Before you start
- A Kubernetes cluster with Flux or Argo CD installed.
- The
alienCLI, signed in. - Outbound HTTPS from the cluster to your manager.
Target Kubernetes in your stack
Add "kubernetes" to the stack's platforms in alien.ts, next to the clouds you already deploy to. Alien then builds a Helm chart for every release, next to the CloudFormation and Terraform packages it builds for each cloud in the list.
import * as alien from "@alienplatform/core"
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
.cpu(0.5)
.memory("512Mi")
.port(8080)
.build()
export default new alien.Stack("acme-agent")
// The clouds you deploy to, plus Kubernetes.
.platforms(["aws", "gcp", "azure", "kubernetes"])
.add(api, "live")
.build()Publish a release:
alien releaseCreate the deployment and get its values
Create a setup link for the cluster. For your own cluster, the admin is you.
alien onboard internal --allow you@acme.com --platforms kubernetesOpen the link and choose On-prem, then Kubernetes, then Helm. Choose On-prem even when the cluster runs in AWS, Google Cloud or Azure: it installs into a cluster you already operate. The page shows a values.yaml and a helm install command. You don't run the command. You take two things from the page and put them in Git:
- The chart: the
oci://address and the--versionin thehelm installcommand. - The values: the whole
values.yaml, as shown.
The values that matter:
| Value | What it is |
|---|---|
management.url | Your manager's address |
management.enrollmentCode | A one-use code that lets the Operator register. It is valid for one hour. |
management.deploymentId, management.audience | Identify the deployment the code belongs to |
serviceAccountPrefix | The deployment's resource prefix |
The enrollment code is the only credential. The Operator trades it for its own key the first time it starts and ignores the code afterwards, so the file in Git holds no long-lived secret.
Commit one file
Put the chart address and the values in a HelmRelease for Flux, or an Application for Argo CD, and commit it to the repository your cluster syncs from. The examples below use oci://registry.example.com/charts/acme-agent-operator: replace it with the address from the setup page, and paste your values.yaml under values. The chart is public, so Flux and Argo CD need no credentials to pull it.
Flux pulls the chart from the address on the setup page. Commit:
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
name: acme-agent
namespace: acme-agent
spec:
interval: 10m
url: oci://registry.example.com/charts/acme-agent-operator
ref:
semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: acme-agent
namespace: acme-agent
spec:
interval: 10m
# Without retries, Flux stops after one failed install or upgrade
# until someone forces a reconcile.
install:
remediation:
retries: 3
upgrade:
remediation:
retries: 3
chartRef:
kind: OCIRepository
name: acme-agent
values:
management:
url: https://manager.example.com
enrollmentCode: replace-with-the-enrollment-code
deploymentId: dep_replace_me
audience: https://manager.example.com
serviceAccountPrefix: replace-with-the-resource-prefixUse v1 instead of v1beta2 on Flux 2.6 and newer.
If you run your own manager with alien serve or the alien-manager image, it serves the chart at oci://<manager>/charts/<stack-id> and asks for credentials. Create a kubernetes.io/dockerconfigjson Secret with the deployment's token and add secretRef to the OCIRepository.
Install each deployment in its own namespace.
Watch it come up
Flux or Argo CD installs the chart. The Operator starts, registers with the enrollment code, fetches your latest release and deploys it.
kubectl -n acme-agent get pods
alien deployments lsThe deployment shows Running in a minute or two. A later alien release reaches the cluster in a few minutes. From here it behaves like every other Alien deployment: logs, commands, release pinning and rollbacks work the same way.
What happens after
A new release. Run alien release. The Operator rolls it out in the cluster. You don't change Git.
A new chart version. Each release also publishes a new chart version: 1.0.0, 1.0.1, 1.0.2. With the ranges above (1.x in Flux, 1.* in Argo CD) your GitOps tool picks it up on its next sync, so the chart follows your releases without a commit. A published version never changes.
Hold a version. Pin it in Git: ref.semver: "1.0.2" in Flux, targetRevision: "1.0.2" in Argo CD. To go back, pin the version that ran before.
Apply the file again. Nothing changes. The Operator already has its own key and ignores the used code.
Remove the install. Delete the HelmRelease or the Application. The chart's cleanup job removes what the Operator created. Argo CD needs version 3.3 or newer and both finalizers from the example.
Keep the code out of Git
To keep even the one-hour code out of the repository, put it in a Secret and point the chart at it:
kubectl -n acme-agent create secret generic acme-agent-enrollment \
--from-literal=enrollment-code=<enrollment-code>management:
url: https://manager.example.com
enrollmentCodeSecret:
name: acme-agent-enrollment
deploymentId: dep_replace_me
audience: https://manager.example.com
runtime:
imagePullSecrets:
- name: operator-image-pullThe chart can't read that Secret while it renders, so it can't build the Operator's first pull credential from the code. runtime.imagePullSecrets names a pull Secret you create for the Operator image's registry.
Buckets, databases and other infrastructure
A stack with only containers needs nothing else.
If your stack has frozen resources, such as Storage, a Queue or a Vault, each one maps to infrastructure that already exists in the cluster's cloud account. Create it with the Terraform module Alien builds for the cluster, and leave the chart to Flux or Argo CD:
- In the setup page, choose the Terraform method for your cluster, and set
helm_install_enabled = falsein the module. - Run
terraform apply. It creates the buckets, roles and other resources. - Add the module's
chart_infrastructure_jsonoutput to your file as theinfrastructurevalue.
A Postgres resource uses a database you provide: add its connection to the same JSON.
What the cluster needs
- HTTPS to your manager with a trusted certificate. The Operator and the nodes' image pulls both use it. Plain HTTP fails with
ImagePullBackOff. - A default StorageClass. The Operator keeps a small volume. EKS Auto Mode has no default StorageClass; the chart can create one with
clusterBootstrap.storageClass.default. Enable that in one install only, because a StorageClass belongs to the whole cluster. - A network plugin that enforces NetworkPolicy. EKS Auto Mode enforces it already. On standard EKS, turn on the network policy controller: set
enableNetworkPolicyto"true"in the VPC CNI add-on configuration.
clusterBootstrap:
storageClass:
default:
enabled: true
name: auto-ebs
provisioner: ebs.csi.eks.amazonaws.com
parameters:
type: gp3
encrypted: "true"To restrict the Operator's own network access, turn on its NetworkPolicy in restricted mode and list the ports it may use. A listed port is allowed to any destination:
runtime:
networkPolicy:
enabled: true
mode: restricted
dns:
# kubectl -n kube-system get svc kube-dns
clusterIPs: ["172.20.0.10"]
egress:
ports: [443, 6443, 5432] # HTTPS, the API server, and your bindings, such as a databaseGood to know
- The Operator's Secret. The Operator creates its encryption key and its other secrets once, in the Secret
<release>-operator, and never replaces them. Keep that Secret: the key unlocks the Operator's stored state. A delete leaves it in place, so a reinstall in the same namespace finds its data. - Pull credentials. The chart renders one pull Secret from the code,
<release>-bootstrap-pull, for the first image pull. The Operator keeps its refreshed credential in a separate Secret,<release>-registry, so a sync never overwrites it. - Argo CD and version ranges. Recent Argo CD versions resolve
1.*for OCI Helm sources. Where yours doesn't, pin an exact version and let Renovate or Argo CD Image Updater open the bump. - Remote Operator. A Remote Operator reads Helm release history. Install a chart that has one with Helm or Flux, not Argo CD.
Next
- Kubernetes: how a Kubernetes deployment works, and the other ways to set one up.
- Run a service in your customers' Kubernetes clusters: a complete project you can run on your laptop.
- Rollouts: release channels, pinning and rollbacks.
Run in customer Kubernetes
Ship one Rust service to every customer's Kubernetes cluster, including air-gapped sites, with one Helm install per customer and outbound-only updates.
A complete application
Deploy a gateway, dashboard, API, worker, scheduler, Postgres, Redis, and object storage as one release into each customer's cluster.