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:
requestNamespace | The request goes to | The form asks for |
|---|---|---|
{from: form} (default) | the namespace the developer types | Name, Namespace |
{from: group} | the namespace named after the Group the developer picks | Name, Group |
{from: group, annotation: <key>} | the namespace in that annotation on the picked Group | Name, Group |
{from: fixed, namespace: <name>} | the defined namespace | Name |
The setting applies to every namespaced Promise on the portal. Cluster-scoped Promises are unaffected.
Requirements
@syntasso/plugin-ske-backendv0.24.0or later. Upgrade the backend plugin before you setrequestNamespace. Earlier versions of the backend plugin cannot handle the new request form.@syntasso/plugin-ske-frontendv0.22.0or later.- Portal Controller
v0.6.1or later.
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.
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.
The Group check trusts the Backstage catalog. If users can register their own catalog locations, they can:
- Create a Group named after any namespace, or with any namespace in its annotation.
- List themselves as members of that Group.
- 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.
