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.

Before you begin

  1. Configure the developer portal, including to create and expose the portal server securely.
  2. Make sure that you set up the OAuth external authentication policy for the OIDC provider that you want to use, such as Keycloak or Okta.
  3. Configure the OAuth details to protect your frontend app. The steps vary by OIDC provider. For instructions, see the Basic OAuth for Portal guide.

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.

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.

  1. 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

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

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

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

      open packages/app/src/App.tsx

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

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

  5. 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 />}
/>

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

      open packages/app/src/components/Root/Root.tsx

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

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

  8. In the same Root.tsx file, add the following icon to the <SidebarScrollWrapper/> element.

      <SidebarItem icon={GlooIcon} to="gloo-platform-portal" text="Gloo Portal" />

  9. From the Backstage app root directory, open the app-config.local.yaml file.

      open app-config.local.yaml

  10. 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"

  11. Open the Backstage app. The app opens on http://localhost:3000.

      yarn dev

  12. 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

  13. 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.

  1. 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.

  2. 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

  3. 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.
      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

  4. 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.
      kubectl apply -n backstage -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/backstage-frontend-deployment.yaml

  5. Create a route table to expose the frontend app securely through the ingress gateway. The following example uses the host developer.example.com. It refers to the virtual gateway that you created when you configured the developer portal. For more examples such as HTTPS/TLS, see Configure gateway listeners.

      kubectl apply -f- <<EOF
apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: portal-backstage-frontend
  namespace: gloo-mesh-gateways
  labels:
    app: backstage-frontend
spec:
  hosts:
    - "developer.example.com"
  virtualGateways:
    - name: istio-ingressgateway-portal
      namespace: gloo-mesh-gateways
  http:
    - name: backstage-frontend
      forwardTo:
        destinations:
          - port:
              number: 80
            ref:
              name: backstage-frontend
              namespace: backstage
              cluster: $CLUSTER_NAME
      labels:
        route: portal-api
      matchers:
        - uri:
            prefix: /
EOF

  6. 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.

  1. Check that the Backstage frontend app’s resources are healthy.

      kubectl get all -n backstage -l app=backstage-frontend

  2. 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.