Inputs and secrets

An input is a value that differs between deployments, such as your backend's URL, a retention period, or a license key. You say who provides it; Alien asks for it, validates it, and passes it to your code as an environment variable.

Declare inputsCopy Anchor Link

The running example needs two values from you:

const config = alien.inputs({
  // You provide these when you onboard a customer.
  acmeApiUrl: alien.string({
    providedBy: "developer",
    required: true,
    label: "acme API URL",
    description: "Where the deployment reports processing results.",
    pattern: "^https://",
    env: "ACME_API_URL",
  }),
  signingSecret: alien.secret({
    providedBy: "developer",
    required: true,
    label: "Signing secret",
    description: "Signs results sent to the acme API.",
    generate: { length: 64 },
    env: { name: "ACME_SIGNING_SECRET", targetResources: ["processor"] },
  }),

It also asks the customer's admin three questions at initial setup, the one-time step they run in their account. Continue the same object, then attach the set to the stack:

  // The customer's admin answers these at initial setup.
  retentionDays: alien.integer({
    providedBy: "deployer",
    required: false,
    label: "Retention (days)",
    description: "How long to keep processed documents.",
    default: 90,
    min: 1,
    max: 3650,
    env: "RETENTION_DAYS",
  }),
  ocrLicenseKey: alien.secret({
    providedBy: "deployer",
    required: true,
    label: "OCR license key",
    description: "License key for the OCR engine.",
    env: { name: "OCR_LICENSE_KEY", targetResources: ["processor"] },
  }),
  summaries: alien.boolean({
    providedBy: "deployer",
    required: false,
    label: "Generate summaries",
    description: "Summarize documents with a model in your cloud account.",
    default: false,
  }),
})

export default new alien.Stack("acme-docs")
  .inputs(config)
  // .add(...) each resource, as before
  .build()

providedBy: "developer" means you supply the value. providedBy: "deployer" means the customer's admin answers it at initial setup. See Developer and deployer inputs.

Input types are string, secret, number, integer, boolean, enum, and stringList.

• Validation (pattern, minLength, min, max, minItems) is enforced the same way in every setup method.
• env maps the value to an environment variable, and targetResources limits it to named workloads.

Every option is in the stack reference.

Every input needs a label, and a required input also needs a description. Input ids use letters, digits, and _, and can't be all caps like an environment variable name.

pattern must match the whole value, and it has to run in CloudFormation rules and Terraform validation blocks as well as JavaScript. The build rejects a pattern that uses any of these:

• /.../ delimiters
• backreferences, lookarounds, named captures, or non-capturing groups
• Unicode classes (\p{...}) or inline flags

Developer and deployer inputsCopy Anchor Link

Each input has one or two providers. Alien asks for it in every initial setup path: the deployment portal (the setup page Alien hosts for the admin), CloudFormation, Terraform, Helm, and the CLI.

A developer input never appears on the customer's surfaces or in the setup templates they run. Keep deployer inputs few: every one is a question the admin must answer before your product works.

Required and optionalCopy Anchor Link

An input with required: true must have a value before the deployment is created. An optional input can declare a default; without one, its variable is unset and your code must handle that.

Use platforms to ask for an input only on some platforms, so a Kubernetes-only value doesn't appear on an AWS setup page.

Generated secretsCopy Anchor Link

generate: { length } tells Alien to create a random secret (16 to 256 characters) once per deployment and reuse it across every update. Use it for values nobody should type, such as a signing key shared between the deployment and your backend.

A generated secret must be providedBy: "developer"; a value you provide replaces it.

Customer secrets never pass through AlienCopy Anchor Link

A secret the deployer provides is never sent to Alien. The customer's admin writes it into the deployment's deployer-secrets vault, in their own secret store: SSM Parameter Store on AWS, Secret Manager on Google Cloud, Key Vault on Azure, or a Kubernetes Secret.

1. 1

   Initial setup shows whereAlien

   The deployment status shows the secret's name in the customer's store and a command to write it.

2. 2

   Admin writes the valuecustomer admin

   The value goes straight into the customer's secret store, in their account.

3. 3

   Workload startsdeployment

   Alien checks only whether the secret exists. The workload reads the value at start and gets it as OCR_LICENSE_KEY.

Until a required deployer secret exists, the deployment waits in WaitingForSecrets and the workloads don't start.

For the same reason, alien-deploy deploy refuses --secret-input: no setup method carries a deployer secret's value. Validation options apply only to developer-provided values, because Alien never sees the deployer's.

Locally, set a deployer secret with alien dev vault set deployer-secrets ocr-license-key --stdin. The key is the input id in kebab case.

Links, not inputs, for resource accessCopy Anchor Link

Don't ask for credentials to resources in the stack. A Worker linked to documents already has scoped access through its cloud identity; there is no bucket key to collect.

Use inputs for real choices and for values that live outside the stack: a license, an external endpoint, your backend's URL. See Using resources.

Optional resourcesCopy Anchor Link

A deployer boolean can decide whether a resource exists. .enabled(input) creates the resource only when the answer is true:

const model = new alien.AI("summarizer").enabled(config.summaries).build()

The input must be a deployer boolean that is required or has a default. A declined resource isn't created, and it's left out of the setup templates and the IAM policies.

• Frozen. The resource keeps the answer given at initial setup.
• Live. The resource follows later changes to the input. Turning it off deletes the resource and its data; turning it back on recreates it empty.

Workers, Containers, and Daemons can be gated too: turning off a live workload removes it the same way as deleting it from a release.

Change inputs laterCopy Anchor Link

Change a deployment's input values after it's created, from the dashboard, the CLI, or the API.

When you change inputs:

• Use input ids from the release, such as retentionDays, not their environment variable names.
• Inputs you omit keep their values. List an id in clearInputIds to clear it; its validation rules still apply.
• A generated input can't be cleared, because clearing it would make Alien generate a new value. Set a new value to rotate it.
• A secret the deployer provides can't be set here or anywhere through Alien. The admin writes it into the deployment's deployer-secrets vault.
• Secret values are never returned.
• Alien validates the values, rebuilds the environment variables, and requests an update when runtime configuration changed. The response has runtimeUpdateRequested and outcome: "accepted" with the update operation, or "unchanged". Accepted doesn't mean the new values are serving yet; check the deployment with alien deployments get.

The key must belong to the deployment's workspace. The workspace parameter takes that workspace's name or ID; it doesn't grant access to another workspace.

Viewer and manager-runtime keys can't change inputs. A deployment or deployment group key can't set a developer-only input. See the API reference for the request schema and concurrency checks.

NextCopy Anchor Link

• Permissions: what each workload can access
• Commands: send commands from your backend to code in a deployment
• Deployment UX: what the customer's admin sees