Reorg Kubernetes section
This commit is contained in:
Adam Harvey
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
@@ -0,0 +1,129 @@
|
||||
---
|
||||
id: configuration
|
||||
title: Configuring Kubernetes integration
|
||||
sidebar_label: Configuration
|
||||
description: Monitoring Kubernetes based services with the service catalog
|
||||
---
|
||||
|
||||
Configuring the Backstage Kubernetes integration involves two steps:
|
||||
|
||||
1. Enabling the backend to collect objects from your Kubernetes cluster(s).
|
||||
2. Surfacing your Kubernetes as part of a catalog entity
|
||||
|
||||
## 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'
|
||||
```
|
||||
@@ -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:
|
||||
|
||||
|
||||
```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).
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installation
|
||||
description: Installing Kubernetes plugin
|
||||
---
|
||||
|
||||
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 them
|
||||
[configure them](configuration.md).
|
||||
@@ -39,7 +39,11 @@
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Kubernetes",
|
||||
"ids": ["features/kubernetes/overview"]
|
||||
"ids": [
|
||||
"features/kubernetes/overview",
|
||||
"features/kubernetes/installation",
|
||||
"features/kubernetes/configuration"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "subcategory",
|
||||
|
||||
Reference in New Issue
Block a user