Index of every page on this site: llms.txt
All skills
rknall avatar

/newt-blueprint-generator

@ca7fbd0
by Roland Knallrknall/claude-skills93 stars
13
Run it yourself

Generate and validate Pangolin Newt blueprint configurations in YAML or Docker Labels format. Use when creating Pangolin resource configurations, proxy resources, client resources, authentication settings, or Docker Compose blueprints.

Use this Skill: https://skilld.dev/gh/rknall/claude-skills/newt-blueprint-generator

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

validation-reference.md

≈2.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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

Property Scope Range Uniqueness
proxy-port proxy-resources 1-65535 Must be unique within proxy-resources
proxy-port client-resources 1-65535 Must be unique within client-resources
port (target) All 1-65535 No uniqueness constraint
internal-port All 1-65535 No uniqueness constraint

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

Property Scope Uniqueness Format
full-domain proxy-resources (HTTP only) Must be unique across all proxy resources Valid domain name

String Length Constraints

Property Min Length Max Length Context
name 2 100 All resources
hostname 1 255 All targets
site 2 100 Optional site identifier
header.name 1 - Header names
header.value 1 - Header values

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings25d5 checks · Risk SAFE
  • Gen Agent Trust Hub25d

    This skill is a safe utility designed to help users generate and validate Pangolin Newt blueprint configurations in YAML or Docker Labels format.

  • Socket26d

    No alerts

  • Snyk26d

    Risk: LOW · No issues

  • Runlayer9mo

    2/3 files flagged

  • ZeroLeaks7mo

    2 findings · Score: 76/100

Signed by skilld at ca7fbd0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Dormantupdated last year

README badge

README badge for rknall/claude-skills/newt-blueprint-generator