Install on Kubernetes

Remote Operator setup in the dashboard generates everything for one Kubernetes installation: a Helm chart, a credentials Secret, and the Helm commands that install them. Nothing runs from the dashboard. You run each command against a Kubernetes context and namespace that you name.

For a first run in a test cluster, follow the quickstart. This page describes each part of the setup so you can review it and install it in other environments.

Open setupCopy Anchor Link

1. On the project overview, select Set up Remote operator. After the first installation exists, the button is Manage installations.
2. Select Set up manually instead. The first view is a prompt for a coding agent.
3. Under Installation platform, select Existing Kubernetes.

The setup page then shows these steps:

The page URL saves the installation, the namespace, the Kubernetes context, and the log scope. It never saves secret values.

You do not need to keep the URL. In a project that uses only Remote Operator, the project overview lists each installation whose operator has not registered yet under Unfinished setups. Select Resume setup to open that installation in setup again. The entry shows values expired when its registration token has expired.

Per-installation valuesCopy Anchor Link

Generate test values creates one installation in Alien and shows two files once. Save both outside version control. In the file and resource names below, <installation-id> is the installation's ID in Alien with underscores replaced by hyphens.

operator-credentials.yaml is a Kubernetes Secret that the install command creates before Helm runs. Helm never stores these values:

apiVersion: v1
kind: Secret
metadata:
  name: operator-<installation-id>-credentials
type: Opaque
stringData:
  sync-token: "<one-time registration token>"
  encryption-key: "<random 32-byte hex value>"
  collector-token: "<random 32-byte hex value>"

operator-values.yaml holds the non-secret Helm values that point the chart at that Secret:

remoteOperator:
  enabled: true
  existingSecret:
    name: operator-<installation-id>-credentials
    encryptionKeySha256: <SHA-256 of encryption-key>
  bootstrapIdentity: false
  syncTokenRevision: 0
  serviceAccountAnnotations: {}
  podLabels: {}

The chart checks that the live Secret contains sync-token and encryption-key, and that the SHA-256 of encryption-key matches encryptionKeySha256. After the first install, the encryption key must never change. Only sync-token changes, through credential rotation.

The registration token expires at the time the dashboard shows. If it expires before you create the credentials Secret, open the same installation in setup and select Generate replacement values. That button is available only until the operator registers. Replace the whole values file and the whole Secret file. If an earlier install or enable attempt already created the Secret, follow Repair a connection instead; do not replace its encryption key.

Choose the owning Helm releaseCopy Anchor Link

Under Owning Helm release, choose which Helm release owns the operator. Choose from your own installation records, not from the release name.

Product release is available only when the newest ready Helm package for the project's active release embeds the same operator image as this installation. While a newer package is building, setup waits. It never uses an older package instead.

Dedicated operator releaseCopy Anchor Link

Create a directory named remote-operator with crds and templates subdirectories. Download each file that setup shows into it:

The Download button in the review step saves the unsplit template, which also contains the shared CRD. Do not put that file in this chart. The release would own the CRD and delete it on uninstall. Use the per-file downloads.

If you change the Pod label and select Apply log scope again, download the chart files again. The review checkbox clears, because the chart you reviewed had the earlier label.

Select the review checkbox, then copy Install dedicated operator release. Run it from the directory that contains remote-operator/, operator-credentials.yaml, and operator-values.yaml. The command:

1. Checks that the namespace exists.
2. Stops if this installation already completed once. A completed installation cannot be installed again. Register a new installation instead.
3. Sets operator-credentials.yaml to owner-only permissions and creates the Secret. If the Secret already exists, the command continues only when it is identical to the file.
4. Runs helm install with --dry-run=server, then installs the chart:

helm install operator-<installation-id> ./remote-operator --namespace <namespace> --kube-context '<context>' --values operator-values.yaml --replace --atomic --wait --timeout 5m

To check the release afterwards, use Inspect this release. For a dedicated release it is:

helm status operator-<installation-id> --namespace <namespace> --kube-context '<context>'
helm history operator-<installation-id> --namespace <namespace> --kube-context '<context>'
kubectl --context '<context>' --namespace <namespace> get pods,pvc
kubectl --context '<context>' --namespace <namespace> get secret/operator-<installation-id>-credentials

Product releaseCopy Anchor Link

A product chart that Alien builds includes the operator, disabled by default (remoteOperator.enabled: false). The chart carries the annotation alien.dev/remote-operator-lifecycle: "v2", and the generated install, enable, upgrade, and restore commands check for it with helm show chart before they change the release.

The chart refuses to enable the operator on the first helm install. The release must first exist with the operator disabled, so Helm has a history revision to roll back to. For that reason setup gives two commands:

1. Install product release. Save the application values for this environment as product-values.yaml. The command runs helm install for the exact chart reference and version with --values product-values.yaml --set remoteOperator.enabled=false --set remoteOperator.bootstrapIdentity=false, first as a server dry run and then with --atomic --wait --timeout 5m.
2. Enable operator in the deployed product release. Run it only after step 1 succeeds. It creates the Secret from operator-credentials.yaml, runs helm upgrade --reuse-values --values operator-values.yaml --set remoteOperator.bootstrapIdentity=true to create the operator identity, then runs helm upgrade --reuse-values --set remoteOperator.bootstrapIdentity=false so later upgrades cannot create a second identity. If the identity records show a completed bootstrap, it skips the first upgrade. If the records are inconsistent, it stops.

Record the exact chart reference from the install command (repository-qualified chart name or OCI URL), the chart version, and the release name with your deployment records. Rotation and restore need the reference later; helm history shows the chart name and version but does not retain its repository or OCI source.

If the product release is already deployed, select Enable Remote Operator in an existing deployed product release and run only the enable command. It reuses the release's current application values.

Enabling the operator in a product release may create the shared access-request CRD, so a cluster administrator must approve it.

By default the product chart expects Helm's Secret storage backend. If you set HELM_DRIVER=configmap, also set remoteOperator.helmHistoryBackend=configmap and runtime.cleanup.onUninstall.helmHistoryBackend=configmap. The chart rejects the SQL and memory backends.

If the enable command stops with a pending revision, do not run it again. Use the guarded recovery command in Upgrade and roll back.

PrerequisitesCopy Anchor Link

Setup lists these before it shows any command:

• Bash, jq, yq, and OpenSSL on the machine that runs the commands.
• Helm 3.13 or later, or Helm 4. On Helm 4, the commands add --server-side=false.
• An existing namespace. Use a different namespace for each environment.
• A default StorageClass for the identity volume.
• Image pull access to the operator image.
• Outbound HTTPS from the namespace to the management endpoint in the generated template.
• For log collection, read access to the node log paths.
• A cluster administrator who reviews the shared access-request CRD and confirms that any existing definition is compatible. Do not replace or delete an existing CRD.

Verify the installationCopy Anchor Link

Setup waits for the operator to register and send a heartbeat. A heartbeat counts as fresh for five minutes. When the installation connects, select Run read-only pod diagnostic, or run a read-only operation yourself:

alien operations invoke --deployment <deployment-id> --operation kubernetes/get-pods

Setup marks the installation verified only after a read-only operation succeeds on that exact installation. A ready pod alone is not proof.

Next stepsCopy Anchor Link

• Rotate the connection key
• Upgrade and roll back
• Repair a connection
• Uninstall