Konstruct 0.5

Released: May 2026

Highlights

• Global vs. org-scoped resources — every shareable resource (cluster templates, pipeline templates, Helm templates, environments, GitOps catalog items) can now be created once and made available to every organization, or scoped to a specific list of orgs
• API keys redesign — refreshed list page with sortable columns and filters, dedicated activity page per key, and refreshed revoke dialog
• MCP support — generate MCP-flavoured API keys to drive Konstruct from AI assistants (Claude Code, Codex, Gemini CLI)
• Deploy GitOps catalog items — pick clusters, environments, and configure values from a guided modal; envs are namespace-aware so duplicate names don't collide
• Sharper "Available to" everywhere — every list, detail, and edit page tells you whether a resource is Global (visible to every org) or scoped to a specific org
• Multi-org create flows — registering a template, environment, or catalog item in multiple orgs at once is now a single form submission

Global vs. org-scoped resources

The 0.5 release introduces a single mental model for sharing resources across organizations. When you create one of the following resources, you choose its availability scope:

Scope	Behaviour
All organizations (Global)	Stored in the default namespace. Visible to every org, including ones created later. Only Platform Admins / super-users can create Global resources.
Specific organizations	Stored once per selected org's namespace. Visible only to those orgs.

Global resources are tagged with a green Global badge in lists; org-scoped resources show the org's display name in a gray badge.

Resources that support availability scoping:

• Cluster templates — share a vetted cluster blueprint across orgs
• Pipeline templates — share CI workflows across orgs
• Helm templates — share Helm chart packaging templates across orgs
• Environments — share a deployment target (e.g. staging, prod) and reuse it across orgs
• GitOps catalog items — share a catalog application across orgs

When you create a resource and pick All organizations, one record is created in the default namespace and every org sees it. When you pick Specific organizations, one record is created per selected org's namespace — a single form submission fans out to multiple POSTs under the hood.

Smart defaults for create flows

When you enter any create flow with a specific org selected in the Viewing as dropdown, that org is pre-selected as the availability scope. Under All organizations the form defaults to Global. You can still amend either way before submitting.

Edit + view pages now show scope inline

Every detail and edit page now surfaces the availability scope as the first row:

• Cluster templates view + update
• Pipeline templates view + update
• Helm templates edit

The scope on a resource cannot be amended after creation (you'd have to delete and recreate), so the field is read-only on edit pages. The detail card row also lets you confirm at a glance whether you're looking at a Global resource or one bound to your org.

Org switching redirects you home

When you're on a resource detail or edit page and you switch the Viewing as dropdown to an org that doesn't have access to that resource, Konstruct now redirects you back to that resource's list page (in the new org's context). Global resources stay visible across orgs and don't trigger the redirect, and the All organizations view never redirects either. This behaviour is now consistent across cluster templates, pipeline templates, Helm templates, GitOps catalog items, app repositories, and environments.

API keys redesign

The API keys page has a new layout: a header with key-contract info pills (Max lifetime: 30 days, Inherits your role, Shown only once), a filter bar (search, Type, Role, Created), and a sortable table with relative Last used times so dormant keys are easy to spot. Per-row actions are now a kebab menu with View activity and Delete. See API keys for the full reference.

Activity page

Each key now has its own dedicated activity page (reachable from the kebab menu's View activity) with a breadcrumb back to the keys list, search by tool name or path, Method + Status filters, and a sortable table:

Column	Notes
Time	Relative time
Method	HTTP verb pill
Tool / Path	The MCP tool name when the call came from the MCP server, otherwise the API path
Status	HTTP status with a green dot for 2xx and a red dot for 4xx/5xx
Latency	Server-side processing time in ms
Source	The user-agent (e.g. Claude Code 1.0.43) when present
Source IP	Client IP for the request

Refreshed revoke dialog

The revoke confirmation dialog now spells out the consequences of revocation and shows an In active use callout when the key was used in the last 24 hours, so you know which clients are about to start failing.

MCP keys

API keys can now be issued in two flavours:

• API key (prefix konst_api_) — for scripts, CI, and direct API calls.
• MCP key (prefix konst_mcp_) — for AI assistants connecting through the Konstruct MCP server. Use it in Claude Code, Codex, Gemini CLI, etc.

When you generate an MCP key, the success modal includes a tabbed snippet generator with ready-to-paste configurations for the supported MCP clients.

GitOps catalog: deploy + manage

Deploy modal

The Deploy flow for a catalog item is a guided 3-step modal:

1. Define scope — App release name, organization, "deploy as" (shared or team-specific), team(s).
2. Configure — Fill in the application/infrastructure values defined by the catalog item (<APP_VERSION>, <DOMAIN>, etc.).
3. Select clusters — Pick a workload cluster and one or more environments to deploy to.

Several improvements landed for 0.5:

• Org lock for org-scoped catalog items. If the catalog item is registered to a specific org (not Global), the Organization picker on step 1 is replaced with a read-only label of that org. Only Global catalog items let you pick from your accessible orgs.
• Real-time release-name uniqueness check. As you type the App release name, Konstruct compares it against every deployment you can see (org + Global + any other namespace) and shows an inline error like "A deployment with this release name already exists in Global" before you can advance.
• Environment disambiguation by namespace. Environments that share a name across namespaces (a dev in your org and a dev in Global) are now shown distinctly throughout the modal — both in the + menu where you pick them and in the chips that appear after selection. Each entry is suffixed with its scope: dev (Global) or dev (test4).
• Smarter availability for cluster envs. The + menu now unions two sources of truth — the environment's own clusters list and the cluster's own env list — so envs always show up regardless of which side has the association.
• Catalog item create form — when you add a new catalog item, you pick Application (YAML), Infrastructure (Terraform IaC), or Hybrid from a card-based selector. Each form has the right fields for that type. The new Available to toggle decides whether the catalog item is Global or org-scoped.

Deployed tab

The new Deployed tab on the GitOps catalog page lists every deployment Konstruct currently manages, grouped by catalog item:

• Sortable + filterable (search, organization, cluster, environment).
• Each deployment row shows the release name, target cluster, and attached environments. Envs are shown as <name> (Global) or <name> (<org>) so duplicates stay distinguishable.
• A delete action sends DELETE /catalog-deployment/{namespace}/{instance_name}, removing the deployment.

Catalog item delete

Deleting a deployed catalog item now hits DELETE /catalog-deployment/{namespace}/{instance_name} (was {namespace}/{instance_name}-{cluster_name}), aligning with the renamed backend resource shape.

Workload cluster environments

Environments attached to a workload cluster are now stored as { name, namespace } pairs on the cluster, not just names. This unblocks two long-standing limitations:

• An org's staging and Global's staging can both be attached to the same cluster without colliding.
• Deployments referencing those envs send the namespace alongside the name, so the platform knows which env to target.

The change is transparent in the UI — env multiselects on the workload cluster form already disambiguate by namespace label (e.g. staging: Global) — and the wire payload now sends:

"env": [{ "name": "staging", "namespace": "default" }]

Older clusters that only carry the legacy environments name list continue to render correctly.

Cluster templates

Three empty states

The Cluster templates list page now renders one of three role-aware empty states when the list is empty, matching the latest design:

• Platform admin (no org selected) — "No cluster templates yet" with both Learn more and Create cluster template CTAs.
• Team admin (org selected) — "{Org} does not have any templates yet" — same CTAs, scoped to that org.
• Read-only role — "No templates yet for {Org}" with a dashed-outline illustration and only the Learn more CTA. Cluster templates are administered by your platform admins; once one's been assigned, you'll see it here.

Custom template fields

Cluster templates can now expose typed input fields (string / enum / boolean / secret) that get filled in at cluster-creation time. When you provision a workload cluster from a custom template, Konstruct fetches the template's input schema, renders the right form controls, validates required fields, and inlines secrets into the cluster's customTemplateFieldsInputs. The mgmt + workload cluster forms group these as Template → Configuration → Parameters.

The cluster panel on the Clusters page also gained a new Parameters tab that displays the values used to provision a cluster from a custom template (read-only, secrets masked).

App registration & deployment

Cleaner register flow

The app repositories register form was reworked to remove confusing UX and align with the rest of the platform:

• Pipeline template — when you pick a custom template, the dropdown shows pipeline templates from your org and from Global (suffixed with (Global)). Submit ships both pipeline_template_name and pipeline_template_namespace to the backend so the rename across namespaces no longer hides templates from the form.
• Helm chart template — same dropdown pattern as Pipeline; sends helm_template_name + helm_template_namespace on submit.
• Stages — the environments dropdown now lists all environments your org can see (org + Global), not just the ones currently associated with a cluster. The org dropdown the form used to derive its query from is gone — it just uses the org you're "Viewing as".
• Validation cleanup — form validation messages now read "Required" instead of the raw Zod default.

Deploy

Deploying a registered app from either the dedicated deploy form or the three-dots menu now:

• Sends environment_namespace alongside environment_name, so the platform knows exactly which env to deploy to even when names collide across namespaces.
• Lists envs with the same merging logic the workload cluster form uses (org + Global, namespace-disambiguated labels).

Edit

The edit form was reworked to match the register flow — pipeline + Helm template dropdowns, env stage list, namespace-aware payloads, and the org_id → namespace field rename to match the backend Environment struct.

Applications page empty states

The Applications page used to show a generic "An error occurred while fetching applications details" banner whenever the backend returned 500 from /applications. 0.5 detects two common causes and shows a targeted empty state instead:

• No management cluster yet. A freshly created org with no cluster provisioned. The page shows "No management cluster yet" with a Provision management cluster CTA pointing at the Clusters page.
• Management cluster is no longer available. An older org whose EKS cluster was deleted in AWS but the org record still references it. The page shows "Management cluster is no longer available" with guidance to provision a new cluster or remove the org if it's no longer needed.

Other 500s still fall back to the existing red banner, but now with the actual backend message included so you can copy it into a support ticket.

Permission gating

• The All organizations option in the Available to control is now visible only to Platform Admin and konstruct-super-user roles. Non-admin users only see Specific organizations — they can't accidentally publish a Global resource. If a non-admin lands on a form pre-defaulted to All organizations (e.g. cluster template create), the form auto-flips to Specific organizations on mount.
• The top-bar ADMIN badge next to the "Viewing as" selector now only appears when a super-user is on the All organizations view; switching to a specific org hides it.

Other improvements

• Catalog item values endpoint now lives at GET /catalog-application/{name}/{namespace}/values (was /{name}/values) so values can be looked up correctly for org-scoped catalog items.
• Catalog application list uses the getAll + filter pattern when no org is selected, and the namespaced endpoint when an org is selected — symmetric with the Deployed tab.
• Env list/edit — environment edit page now scopes its cluster-association picker to the env's own org (read-only display) when the env is org-scoped; Global envs keep the org dropdown so platform admins can attach clusters from any org.
• Workload cluster form — the Advanced options block was retired; its only configurable field (engineVersion) is now sent as a hidden default.
• Self-hosted detection for the License key sidebar entry is now strict (only selfHosted: true shows the link) so SaaS users never see a license key page that doesn't apply to them.

Backend payload changes worth noting

For platform admins integrating with the Konstruct API directly, these payload renames are visible in 0.5:

Endpoint	Old	New
Create catalog deployment	name, body	catalog_application_name + catalog_application_namespace
Cluster response env attachments	environments: string[]	env: [{ name, namespace }] (legacy environments still emitted)
Catalog deployment env attachments	environments: string[]	env: [{ name, namespace }] (legacy environments always sent empty)
Application register / update	pipeline_template_name	adds pipeline_template_namespace
Application register / update	helm_template_name	adds helm_template_namespace
Application deploy	environment_name	adds environment_namespace
Workload cluster create	cluster_template_name	adds cluster_template_namespace + cluster_template_git_* fields
Environment create / update	org_id	renamed to namespace
Catalog item values	GET /catalog-application/{name}/values	GET /catalog-application/{name}/{namespace}/values

The legacy fields are still accepted on the read side where applicable to keep older clients working through the upgrade.

Breaking Changes

None for end users. Existing org-scoped resources continue to work as-is — resources created before 0.5 default to org-scoped and stay visible to the org they were created in. Platform Admins can re-create them as Global to share across orgs.

Direct API consumers should review the Backend payload changes table — these are non-breaking renames with legacy-field fallbacks on the read side, but new clients should prefer the new field names.

Upgrade notes

• The Helm chart bumps to 0.5.0. Follow the installation guide for the upgrade path.
• New backend fields (*_namespace suffixes) are populated by the BE on existing data during upgrade; a one-time reconciliation reindexes the cluster env field on each provisioned cluster.
• API keys created on 0.4 and earlier remain valid; the View activity page picks up new entries as soon as the key is used post-upgrade.

What's Next?

• API keys — generate API and MCP keys, configure clients
• Cluster templates — including the new custom template fields
• GitOps catalog — deploy flow and the Deployed tab
• App registration — refreshed register, edit, and deploy flows
• Environments — namespace-aware environments