Create a Stack from axio.yaml

Upload a valid axio.yaml or axio.yml stack blueprint. Axio parses the manifest and imports placement, runtime, variables, secrets, policies, and runner settings — then you review and create the stack.

Warning

Important

axio.yaml is not Platform as Code. Stack blueprints live in IaC repositories and describe how to provision a stack (variables, runtime, workflow). PaC manifests under platform-config/ declare organization resources such as projects, workspaces, and environments. See Organization overview.

This path is different from Manual setup. Manual setup walks through repository, engine, backend, workflow, and policies in the Axio UI and does not read axio.yaml during creation. Use From axio.yaml when your repository already contains a manifest.

Info

Prerequisites

  • Permission to create stacks (Member or higher with iac:manage in the target project, workspace, or environment scope).
  • A valid axio.yaml or axio.yml file on your computer.
  • The Project, Team workspace, and Environment named in the manifest placement section must already exist in Axio (or match defaults such as Default Project / Default Workspace).
  • If the manifest declares runtime.cloud.provider, a matching cloud credential must exist under Administration → Integrations → Cloud providers, or you select one on the review step.
  • Optional: if the manifest includes a sourceControl block, the named Git connection must exist under Administration → Integrations → Source Control.
STACK CREATION

Create Stack from axio.yaml

Go to Stacks → New Stack and choose From axio.yaml. Upload your manifest — Axio validates it and pre-fills the review screen.

i
The axio.yaml file defines your stack blueprint.

Required fields include metadata.name, runtime.iac.engine, and runtime.iac.version. When a cloud provider is declared, runtime.cloud.credential (or credentialId) and runtime.cloud.region are required as well.

Create Stack

From `axio.yaml`

Click Choose file and select axio.yaml or axio.yml. Axio parses the file immediately and shows validation errors if anything is missing or invalid.
✓
Manifest loaded Placement, runtime, variables, secrets, and policies imported from the file.
ProjectAbcd Corp
Team workspaceplatform-team
EnvironmentDevelopment
Stack namemy-app-stack
IaC engineTerraform 1.9.5
Cloud providerAWS · us-east-1
Cloud credentialabcd-aws-prod
Variables / policies3 variables · 1 policy pack
✓
Axio resolves placement from the manifest Values come from placement.project, placement.workspace, and placement.environment (names or IDs). Stack name comes from metadata.name.
If the manifest declares a cloud provider but the credential name does not match an existing connection, select the correct credential on this step before creating the stack. Workflow templates are chosen when you Run stack, not during creation.
✓
That's it! Your stack is created and appears in the Stacks inventory.
</>
Repository & file location

For upload-based creation, Git is optional. To tie the stack to a repository, include a sourceControl block in the manifest (connection, repository, branch/tag/commit, and workingDirectory). When Axio discovers manifests from Git, it looks for axio.yaml or axio.yml at the repository root or under the configured working directory (for example terraform/axio.yaml). After creation, use Sync from repository on the stack detail page to pull manifest updates.

Best Practices

  • Keep axio.yaml in the repository root or the IaC working directory referenced by sourceControl.workingDirectory.
  • Use meaningful values for metadata.name and metadata.description.
  • Declare explicit cloud credentials in the manifest — Axio does not auto-select ambient runner credentials.
  • Store sensitive values using Axio secrets or secret references in the manifest, not plain text.
  • Review imported variables, policies, and runner targeting on the review step before clicking New stack.
  • Prefer From axio.yaml for GitOps-style stacks; use Manual setup only when no manifest exists yet.