Skip to main content

API Portal

Configure and manage API Portals.

Introduction​

An API Developer Portal is a centralized hub designed for developers, architects, and other API-focused roles. It serves as a comprehensive catalog where both internal and external API consumers can discover, understand, and use APIs created by API publishers.

The primary purpose of an API Developer Portal is to ensure that developers can effectively consume APIs when building services and applications. It provides a user-friendly interface to browse API documentation, test API endpoints, and manage credentials.

By offering the above resources, the portal removes the burden of credential management from the API creator. This lets developers handle various aspects of the application development lifecycle independently.

Traefik Hub API Management enables API owners to automatically create a developer portal based on the API resources declared in their cluster.

The APIPortal Object​

The APIPortal object is a Kubernetes Custom Resource Definition (CRD) that allows API owners to create an API Developer Portal. It automatically generates a web interface to browse the documentation of all APIs within its scope. This portal provides a unified view of available APIs tailored to the specific needs of different user groups.

API visibility in the APIPortal depends on user groups. An API will be visible only if the connected API consumer belongs to a group with access to that API, as specified by APIAccess objects. This means that users only see APIs assigned to their groups, maintaining controlled and segmented access.

important

The portal enforces namespace boundaries and considers only APIAccess resources within the same namespace as the APIPortal.

Once configured, APIPortals are exposed to end users using Ingress or IngressRoute objects. To do this, follow these steps:

  1. Use an Ingress or an IngressRoute to expose the apiportal Service located in the traefik-hub namespace on port 9903.
  2. Link it with APIPortal resource using the annotation hub.traefik.io/api-portal.

The apiportal Service is automatically created during the installation of Traefik Hub and is located in the traefik-hub namespace. Unless cross-namespace references are supported, the APIPortal must be declared in this namespace.

info

Cross-namespace reference support depends of the Ingress object and therefore depends on the Traefik providers:

  • Ingress object, controlled by the Traefik provider kubernetesIngress, supports cross-namespace, this capability can't be turned off.
  • IngressRoute object, controlled by the Traefik provider kubernetesCRD, supports cross-namespace but the capability needs to be enabled.

You can enable cross-namespace support on IngressRoute resources using the following static configuration:

providers:
  kubernetesCRD:
    allowCrossNamespace: true
tip

Using a combination of Ingress objects for APIPortals and IngressRoute for routing offers more flexibility in managing your APIs. You can define your API, APIAccess, and APIPortal in one namespace, while still referencing the apiportal Service from the traefik-hub namespace. This approach allows you to maintain security by keeping cross-namespace references turned off on IngressRoute.

This method also simplifies the deployment process, ensuring that your APIPortals are accessible without compromising on namespace isolation.

Configuring Portal Authentication​

The content of an API Developer Portal is only visible to authenticated users. For details on onboarding new users, refer to the User and Group Management documentation page.

To ensure secure authentication, configure the list of trusted URLs in your API Developer Portal setup. The trustedUrls property acts as an allowlist, specifying URLs authorized to receive authentication redirects from the portal. This ensures that sensitive authentication data is only sent to approved destinations.

Typically, the values to include are the host configured in your Ingress object with the path prefix under which your portal is exposed. For example:

trustedUrls:
  - https://portal.example.com/prefix

Example​

In this example, we will create a new API Developer Portal for a set of APIs deployed in the default namespace. First of all, we need to create a new APIPortal object.

Configuration of an APIPortal
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: my-portal
  namespace: default
spec:
  title: "My Portal" # The title for the Portal
  description: "API documentations" # A short description of the Portal
  trustedUrls:
    - "https://portal.example.com"
  ui:
    logoUrl: https://traefik.io/favicon.png # URL to a picture used as logo

Next, the APIPortal can be exposed:

Ingress exposing the APIPortal
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-portal-ingress
  namespace: traefik-hub
  annotations:
    hub.traefik.io/api-portal: my-portal@default # Reference the APIPortal object
spec:
  rules:
    - host: portal.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: apiportal
                port:
                  number: 9903