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

Merge pull request #4250 from adamdmharvey/k8s-realign-doco

Browse Source 
docs: Update Kubernetes section with install & configure
This commit is contained in:
Ben Lambert
2021-01-26 10:37:05 +01:00
committed by GitHub
parent 592f2180ac 682b2c6a10
commit 3362a8571b
7 changed files with 302 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/features/kubernetes/backstage-k8s-2-deployments.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 125 KiB

docs/features/kubernetes/configuration.md
+130
View File
@@ -0,0 +1,130 @@
---
id: configuration
title: Configuring Kubernetes integration
sidebar_label: Configuration
# prettier-ignore
description: Configuring the Kubernetes integration for Backstage expose your entity's objects
---
Configuring the Backstage Kubernetes integration involves two steps:
1. Enabling the backend to collect objects from your Kubernetes cluster(s).
2. Surfacing your Kubernetes objects in catalog entities
## Configuring Kubernetes Clusters
The following is a full example entry in `app-config.yaml`:
```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/kubernetes/index.md
+17 -114
View File
@@ -5,123 +5,26 @@ 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.
Kubernetes in Backstage is a tool that's designed around the needs of service
owners, not cluster admins. Now developers can easily check the health of their
services no matter how or where those services are deployed — whether it's on a
local host for testing or in production on dozens of clusters around the world.
## Configuration
It will elevate the visibility of errors where identified, and provide drill
down about the deployments, pods, and other objects for a service.
Example:
![Kubernetes plugin screenshot](../../assets/features/kubernetes/backstage-k8s-2-deployments.png)
```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'
```
The feature is made up of two plugins:
[`@backstage/plugin-kubernetes`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes)
and
[`@backstage/plugin-kubernetes-backend`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend).
### serviceLocatorMethod
The frontend plugin exposes information to the end user in a digestible way,
while the backend wraps the mechanics to connect to Kubernetes clusters to
collect the relevant information.
This configures how to determine which clusters a component is running in.
## Let's use it!
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'
```
To get started, first you must [install the Kubernetes plugins](installation.md)
and then [configure them](configuration.md).
docs/features/kubernetes/installation.md
+119
View File
@@ -0,0 +1,119 @@
---
id: installation
title: Installation
description: Installing Kubernetes plugin into Backstage
---
The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when
viewing entities in the software catalog.
If you haven't setup Backstage already, start
[here](../../getting-started/index.md).
## Adding the Kubernetes frontend plugin
The first step is to add the frontend Kubernetes plugin to your Backstage
application. Navigate to your new Backstage application directory. And then to
your `packages/app` directory, and install the `@backstage/plugin-kubernetes`
package.
```bash
cd my-backstage-app/
cd packages/app
yarn add @backstage/plugin-kubernetes
```
Once the package has been installed, you need to import the plugin in your app.
Add the following to `packages/app/src/plugins.ts`:
`plugins.ts`:
```typescript
export { plugin as Kubernetes } from '@backstage/plugin-kubernetes';
```
Now, add the "Kubernetes" tab to the catalog entity page. In
`packages/app/src/components/catalog/EntityPage.tsx`, you'll add a router to get
to the tab, and add the tab itself.
`EntityPage.tsx`:
```tsx
import { Router as KubernetesRouter } from '@backstage/plugin-kubernetes';
// ...
const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
<EntityPageLayout>
// ...
<EntityPageLayout.Content
path="/kubernetes/*"
title="Kubernetes"
element={<KubernetesRouter entity={entity} />}
/>
// ...
</EntityPageLayout>
);
```
That's it! But now, we need the Kubernetes Backend plugin for the frontend to
work.
## Adding Kubernetes Backend plugin
Navigate to `packages/backend` of your Backstage app, and install the
`@backstage/plugin-kubernetes-backend` package.
```bash
cd my-backstage-app/
cd packages/backend
yarn add @backstage/plugin-kubernetes-backend
```
Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and
add the following
`kubernetes.ts`:
```typescript
import { createRouter } from '@backstage/plugin-kubernetes-backend';
import { PluginEnvironment } from '../types';
export default async function createPlugin({
logger,
config,
}: PluginEnvironment) {
return await createRouter({ logger, config });
}
```
And import the plugin to `packages/backend/src/index.ts`. There are three lines
of code you'll need to add, and they should be added near similar code in your
existing Backstage backend.
`index.ts`:
```typescript
import kubernetes from './plugins/kubernetes';
// ...
const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
// ...
apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
```
That's it! The Kubernetes frontend and backend have now been added to your
Backstage app.
## Running Backstage locally
Start the frontend and the backend app by
[running backstage locally](../../getting-started/running-backstage-locally.md).
## Configuration
After installing the plugins in the code, you'll need to then
[configure them](configuration.md).
microsite/sidebars.json
+5 -1
View File
@@ -39,7 +39,11 @@
{
"type": "subcategory",
"label": "Kubernetes",
"ids": ["features/kubernetes/overview"]
"ids": [
"features/kubernetes/overview",
"features/kubernetes/installation",
"features/kubernetes/configuration"
]
},
{
"type": "subcategory",
plugins/kubernetes-backend/README.md
+9 -73
View File
@@ -1,83 +1,19 @@
# Kubernetes Backend
WORK IN PROGRESS
This is the backend part of the Kubernetes plugin for Backstage. It is called by and responds to requests from the frontend [`@backstage/plugin-kubernetes`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes) plugin.
This is the backend part of the Kubernetes plugin.
It directly interfaces with the Kubernetes API control plane to obtain information about objects that will then be presented at the front end.
It responds to Kubernetes requests from the frontend.
## Introduction
## Configuration
See our announcement blog post [New Backstage feature: Kubernetes for Service Owners](https://backstage.io/blog/2021/01/12/new-backstage-feature-kubernetes-for-service-owners) to learn more about the motivation behind developing the plugin.
### serviceLocatorMethod
## Setup & Configuration
This configures how to determine which clusters a component is running in.
This plugin must be explicitly added to a Backstage app, along with it's peer frontend plugin.
Currently, the only valid serviceLocatorMethod is:
The plugin requires configuration in the Backstage `app-config.yaml` to connect to a Kubernetes API control plane.
#### multiTenant
In addition, configuration of an entity's `catalog-info.yaml` helps identify which specific Kubernetes object(s) should be presented on a specific entity catalog page.
This configuration assumes that all components run on all the provided clusters.
### clusterLocatorMethods
This is used to determine where to retrieve cluster configuration from.
Currently, the only valid serviceLocatorMethod is:
#### config
This clusterLocatorMethod will read cluster information in from config
Example:
```yaml
kubernetes:
serviceLocatorMethod: 'multiTenant'
clusterLocatorMethods:
- 'config'
clusters:
- url: http://127.0.0.1:9999
name: minikube
serviceAccountToken: <TOKEN FROM STEP 4>
authProvider: 'serviceAccount'
- url: http://127.0.0.2:9999
name: gke-cluster-1
authProvider: 'google'
```
##### clusters
Used by the `config` `clusterLocatorMethods` to construct Kubernetes clients.
###### 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.
###### 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.
###### authProvider
This determines how the Kubernetes client authenticate 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. |
###### serviceAccount (optional)
The service account token to be used when using the `authProvider`, `serviceAccount`.
## RBAC
The current RBAC permissions required are read-only cluster wide, for the following objects:
- pods
- services
- configmaps
- deployments
- replicasets
- horizontalpodautoscalers
- ingresses
For more information, see the [formal documentation about the Kubernetes feature in Backstage](https://backstage.io/docs/features/kubernetes/overview).
plugins/kubernetes/README.md
+22 -39
View File
@@ -1,9 +1,29 @@
# kubernetes
# Kubernetes
Welcome to the kubernetes plugin!
Welcome to the Backstage Kubernetes frontend plugin!
This plugin exposes information about your entity-specific Kubernetes objects with a desire to provide value to the service owner, rather than just a Kubernetes cluster administrator.
It will elevate the visibility of errors where identified, and provide drill down about the deployments, pods, and other objects for a service.
It directly interfaces with the [Kubernetes Backend Plugin (`@backstage-plugin-kubernetes-backend`)](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend).
_This plugin was created through the Backstage CLI_
## Introduction
See our announcement blog post [New Backstage feature: Kubernetes for Service Owners](https://backstage.io/blog/2021/01/12/new-backstage-feature-kubernetes-for-service-owners) to learn more about the motivation behind developing the plugin.
## Setup & Configuration
This plugin must be explicitly added to a Backstage app, along with it's peer backend plugin.
It requires configuration in the Backstage `app-config.yaml` to connect to a Kubernetes API control plane.
In addition, configuration of an entity's `catalog-info.yaml` helps identify which specific Kubernetes object(s) should be presented on a specific entity catalog page.
For more information, see the [formal documentation about the Kubernetes feature in Backstage](https://backstage.io/docs/features/kubernetes/overview).
## 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 [/kubernetes](http://localhost:3000/kubernetes).
@@ -11,40 +31,3 @@ Your plugin has been added to the example app in this repository, meaning you'll
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.
## 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.
```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 must be labeled with the following label:
```yaml
'backstage.io/kubernetes-id': <ENTITY_NAME>
```
### label selector query annotation
#### Adding a 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 documentation [here](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'
```