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

Merge branch 'master' into gh-3788-auth-tutorial-docs

Browse Source 
# Conflicts:
#	docs/tutorials/quickstart-app-auth.md
This commit is contained in:
Jussi Hallila
2021-01-13 08:52:48 +01:00
parent 6d74776e12 5032aa4bba
commit 85fb668164
195 changed files with 6790 additions and 2494 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture-decisions/adr000-template.md
+32
View File
@@ -0,0 +1,32 @@
---
id: adrs-adr000
title: ADR000: [TITLE]
description: Architecture Decision Record (ADR) for [TITLE] [DESCRIPTION]
---
| Created | Status |
| ---------- | ------ |
| YYYY-MM-DD | Open |
# ADR000: [title]
<!-- These documents have names that are short noun phrases. For example, "ADR001: Deployment on Ruby on Rails 3.0.10" or "ADR009: LDAP for Multitenant Integration" -->
## Status
<!-- A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. -->
## Context
<!--
This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. -->
## Decision
<!-- This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..." -->
## Consequences
<!-- This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. -->
<!-- This template is taken from a blog post by Michael Nygard http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions -->
docs/architecture-decisions/index.md
+3 -2
View File
@@ -18,8 +18,9 @@ Records should be stored under the `architecture-decisions` directory.
### Creating an ADR
- Copy `0000-template.md` to `docs/architecture-decisions/0000-my-decision.md`
(my-decision should be descriptive. Do not assign an ADR number.)
- Copy `docs/architecture-decisions/adr000-template.md` to
`docs/architecture-decisions/adr000-my-decision.md` (my-decision should be
descriptive. Do not assign an ADR number.)
- Fill in the ADR following the guidelines in the template
- Submit a pull request
- Address and integrate feedback from the community
docs/assets/software-catalog/software-model-core-entities.drawio.svg
+3
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 8.5 KiB

docs/assets/software-catalog/software-model-core-entities.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.1 KiB

docs/assets/software-catalog/software-model-entities.drawio.svg
+3
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

docs/auth/oauth.md
+2 -3
View File
@@ -1,9 +1,8 @@
---
id: oauth
title: OAuth and OpenID Connect
description: This section describes how Backstage allows plugins to request
OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be
used for auth to various third party APIs
# prettier-ignore
description: This section describes how Backstage allows plugins to request OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be used for auth to various third party APIs
---
This section describes how Backstage allows plugins to request OAuth Access
docs/dls/figma.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: figma
title: Figma
description: Documentation on using Figma to build your own plugins for
Backstage
# prettier-ignore
description: Documentation on using Figma to build your own plugins for Backstage
---
We have a [Figma component library](https://www.figma.com/@backstage) that you
docs/features/kubernetes/index.md
+127
View File
@@ -0,0 +1,127 @@
---
id: overview
title: Kubernetes
sidebar_label: Overview
description: Monitoring Kubernetes based services with the service catalog
---
Kubernetes in Backstage is a way to monitor your service's current status when
it is deployed on Kubernetes.
## Configuration
Example:
```yaml
kubernetes:
serviceLocatorMethod: 'multiTenant'
clusterLocatorMethods:
- 'config'
clusters:
- url: http://127.0.0.1:9999
name: minikube
authProvider: 'serviceAccount'
serviceAccountToken:
$env: K8S_MINIKUBE_TOKEN
- url: http://127.0.0.2:9999
name: gke-cluster-1
authProvider: 'google'
```
### serviceLocatorMethod
This configures how to determine which clusters a component is running in.
Currently, the only valid value is:
- `multiTenant` - This configuration assumes that all components run on all the
provided clusters.
### clusterLocatorMethods
This is an array used to determine where to retrieve cluster configuration from.
Currently, the only valid cluster locator method is:
- `config` - This cluster locator method will read cluster information from your
app-config (see below).
### clusters
Used by the `config` cluster locator method to construct Kubernetes clients.
### clusters.\*.url
The base URL to the Kubernetes control plane. Can be found by using the
"Kubernetes master" result from running the `kubectl cluster-info` command.
### clusters.\*.name
A name to represent this cluster, this must be unique within the `clusters`
array. Users will see this value in the Service Catalog Kubernetes plugin.
### clusters.\*.authProvider
This determines how the Kubernetes client authenticates with the Kubernetes
cluster. Valid values are:
| Value | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. |
| `google` | This will use a user's Google auth token from the [Google auth plugin](https://backstage.io/docs/auth/) to access the Kubernetes API. |
### clusters.\*.serviceAccount (optional)
The service account token to be used when using the `serviceAccount` auth
provider.
## Role Based Access Control
The current RBAC permissions required are read-only cluster wide, for the
following objects:
- pods
- services
- configmaps
- deployments
- replicasets
- horizontalpodautoscalers
- ingresses
## Surfacing your Kubernetes components as part of an entity
There are two ways to surface your Kubernetes components as part of an entity.
The label selector takes precedence over the annotation/service id.
### Common `backstage.io/kubernetes-id` label
#### Adding the entity annotation
In order for Backstage to detect that an entity has Kubernetes components, the
following annotation should be added to the entity's `catalog-info.yaml`:
```yaml
annotations:
'backstage.io/kubernetes-id': dice-roller
```
#### Labeling Kubernetes components
In order for Kubernetes components to show up in the service catalog as a part
of an entity, Kubernetes components themselves can have the following label:
```yaml
'backstage.io/kubernetes-id': <BACKSTAGE_ENTITY_NAME>
```
### Label selector query annotation
You can write your own custom label selector query that Backstage will use to
lookup the objects (similar to `kubectl --selector="your query here"`). Review
the
[labels and selectors Kubernetes documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
for more info.
```yaml
'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'
```
docs/features/software-catalog/configuration.md
+1 -1
View File
@@ -60,7 +60,7 @@ data from. Each entry is a structure with up to four elements:
and raw. If it is not supplied, anonymous access will be used.
- `apiBaseUrl` (optional): If you want to communicate using the APIv3 method
with this provider, specify the base URL for its endpoint here, with no
trailing slash. Specifically when the target is github, you can leave it out
trailing slash. Specifically when the target is GitHub, you can leave it out
to be inferred automatically. For a GitHub Enterprise installation, it is
commonly at `https://api.<host>` or `https://<host>/api/v3`.
- `rawBaseUrl` (optional): If you want to communicate using the raw HTTP method
docs/features/software-catalog/descriptor-format.md
+251 -41
View File
@@ -60,7 +60,7 @@ software catalog API.
},
"spec": {
"lifecycle": "production",
"owner": "artist-relations@example.com",
"owner": "artist-relations-team",
"type": "website"
}
}
@@ -84,7 +84,7 @@ metadata:
spec:
type: website
lifecycle: production
owner: artist-relations@example.com
owner: artist-relations-team
```
The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the
@@ -268,7 +268,7 @@ identical in use to
Their purpose is mainly, but not limited, to reference into external systems.
This could for example be a reference to the git ref the entity was ingested
from, to monitoring and logging systems, to pagerduty schedules, etc. Users may
from, to monitoring and logging systems, to PagerDuty schedules, etc. Users may
add these to descriptor YAML files, but in addition to this automated systems
may also add annotations, either during ingestion into the catalog, or at a
later time.
@@ -381,7 +381,8 @@ metadata:
spec:
type: website
lifecycle: production
owner: artist-relations@example.com
owner: artist-relations-team
system: artist-engagement-portal
providesApis:
- artist-api
```
@@ -427,8 +428,8 @@ The current set of well-known and common values for this field is:
### `spec.owner` [required]
The owner of the component, e.g. `artist-relations@example.com`. This field is
required.
An [entity reference](#string-references) to the owner of the component, e.g.
`artist-relations-team`. This field is required.
In Backstage, the owner of a component is the singular entity (commonly a team)
that bears ultimate responsibility for the component, and has the authority and
@@ -440,25 +441,45 @@ not to be used by automated processes to for example assign authorization in
runtime systems. There may be others that also develop or otherwise touch the
component, but there will always be one ultimate owner.
Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
### `spec.system` [optional]
An [entity reference](#string-references) to the system that the component
belongs to, e.g. `artist-engagement-portal`. This field is optional.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
### `spec.subcomponentOf` [optional]
An [entity reference](#string-references) to another component of which the
component is a part, e.g. `spotify-ios-app`. This field is optional.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ---------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`Component`](#kind-component) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
### `spec.providesApis` [optional]
Links APIs that are provided by the component, e.g. `artist-api`. This field is
optional.
An array of [entity references](#string-references) to the APIs that are
provided by the component, e.g. `artist-api`. This field is optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) |
### `spec.consumesApis` [optional]
Links APIs that are consumed by the component, e.g. `artist-api`. This field is
optional.
An array of [entity references](#string-references) to the APIs that are
consumed by the component, e.g. `artist-api`. This field is optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) |
## Kind: Template
@@ -597,7 +618,8 @@ metadata:
spec:
type: openapi
lifecycle: production
owner: artist-relations@example.com
owner: artist-relations-team
system: artist-engagement-portal
definition: |
openapi: "3.0.0"
info:
@@ -663,8 +685,8 @@ The current set of well-known and common values for this field is:
### `spec.owner` [required]
The owner of the API, e.g. `artist-relations@example.com`. This field is
required.
An [entity reference](#string-references) to the owner of the component, e.g.
`artist-relations-team`. This field is required.
In Backstage, the owner of an API is the singular entity (commonly a team) that
bears ultimate responsibility for the API, and has the authority and capability
@@ -676,9 +698,18 @@ processes to for example assign authorization in runtime systems. There may be
others that also develop or otherwise touch the API, but there will always be
one ultimate owner.
Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
### `spec.system` [optional]
An [entity reference](#string-references) to the system that the API belongs to,
e.g. `artist-engagement-portal`. This field is optional.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
### `spec.definition` [required]
@@ -751,11 +782,11 @@ parent; the catalog supports multi-root hierarchies. Groups may however not have
more than one parent.
This field is an
[entity reference](https://backstage.io/docs/features/software-catalog/references),
with the default kind `Group` and the default namespace equal to the same
namespace as the user. Only `Group` entities may be referenced. Most commonly,
this field points to a group in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of that group.
[entity reference](https://backstage.io/docs/features/software-catalog/references).
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`childOf`, and reverse `parentOf`](well-known-relations.md#parentof-and-childof) |
### `spec.children` [required]
@@ -765,11 +796,11 @@ no child groups. The items are not guaranteed to be ordered in any particular
way.
The entries of this array are
[entity references](https://backstage.io/docs/features/software-catalog/references),
with the default kind `Group` and the default namespace equal to the same
namespace as the user. Only `Group` entities may be referenced. Most commonly,
these entries point to groups in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of those groups.
[entity references](https://backstage.io/docs/features/software-catalog/references).
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`hasMember`, and reverse `memberOf`](well-known-relations.md#memberof-and-hasmember) |
## Kind: User
@@ -825,23 +856,202 @@ user is not member of any groups. The items are not guaranteed to be ordered in
any particular way.
The entries of this array are
[entity references](https://backstage.io/docs/features/software-catalog/references),
with the default kind `Group` and the default namespace equal to the same
namespace as the user. Only `Group` entities may be referenced. Most commonly,
these entries point to groups in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of those groups.
[entity references](https://backstage.io/docs/features/software-catalog/references).
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`memberOf`, and reverse `hasMember`](well-known-relations.md#memberof-and-hasmember) |
## Kind: Resource
This kind is not yet defined, but is reserved [for future use](system-model.md).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `Resource` |
A resource describes the infrastructure a system needs to operate, like BigTable
databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
components and systems allows to visualize resource footprint, and create
tooling around them.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
name: artists-db
description: Stores artist details
spec:
type: database
owner: artist-relations-team
system: artist-engagement-portal
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `Resource`, respectively.
### `spec.owner` [required]
An [entity reference](#string-references) to the owner of the resource, e.g.
`artist-relations-team`. This field is required.
In Backstage, the owner of a resource is the singular entity (commonly a team)
that bears ultimate responsibility for the resource, and has the authority and
capability to develop and maintain it. They will be the point of contact if
something goes wrong, or if features are to be requested. The main purpose of
this field is for display purposes in Backstage, so that people looking at
catalog items can get an understanding of to whom this resource belongs. It is
not to be used by automated processes to for example assign authorization in
runtime systems. There may be others that also manage or otherwise touch the
resource, but there will always be one ultimate owner.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
### `spec.type` [required]
The type of resource as a string, e.g. `database`. This field is required. There
is currently no enforced set of values for this field, so it is left up to the
adopting organization to choose a nomenclature that matches the resources used
in their tech stack.
Some common values for this field could be:
- `database`
- `s3-bucket`
- `cluster`
### `spec.system` [optional]
An [entity reference](#string-references) to the system that the resource
belongs to, e.g. `artist-engagement-portal`. This field is optional.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
## Kind: System
This kind is not yet defined, but is reserved [for future use](system-model.md).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `System` |
A system is a collection of resources and components. The system may expose or
consume one or several APIs. It is viewed as abstraction level that provides
potential consumers insights into exposed features without needing a too
detailed view into the details of all components. This also gives the owning
team the possibility to decide about published artifacts and APIs.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
name: artist-engagement-portal
description: Handy tools to keep artists in the loop
spec:
owner: artist-relations-team
domain: artists
providesApis:
- artist-api
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `System`, respectively.
### `spec.owner` [required]
An [entity reference](#string-references) to the owner of the system, e.g.
`artist-relations-team`. This field is required.
In Backstage, the owner of a system is the singular entity (commonly a team)
that bears ultimate responsibility for the system, and has the authority and
capability to develop and maintain it. They will be the point of contact if
something goes wrong, or if features are to be requested. The main purpose of
this field is for display purposes in Backstage, so that people looking at
catalog items can get an understanding of to whom this system belongs. It is not
to be used by automated processes to for example assign authorization in runtime
systems. There may be others that also develop or otherwise touch the system,
but there will always be one ultimate owner.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
### `spec.domain` [optional]
An [entity reference](#string-references) to the domain that the system belongs
to, e.g. `artists`. This field is optional.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
## Kind: Domain
This kind is not yet defined, but is reserved [for future use](system-model.md).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `Domain` |
A Domain groups a collection of systems that share terminology, domain models,
business purpose, or documentation, i.e. form a bounded context.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
name: artists
description: Everything about artists
spec:
owner: artist-relations-team
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `Domain`, respectively.
### `spec.owner` [required]
An [entity reference](#string-references) to the owner of the domain, e.g.
`artist-relations-team`. This field is required.
In Backstage, the owner of a domain is the singular entity (commonly a team)
that bears ultimate responsibility for the domain, and has the authority and
capability to develop and maintain it. They will be the point of contact if
something goes wrong, or if features are to be requested. The main purpose of
this field is for display purposes in Backstage, so that people looking at
catalog items can get an understanding of to whom this domain belongs. It is not
to be used by automated processes to for example assign authorization in runtime
systems. There may be others that also develop or otherwise touch the domain,
but there will always be one ultimate owner.
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
## Kind: Location
docs/features/software-catalog/system-model.md
+3 -5
View File
@@ -23,7 +23,7 @@ We model software in the Backstage catalogue using these three core entities
- **Resources** are physical or virtual infrastructure needed to operate a
component
![](../../assets/software-catalog/software-model-core-entities.png)
![](../../assets/software-catalog/software-model-core-entities.drawio.svg)
### Component
@@ -73,6 +73,8 @@ these entities using the following (optional) concepts:
function
- **Domains** relate entities and systems to part of the business
![](../../assets/software-catalog/software-model-entities.drawio.svg)
### System
With increasing complexity in software, systems form an important abstraction
@@ -107,10 +109,6 @@ product or use-case, share the same entity types in their APIs, and integrate
well with each other. Other domains could be “Content Ingestion”, “Ads” or
“Search”.
## Current status
Backstage currently supports Components and APIs.
## Links
- [Original RFC](https://github.com/backstage/backstage/issues/390)
docs/features/software-catalog/well-known-relations.md
+21 -8
View File
@@ -48,11 +48,10 @@ where present.
### `providesApi` and `apiProvidedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
[Component](descriptor-format.md#kind-component) or
[System](descriptor-format.md#kind-system).
[Component](descriptor-format.md#kind-component).
These relations express that a component or system exposes an API - meaning that
it hosts callable endpoints from which you can consume that API.
These relations express that a component exposes an API - meaning that it hosts
callable endpoints from which you can consume that API.
This relation is commonly generated based on `spec.providesApis` of the
component or system in question.
@@ -60,11 +59,10 @@ component or system in question.
### `consumesApi` and `apiConsumedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
[Component](descriptor-format.md#kind-component) or
[System](descriptor-format.md#kind-system).
[Component](descriptor-format.md#kind-component).
These relations express that a component or system consumes an API - meaning
that it depends on endpoints of the API.
These relations express that a component consumes an API - meaning that it
depends on endpoints of the API.
This relation is commonly generated based on `spec.consumesApis` of the
component or system in question.
@@ -91,3 +89,18 @@ A membership relation, typically for [Users](descriptor-format.md#kind-user) in
[Groups](descriptor-format.md#kind-group).
This relation is commonly based on `spec.memberOf`.
### `partOf` and `hasPart`
A relation with a [Domain](descriptor-format.md#kind-domain),
[System](descriptor-format.md#kind-system) or
[Component](descriptor-format.md#kind-component) entity, typically from a
[Component](descriptor-format.md#kind-component),
[API](descriptor-format.md#kind-api), or
[System](descriptor-format.md#kind-system).
These relations express that a component belongs to a larger component; a
component, API or resource belongs to a system; or that a system is grouped
under a domain.
This relation is commonly based on `spec.system` or `spec.domain`.
docs/features/software-templates/index.md
+2 -2
View File
@@ -2,8 +2,8 @@
id: software-templates-index
title: Backstage Software Templates
sidebar_label: Overview
description: The Software Templates part of Backstage is a tool that can help
you create Components inside Backstage
# prettier-ignore
description: The Software Templates part of Backstage is a tool that can help you create Components inside Backstage
---
The Software Templates part of Backstage is a tool that can help you create
docs/features/techdocs/README.md
+2 -2
View File
@@ -2,8 +2,8 @@
id: techdocs-overview
title: TechDocs Documentation
sidebar_label: Overview
description: TechDocs is Spotify’s homegrown docs-like-code solution built
directly into Backstage
# prettier-ignore
description: TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage
---
## What is it?
docs/features/techdocs/concepts.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: concepts
title: Concepts
description: Documentation on concepts that are introduced with
Spotify's docs-like-code solution in Backstage
# prettier-ignore
description: Documentation on concepts that are introduced with Spotify's docs-like-code solution in Backstage
---
This page describes concepts that are introduced with Spotify's docs-like-code
docs/features/techdocs/configuration.md
+20 -14
View File
@@ -1,8 +1,8 @@
---
id: configuration
title: TechDocs Configuration Options
description:
Reference documentation for configuring TechDocs using app-config.yaml
# prettier-ignore
description: Reference documentation for configuring TechDocs using app-config.yaml
---
Using the `app-config.yaml` in the Backstage app, you can configure TechDocs
@@ -54,28 +54,34 @@ techdocs:
# Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise.
googleGcs:
# An API key is required to write to a storage bucket.
# (Required) Cloud Storage Bucket Name
bucketName: 'techdocs-storage'
# (Optional) An API key is required to write to a storage bucket.
# If missing, GOOGLE_APPLICATION_CREDENTIALS environment variable will be used.
# https://cloud.google.com/docs/authentication/production
credentials:
$file: '/path/to/google_application_credentials.json'
# Your GCP Project ID where the Cloud Storage Bucket is hosted.
projectId: 'gcp-project-id'
# Cloud Storage Bucket Name
bucketName: 'techdocs-storage'
# Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise.
awsS3:
# An API key is required to write to a storage bucket.
# (Required) AWS S3 Bucket Name
bucketName: 'techdocs-storage'
# (Optional) An API key is required to write to a storage bucket.
# If not set, environment variables or aws config file will be used to authenticate.
# https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html
# https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html
credentials:
accessKeyId:
$env: TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL
secretAccessKey:
$env: TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL
region:
$env: AWSS3_REGION
# AWS S3 Bucket Name
bucketName: 'techdocs-storage'
# (Optional) AWS Region of the bucket.
# If not set, AWS_REGION environment variable or aws config file will be used.
# https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
region:
$env: AWS_REGION
```
docs/features/techdocs/using-cloud-storage.md
+76 -146
View File
@@ -30,20 +30,35 @@ techdocs:
type: 'googleGcs'
```
**2. GCP (Google Cloud Platform) Project**
**2. Create a GCS Bucket**
Create or choose a dedicated GCP project. Set
`techdocs.publisher.googleGcs.projectId` to the project ID.
Create a dedicated Google Cloud Storage bucket for TechDocs sites.
techdocs-backend will publish documentation to this bucket. TechDocs will fetch
files from here to serve documentation in Backstage. Note that the bucket names
are globally unique.
Set the config `techdocs.publisher.googleGcs.bucketName` in your
`app-config.yaml` to the name of the bucket you just created.
```yaml
techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
googleGcs:
bucketName: 'name-of-techdocs-storage-bucket'
```
**3. Service account API key**
**3a. (Recommended) Authentication using environment variable**
The GCS Node.js client will automatically use the environment variable
`GOOGLE_APPLICATION_CREDENTIALS` to authenticate with Google Cloud. It might
already be set in Compute Engine, Google Kubernetes Engine, etc. Read
https://cloud.google.com/docs/authentication/production for more details.
**3b. Authentication using app-config.yaml**
If you do not prefer (3a) and optionally like to use a service account, you can
follow these steps.
Create a new Service Account and a key associated with it. In roles of the
service account, use "Storage Admin".
@@ -65,41 +80,32 @@ techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
bucketName: 'name-of-techdocs-storage-bucket'
credentials:
$file: '/path/to/google_application_credentials.json'
```
**4. GCS Bucket**
Create a dedicated bucket for TechDocs sites. techdocs-backend will publish
documentation to this bucket. TechDocs will fetch files from here to serve
documentation in Backstage.
Set the name of the bucket to `techdocs.publisher.googleGcs.bucketName`.
Note: If you are finding it difficult to make the file
`google_application_credentials.json` available on a server, you could use the
file's content and set as an environment variable. And then use
```yaml
techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
credentials:
$file: '/path/to/google_application_credentials.json'
bucketName: 'name-of-techdocs-storage-bucket'
credentials:
$env: GOOGLE_APPLICATION_CREDENTIALS
```
**5. That's it!**
**4. That's it!**
Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to
store the static generated documentation files.
store and read the static generated documentation files.
## Configuring AWS S3 Bucket with TechDocs
Follow the
[official AWS S3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html)
for the latest instructions on the following steps involving AWS S3.
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
Set `techdocs.publisher.type` to `'awsS3'`.
@@ -110,43 +116,17 @@ techdocs:
type: 'awsS3'
```
**2. AWS Policies**
**2. Create an S3 Bucket**
AWS Policies lets you **control access** to Amazon Web Services (AWS) products
and resources.
Here we will use a user policy **and** a bucket policy to show you the different
possibilities you have but you can use only one.
Create a dedicated AWS S3 bucket for the storage of TechDocs sites.
[Refer to the official documentation](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html).
<img data-zoomable src="../../assets/techdocs/aws-s3.drawio.svg" alt="AWS S3" width="500" />
TechDocs will publish documentation to this bucket and will fetch files from
here to serve documentation in Backstage. Note that the bucket names are
globally unique.
This is an example of how you can manage your policies:
a. Admin user creates a **bucket policy** granting a set of permissions to our
TechDocs user.
b. Admin user attaches a **user policy** to the TechDocs user granting
additional permissions.
c. TechDocs User then tries permissions granted via both the **bucket** policy
and the **user** policy.
**2.1 Creation**
**2.1.1 Create an Admin user** (if you don't have one yet)
Create an **administrator user** account `ADMIN_USER` and grant it administrator
privileges by attaching a user policy giving the account **full access**.
Note down the Admin User credentials and IAM User Sign-In URL as you will need
to use this information in the next step.
**2.1.2 Create an AWS S3 Bucket**
Using the credentials of your Admin User `ADMIN_USER`, and the special IAM user
sign-in URL, create a dedicated **bucket** for TechDocs sites. techdocs-backend
will publish documentation to this bucket. TechDocs will fetch files from here
to serve documentation in Backstage.
Set the name of the bucket to `techdocs.publisher.awsS3.bucketName`.
Set the config `techdocs.publisher.awsS3.bucketName` in your `app-config.yaml`
to the name of the bucket you just created.
```yaml
techdocs:
@@ -156,112 +136,62 @@ techdocs:
bucketName: 'name-of-techdocs-storage-bucket'
```
**2.1.3 Create the `TechDocs` user**
**3a. (Recommended) Setup authentication the AWS way, using environment
variables**
This user will be used to interact with your bucket, it will only have
permissions to **get - put** objects.
You should follow the
[AWS security best practices guide for authentication](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
In the IAM console, do the following:
If the environment variables
- Create a new user, `TechDocs`
- Note down the TechDocs User credentials
- Note down the Amazon Resource Name (ARN) for the TechDocs user. In the IAM
console, select the TechDocs user, and you can find the user ARN in the
Summary tab.
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_REGION`
**2.2 Attach policies**
are set and can be used to access the bucket you created in step 2, they will be
used by the AWS SDK v3 Node.js client for authentication.
[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html)
Remember that you can use Bucket policy **or** User policy.
Just make sure that you grant all the permissions to the TechDocs user:
`3:PutObject`, `s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`.
If the environment variables are missing, the AWS SDK tries to read the
`~/.aws/credentials` file for credentials.
[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html)
**2.2.1 Create the bucket policy**
Note that the region of the bucket has to be set for the AWS SDK to work.
[See this](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html).
You now have to attach the following policy to your bucket in the Permission
section:
**3b. Authentication using app-config.yaml**
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
},
"Action": ["s3:GetBucketLocation", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket"]
},
{
"Sid": "statement2",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
},
"Action": ["s3:GetObject"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket/*"]
}
]
}
```
- The first statement grants **TechDocs User** the bucket operation permissions
`s3:GetBucketLocation` and `s3:ListBucket` which are permissions required by
the console.
- The second statement grants the `s3:GetObject` permission.
(**NOTE :** if you do not use the user policy defined below you must also add
the `s3:PutObject` permission to allow the TechDocs user to add objects.)
**2.2.2 Create the user policy**
Create an inline policy for the TechDocs user by using the following policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PermissionForObjectOperations",
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket/*"]
}
]
}
```
See more details in the section
[Working with Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).
Now you need to fill in the environment variables with the `TechDocs` User
credentials. You can also specify a region if you want to accesses the resources
in a specific region. Otherwise no region will be selected by default.
```properties
TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL="TECHDOCS_ACCESS_KEY_ID"
TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL="TECHDOCS_SECRET_ACCESS_KEY"
AWSS3_REGION="" // Optional
```
Make it available in your Backstage server and/or your local development server
and set it in the app config techdocs.publisher.awsS3.
AWS credentials and region can be provided to the AWS SDK via `app-config.yaml`.
If the configs below are present, they will be used over existing `AWS_*`
environment variables and the `~/.aws/credentials` config file.
```yaml
techdocs:
publisher:
type: 'awsS3'
awsS3:
bucketName: 'name-of-techdocs-storage-bucket'
region:
$env: AWS_REGION
credentials:
accessKeyId:
$env: TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL
$env: AWS_ACCESS_KEY_ID
secretAccessKey:
$env: TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL
region:
$env: AWSS3_REGION
$env: AWS_SECRET_ACCESS_KEY
```
**3. That's it!**
Refer to the
[official AWS documentation for obtaining the credentials](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-your-credentials.html).
Your Backstage app is now ready to use AWS S3 for TechDocs, to store the static
generated documentation files.
Note: If you are using Amazon EC2 instance to deploy Backstage, you do not need
to obtain the access keys separately. They can be made available in the
environment automatically by defining appropriate IAM role with access to the
bucket. Read more
[here](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html#use-roles).
**4. That's it!**
Your Backstage app is now ready to use AWS S3 for TechDocs, to store and read
the static generated documentation files. When you start the backend of the app,
you should be able to see
`techdocs info Successfully connected to the AWS S3 bucket` in the logs.
docs/getting-started/deployment-other.md
+1 -1
View File
@@ -16,7 +16,7 @@ $ yarn docker-build
$ docker run --rm -it -p 7000:7000 -e APP_ENV=production -e NODE_ENV=development example-backend:latest
```
Then open http://localhost/ on your browser.
Then open http://localhost:7000 on your browser.
## Heroku
docs/getting-started/development-environment.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: development-environment
title: Development Environment
description: Documentation on how to get set up for doing development on
the Backstage repository
# prettier-ignore
description: Documentation on how to get set up for doing development on the Backstage repository
---
This section describes how to get set up for doing development on the Backstage
docs/overview/adopting.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: adopting
title: Strategies for adopting
description: Documentation on some general best practices that have been key
to Backstage's success inside Spotify
# prettier-ignore
description: Documentation on some general best practices that have been key to Backstage's success inside Spotify
---
This document outlines some general best practices that have been key to
docs/overview/background.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: background
title: The Spotify Story
description: Backstage was born out of necessity at Spotify. We found that as we grew, our
infrastructure was becoming more fragmented, our engineers less productive.
# prettier-ignore
description: Backstage was born out of necessity at Spotify. We found that as we grew, our infrastructure was becoming more fragmented, our engineers less productive.
---
Backstage was born out of necessity at Spotify. We found that as we grew, our
docs/overview/roadmap.md
+3 -3
View File
@@ -8,9 +8,9 @@ description: Roadmap of Backstage Project
> Backstage is currently under rapid development. This means that you can expect
> APIs and features to evolve. It is also recommended that teams who adopt
> Backstage today upgrade their installation as new
> [releases](https://github.com/backstage/backstage/releases) become available,
> as Backwards compatibility is not yet guaranteed.
> Backstage today [upgrade their installation](../cli/commands.md#versionsbump)
> as new [releases](https://github.com/backstage/backstage/releases) become
> available, as Backwards compatibility is not yet guaranteed.
## Phases
docs/overview/stability-index.md
+3 -4
View File
@@ -1,9 +1,8 @@
---
id: stability-index
title: Stability Index
description:
An overview of the commitment to stability for different parts of the
Backstage codebase.
# prettier-ignore
description: An overview of the commitment to stability for different parts of the Backstage codebase.
---
## Overview
@@ -291,7 +290,7 @@ Stability: `1`. There are plans to rework parts of the Processor interface.
### `catalog-graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-graphql/)
Provides the catalog schema and resolvers for the graphql backend.
Provides the catalog schema and resolvers for the GraphQL backend.
Stability: `0`. Under heavy development and subject to change.
docs/overview/vision.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: vision
title: Vision
description: Goal is to provide engineers with the best developer experience in
the world
# prettier-ignore
description: Goal is to provide engineers with the best developer experience in the world
---
Our goal is to provide engineers with the best developer experience in the
docs/overview/what-is-backstage.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: what-is-backstage
title: What is Backstage?
description: Backstage is an open platform for building developer portals.
Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure
# prettier-ignore
description: Backstage is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure
---
![service-catalog](https://backstage.io/blog/assets/6/header.png)
docs/plugins/call-existing-api.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: call-existing-api
title: Call Existing API
description: Describes the various options that Backstage frontend plugins have,
in communicating with service APIs that already exist
# prettier-ignore
description: Describes the various options that Backstage frontend plugins have, in communicating with service APIs that already exist
---
This article describes the various options that Backstage frontend plugins have,
docs/plugins/publishing.md
+1 -1
View File
@@ -7,7 +7,7 @@ description: Documentation on Publishing npm packages
## npm
npm packages are published through CI/CD in the
[.github/workflows/master.yml](https://github.com/backstage/backstage/blob/master/.github/workflows/master.yml)
[`.github/workflows/master.yml`](https://github.com/backstage/backstage/blob/master/.github/workflows/master.yml)
workflow. Every commit that is merged to master will be checked for new versions
of all public packages, and any new versions will automatically be published to
npm.
docs/reference/utility-apis/ErrorApi.md
+1 -1
View File
@@ -29,7 +29,7 @@ These types are part of the API declaration, but may not be unique to this API.
### Error
Mirrors the javascript Error class, for the purpose of providing documentation
Mirrors the JavaScript Error class, for the purpose of providing documentation
and optional fields.
<pre>
docs/support/project-structure.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
id: project-structure
title: Backstage Project Structure
description:
Introduction to files and folders in the Backstage Project repository
# prettier-ignore
description: Introduction to files and folders in the Backstage Project repository
---
Backstage is a complex project, and the GitHub repository contains many
docs/tutorials/quickstart-app-plugin.md
+1 -1
View File
@@ -59,7 +59,7 @@ import GitHubIcon from '@material-ui/icons/GitHub';
```
Simple! The App will reload with your changes automatically. You should now see
a github icon displayed in the sidebar. Clicking that will link to our new
a GitHub icon displayed in the sidebar. Clicking that will link to our new
plugin. And now, the API fun begins.
# The Identity