Operations

Configure operations before generating the Helm template. The selected set changes what the generated operator image can do and what access it needs.

Start with read-only diagnostics. Add a mutating operation only when there is a concrete support or maintenance task that needs it.

Good operations answer one question or perform one repair:

• read Kubernetes events for one workload;
• inspect pod status;
• check a private service;
• restart a specific workload; or
• run a product-specific repair with typed inputs.

Avoid general shell, arbitrary SQL, or an unrestricted Kubernetes proxy. Those interfaces are difficult to review and turn a narrow operator into broad remote access.

Operations and commandsCopy Anchor Link

Define an Operation for a controlled capability that Remote Operator runs in the customer's environment. Each operation declares its risk and how to verify its result. An invocation runs when the project's operations approval policy allows it, or when a customer-approved access request already covers it. Invoke it with alien operations invoke. Define a Command for application RPC: your code registers a handler on a Worker, Container, or Daemon, and your backend invokes it with alien commands invoke. Commands have no approval policy or access requests, so use an Operation for anything that needs approval.

Access is additiveCopy Anchor Link

Selecting an operation is not enough by itself. It can only succeed when the local installation also has the required Kubernetes RBAC, cloud identity, network route, and service credentials.

Test each operation in a non-production installation. Check both success and denial. Keep returned results small and do not include customer records or secrets unless the operation explicitly requires them.

What is actually selectedCopy Anchor Link

Operations are named as plugin/operation. The current operator includes focused plugins for Kubernetes and services such as PostgreSQL, Redis, S3, RDS, CloudWatch, GCS, and Pub/Sub. Each plugin exposes a fixed set of operations with typed parameters.

For example, the S3 plugin exposes exactly these operations:

s3/head-bucket
s3/list-objects
s3/head-object

That is deliberately different from giving the operator a general AWS shell. Select the smallest operation that answers the support question, then grant its local identity only the corresponding IAM action.

question                  selected operation       local access still required
Can we reach the bucket?  s3/head-bucket           network + AWS identity
What objects are there?   s3/list-objects           s3:ListBucket
Does this object exist?   s3/head-object            s3:GetObject metadata access

Run an operation without an agentCopy Anchor Link

List the catalog, then invoke an operation enabled for the project:

alien operations list

alien operations invoke \
  --deployment acme/production \
  --operation kubernetes/get-pods \
  --params '{"namespace":"default","maxResults":10}'

The CLI waits up to 60 seconds by default. Add --timeout <seconds> for a different limit.

Request access for an operationCopy Anchor Link

When the project's operations approval policy does not allow an operation automatically, alien operations invoke does not run it. The command prints Access is required to run <plugin>/<operation>. and the command that requests access. With --json, the result has "status": "pending-approval".

Add --request-access to create the access request, wait for the customer to approve it, and then run the operation:

alien operations invoke \
  --deployment acme/production \
  --operation kubernetes/restart-pod \
  --params '{"namespace":"default","pod":"api-123"}' \
  --request-access --access-duration 1h

You can also create the request first, then invoke the operation after the customer approves it:

alien access-requests create \
  --deployment acme/production \
  --operation kubernetes/restart-pod \
  --params '{"namespace":"default","pod":"api-123"}' \
  --duration 1h

alien access-requests wait ar_123

The customer approves in their own environment. For a Kubernetes installation, the CLI prints the kubectl patch command that the customer runs in the cluster. A request lasts at most six hours.

An approved request allows the exact operation and parameters in the request, on that deployment, until the approval ends.

Only the principal that created an access request can use its approval. Your approved request does not let a teammate, or an API key, run the same operation. The project policy alone decides their invocation. A request that an API key created works only for that API key. The same rule applies to debug sessions.

Preview a plugin's installation permissionsCopy Anchor Link

Run alien operations permissions ./my-plugin --cloud aws --json before installing a plugin. Choose gcp or kubernetes with --cloud to preview those grants. The command works offline and uses the same permission compiler as setup. Provide the exact resources the installation will allow with repeated --s3-bucket-arn, --sqs-queue-arn, or --gcs-bucket flags. The compiler rejects a resource-dependent grant when its resource list is missing.

Kubernetes defaults to --permission diagnostics, which grants reads. --permission remediation also includes supported pod deletion and workload scaling declared by the plugin. Namespace or cluster scope comes from the installation. A plugin cannot use its manifest to widen that scope.

The output lists what the plugin's operations declare. Setup adds those rules to the permissions every operator has. See Kubernetes permissions.

See the CLI reference for complete commands and the JSON output format.

Build a custom pluginCopy Anchor Link

A custom plugin is a Rust program that exposes your own operations, such as a health check against your application's admin API. The plugin defines each operation once, with typed parameters and a typed result. The plugin generates its metadata.json from those definitions. alien operations check, package, and publish reject metadata that does not come from them.

1. Create the plugin:

   Copy Text

   alien operations init my-plugin
   cd my-plugin

   The plugin starts with one read-only health operation in src/lib.rs, registered in a TypedOperations registry, and a generate-metadata binary in src/bin/generate-metadata.rs.

2. Add your operations to the registry with OperationDefinition. Each definition sets the operation's name, risk tier, description, and permissions. The parameter and result types produce the inputSchema and outputSchema in metadata.json.

3. Regenerate metadata.json after every change to an operation:

   Copy Text

   cargo run --bin generate-metadata

4. Check the plugin:

   Copy Text

   alien operations check
   alien operations test

   alien operations check validates metadata.json, then builds and runs generate-metadata -- --check. It fails when metadata.json differs from the generated metadata, or when the plugin has no src/bin/generate-metadata.rs. alien operations test runs cargo test.

5. Build the bundle:

   Copy Text

   alien operations package

   The command runs the same metadata check, builds a Linux release binary for the architecture of the machine it runs on, and writes <name>-<version>.zip. To support both amd64 and arm64, build on each architecture and put both binaries in one bundle with the generated metadata.json.

6. Publish the bundle, then enable the plugin in the project's Operations settings:

   Copy Text

   alien operations publish ./my-plugin-0.1.0.zip

   alien operations publish rejects a bundle when an operation in its metadata.json has no inputSchema or outputSchema object.

To check a plugin that you do not trust, run alien operations check --manifest-only. It validates metadata.json and does not build or run the plugin's code.

The custom operations example is a complete typed plugin. It has a read-only doctor operation and a mutating throttle-export-automation operation that call an application's HTTP admin API, with tests that run the compiled plugin.

These commands stop with one of the following messages when the metadata is not generated.