> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Stack Profiles
> Capture a working stack as a reusable, versioned, parameterised template - then roll it out to any cluster.
A Stack Profile is a reusable template captured from a real [stack](/concepts/stacks). Build a stack once, save it as a profile, and instantiate it on any cluster - with parameters filled in per environment. Profiles are versioned, so you can publish updates, diff versions, and see which deployments have drifted behind the latest.
A profile is a **template**, not a running deployment. Instantiating a profile produces a stack draft on a target cluster, which you then review and commit like any other stack change.
***
## Why use profiles
* **Standardise** a golden stack (monitoring, ingress, security baseline) and reuse it across clusters.
* **Parameterise** the bits that differ per environment - domains, replica counts, sizes - instead of copy-pasting YAML.
* **Version** changes with a changelog and channels, and **diff** any two versions.
* **Track drift**: a profile shows how many instantiations are behind its latest version.
***
## Anatomy of a profile
| Concept | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Version** | An immutable snapshot of the stack spec. Versions increment as you publish updates and carry a `channel` (e.g. `stable`) and an optional changelog. |
| **Parameters** | Typed inputs callers fill in at instantiation. Each parameter has a `type` (`string`, `number`, `boolean`, `enum`, or `secret`), and may be `required`, have a `default`, an `enum` list, or a validation `pattern`. |
| **Visibility** | `organisation` (default) keeps the profile private to your org; `public` shares it more widely. Independently of visibility, a profile can be [shared with specific organisations](#share-with-specific-organisations). |
| **Category & tags** | Metadata for organising and searching profiles. |
| **Publisher** | The organisation that owns the profile. Publisher names, logos, and verified badges help you identify trusted profiles. Verified Ankra profiles appear first in profile results. |
| **Drafts** | An editable working copy used to build or edit a profile before publishing a version. |
Secret-typed parameters and other sensitive values are redacted when a profile is captured, so credentials are never baked into a shared template.
***
## Create a profile
You can create a profile two ways:
Capture a profile directly from a stack already running on a cluster.
Optionally include addon configurations. This is the fastest path - build
and validate the stack first, then snapshot it.
Import a profile from exported IaC content, for sharing across
organisations or storing in Git.
In the portal, **Save as Profile** starts with the stack's existing name and description. Categories combine common options with values your organisation already uses, and tags are suggested as you type.
Choose who can use the profile before saving:
* **This organisation** keeps it private to members of your organisation.
* **Public** makes it available to every organisation.
* **Specific organisations** keeps it private and grants access to the organisation slugs you enter.
Public and specific-organisation sharing require an organisation admin. Quick save publishes immediately. Save and customise opens the profile builder so you can review inputs before publishing.
```bash theme={null}
# Capture from a cluster's stack
POST /org/stack-profiles
{
"name": "platform-baseline",
"description": "Shared platform services",
"category": "platform",
"tags": ["baseline", "production"],
"visibility": "organisation",
"share_organisation_slugs": ["partner-org"],
"source_cluster_id": "...",
"stack_name": "platform",
"include_addon_configurations": true
}
```
Organisation admins can upload a publisher logo under **Organisation Settings**. Profile cards fall back to the organisation's initials when no logo is configured.
### Build with drafts
For more control, work in a draft: create a draft (optionally seeded from a cluster's stack), edit its spec and parameters, validate it, then publish it as a new version.
`POST /org/stack-profiles/drafts` - optionally seeded from an existing profile or a source cluster stack.
Update the draft's spec and parameters, then `POST /org/stack-profiles/drafts/{draft_id}/validate` to surface any issues before publishing.
`POST /org/stack-profiles/drafts/{draft_id}/publish` with a channel and changelog. This creates the profile (or a new version of it).
***
## Instantiate a profile
Instantiating turns a profile into a stack on a target cluster:
Pick the profile and, optionally, a specific version. When no version is
given, the profile's **current** version is used - the pinned version,
which can be older than latest after a rollback.
Supply values for the profile's parameters. Required parameters must be set; others fall back to their defaults.
Instantiation creates a stack draft on the cluster (with the resolved addons and manifests). Review it.
Commit the draft to deploy, exactly like any other [stack](/concepts/stacks) change.
### From the CLI
The [Ankra CLI](/integrations/ankra-cli) can instantiate a profile directly. Inspect a
profile's parameters first, then apply it to a cluster as a draft (or pass `--deploy`
to deploy in one step):
```bash theme={null}
# See the profile's versions and parameters
ankra stack-profiles get
# Create a draft on a cluster, binding parameters
ankra stack-profiles apply --cluster production \
--set replicas=3 \
--set-env api_token=MONITORING_API_TOKEN
# Or apply a specific version and deploy immediately
ankra stack-profiles apply --cluster production --version 3 --deploy
```
For **secret** parameters use `--set-file ` or `--set-env ` rather
than `--set` so the value never appears in your shell history or process list.
***
## Demo a profile before you deploy it
Instantiating a profile puts it on a real cluster. When you only want to see what it deploys - to review a new version, to check a public profile before adopting it, or to show someone the stack running - launch it as a **demo** instead.
A demo installs the profile into its own throwaway namespace on your organisation's staging cluster, quota-bounded and on a timer, and deletes itself when the timer runs out. Open the profile's **Demos** tab to launch one. See [Stack Profile Demos](/guides/stack-profile-demos).
***
## Share with specific organisations
Making a profile `public` exposes it to everyone. When you want to share a golden stack with one partner, customer, or sibling organisation - and nobody else - share it directly instead:
* Shared organisations can **list, view, diff, export, and instantiate** every version of the profile. They cannot edit, delete, or re-share it.
* The profile keeps its `organisation` visibility; sharing is an explicit per-organisation grant.
* The target organisation is identified by its **organisation slug** (found under organisation settings). Ask the other organisation for theirs.
* Only **organisation admins** can grant or revoke shares, and a grant re-runs the plaintext-secret scan over every published version - a profile that still carries plaintext secrets cannot be shared. Grants and revokes are recorded in the audit log.
* Revoking a share hides the profile from the other organisation again. Stacks they already deployed from it keep running - they just stop seeing profile updates.
In the portal, open a profile you own and use **Share**. Via the API:
```bash theme={null}
# Grant an organisation access
POST /org/stack-profiles/{profile_id}/shares
{ "organisation_slug": "acme-corp" }
# List grants / revoke one
GET /org/stack-profiles/{profile_id}/shares
DELETE /org/stack-profiles/{profile_id}/shares/{share_id}
```
Profiles shared **with** your organisation show up in your profile list marked "Shared with you".
***
## Versioning, diffing, and updates
* **Save a new version** from an updated source stack, or by publishing an edited draft.
* **Diff** any two versions to see what changed: `GET /org/stack-profiles/{profile_id}/diff?from_version=1&to_version=2`.
* **Diff a draft** before publishing it, against the version it was opened from: `GET /org/stack-profiles/drafts/{draft_id}/diff`. The draft is redacted first, so the comparison shows what publishing would actually store rather than your working copy. A draft that will create a brand-new profile has no base, so everything in it reads as added.
* **Update tracking**: a profile reports `outdated_instantiation_count` and `has_update_available` so you can find deployments that are behind and re-instantiate them on the newer version.
* **Export IaC** for a version to store the template in Git or move it between organisations.
***
## See where a profile is deployed
The profile detail page has a **Deployments** tab listing every stack your organisation
has created from the profile: the cluster, the stack (a link to the running stack, or to
the still-open draft when it was never committed), its current state, the profile version
it runs, the non-secret parameter values it was instantiated with, and when. Rows running
a version older than the profile's current version carry an **Update** action that opens
the update flow pre-filled with the values used last time.
A stack that is deleted from its cluster drops off the list, as does a draft that is
discarded, so the tab always reflects what is actually running. The same rows are served by
`GET /org/stack-profiles/{profile_id}/instantiations`.
***
## API
All endpoints are under `/org/stack-profiles` and require authentication; write operations require a CSRF header for browser-originated requests.
| Method | Path | Purpose |
| --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/org/stack-profiles` | List profiles (paginated) |
| `POST` | `/org/stack-profiles` | Create a profile from a cluster's stack, with optional visibility and organisation shares |
| `GET` | `/org/stack-profiles/metadata-suggestions` | List categories and tags already used by your organisation |
| `POST` | `/org/stack-profiles/import` | Import a profile from IaC content |
| `GET` | `/org/stack-profiles/{profile_id}` | Profile detail, versions, and update status |
| `PATCH` | `/org/stack-profiles/{profile_id}` | Update metadata (name, description, category, tags, visibility; making a profile public requires the org admin role) |
| `DELETE` | `/org/stack-profiles/{profile_id}` | Delete a profile |
| `POST` | `/org/stack-profiles/{profile_id}/current-version` | Pin the current version (roll back / roll forward) |
| `POST` | `/org/stack-profiles/{profile_id}/versions` | Save a new version from a source stack |
| `GET` | `/org/stack-profiles/{profile_id}/versions/{version}` | Get a version's spec and parameters |
| `GET` | `/org/stack-profiles/{profile_id}/versions/{version}/iac-export` | Export a version as IaC |
| `GET` | `/org/stack-profiles/{profile_id}/diff` | Diff two versions |
| `GET` | `/org/stack-profiles/{profile_id}/instantiations` | List the live deployments of the profile (cluster, stack, state, version, parameters) |
| `GET` | `/org/stack-profiles/{profile_id}/shares` | List the organisations a profile is shared with |
| `POST` | `/org/stack-profiles/{profile_id}/shares` | Share the profile with an organisation by slug (org admin role required) |
| `DELETE` | `/org/stack-profiles/{profile_id}/shares/{share_id}` | Revoke a share (org admin role required) |
| `GET`/`POST` | `/org/stack-profiles/drafts` | List or create drafts |
| `GET`/`POST`/`DELETE` | `/org/stack-profiles/drafts/{draft_id}` | Get, update, or delete a draft |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/validate` | Validate a draft |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/publish` | Publish a draft as a profile version |
See [Stacks](/concepts/stacks) for the deploy/commit flow and the [API Reference](/api-reference/introduction) for full schemas.