Skip to main content

Choosing the request namespace

For the complete setup and request lifecycle, see Send resource requests.

By default, the request form asks the developer to type the Kubernetes namespace their resource goes into. A Backstage portal's config.requestNamespace setting lets you choose it for them instead:

requestNamespaceThe request goes toThe form asks for
{from: form} (default)the namespace the developer typesName, Namespace
{from: group}the namespace named after the Group the developer picksName, Group
{from: group, annotation: <key>}the namespace in that annotation on the picked GroupName, Group
{from: fixed, namespace: <name>}the defined namespaceName

The setting applies to every namespaced Promise on the portal. Cluster-scoped Promises are unaffected.

Requirements​

  • @syntasso/plugin-ske-backend v0.24.0 or later. Upgrade the backend plugin before you set requestNamespace. Earlier versions of the backend plugin cannot handle the new request form.
  • @syntasso/plugin-ske-frontend v0.22.0 or later.
  • Portal Controller v0.6.1 or later.
note

Kratix does not create namespaces. Create each one before developers request resources into it, otherwise the request fails when it is applied.

Configuration​

Set requestNamespace in the config of a type: backstage entry in portals[]:

apiVersion: platform.syntasso.io/v1alpha1
kind: SKEIntegration
metadata:
name: portal-controller
spec:
type: portal-controller
version: v0.6.1
portals:
- name: prod
type: backstage
config:
requestNamespace:
from: group

If requestNamespace is invalid, the portal's request forms are not updated. They keep their current fields until you correct the value. The Promise-level sync pipeline for the portal fails with a message that names the portal and the invalid value.

From the Group's name​

With from: group, the Group field lists the Groups the developer is a direct member of (spec.members of the Group). The request goes to the namespace with the same name as the Group, so each Group name must be a valid namespace name. It must:

  • use only lowercase letters, numbers and hyphens
  • be at most 63 characters long
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
name: payments
spec:
type: team
children: []
members:
- alice

From an annotation on the Group​

If your Group names don't match your namespaces, name an annotation to read instead:

requestNamespace:
from: group
annotation: acme.io/k8s-namespace

A Group with acme.io/k8s-namespace: payments then sends its requests to payments, whatever the Group is called. A Group without the annotation is refused; its name is not used instead.

If you import Groups with an organisation provider, such as GitHub, LDAP or Microsoft Entra ID, the imported Groups may not have your annotation. You can add it with a small catalog processor.

One namespace for every request​

requestNamespace:
from: fixed
namespace: platform-team

Who can request and change a resource​

Each request records its Group in the resource's kratix.io/backstage-group annotation. That Group becomes the resource's owner in the Backstage catalog.

A request is refused, with a message saying why, when:

  • nobody is signed in (Group modes only);
  • the developer is not a member of the picked Group;
  • the namespace would not be a valid namespace name, or the Group lacks the annotation;
  • a resource with that name already exists in the namespace and belongs to another Group.

The Manage tab keeps the resource's existing namespace. Templates generated with from: group or from: fixed run ske:resolve-namespace, which checks recorded Group membership on updates and deletes, including for Groups sharing a namespace. The backend delete route also checks the recorded Group. Resources without one have no Group check.

Namespace policy is not a permanent access boundary

Changing to from: form regenerates Templates without ske:resolve-namespace, so Template updates no longer enforce recorded Group membership. The Manage tab's membership check is not backend enforcement. Keep Kubernetes RBAC, Git permissions and review controls in place when changing policy.

Only accept Groups from sources you trust

The Group check trusts the Backstage catalog. If users can register their own catalog locations, they can:

  1. Create a Group named after any namespace, or with any namespace in its annotation.
  2. List themselves as members of that Group.
  3. Create and change resources in that namespace.

To prevent this, only let Groups into the catalog from sources the platform team controls, such as an organisation provider or catalog locations that only the platform team can change. Use Backstage's catalog.rules setting to limit which locations can add Group entities.