paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

Merge pull request #31041 from backstage/freben/ns

Browse Source 
relax the wording around namespaces a bit
This commit is contained in:
Fredrik Adelöw
2025-09-02 11:17:04 +02:00
committed by GitHub
parent 89247ccf44 d791dd7d27
commit bfd5e68ba8
1 changed files with 21 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-catalog/descriptor-format.md
+21 -6
View File
@@ -239,18 +239,33 @@ Example: `visits-tracking-service`, `CircleciBuildsDumpV2_avro_gcs`
### `namespace` [optional]
The ID of a namespace that the entity belongs to. This field is optional, and
currently has no special semantics apart from bounding the name uniqueness
constraint if specified. It is reserved for future use and may get broader
semantic implication later.
has no special semantics apart from bounding the name uniqueness constraint if
specified.
For now, it is recommended to not specify a namespace unless you have specific
need to do so. This means the entity belongs to the `"default"` namespace.
This can be used for ingesting entities (of the same kind) from different
contexts where their names might otherwise end up overlapping. An example of
this is to import users and groups from your HR system into the default
namespace, but also wanting to ingest users from your GitHub enterprise
installation and those potentially having the same names as the HR system users.
Then you could set up your GitHub enterprise ingestion to place those users in a
`"ghe"` namespace to avoid collisions.
If you do not specify a namespace, it assumes the value `"default"`.
Namespaces must be sequences of `[a-zA-Z0-9]`, possibly separated by `-`, at
most 63 characters in total. Namespace names are case insensitive and will be rendered as lower case in most places.
most 63 characters in total. Namespace names are case insensitive and will be
rendered as lower case in most places.
Example: `tracking-services`, `payment`
Note that using namespaces typically means that you need to explicitly specify
the namespace when referring to the entity. In some contexts, notably in entity
catalog-info definition YAML files, you often refer to other entities by name.
When they are in a different namespace, you need to use the syntax
`<namespace>/<name>`, while if they are in the default namespace you can omit
that part as a shorthand. Therefore it's practical to use the default namespace
for simplicity until it's necessary to use supplemental ones. See [the references article](references.md) for more information.
### `uid` [output]
Each entity gets an automatically generated globally unique ID when it first