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

Merge branch 'master' into timbonicus/keep-updated

Browse Source
This commit is contained in:
Tim Hansen
2021-03-08 08:06:16 -07:00
parent 2369c72cac d661bece6a
commit bae135c88e
224 changed files with 4424 additions and 1595 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/kubernetes/configuration.md
+60 -19
View File
@@ -17,18 +17,22 @@ The following is a full example entry in `app-config.yaml`:
```yaml
kubernetes:
serviceLocatorMethod: 'multiTenant'
serviceLocatorMethod:
type: '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'
- type: '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: aws-cluster-1
authProvider: 'aws'
- type: 'gke'
projectId: 'gke-clusters'
region: 'europe-west1'
```
### `serviceLocatorMethod`
@@ -44,26 +48,28 @@ Currently, the only valid value is:
This is an array used to determine where to retrieve cluster configuration from.
Currently, the only valid cluster locator method is:
Valid cluster locator methods are:
- `config` - This cluster locator method will read cluster information from your
app-config (see below).
#### `config`
### `clusters`
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`
##### `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`
##### `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`
##### `clusters.\*.authProvider`
This determines how the Kubernetes client authenticates with the Kubernetes
cluster. Valid values are:
@@ -73,7 +79,7 @@ cluster. Valid values are:
| `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.\*.serviceAccountToken` (optional)
##### `clusters.\*.serviceAccountToken` (optional)
The service account token to be used when using the `serviceAccount` auth
provider. You could get the service account token with:
@@ -85,6 +91,38 @@ kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOU
| base64 --decode
```
#### `gke`
This cluster locator is designed to work with Kubernetes clusters running in
[GKE][1]. It will configure the Kubernetes backend plugin to make requests to
clusters running within a Google Cloud project.
This cluster locator method will use the `google` authentication mechanism.
The Google Cloud service account to use can be configured through the
`GOOGLE_APPLICATION_CREDENTIALS` environment variable. Consult the [Google Cloud
docs][2] for more information.
For example:
```yaml
- type: 'gke'
projectId: 'gke-clusters'
region: 'europe-west1'
```
Will configure the Kubernetes plugin to connect to all GKE clusters in the
project `gke-clusters` in the region `europe-west1`.
##### `projectId`
The Google Cloud project to look for Kubernetes clusters in.
##### `region` (optional)
The Google Cloud region to look for Kubernetes clusters in. Defaults to all
regions.
### Role Based Access Control
The current RBAC permissions required are read-only cluster wide, for the
@@ -135,3 +173,6 @@ for more info.
```yaml
'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'
```
[1]: https://cloud.google.com/kubernetes-engine
[2]: https://cloud.google.com/docs/authentication/production#linux-or-macos
docs/features/software-templates/writing-custom-actions.md
+3 -3
View File
@@ -19,7 +19,7 @@ passed as `input` to the function.
In `packages/backend/src/actions/custom.ts` we can create a new action.
```ts
import { createTemplateAction } from '../../createTemplateAction';
import { createTemplateAction } from '@backstage/plugin-scaffolder-backend';
import fs from 'fs-extra';
export const createNewFileAction = () => {
@@ -35,7 +35,7 @@ export const createNewFileAction = () => {
title: 'Contents',
description: 'The contents of the file',
},
contents: {
filename: {
type: 'string',
title: 'Filename',
description: 'The filename of the file that will be created',
@@ -46,7 +46,7 @@ export const createNewFileAction = () => {
async handler(ctx) {
await fs.outputFile(
`${ctx.workspacePath}/${ctx.input.filename}`,
ctx.input.content,
ctx.input.contents,
);
},
});
docs/features/techdocs/README.md
+1
View File
@@ -54,6 +54,7 @@ providers are used.
| Google Cloud Storage (GCS) | Yes ✅ |
| Amazon Web Services (AWS) S3 | Yes ✅ |
| Azure Blob Storage | Yes ✅ |
| OpenStack Swift | Yes ✅ |
[Reach out to us](#feedback) if you want to request more platforms.
docs/features/techdocs/using-cloud-storage.md
+76 -1
View File
@@ -257,7 +257,8 @@ techdocs:
**3a. (Recommended) Authentication using environment variable**
Set the config `techdocs.publisher.azureBlobStorage.credentials.accountName` in
If you do not prefer (3a) and optionally like to use a service account, you can
set the config `techdocs.publisher.azureBlobStorage.credentials.accountName` in
your `app-config.yaml` to the your account name.
The storage blob client will automatically use the environment variable
@@ -309,3 +310,77 @@ 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 Azure Blob Storage container` in
the logs.
## Configuring OpenStack Swift Container with TechDocs
Follow the
[official OpenStack Api documentation](https://docs.openstack.org/api-ref/identity/v3/)
for the latest instructions on the following steps involving OpenStack Storage.
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
Set `techdocs.publisher.type` to `'openStackSwift'`.
```yaml
techdocs:
publisher:
type: 'openStackSwift'
```
**2. Create an OpenStack Swift Storage Container**
Create a dedicated container for TechDocs sites.
[Refer to the official documentation](https://docs.openstack.org/mitaka/user-guide/dashboard_manage_containers.html).
TechDocs will publish documentation to this container and will fetch files from
here to serve documentation in Backstage. Note that the container names are
globally unique.
Set the config `techdocs.publisher.openStackSwift.containerName` in your
`app-config.yaml` to the name of the container you just created.
```yaml
techdocs:
publisher:
type: 'openStackSwift'
openStackSwift:
containerName: 'name-of-techdocs-storage-container'
```
**3. Authentication using app-config.yaml**
Set the configs in your `app-config.yaml` to point to your container name.
https://docs.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-unscoped-authorization-detail#password-authentication-with-unscoped-authorization
for more details.
```yaml
techdocs:
publisher:
type: 'openStackSwift'
openStackSwift:
containerName: 'name-of-techdocs-storage-bucket'
credentials:
userName:
$env: OPENSTACK_SWIFT_STORAGE_USERNAME
password:
$env: OPENSTACK_SWIFT_STORAGE_PASSWORD
authUrl:
$env: OPENSTACK_SWIFT_STORAGE_AUTH_URL
keystoneAuthVersion:
$env: OPENSTACK_SWIFT_STORAGE_AUTH_VERSION
domainId:
$env: OPENSTACK_SWIFT_STORAGE_DOMAIN_ID
domainName:
$env: OPENSTACK_SWIFT_STORAGE_DOMAIN_NAME
region:
$env: OPENSTACK_SWIFT_STORAGE_REGION
```
**4. That's it!**
Your Backstage app is now ready to use OpenStack Swift Storage 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 OpenStack Swift Storage container`
in the logs.
docs/getting-started/configure-app-with-plugins.md
+14 -4
View File
@@ -4,20 +4,30 @@ title: Configuring App with plugins
description: Documentation on How Configuring App with plugins
---
Backstage plugins customize the app for your needs. There is a
[plugin marketplace](https://backstage.io/plugins) with plugins for many common
infrastructure needs - CI/CD, monitoring, auditing, and more.
## Adding existing plugins to your app
The following steps assume that you have created a new Backstage app and want to
add an existing plugin to it. We are using the
The following steps assume that you have
[created a Backstage app](./create-an-app.md) and want to add an existing plugin
to it. We are using the
[CircleCI](https://github.com/backstage/backstage/blob/master/plugins/circleci/README.md)
plugin in this example.
1. Add the plugin's npm package to the repo:
```bash
yarn add @backstage/plugin-circleci
yarn workspace app add @backstage/plugin-circleci
```
2. Add the plugin itself:
Note the plugin is added to the `app` package, rather than the root
package.json. Backstage Apps are set up as monorepos with
[yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). Since
CircleCI is a frontend UI plugin, it goes in `app` rather than `backend`.
2. Add the plugin itself to the App:
```js
// packages/app/src/plugins.ts
docs/getting-started/deployment-docker.md
+15 -27
View File
@@ -27,9 +27,9 @@ The required steps in the host build are to install dependencies with
`yarn install`, generate type definitions using `yarn tsc`, and build all
packages with `yarn build`.
> NOTE: Using `yarn build` to build packages and bundle the backend assumes that
> you have migrated to using `backstage-cli backend:bundle` as your build script
> in the backend package.
> NOTE: If you created your app prior to 2021-02-18, follow the
> [migration step](https://github.com/backstage/backstage/releases/tag/release-2021-02-18)
> to move from `backend:build` to `backend:bundle`.
In a CI workflow it might look something like this:
@@ -43,22 +43,10 @@ yarn tsc
yarn build
```
Once the host build is complete, we are ready to build our image. We use the
following `Dockerfile`, which is also included when creating a new app with
`@backstage/create-app`:
Once the host build is complete, we are ready to build our image. The following
`Dockerfile` is included when creating a new app with `@backstage/create-app`:
```Dockerfile
# This dockerfile builds an image for the backend package.
# It should be executed with the root of the repo as docker context.
#
# Before building this image, be sure to have run the following commands in the repo root:
#
# yarn install
# yarn tsc
# yarn build
#
# Once the commands have been run, you can build the image using `yarn build-image`
FROM node:14-buster-slim
WORKDIR /app
@@ -78,15 +66,15 @@ CMD ["node", "packages/backend", "--config", "app-config.yaml"]
For more details on how the `backend:bundle` command and the `skeleton.tar.gz`
file works, see the
[`backend:bundle` command docs](../cli/commands.md#backendbundle)
[`backend:bundle` command docs](../cli/commands.md#backendbundle).
The `Dockerfile` is typically placed at `packages/backend/Dockerfile`, but needs
to be executed with the root of the repo as the build context, in order to get
access to the root `yarn.lock` and `package.json`, along with any other files
that might be needed, such as `.npmrc`.
The `Dockerfile` is located at `packages/backend/Dockerfile`, but needs to be
executed with the root of the repo as the build context, in order to get access
to the root `yarn.lock` and `package.json`, along with any other files that
might be needed, such as `.npmrc`.
In order to speed up the build we can significantly reduce the build context
size using the following `.dockerignore` in the root of the repo:
The `@backstage/create-app` command adds the following `.dockerignore` in the
root of the repo to speed up the build by reducing build context size:
```text
.git
@@ -96,9 +84,9 @@ packages
plugins
```
With the project build and the `.dockerignore` and `Dockerfile` in place, we are
now ready to build the final image. Assuming we're at the root of the repo, we
execute the build like this:
With the project built and the `.dockerignore` and `Dockerfile` in place, we are
now ready to build the final image. From the root of the repo, execute the
build:
```bash
docker image build . -f packages/backend/Dockerfile --tag backstage