> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/plugins/available-plugins/kubernetes.md).

# Kubernetes

| Plugin details |                                                                                 |
| -------------- | ------------------------------------------------------------------------------- |
| **Created by** | Spotify                                                                         |
| **Category**   | Monitoring                                                                      |
| **Source**     | [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes) |
| **Type**       | Open-source plugin                                                              |

### Configuration <a href="#configuration" id="configuration"></a>

#### Application configuration YAML <a href="#application-configuration-yaml" id="application-configuration-yaml"></a>

The plugin supports two types of application configuration, which needs to be updated by the user in the **Configurations**

![](/files/9D7FUrQnAhNNyUyNsvCu)

**Authentication using a Kubernetes service account (default)**

```yaml
kubernetes:
  serviceLocatorMethod:
    type: "multiTenant"
  clusterLocatorMethods:
    - type: "config"
      clusters:
        - url: "<your-base-url>"
          name: "<your-cluster-name>"
          authProvider: "serviceAccount"
          skipTLSVerify: true
          skipMetricsLookup: false
          serviceAccountToken: ${K8S_SA_TOKEN}
```

**Authentication using Google Cloud Platform (GCP) credentials.**

```yaml
kubernetes:
  serviceLocatorMethod:
    type: "multiTenant"
  clusterLocatorMethods:
    - type: "config"
      clusters:
        - url: "<your-base-url>"
          name: "<your-cluster-name>"
          authProvider: "google"
          skipTLSVerify: true
          skipMetricsLookup: false
```

In both cases, replace `<your-base-url>` with the base URL of the target cluster. Replace `<your-cluster-name>` with a name that identifies the target cluster.

#### Secrets <a href="#secrets" id="secrets"></a>

If you are using a service account to authenticate, ensure that a secret variable `K8S_SA_TOKEN` is set with the Kubernetes service account key.

Make sure, the `Service Account` token generated above must have a `ClusterRole` with permissions as mentioned below in the example reference YAML.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 name: idp-clusterrole
 namespace: <namespace_name>
rules:
  - apiGroups: [""]
    resources: ["pods", "services", "configmaps", "namespaces", "limitranges"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets","daemonsets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["batch"]
    resources: ["jobs", "cronjobs"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses", "networkpolicies"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get", "list"]
```

If you are using GCP credentials to authenticate, you do not have to add a variable. Instead, configure the [Google OAuth provider](/internal-developer-portal/use-idp/plugins/oauth-support-for-plugins.md) on the **OAuth Configurations** page to enable the plugin to use the logged-in user's credentials when making requests.

#### Delegate proxy <a href="#delegate-proxy" id="delegate-proxy"></a>

If the target cluster is on a private network, ensure that you include the host portion of the cluster's base URL in this section. If the cluster is not on a private network, skip this section.

After adding the host, you can select one or more delegates that have access to the host. If you leave the delegate selectors field empty, it is assumed that all delegates in the account have access to the host/cluster.

{% hint style="info" %}
When adding the host, include only the host name. Remove the protocol (HTTP/HTTPS) and any port number associated with it.
{% endhint %}

![](/files/YeD4lpaXCiuZsAuofD1q)

### Layout <a href="#layout" id="layout"></a>

This plugin exports a UI tab that you can use as a new **Kubernetes** tab for a service or for any other layout page. Go to **Configure** → **Layout**, select **Service** in the dropdown menu. And then add the following in a new **Kubernetes** section:

```yaml
- name: kubernetes
  path: /kubernetes
  title: Kubernetes
  contents:
    - component: EntityKubernetesContent
```

![](/files/m3wNLx8jnS7UiOuhQzMl)

### Annotations <a href="#annotations" id="annotations"></a>

There are several annotations supported by the Kubernetes plugin, and you can use them in your service's `catalog-info.yaml` descriptor file to link to a Kubernetes entity. For details, go to the [plugin docs](https://backstage.io/docs/features/kubernetes/configuration#surfacing-your-kubernetes-components-as-part-of-an-entity).

#### Add the entity annotation <a href="#add-the-entity-annotation" id="add-the-entity-annotation"></a>

In order for IDP 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
```

#### Add the namespace annotation <a href="#add-the-namespace-annotation" id="add-the-namespace-annotation"></a>

Entities can have the `backstage.io/kubernetes-namespace` annotation, this will cause the entity's Kubernetes resources to by looked up via that namespace.

```yaml
annotations:
  'backstage.io/kubernetes-namespace': dice-space
```

#### Label selector query annotation <a href="#label-selector-query-annotation" id="label-selector-query-annotation"></a>

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 for more info.

```yaml
'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'
```

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Kubernetes is not showing up on service entities <a href="#kubernetes-is-not-showing-up-on-service-entities" id="kubernetes-is-not-showing-up-on-service-entities"></a>

This can be debugged by checking if the Service Account token has appropriate permissions or not.

The Kubernetes tab will not show anything when the catalog info annotation does not match the related Kubernetes resource. We recommend you add the following labels to your resources and use the label selector annotation as follows:

`backstage.io/kubernetes-id: <entity-service-name>` for get k8s service-related objects. [See the plugin code](https://github.com/backstage/backstage/blob/a1f587c/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts#L119)

```yaml
# k8s related yaml (service.yaml, deployment.yaml, ingress.yaml) <a href="#k8s-related-yaml-serviceyaml-deploymentyaml-ingressyaml" id="k8s-related-yaml-serviceyaml-deploymentyaml-ingressyaml"></a>
metadata:
  creationTimestamp: '2022-03-13T13:52:46.000Z'
  labels:
    app: <k8s-app-name>
    env: <environment>
    backstage.io/kubernetes-id: <service-entity-name>
  name: <k8s-app-name>
  namespace: <namespace>
```

`k8s-app-name` and `service-entity-name` could be different, but if you would like to have consistent names between k8s and backstage, we recommend use same name and the catalog info annotations would use label selector:

```yaml
# catalog-info.yaml (backstage) <a href="#catalog-infoyaml-backstage" id="catalog-infoyaml-backstage"></a>
annotations:
  backstage.io/kubernetes-label-selector: '<label-selector>'
```

### Use of K8s plugin <a href="#use-of-k8s-plugin" id="use-of-k8s-plugin"></a>

The Plugin displays the information on your cluster and health of the pods under these clusters, including information on namespace and CPU and Memory usage.

![](/files/h0JYkBhASjzpPGkKxjUl)

You can as well have a detailed view of your containers and pods, including the YAML view.

![](/files/ujB6n4uTVlB4b8d6UEZO) ![](/files/TnqykhXhCCBuHzLeLgg1) ![](/files/Cr2fbRWpYtPIRfq5mfZ7)

### Support <a href="#support" id="support"></a>

The plugin is owned by Spotify and managed in the [Backstage repository](https://github.com/backstage/backstage/tree/master/plugins/kubernetes) as an open-source project. Create a GitHub issue to report bugs or suggest new features for the plugin.