Skip to content

Stacks

A stack connects one Terraform or OpenTofu project to a managed lifecycle: a Git repository, branch and project root; the IaC engine and version; where the Terraform state lives; the configuration bundles and cloud integrations its runs receive; and the worker pool that executes them. Stacks live in a space.

Creating a stack, changing its details, engine, version or labels, and deleting it require the Admin role. Write users can trigger runs and change the stack's source, triggers, variables and bundle attachments. See Identity & Access.

Stack list

The Stacks page lists every stack with its Status (the most recent run's status, or No runs), Name, Space, Execution Target (Public or the private pool's name), IAC engine and Created date.

Each row's three-dot menu holds View Details, Add to favorites (or Remove from favorites, see Favorite stacks), Edit and Delete.

Creating a stack

Click Create Stack to open the four-step wizard.

Basic Info

  • Stack Name
  • Space: the space the stack belongs to. It cannot be changed later.
  • Worker Pool: Public Worker Pool, or one of your private pools. The picker warns when a private pool has no active workers or is inactive.

Git Config

  • Source type: VCS Integration (a connected provider; automated triggers where the provider delivers webhooks, see Triggers) or Raw Git URL (a public HTTPS repository; no automated triggers, runs start manually or through the API).
  • Integration, Repository and Branch. Only repositories enabled on the integration are offered.
  • Path (optional): the project root, the directory inside the repository where the tool runs. Leave it empty when the code is at the repository root. See how source is used in runs.
  • IaC Engine: OpenTofu (default) or Terraform, and the Version.
  • Terraform State: Zenfra-managed (default; Zenfra stores and locks state for you) or Customer-managed S3 (Your source declares an s3 backend; Zenfra never touches the state). This choice cannot be changed after creation. Read Terraform State before choosing Customer-managed S3.

Bundles

Optionally attach configuration bundles (in priority order) and Cloud Integrations, each with Read (for plan runs) and Write (for apply/destroy runs) permissions.

Review

Check the four cards, use Edit to go back, then Create Stack.

Stack detail

The header shows the stack's name and the status of its last run (Idle when there is none), the repository, branch, project root, engine and version, and the worker pool.

Trigger offers three run types:

Run type What it does
Plan & Apply Requires approval before applying. The standard deployment workflow: a tracked run plans, waits for your confirmation, then applies.
Plan Only Preview changes without applying.
Destroy Remove all managed resources.

If a run is already active, Zenfra asks Trigger Run While Active? before starting another one. The three-dot menu holds Add to favorites (or Remove from favorites), Edit Stack and Delete Stack.

Tabs:

  • Runs: the stack's run history with a trigger-source filter. See Runs.
  • Resources: the inventory of resources this stack manages, indexed from its state; available for Zenfra-managed state. See Resources.
  • Configuration: a read-only view of the stack. The Source card shows Project root (working directory) (Repository root when unset) and, when push triggers are on, Also triggers on with the project globs, or Push globs (not in effect) when the stack has no project root because every push already triggers it.
  • Schedules: drift detection schedules for this stack. See Schedules and drift detection below.
  • Settings: Stack ID, Space, Worker Pool, Terraform State (read-only), Created and Last Run.

Editing a stack

Edit Stack opens a page with these sections. Each form has Reset and Save changes; bundle and cloud integration attachments are saved immediately.

  • Stack details: name and worker pool. The space cannot be changed after creation; to move a stack to a different space, delete and recreate it.
  • Source code: source type, integration, repository, branch and path, plus Automation Triggers: the Push Trigger switch and Project globs. See Triggers.
  • IAC configuration: engine and version.
  • Labels: the stack's labels.
  • Bundles: attach or detach bundles. Bundles that attach themselves through a label are listed under Attached by label and cannot be detached here; see Attaching by label.
  • Cloud integrations: attach an integration with Read or Write permission (Write includes read). Integrations attached through an auto-attach label appear as Auto-attached.
  • Danger zone: Delete this stack, confirmed by typing the stack's name. Deletion is a soft delete: the stack disappears from the list while its record and run history are kept for audit; its bundle and cloud integration attachments and its drift schedules are removed. It is not self-service reversible.

Labels

Labels are short lowercase tags on a stack, such as prod, team-payments or pci. Set them under Edit Stack > Labels: type a label and press Enter, then Save changes. With the Terraform provider, set labels on zenfra_stack.

  • A label is 1 to 63 characters: lowercase letters, digits, ., _ and -, starting with a letter or digit. Uppercase is refused, not converted.
  • A stack has at most 20 labels. Spaces around a label are trimmed and duplicates are dropped.

Labels do two things:

  • Attach bundles. A configuration bundle attaches itself to every stack that carries one of its auto-attach labels, within the bundle's space and the spaces that inherit its bundles. See Attaching by label.
  • Feed plan policies. A plan policy reads the labels as input.zenfra.stack.labels, so a rule can apply only to stacks labelled prod, or require that every stack has a team label.

A run keeps the labels the stack had when the run was created. Changing labels affects later runs only, and a policy re-evaluated on an existing run still sees that run's labels.

Schedules and drift detection

A drift schedule periodically runs the stack to compare its configuration against the real infrastructure. Schedules live on the stack's Schedules tab under Drift detection. Creating, editing and deleting them requires the Admin role, and drift detection is available on the Starter plan and above: on the Free plan the tab shows Drift detection requires Starter plan, and plan changes go through support@zenfra.cloud. After a downgrade, existing schedules can still be viewed and deleted but no longer fire.

A schedule has:

  • Name.
  • Cron expression: 5-field cron (minute, hour, day of month, month, day of week), minimum cadence 15 minutes.
  • Timezone: an IANA name the cron fires in; defaults to UTC.
  • Enabled: switch it off to pause without deleting.
  • Reconcile (auto-apply): on, each fire creates a tracked run (Plan & Apply, so the changes still wait for approval); off, a plan-only proposed run.
  • Ignore state: off (the default), a fire is skipped while the stack holds a lock because a run is active; on, the schedule fires anyway and the run queues behind the active one.

The tab lists each schedule's Schedule, Timezone, Mode (Reconcile or Plan only, plus Ignore state), Next run and Status (Enabled or Paused; Plan required when the plan no longer includes drift detection).

When a drift run finds differences, the stack shows a Drift detected banner with the time of the last check and a link to that run, the affected resources carry a Drift signal in Resources, and the run appears with a Drift badge in the Runs tab.