rknall/claude-skills/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

1. 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

1. Domain Uniqueness: full-domain values must be unique across all proxy resources
2. 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.