add some documentation

This commit is contained in:
Manabu Mccloskey 2023-07-07 08:21:11 -07:00
parent 9156119940
commit 250f7a20fb
3 changed files with 70 additions and 9 deletions

View file

@ -1,13 +1,76 @@
# apache-spark
# Apache Spark Plugin for Backstage
Welcome to the apache-spark plugin!
Welcome to the Apache Spark plugin for Backstage!
_This plugin was created through the Backstage CLI_
This plugin allows you to display information related to your Apache Spark Applications running in Kubernetes on Backstage
## Getting started
Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/apache-spark](http://localhost:3000/apache-spark).
![GIF](doc/images/demo1.gif)
You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
### Configuration
Entities must be annotated with Kubernetes annotations. For example:
[The Kubernetes plugin](https://backstage.io/docs/features/kubernetes/) must also be installed and enabled.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: backstage
annotations:
backstage.io/kubernetes-namespace: default
backstage.io/kubernetes-label-selector: env=dev,my=label
```
Update your Entity page. For example:
```typescript
// in packages/app/src/components/catalog/EntityPage.tsx
```
#### Annotations
- `backstage.io/kubernetes-namespace`: Optional. Defaults to the `default` namespace.
- `backstage.io/kubernetes-label-selector`: Conditionally required. One of label selectors must be defined.
- `apache-spark/label-selector`: Conditionally required. One of label selectors must be defined. This value takes precedent over the one above.
- `apache-spark/cluster-name`: Optional. Specifies the name of Kubernetes cluster to retrieve information from.
### Authentication
This plugin uses the Kubernetes plugin for authentication.
#### Using configured Kubernetes API
The plugin uses configured Kubernetes clusters to fetch resources.
For example, for a Kubernetes cluster given in your `app-config.yaml`
```yaml
kubernetes:
serviceLocatorMethod:
type: "multiTenant"
clusterLocatorMethods:
- type: "config"
clusters:
- url: https://abcd.gr7.us-west-2.eks.amazonaws.com:443
name: my-cluster-1
authProvider: "serviceAccount"
serviceAccountToken: eyJh
caData: LS0t
```
For this configuration, the `argo-workflows/cluster-name` annotation value must be `my-cluster-1`. If this is not specified, the first cluster in the list is selected.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: backstage
annotations:
backstage.io/kubernetes-namespace: default
backstage.io/kubernetes-label-selector: env=dev,my=label
argo-workflows/cluster-name: my-cluster-1
```

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.9 MiB

View file

@ -2,8 +2,6 @@ import {
createApiFactory,
createPlugin,
createRoutableExtension,
discoveryApiRef,
fetchApiRef,
} from '@backstage/core-plugin-api';
import { rootRouteRef } from './routes';