Skip to main content

Nutanix Prism Central

The Nutanix Prism Central provider enables automatic service discovery for virtual machines running on Nutanix AHV infrastructure. It queries the Prism Central API to discover powered-on VMs and dynamically generates Traefik HTTP services by grouping VMs based on Prism Central category metadata.

Overview​

The provider continuously polls the Prism Central API to retrieve VM configurations, network details, and category assignments. VMs are grouped into Traefik services using a configurable category key (default: TraefikServiceName), with each unique category value becoming a distinct service. This allows you to manage service discovery through Nutanix's native category system without requiring additional registry infrastructure.

Key features include:

  • Automatic VM Discovery: Discovers all powered-on VMs from Prism Central
  • Category-Based Grouping: Groups VMs into services using Prism Central categories
  • VPC Filtering: Optional filtering to restrict discovery to specific Virtual Private Clouds
  • Load Balancing Strategies: Configurable load balancing algorithms per service
  • Prism Central Authentication: Connects to the Prism Central API using API Key or Basic Authentication
  • TLS Support: Flexible TLS configuration for Prism Central API connections, including support for self-signed certificates

Requirements​

To use the Nutanix Prism Central provider, you need:

  • Nutanix Prism Central with API v4.x support
  • Service Account with the following permissions:
    • Read access to VMs
    • Read access to Categories
    • Read access to Subnets and VPCs if using VPC filtering
  • Flow Virtual Networking enabled (required only for VPC filtering features)
  • VMs must be in ON power state to be discovered

Configuration Example​

providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com:9440
    apiKey: your-api-key-here
    filename: /etc/traefik/nutanix-base-config.yaml
    pollInterval: 30s
    pollTimeout: 5s
    serviceNameCategoryKey: TraefikServiceName
    allowedVPCs:
      - uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      - uuid: b2c3d4e5-f6g7-8901-bcde-f12345678901
    tls:
      ca: /etc/traefik/certs/prism-central-ca.pem
      cert: /etc/traefik/certs/client.pem
      key: /etc/traefik/certs/client-key.pem
      insecureSkipVerify: false

Configuration Options​

FieldDescriptionDefaultRequired
providers.nutanixPrismCentral.endpointPrism Central base URL. Must include scheme (http:// or https://).""Yes
providers.nutanixPrismCentral.apiKeyAPI key for authentication. Mutually exclusive with username/password.""Yes*
providers.nutanixPrismCentral.usernameUsername for basic authentication. Requires password. Mutually exclusive with apiKey.""Yes*
providers.nutanixPrismCentral.passwordPassword for basic authentication. Requires username. Mutually exclusive with apiKey.""Yes*
providers.nutanixPrismCentral.filenamePath to the base configuration file defining services, routers, and middlewares. See Base Configuration File.""Yes
providers.nutanixPrismCentral.tls.insecureSkipVerifySkip verification of Prism Central's server certificate. Use only when ca is not provided and Prism Central uses a self-signed or untrusted certificate.falseNo
providers.nutanixPrismCentral.tls.caPath to CA certificate file to verify Prism Central's server certificate. Use this instead of insecureSkipVerify when Prism Central uses a private CA.""No
providers.nutanixPrismCentral.tls.certPath to client certificate file for mutual TLS (mTLS) authentication with Prism Central. Requires key.""No
providers.nutanixPrismCentral.tls.keyPath to client private key file for mutual TLS (mTLS) authentication with Prism Central. Requires cert.""No
providers.nutanixPrismCentral.pollIntervalFrequency of polling the Prism Central API for VM updates and reloading the base configuration file.30sNo
providers.nutanixPrismCentral.pollTimeoutTimeout for each API request to Prism Central.5sNo
providers.nutanixPrismCentral.serviceNameCategoryKeyCategory key used to map VMs to services defined in the base configuration file. VMs with the same category value are added as backend servers to the corresponding service.TraefikServiceNameNo
providers.nutanixPrismCentral.allowedVPCs[n].uuidList of VPC UUIDs to filter VMs. Only VMs attached to subnets in these VPCs will be discovered. When empty, all VMs are discovered regardless of VPC.[]No
Required Fields

  • Authentication requirement: Exactly one authentication method must be configured: either apiKey OR both username and password. Configuring both methods or neither will cause the provider to fail initialization.

  • Configuration file requirement: The filename field is required and must point to a valid base configuration file containing service definitions.

Authentication Methods​

The Nutanix Prism Central provider supports two authentication methods. You must configure exactly one method.

API Key authentication is the recommended method for production environments as it provides better security and audit capabilities.

providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com:9440
    apiKey: your-api-key-here

To generate an API key in Prism Central:

  1. Navigate to Settings > Local User Management
  2. Create a new service account or select an existing user
  3. Generate an API key for the account
  4. Store the API key securely - it cannot be retrieved after creation

Basic Authentication​

Basic authentication using username and password is also supported. Both fields must be provided together.

providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com:9440
    username: admin
    password: your-password-here
info

Only one authentication method can be configured at a time. If both apiKey and username/password are provided, the provider will fail to initialize with an error.

Base Configuration File​

The Nutanix Prism Central provider requires a base configuration file where you define your services, routers, middlewares, and service properties like ports, health checks, and load balancing strategies. The provider discovers VM IP addresses from Prism Central and automatically merges them with the service definitions in this file.

How It Works​

  1. Define Services: Create a YAML/TOML/JSON file with service definitions including port, scheme, health checks, and load balancing strategy
  2. Tag VMs: Assign VMs the TraefikServiceName category in Prism Central to map them to services
  3. Automatic Merging: The provider discovers VM IPs and creates backend servers by combining the discovered IPs with your service configuration
  4. File Watching: Changes to the base configuration file are automatically detected and reloaded

File Structure​

The base configuration file uses standard Traefik dynamic configuration format with the following supported sections:

http:
  routers:
    # Define routing rules for your services
  services:
    # Define service properties (port, health checks, strategy)
  middlewares:
    # Optional middlewares for your services

Configuration Example​

http:
  routers:
    web-route:
      rule: "Host(`example.com`)"
      entryPoints:
        - web
      service: web-app
      middlewares:
        - compression

    api-route:
      rule: "Host(`api.example.com`)"
      entryPoints:
        - websecure
      service: api-service
      tls: {}

  middlewares:
    compression:
      compress: {}

  services:
    web-app:
      loadBalancer:
        scheme: http
        port: "8080"
        strategy: p2c
        healthCheck:
          path: /health
          interval: 10s
          timeout: 3s
          headers:
            X-Health-Check: "true"

    api-service:
      loadBalancer:
        scheme: https
        port: "3000"
        strategy: wrr
        healthCheck:
          path: /healthz
          method: POST
          status: 204
          interval: 15s
          unhealthyInterval: 5s
          timeout: 5s
          followRedirects: true

With this configuration and VMs tagged with TraefikServiceName=web-app, the provider will:

  1. Discover all VMs with category TraefikServiceName=web-app
  2. Extract their IP addresses
  3. Create backend servers at http://<vm-ip>:8080
  4. Configure health checks to poll http://<vm-ip>:8080/health every 10 seconds

Service Configuration Options​

Each service in the base configuration file can include:

FieldDescriptionRequired
schemeProtocol scheme (http or https)No (default: http)
portBackend port numberYes
healthCheckHealth check configurationNo
healthCheck.pathHTTP path for health checksYes (if healthCheck is defined)
healthCheck.modeHealth check mode (http or grpc)No (default: http)
healthCheck.methodHTTP method for health checks (e.g., GET, POST)No (default: GET)
healthCheck.statusExpected HTTP status code for healthy responseNo (default: 200)
healthCheck.intervalTime between health checks (e.g., 10s)No (default: Traefik's default)
healthCheck.unhealthyIntervalTime between health checks for unhealthy backendsNo (uses interval value)
healthCheck.timeoutHealth check request timeout (e.g., 3s)No (default: Traefik's default)
healthCheck.schemeHealth check protocol overrideNo (uses service scheme)
healthCheck.hostnameHealth check hostname overrideNo
healthCheck.portHealth check port overrideNo (uses service port)
healthCheck.headersCustom headers for health checksNo
healthCheck.followRedirectsFollow HTTP redirects during health checksNo
strategyLoad balancing algorithm (wrr, p2c, hrw, leasttime)No (default: wrr)

File Formats​

The base configuration file supports three formats:

  • YAML: .yaml or .yml extension (recommended)
  • TOML: .toml extension
  • JSON: .json extension

The format is automatically detected from the file extension.

File Watching and Reload​

The provider watches the base configuration file for changes:

  • Automatic Detection: File changes are detected using filesystem notifications
  • Immediate Reload: Configuration is reloaded as soon as changes are detected
  • Graceful Handling: If the file contains errors, the provider continues using the last valid configuration
  • Polling Fallback: During regular polling intervals, the file is also checked for updates
Development Workflow

During development, you can edit the base configuration file and see changes applied immediately without restarting Traefik Hub. This allows you to:

  • Adjust health check parameters
  • Modify load balancing strategies
  • Add new routes or middlewares
  • Update service ports
Service Name Matching

Service names in the base configuration file must exactly match the TraefikServiceName category values assigned to your VMs in Prism Central. If a VM has TraefikServiceName=web-app but your base config defines web-application, the VM will not be included as a backend server.

VPC Filtering​

The allowedVPCs configuration enables you to restrict service discovery to VMs attached to specific Virtual Private Clouds. This is useful in multi-tenant environments or when you want to isolate specific workloads.

How VPC Filtering Works​

  • When empty (allowedVPCs: []): The provider discovers all powered-on VMs regardless of their VPC membership
  • When configured: The provider only discovers VMs whose NICs are attached to subnets belonging to the specified VPCs
  • Filtering mechanism: Uses VPC UUID references, not VPC names, to ensure uniqueness
providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com
    apiKey: your-api-key-here
    allowedVPCs:
      - uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890  # internal-vpc
      - uuid: b2c3d4e5-f6g7-8901-bcde-f12345678901  # datebase-vpc
Requirements

VPC filtering requires Flow Virtual Networking to be enabled in your Nutanix environment. Without Flow Virtual Networking, VPC-related APIs will not be available.

VM Category Configuration​

The provider uses a single Prism Central category to map VMs to services defined in the base configuration file. Categories are key-value pairs attached to VMs that act as metadata.

Service Name Category​

Default Key: TraefikServiceName

This category maps VMs to services defined in your base configuration file. All VMs with the same category value are added as backend servers to the corresponding service.

  • Purpose: Maps VMs to services defined in the base configuration file
  • Required: Yes (VMs without this category are ignored during discovery)
  • Value Format: Must exactly match a service name in your base configuration file
  • Example: TraefikServiceName=web-app adds the VM as a backend to the web-app service

How It Works​

  1. Base Config Defines Service: You define a service named web-app in your base configuration file with port, health check, etc.
  2. Tag VMs: You assign TraefikServiceName=web-app category to VMs in Prism Central
  3. Provider Discovers IPs: The provider discovers IP addresses from VMs with TraefikServiceName=web-app
  4. Merge: The provider creates backend servers by merging discovered IPs with the web-app service definition

Example Workflow​

Base Configuration File (/etc/traefik/nutanix-base-config.yaml):

http:
  services:
    web-app:
      loadBalancer:
        port: "8080"
        scheme: http
        healthCheck:
          path: /health
          interval: 10s

Prism Central: Assign TraefikServiceName=web-app to your VMs

Result: Provider creates backends at http://192.168.1.10:8080, http://192.168.1.11:8080, etc., with health checks configured

Service Properties in Base Config

Service properties like port, scheme, health checks, and load balancing strategy are NOT configured via categories. They are defined in the base configuration file.

Customizing the Category Key​

You can customize the category key name to match your organization's naming standards:

providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com:9440
    apiKey: your-api-key-here
    filename: /etc/traefik/nutanix-base-config.yaml
    serviceNameCategoryKey: AppService

With this configuration, you would assign AppService=web-app instead of TraefikServiceName=web-app in Prism Central.

IP Address Selection​

The provider automatically extracts IP addresses from VM network interface cards (NICs) using the following logic:

Selection Priority​

  1. IPv4 Preferred: IPv4 addresses are preferred over IPv6 when both are available
  2. Learned Addresses: Runtime-learned IP addresses (DHCP, dynamic) are checked first
  3. Configured Addresses: Statically configured IP addresses are used as fallback
  4. NIC Ordering: NICs are sorted by ExtID to ensure deterministic IP selection across provider restarts

VPC Filtering Impact​

When allowedVPCs is configured:

  • Only NICs attached to subnets in the specified VPCs are considered
  • NICs in other VPCs are ignored during IP extraction
  • If no NICs match the VPC filter, the VM is excluded from service discovery

Multiple NICs​

If a VM has multiple NICs:

  • NICs are sorted alphabetically by ExtID
  • The first NIC (after sorting) that has a valid IP address is used
  • Only one IP per VM is included in the service backends

Customizing Category Keys​

While the default category keys follow Traefik naming conventions, you can customize them to match your organization's naming standards:

providers:
  nutanixPrismCentral:
    endpoint: https://prism-central.example.com:9440
    apiKey: your-api-key-here
    serviceNameCategoryKey: AppService

With this configuration, you would create and assign categories in Prism Central using your custom keys:

  • AppService=web-app instead of TraefikServiceName=web-app

Provider Namespace​

Services discovered by the Nutanix Prism Central provider are created in the nutanixprismcentral provider namespace. When referencing these services from routing rules, middleware, or other configurations, use the @nutanixprismcentral suffix:

<service-name>@nutanixprismcentral

For example, a service named web-app discovered from Nutanix would be referenced as:

http:
  routers:
    web-route:
      rule: "Host(`example.com`)"
      entryPoints:
        - web
      service: web-app@nutanixprismcentral

  # No need to define the service - it's auto-discovered
  # services:
  #   web-app@nutanixprismcentral is provided by the Nutanix provider
Provider Namespace vs Kubernetes Namespace

The provider namespace (@nutanixprismcentral) is a Traefik concept and is distinct from Kubernetes namespaces. Do not confuse these when configuring cross-provider routing.

Polling Behavior​

The provider uses continuous polling to keep the service configuration synchronized with Prism Central:

  • Initial Load: Configuration is fetched immediately when the provider starts
  • Periodic Updates: Configuration is refreshed every pollInterval (default: 30s)
  • Automatic Retry: Failed API requests are automatically retried with exponential backoff
  • Graceful Degradation: If an API call fails, the previous configuration is retained until the next successful update

Performance Considerations​

  • Poll Interval: Shorter intervals provide faster discovery but increase API load on Prism Central
  • Poll Timeout: Should be set lower than pollInterval to prevent overlapping requests
  • Large Environments: For environments with hundreds of VMs, consider increasing pollInterval to reduce API load

Recommended settings for different environment sizes:

# Small environments (<50 VMs)
pollInterval: 30s
pollTimeout: 5s

# Medium environments (50-200 VMs)
pollInterval: 60s
pollTimeout: 10s

# Large environments (>200 VMs)
pollInterval: 120s
pollTimeout: 15s

Related Content​