Private Plugins

Traefik Hub API Gateway supports loading plugins from private repositories hosted on GitHub and GitLab. This feature allows you to use proprietary or internal plugins while maintaining security through authentication tokens and hash verification.

Overview

Private plugins extend Traefik Hub's plugin capabilities by enabling access to:

• Private GitHub repositories: Support for GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server
• Private GitLab repositories: Support for GitLab.com and self-hosted GitLab instances
• Secure plugin distribution: With hash verification to ensure plugin integrity
• Token-based authentication: Supporting personal access tokens and project tokens

---

Configuration Examples

Private plugins are configured using the hub.pluginRegistry section in your Traefik Hub configuration. Each registry source requires a base module name (domain) and authentication credentials.

Configuration Examples

Basic Configuration Structure

hub:
  pluginRegistry:
    sources:
      <source-name>:
        baseModuleName: <domain>
        github: # OR gitlab (mutually exclusive)
          token: <access-token>
          enterprise: # Optional for GitHub Enterprise
            url: <enterprise-url>

GitHub Configuration

GitHub.com

hub:
  pluginRegistry:
    sources:
      github:
        baseModuleName: "github.com"
        github:
          token: "ghp_xxxxxxxxxxxxxxxxxxxx"

GitHub Enterprise Cloud

hub:
  pluginRegistry:
    sources:
      github:
        baseModuleName: "github.com"
        github:
          token: "ghp_xxxxxxxxxxxxxxxxxxxx"
          # No enterprise.url needed for Enterprise Cloud

GitHub Enterprise Server

hub:
  pluginRegistry:
    sources:
      github-enterprise:
        baseModuleName: "github.enterprise.local"
        github:
          token: "ghp_xxxxxxxxxxxxxxxxxxxx"
          enterprise:
            url: "https://github.enterprise.local"

GitLab Configuration

GitLab.com

hub:
  pluginRegistry:
    sources:
      gitlab-private:
        baseModuleName: "gitlab.com"
        gitlab:
          token: "glpat-xxxxxxxxxxxxxxxxxxxx"

Self-hosted GitLab

hub:
  pluginRegistry:
    sources:
      gitlab-private:
        baseModuleName: "gitlab.company.com"
        gitlab:
          token: "glpat-xxxxxxxxxxxxxxxxxxxx"
          url: "https://gitlab.company.com"

Plugin Usage

Once configured, use private plugins in your experimental plugins configuration like public plugins:

CLI Arguments

--experimental.plugins.myPrivatePlugin.modulename=github.com/myorg/my-plugin
--experimental.plugins.myPrivatePlugin.version=v1.2.3
--experimental.plugins.myPrivatePlugin.hash=abc123...

Static Configuration

experimental:
  plugins:
    myPrivatePlugin:
      moduleName: "github.com/myorg/my-plugin"
      version: "v1.2.3"
      hash: "sha256:abc123..."

Helm Values

hub:
  pluginRegistry:
    sources:
      github:
        baseModuleName: "github.com"
        github:
          token: "urn:k8s:secret:github-token:access-token"

additionalArguments:
  - --experimental.plugins.myPrivatePlugin.modulename=github.com/myorg/my-plugin
  - --experimental.plugins.myPrivatePlugin.version=v1.2.3
  - --experimental.plugins.myPrivatePlugin.hash=abc123...

---

Configuration Options

The following table shows all available configuration options for private plugin registries:

Plugin Registry Configuration:

Field	Description	Default	Required
hub.pluginRegistry.sources.<source-name>	Plugin registry source configuration. <source-name> is a user-defined identifier.	-	Yes
hub.pluginRegistry.sources.<source-name>.baseModuleName	Base domain for plugin module names. Must match the Git provider domain.	-	Yes
hub.pluginRegistry.sources.<source-name>.github	GitHub registry configuration. Mutually exclusive with gitlab.	-	No*
hub.pluginRegistry.sources.<source-name>.gitlab	GitLab registry configuration. Mutually exclusive with github.	-	No*

GitHub-specific options:

Field	Description	Default	Required
github.token	GitHub personal access token, GitHub App token, or URN reference to Kubernetes secret.	-	Yes
github.enterprise	GitHub Enterprise Server configuration. Not needed for GitHub.com or Enterprise Cloud.	-	No
github.enterprise.url	GitHub Enterprise Server base URL. Required only for GitHub Enterprise Server.	-	Yes**

GitHub API Defaults

• GitHub.com: Uses https://api.github.com (no configuration needed)
• GitHub Enterprise Cloud: Uses https://api.github.com (no configuration needed)
• GitHub Enterprise Server: Requires github.enterprise.url to be set

GitLab-specific options:

Field	Description	Default	Required
gitlab.token	GitLab personal access token, project token, or URN reference to Kubernetes secret.	-	Yes
gitlab.url	GitLab instance URL.	https://gitlab.com	No

info

• Either github or gitlab must be configured for each source, but not both
• github.enterprise.url is required only when using GitHub Enterprise Server (not needed for GitHub.com or Enterprise Cloud)

Plugin Configuration:

Field	Description	Default	Required
experimental.plugins.<plugin-name>.moduleName	Plugin module name matching a configured registry source domain.	-	Yes
experimental.plugins.<plugin-name>.version	Plugin version tag or branch to download.	-	Yes
experimental.plugins.<plugin-name>.hash	SHA-256 hash of the plugin archive for integrity verification.	-	No

Source Names

The <source-name> is a user-defined identifier for each plugin registry source. It serves as:

• Logical grouping: Organize plugins from different repositories or organizations
• Configuration isolation: Separate authentication and settings per source
• Debugging aid: Identify which source a plugin comes from in logs and errors

You can use any descriptive name like github-public, gitlab-internal, enterprise-plugins, etc. The source name doesn't affect plugin functionality—it's purely for organization and identification.

How Source Names work with Plugin Module Names

When you configure a plugin, Traefik Hub matches the module name's domain to the baseModuleName of your sources:

# Source configuration
hub:
  pluginRegistry:
    sources:
      github-main:
        baseModuleName: "github.com" # Matches plugins from github.com/*
      gitlab-internal:
        baseModuleName: "gitlab.company.com" # Matches plugins from gitlab.company.com/*

# Plugin usage
experimental:
  plugins:
    myPlugin:
      moduleName: "github.com/myorg/plugin" # Uses "github-main" source
    internalPlugin:
      moduleName: "gitlab.company.com/team/plugin" # Uses "gitlab-internal" source

---

Token Management

Direct Token Values

You can specify tokens directly in the configuration:

hub:
  pluginRegistry:
    sources:
      github:
        baseModuleName: "github.com"
        github:
          token: "ghp_xxxxxxxxxxxxxxxxxxxx"

Kubernetes Secrets (Recommended)

For enhanced security, reference tokens stored in Kubernetes secrets using the URN format:

hub:
  pluginRegistry:
    sources:
      github:
        baseModuleName: "github.com"
        github:
          token: "urn:k8s:secret:github-token:access-token"

The URN format follows this pattern:

urn:k8s:secret:<secret-name>:<key-name>

Where:

• <secret-name>: Name of the Kubernetes secret
• <key-name>: Key within the secret containing the token value

Create the corresponding secret using the following command:

kubectl create secret generic github-token \
  --from-literal=access-token="ghp_xxxxxxxxxxxxxxxxxxxx" \
  --namespace traefik-hub

Token Requirements

GitHub Tokens

For GitHub repositories, you need either:

• Personal Access Token (Classic): With repo scope for private repositories
• Personal Access Token (Fine-grained): With Contents: Read permission for specific repositories
• GitHub App Token: With appropriate repository permissions

GitLab Tokens

For GitLab repositories, you can use:

• Personal Access Token: With read_repository scope
• Project Access Token: With read_repository scope for specific projects
• Group Access Token: With read_repository scope for group projects

---

Hash Verification

Hash verification ensures that downloaded plugins haven't been tampered with. When you specify a hash, Traefik Hub verifies the plugin archive matches the expected SHA-256 hash.

Obtaining Plugin Hashes

To get the hash of a plugin version:

1. Download the plugin archive manually

2. Calculate the hash of the downloaded archive:

   sha256sum plugin-archive.zip

3. Use the hash in your plugin configuration.

Hash Mismatch Errors

If the hash doesn't match, you'll see an error like:

unable to load plugin myPrivatePlugin: hash mismatch
expected: sha256:abc123...
actual:   sha256:def456...

This indicates either:

• The plugin version was updated without updating the hash
• The plugin archive was modified
• Network issues occurred during download

---

Multiple Registry Sources

You can configure multiple plugin registry sources to access plugins from different repositories:

hub:
  pluginRegistry:
    sources:
      # Public GitHub repositories
      github-main:
        baseModuleName: "github.com"
        github:
          token: "urn:k8s:secret:github-public-token:token"

      # Internal GitHub Enterprise Server
      github-enterprise:
        baseModuleName: "github.enterprise.local"
        github:
          token: "urn:k8s:secret:github-enterprise-token:token"
          enterprise:
            url: "https://github.enterprise.local"

      # Private company GitLab
      gitlab-internal:
        baseModuleName: "gitlab.company.com"
        gitlab:
          token: "urn:k8s:secret:gitlab-token:access-token"
          url: "https://gitlab.company.com"

      # Third-party vendor plugins
      vendor-plugins:
        baseModuleName: "gitlab.vendor.com"
        gitlab:
          token: "urn:k8s:secret:vendor-token:token"
          url: "https://gitlab.vendor.com"

---

Migration from Public Plugins

Compatibility Impact

When hub.pluginRegistry is configured, it completely disables Traefik Hub's native plugin download system. This affects all plugins, including public GitHub plugins that were previously downloaded automatically.

Public Plugin Access After Configuration

If you're currently using public GitHub plugins and want to add private plugins, you must explicitly configure a GitHub plugin registry source to maintain access to public plugins:

hub:
  pluginRegistry:
    sources:
      # Required to maintain access to public GitHub plugins
      github-public:
        baseModuleName: "github.com"
        github:
          token: "your-github-token"  # Required even for public repos

      # Your private GitLab source
      gitlab-private:
        baseModuleName: "gitlab.company.com"
        gitlab:
          token: "your-gitlab-token"
          url: "https://gitlab.company.com"

Hash Changes during Migration

When migrating from Traefik's native plugin system to the private plugin registry, plugin hashes may change due to different download mechanisms. This means:

1. Remove existing hash values when first migrating
2. Calculate new hashes after successful plugin downloads
3. Update configurations with the new hash values

Migration Steps

1. Backup your current configuration
2. Add plugin registry configuration (including GitHub source for public plugins)
3. Remove hash values from existing plugin configurations temporarily
4. Test plugin loading and verify functionality
5. Calculate and add new hashes for security

Example Migration

Before (native system):

experimental:
  plugins:
    publicPlugin:
      moduleName: "github.com/traefik/plugin-example"
      version: "v1.0.0"
      hash: "abc123..."  # Hash from native system

After (plugin registry):

hub:
  pluginRegistry:
    sources:
      github-public:
        baseModuleName: "github.com"
        github:
          token: "your-github-token"

experimental:
  plugins:
    publicPlugin:
      moduleName: "github.com/traefik/plugin-example"
      version: "v1.0.0"
      # hash: "def456..."  # New hash - calculate after migration

---

Troubleshooting

Common Issues

Issue	Symptoms	Solution
Authentication Error	HTTP 401 from Git provider APIs	- Verify token has correct permissions - Check token hasn't expired - Ensure secret exists and is accessible
Repository Not Found	download failed with status 404	- Verify repository path is correct - Check token has access to the repository - Confirm baseModuleName matches repository domain
Download Error	GitLab API request failed with status 404	- Verify GitLab project exists and is accessible - Check GitLab token permissions - Confirm GitLab URL is correct
Hash Verification Error	Plugin hash verification failures	- Update hash value to match current plugin version - Verify plugin version tag exists - Check for plugin archive issues
Secret Resolution Error	loading secrets for source	- Verify secret exists in correct namespace - Check secret key name matches URN - Ensure Traefik Hub has RBAC permissions for secrets
Configuration Error	plugin registry source cannot configure both GitHub and GitLab, choose one	- Each source must configure either GitHub OR GitLab, not both - Use separate source entries for different providers
Public Plugins Stopped Working	Previously working public GitHub plugins fail to load after configuring pluginRegistry	- Add a GitHub source to pluginRegistry with baseModuleName: "github.com" - Configure GitHub token even for public repositories - See Migration from Public Plugins section
Hash Mismatch After Migration	Plugin hash verification fails after switching to plugin registry	- Remove hash values temporarily during migration - Download plugins and calculate new hashes - Update configuration with new hash values

Debug Mode

Enable debug logging to troubleshoot plugin loading issues:

log:
  level: DEBUG

Look for debug messages related to:

• Plugin registry initialization
• Token resolution from secrets
• Plugin download attempts
• Hash verification