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.

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