You are browsing documentation for an older version. See the latest documentation here.

Kong Developer Portal

This guide shows how to deploy the Kong Developer Portal, a self-hosted portal that comes with Kong Gateway Enterprise. For new developer portal deployments, we recommend using the Kong Konnect developer portal.

Prerequisites

• Kong Gateway installed
• Kong’s Admin API is accessible over HTTP from your local machine

Installation

Kong Developer Portal is deployed as part of the kong-cp deployment as it needs access to the database for the Portal API to manage API specifications and content.

1. Update the values-cp.yaml file to enable Dev Portal by merging the following values into your existing values-cp.yaml file.

    env:
      # Portal configuration
      # CHANGE THESE VALUES
      portal_gui_protocol: http
      portal_gui_host: portal.example.com
      portal_api_url: http://portalapi.example.com
      portal_session_conf: '{"cookie_name": "portal_session", "secret": "PORTAL_SUPER_SECRET", "storage": "kong", "cookie_secure": false, "cookie_domain":".example.com"}'
       
    # Enable Developer Portal
    enterprise:
      portal:
        enabled: true
   

2. Update the portal hostname values in values-cp.yaml.

   • env.portal_gui_protocol: The protocol to use for the GUI, either HTTP or HTTPS
   • env.portal_gui_host: The hostname that you’ll use to access the portal
   • env.portal_api_url: The publicly accessible API URL for Dev Portal data
   • env.portal_session_conf: Update the value in secret and cookie_domain

3. Configure the portal section in values-cp.yaml. Replace example.com with your custom domain name.

   EKS

   AKS

   GKE

   KIC

   portal:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portal.example.com
       path: /
       pathType: Prefix
       ingressClassName: alb
       annotations:
         alb.ingress.kubernetes.io/load-balancer-name: kong-alb-public
         alb.ingress.kubernetes.io/group.name: demo.kong-alb-public
         alb.ingress.kubernetes.io/target-type: instance
         alb.ingress.kubernetes.io/scheme: internet-facing
         alb.ingress.kubernetes.io/healthcheck-path: /
         alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'

   portal:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portal.example.com
       path: /
       pathType: Prefix
       ingressClassName: azure-application-gateway
       annotations:
         appgw.ingress.kubernetes.io/use-private-ip: "false"

   portal:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
     annotations:
       beta.cloud.google.com/backend-config: '{"default":"kong-hc"}'
     ingress:
       enabled: true
       hostname: portal.example.com
       path: /
       pathType: Prefix
       annotations:
         kubernetes.io/ingress.class: gce

   portal:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portal.example.com
       path: /
       pathType: Prefix
       ingressClassName: kong

4. Configure the portalapi section in values-cp.yaml. Replace example.com with your custom domain name.

   EKS

   AKS

   GKE

   KIC

   portalapi:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portalapi.example.com
       path: /
       pathType: Prefix
       ingressClassName: alb
       annotations:
         alb.ingress.kubernetes.io/load-balancer-name: kong-alb-public
         alb.ingress.kubernetes.io/group.name: demo.kong-alb-public
         alb.ingress.kubernetes.io/target-type: instance
         alb.ingress.kubernetes.io/scheme: internet-facing
         alb.ingress.kubernetes.io/healthcheck-path: /
         alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'

   portalapi:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portalapi.example.com
       path: /
       pathType: Prefix
       ingressClassName: azure-application-gateway
       annotations:
         appgw.ingress.kubernetes.io/use-private-ip: "false"

   portalapi:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
     annotations:
       beta.cloud.google.com/backend-config: '{"default":"kong-hc"}'
     ingress:
       enabled: true
       hostname: portalapi.example.com
       path: /
       pathType: Prefix
       annotations:
         kubernetes.io/ingress.class: gce

   portalapi:
     enabled: true
     http:
       enabled: true
     tls:
       enabled: false
        
     ingress:
       enabled: true
       hostname: portalapi.example.com
       path: /
       pathType: Prefix
       ingressClassName: kong

5. Run helm upgrade to update the release.

    helm upgrade kong-cp kong/kong -n kong --values ./values-cp.yaml
   

6. Fetch the Ingress IP address and update your DNS records to point at the Ingress address. You can configure DNS manually, or use a tool like external-dns to automate DNS configuration.

   Both portal and portalapi are accessible using the same LoadBalancer. Use the endpoint returned by the following command to configure both portal.example.com and portalapi.example.com.

    kubectl get ingress -n kong kong-cp-kong-portal -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}'
   

Enable the Dev Portal

The Kong Developer Portal is not enabled by default in a new Kong Gateway installation. Use the Admin API to enable the portal. Make sure to change the domain, and Kong-Admin-Token values to match your installation.

curl -X PATCH http://admin.example.com/default/workspaces/default -d config.portal=true -H 'Kong-Admin-User: kong_admin' -H 'Kong-Admin-Token: YOUR_PASSWORD'

Testing

Visit http://portal.example.com/ in a browser. You will see a page that says “Built with Kong” with three sample OpenAPI specifications.

Troubleshooting

I can’t log in

If the screen refreshes but you are not logged in to the dev portal, check that cookie_domain is set correctly in values-cp.yaml. Cookies are set on the portal API domain by default. cookie_domain is required to allow the portal to read authentication cookies from the portal API.