Docs

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.

Git names the chart version. Flux or Argo CD installs the chart. The Operator rolls out each release. Nothing connects into the cluster.

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 alien CLI, 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.

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

Create 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 kubernetes

Open 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 --version in the helm install command.
  • The values: the whole values.yaml, as shown.

The values that matter:

ValueWhat it is
management.urlYour manager's address
management.enrollmentCodeA one-use code that lets the Operator register. It is valid for one hour.
management.deploymentId, management.audienceIdentify the deployment the code belongs to
serviceAccountPrefixThe 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:

acme-agent.yaml
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-prefix

Use 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 ls

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

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

  1. In the setup page, choose the Terraform method for your cluster, and set helm_install_enabled = false in the module.
  2. Run terraform apply. It creates the buckets, roles and other resources.
  3. Add the module's chart_infrastructure_json output to your file as the infrastructure value.

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 enableNetworkPolicy to "true" in the VPC CNI add-on configuration.
Create a default StorageClass on EKS Auto Mode
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 database

Good 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

On this page