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

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

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

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

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

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