Newt Blueprint Generator

Newt Blueprint Generator

Expert assistance for creating, validating, and managing Pangolin Newt blueprint configurations.

When to Use This Skill

This skill should be triggered when:

• Creating Pangolin blueprint configurations
• Generating YAML configuration files for Newt
• Creating Docker Compose files with Pangolin labels
• Configuring proxy resources (HTTP, TCP, UDP)
• Setting up client resources for Olm
• Configuring authentication (SSO, basic auth, pincode, password)
• Validating blueprint configurations
• Troubleshooting blueprint validation errors
• Converting between YAML and Docker Labels formats

Overview

Pangolin Blueprints are declarative configurations that allow you to define resources and their settings in a structured format. They support two formats:

1. YAML Configuration Files: Standalone configuration files 2. Docker Labels: Configuration embedded in Docker Compose files

Blueprint Formats

YAML Configuration Format

YAML configs can be applied using:

• Newt CLI: Pass --blueprint-file /path/to/blueprint.yaml
• API: POST to /org/{orgId}/blueprint with base64-encoded JSON body

Example Newt usage:

newt --blueprint-file /path/to/blueprint.yaml <other-args>

Docker Labels Format

For containerized applications, blueprints can be defined using Docker labels with the pangolin. prefix.

Enable Docker socket access:

newt --docker-socket /var/run/docker.sock <other-args>

Or use environment variable:

DOCKER_SOCKET=/var/run/docker.sock

Resource Types

Proxy Resources

Proxy resources expose HTTP, TCP, or UDP services through Pangolin.

HTTP Proxy Resource Example

proxy-resources:
  resource-nice-id-uno:
    name: this is a http resource
    protocol: http
    full-domain: uno.example.com
    host-header: example.com
    tls-server-name: example.com
    headers:
      - name: X-Example-Header
        value: example-value
      - name: X-Another-Header
        value: another-value
    rules:
      - action: allow
        match: ip
        value: 1.1.1.1
      - action: deny
        match: cidr
        value: 2.2.2.2/32
      - action: pass
        match: path
        value: /admin
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        method: http
        port: 8000
      - site: slim-alpine-chipmunk
        hostname: localhost
        path: /admin
        path-match: exact
        method: https
        port: 8001

TCP/UDP Proxy Resource Example

proxy-resources:
  resource-nice-id-dos:
    name: this is a raw resource
    protocol: tcp
    proxy-port: 3000
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        port: 3000

Targets-Only Resources

Simplified resources containing only target configurations:

proxy-resources:
  additional-targets:
    targets:
      - site: another-site
        hostname: backend-server
        method: https
        port: 8443
      - site: another-site
        hostname: backup-server
        method: http
        port: 8080

Note: When using targets-only resources, name and protocol fields are not required.

Client Resources

Client resources define proxied resources accessible via Olm client (SSH, RDP):

client-resources:
  client-resource-nice-id-uno:
    name: this is my resource
    protocol: tcp
    proxy-port: 3001
    hostname: localhost
    internal-port: 3000
    site: lively-yosemite-toad

Authentication Configuration

Authentication is off by default. Enable by adding fields in the auth section.

Note: Authentication is only allowed on HTTP resources, not TCP/UDP.

proxy-resources:
  secure-resource:
    name: Secured Resource
    protocol: http
    full-domain: secure.example.com
    auth:
      pincode: 123456
      password: your-secure-password
      basic-auth:
        user: asdfa
        password: sadf
      sso-enabled: true
      sso-roles:
        - Member
        - Admin
      sso-users:
        - user@example.com
      whitelist-users:
        - admin@example.com

Docker Labels Format

Complete Docker Compose Example

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - NEWT_ID=h1rbsgku89wf9z3
      - NEWT_SECRET=z7g54mbcwkglpx1aau9gb8mzcccoof2fdbs97keoakg2pp5z
      - DOCKER_SOCKET=/var/run/docker.sock

  nginx1:
    image: nginxdemos/hello
    container_name: nginx1
    labels:
      # Proxy Resource Configuration
      - pangolin.proxy-resources.nginx.name=nginx
      - pangolin.proxy-resources.nginx.full-domain=nginx.fosrl.io
      - pangolin.proxy-resources.nginx.protocol=http
      - pangolin.proxy-resources.nginx.headers[0].name=X-Example-Header
      - pangolin.proxy-resources.nginx.headers[0].value=example-value
      # Target Configuration - port and hostname auto-detected
      - pangolin.proxy-resources.nginx.targets[0].method=http
      - pangolin.proxy-resources.nginx.targets[0].path=/path
      - pangolin.proxy-resources.nginx.targets[0].path-match=prefix

  nginx2:
    image: nginxdemos/hello
    container_name: nginx2
    labels:
      # Additional target with explicit hostname and port
      - pangolin.proxy-resources.nginx.targets[1].method=http
      - pangolin.proxy-resources.nginx.targets[1].hostname=nginx2
      - pangolin.proxy-resources.nginx.targets[1].port=80

networks:
  default:
    name: pangolin_default

Docker Labels Considerations

• Automatic Discovery: When hostname and internal port are not defined, Pangolin auto-detects from container configuration
• Site Assignment: If no site is specified, resource is assigned to the discovering Newt site
• Configuration Merging: Configuration across containers is merged to form complete resource definitions

Configuration Properties Reference

Proxy Resources Properties

Target Configuration Properties

Authentication Properties

Not allowed on TCP/UDP resources.

Rules Configuration Properties

Client Resources Properties

Validation Rules and Constraints

Resource-Level Validations

1. Targets-Only Resources: A resource can contain only targets field, making name and protocol optional 2. Protocol-Specific Requirements:

• HTTP Protocol: Must have full-domain and all targets must have method field
• TCP/UDP Protocol: Must have proxy-port and targets must NOT have method field
• TCP/UDP Protocol: Cannot have auth configuration

3. Port Uniqueness:

• proxy-port values must be unique within proxy-resources
• proxy-port values must be unique within client-resources
• Cross-validation between proxy and client resources is not enforced

4. Domain Uniqueness: full-domain values must be unique across all proxy resources 5. Target Method Requirements: When protocol is http, all non-null targets must specify a method

Common Validation Errors

"Admin role cannot be included in sso-roles"

The Admin role is reserved and cannot be included in the sso-roles array.

Solution: Remove "Admin" from the sso-roles array.

"Duplicate 'full-domain' values found"

Each full-domain must be unique across all proxy resources.

Solution: Use different subdomains or paths for multiple resources.

"Duplicate 'proxy-port' values found"

Port numbers in proxy-port must be unique within their resource type.

Solution: Assign unique port numbers within proxy-resources and client-resources separately.

"When protocol is 'http', all targets must have a 'method' field"

All targets in HTTP proxy resources must specify the connection method.

Solution: Add method: http, method: https, or method: h2c to all targets.

"When protocol is 'tcp' or 'udp', targets must not have a 'method' field"

TCP and UDP targets should not include the method field.

Solution: Remove the method field from TCP/UDP resource targets.

"When protocol is 'tcp' or 'udp', 'auth' must not be provided"

Authentication is only supported for HTTP resources.

Solution: Remove the auth section from TCP/UDP resources.

"Resource must either be targets-only or have both 'name' and 'protocol' fields"

Resources must be either targets-only or complete resource definitions.

Solution: Either provide only targets field, or include both name and protocol fields.

Workflow for Generating Blueprints

When a user requests a Pangolin Newt blueprint configuration:

1. Gather Requirements:

• Resource type (proxy or client)
• Protocol (HTTP, TCP, UDP)
• Domain or port requirements
• Target endpoints (hostname, port, site)
• Authentication needs (if HTTP)
• Access control rules (if any)
• Format preference (YAML or Docker Labels)

2. Select Format:

• Use YAML for standalone configurations or API deployment
• Use Docker Labels for containerized applications

3. Validate Configuration:

• Ensure protocol-specific requirements are met
• Check for unique full-domain (HTTP) or proxy-port (TCP/UDP)
• Verify authentication is only on HTTP resources
• Confirm all HTTP targets have method field
• Ensure TCP/UDP targets don't have method field

4. Generate Configuration:

• Create well-structured YAML or Docker Compose file
• Include helpful comments explaining each section
• Follow naming conventions (kebab-case for resource IDs)

5. Provide Usage Instructions:

• Explain how to apply the configuration (Newt CLI or API)
• Document any environment variables needed
• Include validation commands if applicable

Best Practices

1. Resource IDs: Use descriptive, kebab-case identifiers (e.g., web-app-prod, database-backup) 2. Target Organization: Group related targets under the same resource ID 3. Security First: Enable authentication for sensitive HTTP resources 4. Port Management: Document port assignments to avoid conflicts 5. Site Assignment: Explicitly specify site for multi-site deployments 6. Path Matching: Use prefix for broad matches, exact for specific endpoints 7. Headers: Add custom headers for backend requirements (e.g., X-Forwarded- headers) 8. Rules: Order rules from most specific to least specific 9. Validation: Always validate configurations before deployment 10. Documentation*: Include comments in YAML or Docker Compose files explaining non-obvious choices

Resources

• API Documentation: https://api.pangolin.net/v1/docs/#/Organization/put_org__orgId__blueprint
• Python Example: https://github.com/fosrl/pangolin/blob/dev/blueprint.py
• Official Docs: https://docs.pangolin.net/manage/blueprints

Example Use Cases

Use Case 1: Simple Web Application

Requirements: Expose a web app running on localhost:8080 via HTTPS at app.example.com

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: https

Use Case 2: TCP Database Access

Requirements: Expose PostgreSQL database on port 5432

proxy-resources:
  postgres-db:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432

Use Case 3: Multi-Target Load Balanced HTTP Service

Requirements: Multiple backend servers for the same domain

proxy-resources:
  api-service:
    name: API Service
    protocol: http
    full-domain: api.example.com
    targets:
      - site: site-01
        hostname: backend-01
        port: 8080
        method: http
      - site: site-02
        hostname: backend-02
        port: 8080
        method: http

Use Case 4: Secured Resource with SSO

Requirements: Web app with SSO authentication

proxy-resources:
  secure-app:
    name: Secure Application
    protocol: http
    full-domain: secure.example.com
    auth:
      sso-enabled: true
      sso-roles:
        - Member
        - Developer
      sso-users:
        - admin@example.com
    targets:
      - hostname: localhost
        port: 3000
        method: https

Communication Style

When generating blueprints:

• Ask clarifying questions if requirements are unclear
• Explain validation errors in plain language
• Provide complete, working examples
• Include comments for complex configurations
• Suggest security best practices proactively
• Offer both YAML and Docker Labels formats when appropriate

Newt Blueprint Generator

Generate and validate Pangolin Newt blueprint configurations in YAML or Docker Labels format.

Overview

This skill provides expert assistance for creating, validating, and managing Pangolin Newt blueprint configurations. It supports both YAML configuration files and Docker Compose label-based configurations.

When to Use

Use this skill when you need to:

• Create Pangolin blueprint configurations
• Generate YAML configuration files for Newt
• Create Docker Compose files with Pangolin labels
• Configure proxy resources (HTTP, TCP, UDP)
• Set up client resources for Pangolin Olm
• Configure authentication (SSO, basic auth, pincode, password)
• Validate blueprint configurations
• Troubleshoot blueprint validation errors
• Convert between YAML and Docker Labels formats

Installation

/plugin install newt-blueprint-generator

Usage

Triggering the Skill

The skill automatically activates when you mention:

• "Newt blueprint"
• "Pangolin blueprint"
• "Generate blueprint configuration"
• "Create proxy resource"
• "Pangolin YAML config"
• "Docker labels for Pangolin"

Example Prompts

1. Simple Web Application:

   Create a Newt blueprint for a web app running on localhost:8080
   accessible at app.example.com

2. TCP Database:

   Generate a blueprint for exposing a PostgreSQL database on port 5432

3. Docker Compose Setup:

   Create a Docker Compose file with Pangolin labels for an nginx
   service at nginx.example.com

4. Secured Resource:

   Generate a blueprint with SSO authentication for secure.example.com

5. Multi-Target Resource:

   Create a blueprint with multiple backend targets for load balancing

Features

Comprehensive Blueprint Generation

• HTTP Proxy Resources: Full domain-based routing with headers, rules, and authentication
• TCP/UDP Proxy Resources: Raw port-based proxying for databases, game servers, etc.
• Client Resources: Olm client resources for SSH, RDP, and other protocols
• Authentication: SSO, basic auth, pincode, and password authentication
• Access Control: IP, CIDR, path, and country-based rules

Validation

The skill automatically validates:

• Protocol-specific requirements (HTTP vs TCP/UDP)
• Unique constraints (full-domain, proxy-port)
• Authentication compatibility (HTTP only)
• Target method requirements
• Port ranges (1-65535)
• Email format for SSO users

Format Support

• YAML Configuration: Standalone files for Newt CLI or API
• Docker Labels: Embedded in Docker Compose files

Configuration Examples

HTTP Proxy Resource (YAML)

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    headers:
      - name: X-Custom-Header
        value: custom-value
    targets:
      - hostname: localhost
        port: 8080
        method: https

TCP Proxy Resource (YAML)

proxy-resources:
  database:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432

Docker Compose with Labels

services:
  nginx:
    image: nginx:latest
    labels:
      - pangolin.proxy-resources.web.name=Web Server
      - pangolin.proxy-resources.web.full-domain=web.example.com
      - pangolin.proxy-resources.web.protocol=http
      - pangolin.proxy-resources.web.targets[0].method=http

Common Validation Errors

The skill helps you resolve common errors:

Best Practices

1. Use Descriptive IDs: Name resources clearly (e.g., web-app-prod, db-backup) 2. Enable Authentication: Secure HTTP resources with SSO or password 3. Document Ports: Keep track of port assignments to avoid conflicts 4. Explicit Sites: Specify site for multi-site deployments 5. Path Matching: Use prefix for broad matches, exact for specific endpoints 6. Validate Before Deploy: Test configurations locally before production

Version History

• v1.0.0 (2025-01-20): Initial release with full Pangolin blueprint support

Resources

• Pangolin Documentation
• API Reference
• Example Python Script

Support

For issues or questions:

• Pangolin GitHub: https://github.com/fosrl/pangolin
• Pangolin Slack: https://pangolin.net/slack
• Pangolin Discord: https://pangolin.net/discord

License

This skill follows the same license as the Skills marketplace repository.

Validation Reference

This document provides a comprehensive reference for all validation rules and constraints in Pangolin Newt blueprints.

Table of Contents

1. Resource-Level Validations 2. Property Constraints 3. Common Validation Errors 4. Validation Quick Reference

Resource-Level Validations

Targets-Only Resources

A resource can contain only the targets field:

proxy-resources:
  additional-targets:
    targets:
      - site: another-site
        hostname: backend-server
        method: https
        port: 8443

When using targets-only:

• name field is NOT required
• protocol field is NOT required
• All other resource-level validations are skipped

Protocol-Specific Requirements

HTTP Protocol

Required fields:

• full-domain - Must be unique across all proxy resources
• All targets must have method field (http, https, or h2c)

Optional features:

• auth configuration (SSO, basic auth, pincode, password)
• headers array
• rules array
• host-header
• tls-server-name
• ssl boolean

Not allowed:

• proxy-port (use full-domain instead)

TCP/UDP Protocol

Required fields:

• proxy-port - Must be unique within proxy-resources
• Port range: 1-65535

Not allowed:

• method field in targets
• auth configuration (authentication not supported)
• full-domain (use proxy-port instead)

Property Constraints

Port Constraints

Important: Cross-validation between proxy and client resources is NOT enforced. You can use the same port in both proxy-resources and client-resources.

Domain Constraints

String Length Constraints

Authentication Constraints

SSO Roles

• Cannot include "Admin" role (reserved)
• Must be array of strings
• Each role must be valid

SSO Users & Whitelist Users

• Must be valid email addresses
• Must be array of strings

Pincode

• Must be exactly 6 digits
• Type: number
• Example: 123456

Basic Auth

• Must have both user and password fields
• Both fields are required strings

Common Validation Errors

1. "Admin role cannot be included in sso-roles"

Cause: The Admin role is reserved and cannot be included in sso-roles array.

Solution:

# ❌ Wrong
auth:
  sso-enabled: true
  sso-roles:
    - Admin    # This will fail
    - Member

# ✅ Correct
auth:
  sso-enabled: true
  sso-roles:
    - Member
    - Developer

2. "Duplicate 'full-domain' values found"

Cause: Each full-domain must be unique across all proxy resources.

Solution:

# ❌ Wrong - same domain twice
proxy-resources:
  app1:
    full-domain: app.example.com
    # ...
  app2:
    full-domain: app.example.com  # Duplicate!
    # ...

# ✅ Correct - use different subdomains or paths
proxy-resources:
  app1:
    full-domain: app1.example.com
    # ...
  app2:
    full-domain: app2.example.com
    # ...

3. "Duplicate 'proxy-port' values found"

Cause: Port numbers in proxy-port must be unique within their resource type.

Solution:

# ❌ Wrong - same port twice in proxy-resources
proxy-resources:
  db1:
    protocol: tcp
    proxy-port: 5432
    # ...
  db2:
    protocol: tcp
    proxy-port: 5432  # Duplicate!
    # ...

# ✅ Correct - use different ports
proxy-resources:
  db1:
    protocol: tcp
    proxy-port: 5432
    # ...
  db2:
    protocol: tcp
    proxy-port: 5433
    # ...

4. "When protocol is 'http', all targets must have a 'method' field"

Cause: HTTP targets must specify connection method.

Solution:

# ❌ Wrong - missing method
proxy-resources:
  web-app:
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        # Missing method!

# ✅ Correct - method specified
proxy-resources:
  web-app:
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: https  # Added method

5. "When protocol is 'tcp' or 'udp', targets must not have a 'method' field"

Cause: TCP/UDP targets should not include the method field.

Solution:

# ❌ Wrong - method on TCP target
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432
        method: tcp  # Not allowed for TCP/UDP!

# ✅ Correct - no method field
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432
        # No method field

6. "When protocol is 'tcp' or 'udp', 'auth' must not be provided"

Cause: Authentication is only supported for HTTP resources.

Solution:

# ❌ Wrong - auth on TCP resource
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    auth:
      password: secret  # Not allowed!
    targets:
      - hostname: localhost
        port: 5432

# ✅ Correct - no auth on TCP
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    # No auth field
    targets:
      - hostname: localhost
        port: 5432

7. "Resource must either be targets-only or have both 'name' and 'protocol' fields"

Cause: Incomplete resource definition.

Solution:

# ❌ Wrong - has name but no protocol
proxy-resources:
  incomplete:
    name: My Resource
    # Missing protocol!
    targets:
      - hostname: localhost
        port: 8080

# ✅ Correct - complete definition
proxy-resources:
  complete:
    name: My Resource
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: http

# ✅ Also correct - targets-only
proxy-resources:
  targets-only:
    targets:
      - hostname: localhost
        port: 8080
        method: http

Validation Quick Reference

✅ Valid Configurations

HTTP Resource - Complete

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    enabled: true
    ssl: true
    host-header: backend.internal
    tls-server-name: backend.internal
    headers:
      - name: X-Custom-Header
        value: custom-value
    auth:
      sso-enabled: true
      sso-roles:
        - Member
      sso-users:
        - user@example.com
    rules:
      - action: allow
        match: ip
        value: 1.1.1.1
    targets:
      - site: site-01
        hostname: localhost
        port: 8080
        method: https
        enabled: true
        path: /api
        path-match: prefix

TCP Resource - Complete

proxy-resources:
  database:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    enabled: true
    targets:
      - site: site-01
        hostname: localhost
        port: 5432
        enabled: true

Targets-Only Resource

proxy-resources:
  additional-targets:
    targets:
      - site: site-02
        hostname: backend-02
        port: 8080
        method: http

Client Resource

client-resources:
  ssh-server:
    name: SSH Server
    protocol: tcp
    proxy-port: 2222
    hostname: localhost
    internal-port: 22
    site: site-01
    enabled: true

❌ Invalid Configurations

Mixed Protocol Requirements

# ❌ INVALID - HTTP resource with proxy-port instead of full-domain
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: http
    proxy-port: 8080  # Should be full-domain for HTTP!
    targets:
      - hostname: localhost
        port: 8080
        method: http

TCP with Auth

# ❌ INVALID - TCP resource with auth
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: tcp
    proxy-port: 5432
    auth:  # Auth not allowed on TCP/UDP!
      password: secret
    targets:
      - hostname: localhost
        port: 5432

Missing Required Fields

# ❌ INVALID - HTTP target without method
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        # Missing method field!

Validation Checklist

Before deploying a blueprint, verify:

• [ ] All HTTP resources have unique full-domain values
• [ ] All TCP/UDP resources have unique proxy-port values within their type
• [ ] All HTTP targets have method field specified
• [ ] No TCP/UDP targets have method field
• [ ] No TCP/UDP resources have auth configuration
• [ ] All port numbers are in range 1-65535
• [ ] All email addresses in sso-users and whitelist-users are valid
• [ ] SSO roles do not include "Admin"
• [ ] Pincode (if used) is exactly 6 digits
• [ ] Basic auth (if used) has both user and password fields
• [ ] String fields meet minimum/maximum length requirements
• [ ] Resources are either targets-only OR have both name and protocol