Backstage frontend plugin

Create a developer portal in Backstage for your developers to view and access your portal API products.

You can use the Gloo Portal Backstage frontend plugin to create a developer portal frontend for your developers so that they can view and access your API products. The Backstage platform allows you to expose multiple infrastructure and software development tools under a centralized software catalog. You can also find Gloo Portal’s plugin from the Backstage plugin catalog.

Looking to add your Gloo Portal APIs to your existing Backstage API catalog? Try the backend plugin. By setting up the backend, you create the necessary Backstage entities to integrate your APIs into the Backstage catalog. You also enable periodic fetching to make sure your APIs stay up to date. Then, you can use your APIs as part of Backstage, such as to bundle your API products with other APIs in the Backstage catalog to create your own customized developer portal.

Before you begin

Create the backend portal, to create and expose the portal server securely. Skip the frontend portal steps in that tutorial, which uses the sample React app.
Store the URL to your developer portal app as an environment variable. The following example uses https://developer.example.com.
```
export PORTAL_URL=https://developer.example.com
```
Decide on the OpenID Connect (OIDC) provider that you want to use, such as Keycloak or Okta. For other examples, review the OIDC and OAuth guides. After following the guides, you get the following information for the frontend plug-in.
```
echo $PORTAL_URL
echo $CLIENT_ID
echo $TOKEN_ENDPOINT
echo $AUTH_ENDPOINT
echo $LOGOUT_ENDPOINT
```

Step 1: Install the Gloo Portal Backstage plugin

You can install a frontend plugin for your developer portal in your Backstage application. Choose from among the following options.

This guide assumes that you created a Backstage app that is named portal and that the portal directory represents the Backstage root directory. If you use a Backstage version earlier than v1.27.0, use the Gloo Portal plug-in version 0.0.8. For steps, see the NPM plug-in readme.

You can use a sample container image in Solo’s public image registry, gcr.io/solo-public/docs/portal-backstage-frontend. This image is for a simple Backstage app that already has the Gloo Portal plugin integrated. Continue to Deploy your Backstage app.

The following example uses a sample app for demonstration purposes only. You can use the app to try out the feature and to help design your own app. The app is not intended for production use and might not have updated dependencies or security patches.

Create or use an existing Backstage app. If you do not have a Backstage app, follow the getting started guide to install one on your local machine.
```
cd portal
```

Install the Gloo Portal Backstage frontend plugin into your Backstage app.

yarn --cwd ./packages/app add @solo.io/platform-portal-backstage-plugin-frontend

From the Backstage app root directory, open the /packages/app/src/App.tsx file.
```
open packages/app/src/App.tsx
```

Add the following imports to the top of the App.tsx file.

import {
  GlooPortalHomePage,
  GlooPortalApiDetailsPage,
} from '@solo.io/platform-portal-backstage-plugin-frontend';

In the same App.tsx file, add the following routes to the <FlatRoutes> element.

<Route path="/gloo-platform-portal" element={<GlooPortalHomePage />} />
<Route path="/gloo-platform-portal/apis" element={<GlooPortalHomePage />} />
<Route path="/gloo-platform-portal/usage-plans" element={<GlooPortalHomePage />} />
<Route
  path="/gloo-platform-portal/apis/:apiId"
  element={<GlooPortalApiDetailsPage />}
/>

From the Backstage app root directory, open the /packages/app/src/components/Root/Root.tsx file.
```
open packages/app/src/components/Root/Root.tsx
```

Add the following import to the top of the Root.tsx file.

import { GlooIcon } from '@solo.io/platform-portal-backstage-plugin-frontend';

In the same Root.tsx file, add the following icon to the <SidebarScrollWrapper/> element.
```
<SidebarItem icon={GlooIcon} to="gloo-platform-portal" text="Gloo Portal" />
```
From the Backstage app root directory, open the app-config.local.yaml file.
```
open app-config.local.yaml
```

Configure the details of the OAuth identity provider that you use for external authentication to your Gloo Portal. Replace the $PORTAL_URL, $CLIENT_ID, $TOKEN_ENDPOINT, $AUTH_ENDPOINT, and $LOGOUT_ENDPOINT variables with the values that you previously retrieved. For more information, see the OAuth step in Before you begin.

Example command to get your OAuth details:

echo $PORTAL_URL
echo $CLIENT_ID
echo $TOKEN_ENDPOINT
echo $AUTH_ENDPOINT
echo $LOGOUT_ENDPOINT

Example app-config.local.yaml file:

# Backstage override configuration for your local development environment
glooPlatformPortal:
  # The URL of the Gloo Portal REST server.
  # Format this variable with a "/v1" path, such as: "http://developer.example.com/v1".
  # The default value is: "http://localhost:31080/v1".
  portalServerUrl: "$PORTAL_URL"

  # The OAuth identity provider's Client ID.
  # In Keycloak, open the $KEYCLOAK_URL UI, click Clients, and from the Settings tab, find the Client ID.
  # In Okta, open your $OKTA_URL and from the Applications section, find your app's Client ID.
  clientId: "$CLIENT_ID"

  # In Okta or Keycloak, you can find the following endpoints
  # the well-known OpenID config path for your authorization server, such as:
  # $KEYCLOAK_URL/auth/realms/<your-realm>/.well-known/openid-configuration
  # $OKTA_URL/oauth2/default/.well-known/openid-configuration

  # The `token_endpoint` is where to get the OAuth token.
  tokenEndpoint: "$TOKEN_ENDPOINT"

  # The `authorization_endpoint` is where to get the PKCE authorization code.
  authEndpoint: "$AUTH_ENDPOINT"

  # The `end_session_endpoint` is where to end the session.
  logoutEndpoint: "$LOGOUT_ENDPOINT"

Open the Backstage app. The app opens on http://localhost:3000.
```
yarn dev
```
From the menu, select Gloo Portal. Verify that you see the Gloo Portal welcome screen.
Figure: Gloo Portal welcome screen
Figure: Gloo Portal welcome screen
Click Login. You are redirected to your OAuth provider site, where you can log in with the credentials of one of the users that you configured, such as user1 username and password password for Keycloak.

You successfully installed and verified the Gloo Portal frontend plugin for Backstage!

Step 2: Deploy your Backstage app

In the previous section, you set up your Backstage app with the Gloo Portal frontend plugin locally. Now, you can deploy your Backstage app to your cluster.

The following steps use a simple deployment with Solo’s sample Backstage frontend app. To create your own Backstage app, you can follow the Backstage documentation to containerize and deploy your Backstage app as a Kubernetes deployment.

Create a Postgres database instance that your Backstage app can access.
- Local deployment in the cluster: You might deploy Postgres to your cluster. Make sure that you update the Backstage instructions for your environment, such as the storage classes from your cloud provider.
- Cloud deployment: You might create a Postgres database instance in the same cloud provider, such as Amazon RDS for Postgres SQL or Google Cloud SQL.
  Make sure that your cluster can connect to the Postgres instance. For example, you might have to create the Postgres instance in the same virtual private cloud (VPC) network as your cluster and enable connectivity.
Create a secret with the connection details of the Postgres database instance to use for your Backstage deployment.
- POSTGRES_USER: A common default username is postgres. If your username differs, update this value.
- POSTGRES_PASSWORD: Replace with the password for the username to your Postgres instance.
- POSTGRES_HOST: Replace with the hostname to your Postgres instance. Note that this host must be accessible from your cluster. If you deployed Postgres in your cluster, this value is the name of the service in the same namespace as your Backstage app, such as postgres.
- POSTGRES_PORT: The default port is 5432. If your port is different, update this value.
```
kubectl apply -f- <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: postgres-secrets
  namespace: backstage
type: Opaque
stringData:
  POSTGRES_USER: "postgres"
  POSTGRES_PASSWORD: "password"
  POSTGRES_HOST: "postgres"
  POSTGRES_PORT: "5432"
EOF
```
Create a secret with the details of the OAuth identity provider that you use for external authentication to your Gloo Portal. Replace the variables with the values that you previously retrieved. For more information, see the OAuth step in Before you begin.
- PORTAL_SERVER_URL: The URL that the Gloo Portal REST server is available on. This URL matches the host in the route table for the gloo-mesh-portal-server, such as http://developer.example.com. You can check the hostnames of your route tables with the following command. For local development, use the default value http://localhost:31080/v1. Format this variable with a /v1 path, such as: http://developer.example.com/v1.
- CLIENT_ID: The OAuth identity provider’s Client ID.
  - In Keycloak, open the $KEYCLOAK_URL, click Clients, and from the Settings tab, find the Client ID.
  - In Okta, open the $OKTA_URL and from the Applications section, find your app’s Client ID.
- In your OAuth provider, access the well-known OpenID config path for your authorization server, such as the following examples for Keycloak and Okta.
  - Keycloak OpenID config path: $KEYCLOAK_URL/auth/realms/<your-realm>/.well-known/openid-configuration
  - Okta OpenID config path: $OKTA_URL/oauth2/default/.well-known/openid-configuration
- From the OpenID config path, get the values for the following endpoints:
  - TOKEN_ENDPOINT: The endpoint to get the OAuth token.
  - AUTH_ENDPOINT: The endpoint to get the PKCE authorization code.
  - LOGOUT_ENDPOINT: The endpoint to end the session.
Keep in mind that the Portal URL and OAuth endpoints that you set in the deployment configuration must match. For example, if you use a secure HTTPS gateway, then the Portal URL and OAuth endpoints should begin with https:// instead of http://.
```
kubectl apply -f- <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: backstage-secrets
  namespace: backstage
type: Opaque
stringData:
  PORTAL_SERVER_URL: "http://developer.example.com"
  CLIENT_ID: "$CLIENT_ID"
  TOKEN_ENDPOINT: "$TOKEN_ENDPOINT"
  AUTH_ENDPOINT: "$AUTH_ENDPOINT"
  LOGOUT_ENDPOINT: "$LOGOUT_ENDPOINT"
EOF
```
Create the Kubernetes resources that you need to run your Backstage frontend app.
- ServiceAccount: Create a separate service account for your frontend app so that its identity is separate from the other apps that run in the namespace.
- Service: Create a service for the frontend app so that you can expose it securely.
- Deployment: Create a deployment to run the frontend app.
  The following example uses a sample Backstage image from Solo’s public image registry. If you built your container image in a different container registry, copy and update the YAML configuration file image location before applying the file to your cluster.
```
kubectl apply -n backstage -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/backstage-frontend-deployment.yaml
```

Create a ReferenceGrant to allow HTTPRoutes to refer to Services in the backstage namespace.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: backstage
  namespace: backstage
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: gloo-system
  to:
    - group: ""
      kind: Service
EOF

Create or update the HTTPRoute for the frontend developer portal to forward requests to the Backstage frontend app. Depending on the AuthConfig and related RouteOption that you created to secure access to the portal, update the ExtensionRef filter.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: portal-frontend-backstage
  namespace: gloo-system
spec:
  parentRefs:
    - name: http
      namespace: gloo-system
  hostnames:
    - portal.example.com
  rules:
    - backendRefs:
        - name: backstage-frontend
          namespace: backstage
          port: 4000
      filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.solo.io
            kind: RouteOption
            name: okta-portal-auth-code
EOF

Verify your Backstage frontend app.

Step 3: Verify your Backstage frontend app

Now that you built and deployed your frontend app, you can access the developer portal in your browser.

Check that the Backstage frontend app’s resources are healthy.
```
kubectl get all -n backstage -l app=backstage-frontend
```
Verify that you can access the developer portal frontend in your web browser. If you used the example in this guide, enter http://developer.example.com/ in your web browser.
Figure: Backstage portal welcome screen
Figure: Backstage portal welcome screen

Next steps

Great job! You deployed the Backstage frontend app for the developer portal. Now, when you update your Portal resource to add new API products, usage plans, or metadata, the frontend is automatically updated for you.

If you didn’t already, you can follow the Backstage docs to customize the frontend app for your brand.
Share the developer portal guide with your end users so that they know how to interact with the developer portal.

Backstage backend plugin