backstage-kyverno

• Description
• Setup Backstage with Kyverno-policy-reports
  • Step 1: Install packages
  • Step 2: Add the route
  • Step 3: Add the backend plugin
  • Step 4: Define Kubernetes Clusters
  • Step 5: Annotate Services
  • Optional: Custom policy documentation
    • Step 1: Update the EntityKyvernoPolicyReportsContent component
    • Step 2: Configure the Policy documentation
• How to annotate services
• Publishing New Versions of a Package
  • Step 1: Update the package.json version
  • Step 2: Run Yarn Install
  • Step 3: Include the updated yarn.lock in the pull request
  • Step 4: Merge the branch with main

Description

The Backstage-policy-reporter-plugin integrates Policy Reporter with Backstage to provide a clear and detailed view of Kyverno Policies applied to your entities

Setup Backstage with policy-reporter plugin

Step 1: Install packages

From your backstage root directory, run the following commands:

yarn --cwd packages/app add @kyverno/backstage-plugin-policy-reporter
yarn --cwd packages/backend add @kyverno/backstage-plugin-policy-reporter-backend

Step 2: Add the route

Add the desired policy-reporter component(s) to your Entity routes in packages/app/src/components/catalog/EntityPage.tsx Choose from the available components:

• EntityKyvernoPoliciesContent - Displays kyverno policies for an entity using the kyverno source
• EntityCustomPoliciesContent - Displays policy reports from a custom source

For detailed setup instructions including screenshots, see the Component Setup Guide.

EntityKyvernoPoliciesContent example

+ import { EntityKyvernoPoliciesContent } from '@kyverno/backstage-plugin-policy-reporter';

const serviceEntityPage = (

  <EntityLayout>

    // ...

+    <EntityLayout.Route path="/kyverno" title="kyverno policy">
+      <EntityKyvernoPoliciesContent />
+    </EntityLayout.Route>

    // ..

  </EntityLayout>
)

Step 3: Add the backend plugin

for the new backend system, add the plugin in packages/backend/src/index.ts

const backend = createBackend();

// ..
+backend.add(import('@kyverno/backstage-plugin-policy-reporter-backend'));
// ..

backend.start();

Step 4: Define Kubernetes Clusters

In your Backstage instance, define your Kubernetes clusters using the Resource kind and kubernetes-cluster type. Add the kyverno.io/endpoint annotation with the URL to the Policy Reporter API for each cluster.

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: aks-dev
  annotations:
    # Add the Policy Reporter API endpoint as an annotation
    kyverno.io/endpoint: http://kyverno.io/policy-reporter/api/
spec:
  type: kubernetes-cluster

Policy Reporter Endpoint Configuration

The kyverno.io/endpoint annotation should point to the Policy Reporter API. Use one of the following configurations:

When using Policy Reporter UI:

• UI Version 1: Use http://your-domain/policy-reporter/api/
• UI Version 2: Use http://your-domain/policy-reporter/proxy/default/core/

When using standalone Policy Reporter:

• The Policy Reporter backend needs to be exposed via an ingress (Ingress can be configured in the policy-reporter helmchart)
• Point to your ingress URL that exposes the Policy Reporter API (e.g., https://your-domain/api/)

Step 5: Annotate Services

To show the policies on the service, add a dependency to the Kubernetes cluster resource in the catalog-info.yaml file of your service. Ensure that the necessary annotations are added as well. For more details, refer to the How to annotate services section.

metadata:
  annotations:
    kyverno.io/namespace: default # Specify the namespace of the service
    kyverno.io/kind: Deployment,Pod # Specify the kind(s) of the Kubernetes resource(s)
    kyverno.io/resource-name: policy-reporter # Specify the name of the resource
spec:
  dependsOn:
    # Add dependency to all environments the service is deployed to using the Resource entityRef
    - resource:default/aks-dev
    - resource:default/aks-tst
    - resource:default/aks-qa
    - resource:default/aks-prd

Optional: Custom policy documentation

To configure the plugin to make the policy Chip a link to custom documentation, follow the steps below.

Step 1: Update the EntityKyvernoPolicyReportsContent component

To enable policy Chip links, the EntityKyvernoPolicyReportsContent component requires the policyDocumentationUrl prop to be set to the URL of the documentation.

const serviceEntityPage = (
  <EntityLayout>
    // ...
    <EntityLayout.Route path="/kyverno" title="kyverno policy">
      <EntityKyvernoPoliciesContent policyDocumentationUrl="Your full URL link" />
    </EntityLayout.Route>
    // ..
  </EntityLayout>
);

Step 2: Configure the Policy documentation

The policy documentation file provided in the above step needs to follow a specific structure.

All policies being used should have a header that matches the exact same name as the policy. Under this header, you can add information about the policy and provide a guide on how to solve it.

The plugin will create a link using the following format: <DocumentationUrl>#<PolicyName>

See the example/policy-documentation.md file for an example of how this could look.

How to annotate services

To use the Kyverno-Policy-Reports plugin with your services, you need to add the following annotations to your catalog-info.yaml:

• kyverno.io/namespace: This annotation specifies the Kubernetes namespace where the service is located. Multiple values can be separated by a comma (e.g., default,kyverno)
• kyverno.io/kind: This annotation specifies the kind of Kubernetes resource (e.g., Deployment, StatefulSet, Pod) Multiple values can be separated by a comma (e.g., Deployment,Pod).
• kyverno.io/resource-name: This annotation specifies the name of the resource

metadata:
  annotations:
    # Annotations for Kyverno-Policy-Reports
+    kyverno.io/namespace: default                   # Specify the namespace(s) of the service
+    kyverno.io/kind: Deployment,Pod                 # Specify the kind(s) of the Kubernetes resource(s)
+    kyverno.io/resource-name: policy-reporter       # Specify the name of the resource