Skip to main content

API Management Offline Mode

Traefik Hub API Management (APIM) Offline Mode enables you to deploy and operate comprehensive API management capabilities without requiring connectivity to the Traefik Hub Online Dashboard. This mode is designed for air-gapped environments, regulated industries, or scenarios where external communication is restricted while still maintaining full API management functionality.

important

API Management Offline Mode is only available on Kubernetes and can only be enabled when creating a new gateway. You cannot switch an existing gateway to offline mode.

Prerequisites​

  • License Requirement: Offline Mode is a licensed feature. Access to this feature must be granted by the Traefik Labs sales team.
  • Kubernetes Cluster: API Management Offline Mode is only supported on Kubernetes.
  • License Token: Your license token must include the offline claim to enable this feature.

Enabling API Management Offline Mode​

API Management Offline Mode is enabled through the Traefik Hub Online Dashboard during gateway creation. You can now enable both Offline Mode and API Management features simultaneously.

Step-by-Step Process​

  1. Navigate to Traefik Hub Online Dashboard: In the Traefik Hub Online Dashboard, go to the Gateways section and select "Create new gateway".

  2. Configure Gateway Settings: Fill in your gateway name and other details.

  3. Enable Both Offline Mode and API Management: Toggle both the "Offline gateway" switch and "API management features" switch in the gateway creation form.

https://hub.traefik.io/dashboard/gateways/new

Gateway Creation with Offline Mode and APIM

  1. Copy Updated Token: Once offline mode is enabled, copy the updated token that now includes the offline configuration. The APIM toggle updates the installation snippet to include the necessary CLI flags.

  2. Deploy with Updated Configuration: Use the updated token when deploying your gateway. The deployment configuration will automatically include the --set hub.offline=true flag:

hub:
  token: "<your-updated-token>"
  offline: true
  apimanagement:
    enabled: true
  1. Gateway Status Confirmation: Once deployed, your gateway will appear in the dashboard with an "Offline gateway" status, confirming that it's operating without connectivity to the online dashboard while providing API management capabilities.

Authentication Configuration​

In offline mode, API Management uses Custom Resource Definitions (CRDs) to configure authentication instead of relying on the online dashboard settings.

Two resources are available to configure authentication:

APIAuth Resource​

The APIAuth CRD configures authentication for your APIs, replacing the gateway authentication settings that were previously configured at the workspace level.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: default-auth
  namespace: default
spec:
  isDefault: true
  apiKey: {}

For comprehensive configuration options and examples, see the APIAuth documentation.

APIPortalAuth Resource​

The APIPortalAuth CRD configures authentication for your API Portal, replacing the portal authentication settings configured in the online dashboard.

apiVersion: hub.traefik.io/v1alpha1
kind: APIPortalAuth
metadata:
  name: portal-auth
  namespace: default
spec:
  oidc:
    issuerUrl: https://your-auth-provider.com/
    secretName: portal-auth-secret
    claims:
      groups: groups

For comprehensive configuration options and examples, see the APIPortalAuth documentation.

note

The attributes synchronization feature of the APIPortalAuth resource is not supported in offline mode.

Namespace Scope and Authentication​

APIAuth Namespace Behavior

The APIAuth resource is namespace-scoped and affects all APIs within the same namespace:

  • One APIAuth per namespace: Each namespace should have one APIAuth resource with isDefault: true
  • Automatic application: All APIs in the namespace automatically use the authentication configuration
  • Alphabetical precedence: If multiple APIAuth resources exist with isDefault: true, the first one alphabetically is selected
APIPortalAuth Reference & Namespace Behavior
  • The APIPortalAuth resource must be explicitly referenced in your APIPortal resource:
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: my-portal
  namespace: default
spec:
  title: My API Portal
  auth:
    name: my-portal-auth  # References APIPortalAuth resource
  • Namespace-scoped: The APIPortalAuth resource must be in the same namespace as the APIPortal resource

Complete Configuration Examples​

Here's a complete example demonstrating API Management in offline mode:

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: default-auth
  namespace: apps
spec:
  isDefault: true
  apiKey: {}

---
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: weather-api
  namespace: apps
spec:
  openApiSpec:
    path: /spec.json
    override:
      servers:
        - url: "https://weather.example.com"

---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: weather-ingress
  namespace: apps
  annotations:
    hub.traefik.io/api: weather-api@apps
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`weather.example.com`)
      kind: Rule
      services:
        - name: weather-app
          port: 8080

Offline Mode Capabilities​

When operating in offline mode, certain self-service capabilities are currently not available:

API Portal Limitations
  • No Self-Service Applications: Users cannot create, modify, or delete applications through the portal
  • No Self-Service Subscriptions: Users cannot subscribe to APIs or manage existing subscriptions
  • No API Key Management: Users cannot generate, rotate, or revoke API keys through the portal
Management Capabilities
  • Managed Applications: Continue to work through CRDs and kubectl commands
  • Managed Subscriptions: Can be configured and updated through Kubernetes resources
  • API Catalog: Fully functional for browsing and documentation
  • Authentication: Works normally through the configured authentication providers

Validation​

Use the Traefik Hub static analyzer to validate your offline configuration:

hub-static-analyzer lint --path [path/to/manifests] --offline

The --offline flag enables additional validation checks for environments that don't have external connectivity to the Traefik Hub Online Dashboard .

Migration from Online to Offline​

When migrating from online API Management to offline mode:

  1. Export existing auth configuration: Note your current authentication settings from the online dashboard
  2. Create CRD equivalents: Convert your online authentication configuration to APIAuth and APIPortalAuth resources
  3. Test configuration: Use the static analyzer to validate your offline configuration
  4. Deploy with offline flag: Update your deployment to include hub.offline: true

Troubleshooting​

Common Issues

  • APIs not protected: Ensure you have an APIAuth resource with isDefault: true in the same namespace as your APIs.

  • Portal authentication fails: Verify that your APIPortalAuth resource is correctly referenced in your APIPortal specification.

  • No authentication configured: Check the gateway logs for messages about ignored APIs or portals due to missing authentication configuration.

Log Messages

In offline mode, you may see these informational messages:

API portal will be ignored: no authentication configuration found
API "example-api" will be ignored: no authentication configuration found

These messages indicate that authentication configuration is required for offline operation.

Conclusion​

API Management Offline Mode provides a complete API management solution for environments with restricted connectivity. The combination of APIAuth and APIPortalAuth resources enables full authentication configuration while maintaining the security and functionality of your API ecosystem.

Related Content​