Skip to main content

Integrating External APIs with Traefik Hub on Oracle Cloud Infrastructure

Traefik Hub integrates with Oracle Cloud Infrastructure to provide comprehensive API management capabilities for external APIs. This guide demonstrates how to expose APIs hosted outside your Kubernetes cluster (such as Oracle Integration Cloud endpoints) through Traefik Hub, complete with API plans, developer portals, and security configurations.

This tutorial builds upon the foundation established in the Deploy Traefik Hub API Management from Oracle Marketplace guide, extending it to support external API integration and advanced authentication scenarios.

Prerequisites​

Before you begin, ensure you have:

  • An OCI Kubernetes Engine cluster
  • Traefik Hub installed and running in your OCI Kubernetes Engine cluster. If you haven't set this up yet, follow this guide:
  • Access to your OCI Kubernetes Engine cluster
  • An external API endpoint (such as Oracle Integration Cloud) that you want to expose

Enable External API Support​

By default, Traefik Hub disables access to services of type ExternalName and cross-namespace references to follow the principle of least privilege. These features are safe to enable when needed for your specific use case. Since this integration involves exposing APIs hosted outside your Kubernetes cluster, you must explicitly enable these features.

For detailed information on external API configuration, refer to the External API Management documentation.

Update your Traefik Hub deployment to enable external API support:

helm upgrade --install \
  --namespace traefik \
  traefik traefik/traefik \
  --reset-then-reuse-values \
  --set "providers.kubernetesCRD.allowExternalNameServices=true" \
  --set "providers.kubernetesCRD.allowCrossNamespace=true"
info

You can also edit your Traefik Hub stack helm values to include Redis configuration and rerun the stack as described in the Deploy Traefik Hub API Management from Oracle Marketplace guide instead of using the command above.

Get Your Load Balancer IP​

Before proceeding with the configuration, obtain the IP address of your cluster's load balancer:

export EXTERNAL_IP=$(kubectl get svc -n traefik traefik -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "Use EXTERNAL_IP=${EXTERNAL_IP}"
info

Replace <EXTERNAL_IP> with this value in all subsequent configuration examples.

For production deployments, consider using a fully qualified domain name (FQDN) instead of an IP address to enable proper TLS certificate generation. This guide uses IP addresses to avoid dependencies on DNS providers.

Service and Routing Configuration​

Create Application Namespace​

Create a namespace for your external API configuration if you don't have one already:

kubectl create namespace apps

ExternalName Service Configuration​

Create an ExternalName service that points to your external API endpoint. In this example, we use httpbin.org but you can replace it with your own external API endpoint:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: oci-svc
  namespace: apps
spec:
  type: ExternalName
  externalName: httpbin.org # Replace with your external API endpoint
  ports:
    - port: 443
EOF

IngressRoute for External API​

Configure an IngressRoute to expose your external API through Traefik Hub:

cat <<EOF | kubectl apply -f -
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-ociapi-route
  namespace: apps
  annotations:
    hub.traefik.io/api: traefik-ociapi-api@apps
spec:
  entryPoints:
    - websecure
  routes:
    - match: PathPrefix(\`/ociapi\`)
      services:
        - name: oci-svc
          port: 443
          passHostHeader: false
      middlewares:
        - name: stripprefix-ociapi
EOF

Path Prefix Middleware​

Create a middleware to strip the path prefix from incoming requests:

cat <<EOF | kubectl apply -f -
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: stripprefix-ociapi
  namespace: apps
spec:
  stripPrefix:
    prefixes:
      - /ociapi
      - /oci-portal
EOF

API Definition and Plans​

API Resource Configuration​

Define your external API using Traefik Hub Hub's API resource. This example references an Oracle Integration Cloud OpenAPI specification:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: traefik-ociapi-api
  namespace: apps
spec:
  title: "traefik ociapi"
  description: "traefik ociapi"
  openApiSpec:
    url: https://raw.githubusercontent.com/carlosvillanua/apidefinitions/refs/heads/master/httpbinoas.json  # Replace with your own OpenAPI spec URL
    override:
      servers:
        - url: https://${EXTERNAL_IP}/ociapi/
EOF

Redis Installation for API Plans​

API Plans require Redis for distributed rate limiting and quota management. Install Redis in your cluster:

info

If you already have Redis installed from the marketplace deployment, you can skip this step and reuse your existing Redis configuration.

Demo Redis Installation

The following Redis installation is for demonstration purposes only and uses basic configuration without high availability, advanced security, or production-grade settings. For production deployments, configure Redis with appropriate security, persistence, and high availability settings.

helm install redis oci://registry-1.docker.io/cloudpirates/redis -n traefik --wait

Get your Redis instance password:

export REDIS_PASSWORD=$(kubectl get secret redis -n traefik -o jsonpath="{.data.redis-password}" | base64 -d)

Update your Traefik Hub deployment to include Redis configuration:

helm upgrade traefik -n traefik --wait \
  --reset-then-reuse-values \
  --set hub.redis.endpoints=redis.traefik.svc.cluster.local:6379 \
  --set hub.redis.password=${REDIS_PASSWORD} \
  traefik/traefik
info

You can also edit your Traefik Hub stack helm values to include Redis configuration and rerun the stack as described in the Deploy Traefik Hub API Management from Oracle Marketplace guide instead of using the command above.

Create API Plans​

Define multiple API plans (gold and bronze) with different rate limits and quotas:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: ociapi-gold-plan
  namespace: apps
spec:
  title: Gold
  description: Gold Plan
  rateLimit:
    limit: 100
    period: 1s
  quota:
    limit: 1000000
    period: 750h
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: ociapi-bronze-plan
  namespace: apps
spec:
  title: Bronze
  description: Bronze Plan
  rateLimit:
    limit: 1
    period: 1s
  quota:
    limit: 1000
    period: 750h
EOF

Create API Catalog Items​

Make your API plans available in the developer portal:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: ociapi-gold-catalog-item
  namespace: apps
spec:
  everyone: true
  apis:
    - name: traefik-ociapi-api
  apiPlan:
    name: ociapi-gold-plan
---
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: ociapi-bronze-catalog-item
  namespace: apps
spec:
  everyone: true
  apis:
    - name: traefik-ociapi-api
  apiPlan:
    name: ociapi-bronze-plan
EOF

Developer Portal Setup​

API Portal Resource​

Create an API Portal to provide a developer-friendly interface for your APIs:

cat <<EOF | kubectl apply -f -
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: oci-portal
  namespace: apps
spec:
  title: "OCI Portal"
  description: "Documentation of my APIs"
  trustedUrls:
    - https://${EXTERNAL_IP}/oci-portal
EOF

Portal Routing Configuration​

Configure routing to make the API Portal accessible:

cat <<EOF | kubectl apply -f -
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: oci-portal-route
  namespace: apps
  annotations:
    hub.traefik.io/api-portal: oci-portal@apps
spec:
  entryPoints:
    - websecure
  routes:
    - match: PathPrefix(\`/oci-portal\`)
      kind: Rule
      middlewares:
        - name: stripprefix-ociapi
          namespace: apps
      services:
        - name: apiportal
          namespace: traefik
          port: 9903
EOF

Securing Your OCI API with JWT and SSO​

JWT Authentication Setup​

Configure Traefik Hub to validate JWT tokens issued by OCI Identity Domains.

First, locate your OCI Identity Domain's JWKS URI from the .well-known/openid-configuration endpoint. For example:

https://idcs-**********.identity.oraclecloud.com/admin/v1/SigningCert/jwk

In the Traefik Hub Dashboard, configure JWT authentication:

  1. Navigate to Auth Settings → Gateway → JWT

JWT Authentication Settings

  1. Set the Token validation method to JWKs URL
  2. Paste your JWKS URI in the provided field and save

JWT Validation Configuration

This configuration ensures that Traefik Hub validates JWTs issued by OCI, allowing only authenticated requests to reach your APIs.

Single Sign-on Configuration​

Enable SSO by configuring Traefik Hub to use OCI as an external OIDC Identity Provider:

  1. In Auth Settings, select the OIDC option in the Portal table

OIDC Portal Settings

  1. Complete the OIDC configuration form with:

    • Issuer URL: The OIDC discovery URL from OCI (ends with /.well-known/openid-configuration)
    • Client ID and Client Secret: From your OCI application registration
    • Scopes: At minimum openid; recommended: openid email profile
    • (Optional) Map claims for groups, user ID, email, etc., as needed for access control

  2. Configure the redirect URL in your OCI console:

    • Add the redirect URL: https://<EXTERNAL_IP>/oci-portal/callback
    • Navigate to your Domain → Integrated Applications and specify this URL

OCI Redirect URL Configuration

After saving, Traefik Hub will:

  • Switch the API Portal login to your OCI Identity Provider, enabling SSO for users
  • Require JWT tokens issued by OCI for API access (API keys will be turned off automatically)

SSO Login Portal

For more details on OIDC SSO configuration, refer to the Oracle IAM Identity Domain documentation.

GitOps & Offline Deployment

For GitOps workflows & offline deployments, you can also configure authentication using CRDs. See the API Authentication and API Portal Authentication documentation for CRD-based configuration examples.

Testing the API Portal​

Access the Portal​

Navigate to your API Portal at https://<EXTERNAL_IP>/oci-portal and sign in using your SSO account:

Portal Login Page

Create an Application​

  1. Select the Applications tab and choose Create Application

Applications Tab

  1. Add a name and Application ID.
info

For OCI integration, use the Client ID that creates the JWT and is included as a claim in the JWT token. You can verify the Client ID using JWT.io with one of your JWT tokens.

Application Creation Form

Create a Subscription​

  1. Select Add Subscription and choose your desired plan

Add Subscription

  1. Select an application and plan for the subscription

Subscription Plan Selection

Test the API​

Use the API Portal's built-in testing interface to test your external API endpoints. Obtain a JWT token from your OCI Identity Provider and use it to authenticate your API requests:

API Testing Portal

Conclusion​

This tutorial demonstrated how to:

  • Enable external API routing by configuring Traefik Hub with the required Helm flags
  • Deploy the provided manifests to expose and secure your external APIs via Traefik Hub on OKE
  • Configure authentication using OCI's OIDC integration for robust security

You now have a complete setup that allows you to manage external APIs through Traefik Hub on Oracle Cloud Infrastructure, with comprehensive security, rate limiting, and developer portal capabilities.

For additional details on the base setup, refer to the Deploy Traefik Hub API Management from Oracle Marketplace documentation.

Related Content​