Merge branch 'backstage:master' into techdocs-config-md
This commit is contained in:
Saptarshi Mula
@@ -181,28 +181,30 @@ this remote source, users cannot also register new entities with e.g. the
|
||||
[catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import)
|
||||
plugin.
|
||||
|
||||
## Clean up orphaned entities
|
||||
## Automatic removal of orphaned entities
|
||||
|
||||
In short, entities can become orphaned through multiple means, such as when a catalog-info YAML file is moved from one place to another in the version control system without updating the registration in the catalog. For safety reasons, the default behavior is to just tag the orphaned entities, and keep them around. You can read more about orphaned entities [here](life-of-an-entity.md#orphaning).
|
||||
Entities can become orphaned through multiple means, such as when a catalog-info YAML file is moved from one place to another in the version control system without updating the registration in the catalog. The default behavior is to automatically remove orphaned entities. You can read more about orphaned entities [here](life-of-an-entity.md#orphaning).
|
||||
|
||||
However, if you do wish to automatically remove the orphaned entities, you can use the following configuration, and everything with an orphaned entity tag will be eventually deleted.
|
||||
However, if you wish to keep orphaned entities, you can use the following configuration, and automatic cleanup will be disabled.
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
orphanStrategy: delete
|
||||
orphanStrategy: keep
|
||||
```
|
||||
|
||||
## Clean up entities from orphaned entity providers
|
||||
## Automatic removal of entities from orphaned entity providers
|
||||
|
||||
By default, if an entity provider which has provided entities to the catalog, is no longer configured, then the entities remain in the catalog until they are manually unregistered.
|
||||
By default, if an entity provider which has provided entities to the catalog is no longer configured, then the entities it provided will be automatically removed.
|
||||
|
||||
To remove these entities automatically, you can use the following configuration.
|
||||
To keep these entities instead, you can use the following configuration.
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
orphanProviderStrategy: delete
|
||||
orphanProviderStrategy: keep
|
||||
```
|
||||
|
||||
If you have had providers installed in the past that ingested entities into the catalog that you want to keep, the recommendation is to add the provider back to the catalog. If you don’t want the provider to run, you can schedule it with a very large interval.
|
||||
|
||||
## Processing Interval
|
||||
|
||||
The [processing loop](./life-of-an-entity.md#processing) is
|
||||
|
||||
@@ -254,8 +254,8 @@ either, it becomes _orphaned_. The end result is as follows:
|
||||
the child entity.
|
||||
- The child entity is _not_ removed from the catalog, but stays around until
|
||||
explicitly deleted via the catalog API, implicitly if `orphanStrategy: delete`
|
||||
configuration is set, or until it is "reclaimed" by the original parent
|
||||
or another parent starting to reference it.
|
||||
configuration is set (the default), or until it is "reclaimed" by the original
|
||||
parent or another parent starting to reference it.
|
||||
- The catalog page in Backstage for the child entity detects the new annotation
|
||||
and informs users about the orphan status.
|
||||
|
||||
@@ -282,21 +282,13 @@ Orphaning can occur in several different scenarios.
|
||||
> to inform the owner that something is wrong. But processing and other
|
||||
> behaviors continue as usual.
|
||||
|
||||
The reason that the orphaning mechanism exists instead of having an eager
|
||||
deletion triggered, is safety. Scenarios like these can happen purely by
|
||||
accident, due to the asynchronous nature of the system and the fallible nature
|
||||
of humans. In particular when external systems start consuming and relying on
|
||||
the catalog, there could be substantial consequences to suddenly dropping
|
||||
entities without explicit owner consent. The catalog therefore takes the stance
|
||||
that entities that often were added by direct user action should also be deleted
|
||||
only by direct user action.
|
||||
|
||||
However, if you want to delete orphaned entities automatically anyway, you can
|
||||
enable the automated clean up with the following app-config option.
|
||||
The default behavior of the catalog is to automatically remove orphaned
|
||||
entities. However, if you want to keep them instead, you can disable the
|
||||
automated cleanup with the following app-config option.
|
||||
|
||||
```
|
||||
catalog:
|
||||
orphanStrategy: delete
|
||||
orphanStrategy: keep
|
||||
```
|
||||
|
||||
## Implicit Deletion
|
||||
|
||||
@@ -251,6 +251,46 @@ browser when viewing that user.
|
||||
This annotation can be used on a [User entity](descriptor-format.md#kind-user)
|
||||
to note that it originated from that user on GitHub.
|
||||
|
||||
### github.com/user-id
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
github.com/user-id: '123456'
|
||||
```
|
||||
|
||||
The value of this annotation is the numeric user ID that identifies a user on
|
||||
[GitHub](https://github.com) (either the public one, or a private GitHub
|
||||
Enterprise installation) that is related to this entity. Unlike the username,
|
||||
which can be changed by the user, the user ID is immutable.
|
||||
|
||||
This annotation can be used on a [User entity](descriptor-format.md#kind-user)
|
||||
to note that it originated from that user on GitHub. It enables the
|
||||
`userIdMatchingUserEntityAnnotation` sign-in resolver to match users by their
|
||||
GitHub user ID during authentication.
|
||||
|
||||
### gitlab.com/user-id
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
gitlab.com/user-id: '123456'
|
||||
```
|
||||
|
||||
The value of this annotation is the numeric user ID that identifies a user on
|
||||
[GitLab](https://gitlab.com) (either the public one, or a private GitLab
|
||||
installation) that is related to this entity. For self-hosted GitLab instances,
|
||||
the annotation key will be `{integration-host}/user-id` where
|
||||
`{integration-host}` is the hostname of your GitLab instance. Unlike the
|
||||
username, which can be changed, the user ID is immutable.
|
||||
|
||||
This annotation can be used on a [User entity](descriptor-format.md#kind-user)
|
||||
to note that it originated from that user on GitLab. It enables the
|
||||
`userIdMatchingUserEntityAnnotation` sign-in resolver to match users by their
|
||||
GitLab user ID during authentication.
|
||||
|
||||
### gocd.org/pipelines
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -48,6 +48,65 @@ add the `repoVisibility` key within a software template:
|
||||
repoVisibility: public # or 'internal' or 'private'
|
||||
```
|
||||
|
||||
### Default Environment
|
||||
|
||||
The scaffolder supports a `defaultEnvironment` configuration that provides default parameters and secrets to all templates. This reduces template complexity and improves security by centralizing common values.
|
||||
|
||||
```yaml
|
||||
scaffolder:
|
||||
defaultEnvironment:
|
||||
parameters:
|
||||
region: eu-west-1
|
||||
organizationName: acme-corp
|
||||
defaultRegistry: registry.acme-corp.com
|
||||
secrets:
|
||||
AWS_ACCESS_KEY: ${AWS_ACCESS_KEY}
|
||||
GITHUB_TOKEN: ${GITHUB_TOKEN}
|
||||
DOCKER_REGISTRY_TOKEN: ${DOCKER_REGISTRY_TOKEN}
|
||||
```
|
||||
|
||||
#### Default parameters
|
||||
|
||||
Default parameters are accessible via `${{ environment.parameters.* }}` in templates. Default parameters are isolated in their own context to avoid naming conflicts.
|
||||
|
||||
```yaml
|
||||
parameters:
|
||||
- title: Fill in some steps
|
||||
required:
|
||||
- organizationName
|
||||
properties:
|
||||
organizationName:
|
||||
title: organizationName
|
||||
type: string
|
||||
description: Unique name of the organization
|
||||
ui:autofocus: true
|
||||
ui:options:
|
||||
rows: 5
|
||||
|
||||
steps:
|
||||
- id: deploy
|
||||
name: Deploy Application
|
||||
action: aws:deploy
|
||||
input:
|
||||
region: ${{ environment.parameters.region }} # Resolves to defaultEnvironment.parameters.region
|
||||
organization: ${{ parameters.organizationName }} # Resolves to frontend input value
|
||||
otherOrganization: ${{ environment.parameters.organizationName }} # Resolves to defaultEnvironment.parameters.organizationName
|
||||
```
|
||||
|
||||
#### Secrets
|
||||
|
||||
Default secrets are resolved from environment variables and accessible via `${{ environment.secrets.* }}` in template actions. Secrets are only available during action execution, not in frontend forms.
|
||||
|
||||
```yaml
|
||||
- id: deploy
|
||||
name: Deploy with credentials
|
||||
action: aws:deploy
|
||||
input:
|
||||
accessKey: ${{ environment.secrets.AWS_ACCESS_KEY }} # Resolves to defaultEnvironment.secrets.AWS_ACCESS_KEY
|
||||
```
|
||||
|
||||
**Security Note:** Secrets are automatically masked in logs and are only available to backend actions, never exposed to the frontend.
|
||||
|
||||
## Disabling Docker in Docker situation (Optional)
|
||||
|
||||
Software templates use the `fetch:template` action by default, which requires no
|
||||
|
||||
@@ -468,3 +468,59 @@ repoUrl:
|
||||
The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`.
|
||||
|
||||
If you're also using the `RepoUrlPicker` field extension, you should simply duplicate this part from there.
|
||||
|
||||
## RepoOwnerPicker
|
||||
|
||||
The input props that can be specified under `ui:options` for the `RepoOwnerPicker` field extension.
|
||||
|
||||
### `host`
|
||||
|
||||
The SCM integration host that owners should be fetched from for autocompletion.
|
||||
|
||||
- Fetch owners from `github.com`
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Owner
|
||||
type: string
|
||||
ui:field: RepoOwnerPicker
|
||||
ui:options:
|
||||
host: github.com
|
||||
```
|
||||
|
||||
### `excludedOwners`
|
||||
|
||||
List of owners that should be excluded from autocompletion.
|
||||
|
||||
- Exclude owner `owner_1` from autocompletion
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Owner
|
||||
type: string
|
||||
ui:field: RepoOwnerPicker
|
||||
ui:options:
|
||||
excludedOwners:
|
||||
- owner_1
|
||||
```
|
||||
|
||||
### `requestUserCredentials`
|
||||
|
||||
If defined will request user credentials to auth against the given SCM platform.
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Owner
|
||||
type: string
|
||||
ui:field: RepoOwnerPicker
|
||||
ui:options:
|
||||
requestUserCredentials:
|
||||
secretsKey: USER_OAUTH_TOKEN
|
||||
additionalScopes:
|
||||
github:
|
||||
- workflow:write
|
||||
```
|
||||
|
||||
`secretsKey` is the key used within the template secrets context to store the credential and `additionalScopes` is any additional permission scopes to request.
|
||||
|
||||
The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`.
|
||||
|
||||
@@ -555,6 +555,35 @@ The `RepoBranchPicker` is a custom field that we provide part of the
|
||||
`plugin-scaffolder`. You can provide your own custom fields by
|
||||
[writing your own Custom Field Extensions](./writing-custom-field-extensions.md)
|
||||
|
||||
### The Repository Owner Picker
|
||||
|
||||
Similar to the repository picker, there is a picker for owners to support autocompletion. A full example could look like this:
|
||||
|
||||
```yaml
|
||||
- title: Choose an owner
|
||||
required:
|
||||
- repoOwner
|
||||
properties:
|
||||
repoOwner:
|
||||
title: Repository Owner
|
||||
type: string
|
||||
ui:field: RepoOwnerPicker
|
||||
ui:options:
|
||||
host: github.com
|
||||
excludedOwners:
|
||||
- backstage
|
||||
requestUserCredentials:
|
||||
secretsKey: USER_OAUTH_TOKEN
|
||||
```
|
||||
|
||||
Passing the `requestUserCredentials` and `host` properties is required for autocompletion to work. For more information regarding the `requestUserCredentials` object, please refer to the [Using the Users `oauth` token](#using-the-users-oauth-token) section under [The Repository Picker](#the-repository-picker).
|
||||
|
||||
For a list of all possible `ui:options` input props for `RepoOwnerPicker`, please visit [here](./ui-options-examples.md#repoownerpicker).
|
||||
|
||||
The `RepoOwnerPicker` is a custom field that we provide part of the
|
||||
`plugin-scaffolder`. You can provide your own custom fields by
|
||||
[writing your own Custom Field Extensions](./writing-custom-field-extensions.md)
|
||||
|
||||
### Accessing the signed-in users details
|
||||
|
||||
Sometimes when authoring templates, you'll want to access the user that is running the template, and get details from the profile or the users `Entity` in the Catalog.
|
||||
|
||||
@@ -172,15 +172,17 @@ 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.
|
||||
|
||||
Set the config `techdocs.publisher.awsS3.bucketName` in your `app-config.yaml`
|
||||
to the name of the bucket you just created.
|
||||
Set the bucket name and region in your `app-config.yaml` to the name of the bucket you just created:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'awsS3'
|
||||
/* highlight-add-start */
|
||||
awsS3:
|
||||
bucketName: 'name-of-techdocs-storage-bucket'
|
||||
region: 'us-east-1'
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
**3. Create minimal AWS IAM policies to manage TechDocs**
|
||||
@@ -266,7 +268,7 @@ environment automatically by defining appropriate IAM role with access to the
|
||||
bucket. Read more in the
|
||||
[official AWS documentation for using IAM roles](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html#use-roles).
|
||||
|
||||
**4b. Authentication using app-config.yaml**
|
||||
**4b. Authentication using app-config.yaml via aws.accounts**
|
||||
|
||||
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_*`
|
||||
@@ -290,7 +292,45 @@ aws:
|
||||
Refer to the
|
||||
[official AWS documentation for obtaining the credentials](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html).
|
||||
|
||||
**4c. Authentication using an assumed role** Users with multiple AWS accounts
|
||||
**4c. Authentication using app-config.yaml via integrations.awsS3**
|
||||
|
||||
If you already have an [AWS S3 integration](../../integrations/aws-s3/locations.md), you can use it to authenticate with AWS S3:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'awsS3'
|
||||
awsS3:
|
||||
bucketName: 'name-of-techdocs-storage-bucket'
|
||||
region: 'eu-west-1'
|
||||
integrations:
|
||||
awsS3:
|
||||
- accessKeyId: ${AWS_ACCESS_KEY_ID}
|
||||
secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
|
||||
```
|
||||
|
||||
This will use the credentials from the integration to authenticate with AWS S3 and it does not require any additional configuration in the `app-config.yaml`. However, **if you have multiple S3 integrations**, you **must** specify the target integration by setting the `accessKeyId` in the `techdocs.publisher.awsS3.credentials` config:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'awsS3'
|
||||
awsS3:
|
||||
bucketName: 'name-of-techdocs-storage-bucket'
|
||||
region: 'eu-west-1'
|
||||
/* highlight-add-start */
|
||||
credentials:
|
||||
accessKeyId: ${AWS_ACCESS_KEY_ID_1}
|
||||
/* highlight-add-end */
|
||||
integrations:
|
||||
awsS3:
|
||||
- accessKeyId: ${AWS_ACCESS_KEY_ID_1}
|
||||
secretAccessKey: ${AWS_SECRET_ACCESS_KEY_1}
|
||||
- accessKeyId: ${AWS_ACCESS_KEY_ID_2}
|
||||
secretAccessKey: ${AWS_SECRET_ACCESS_KEY_2}
|
||||
```
|
||||
|
||||
**4d. Authentication using an assumed role** Users with multiple AWS accounts
|
||||
may want to use a role for S3 storage that is in a different AWS account. Using
|
||||
the `roleArn` parameter as seen below, you can instruct the TechDocs publisher
|
||||
to assume a role before accessing S3.
|
||||
|
||||
Reference in New Issue
Block a user