newt blueprint generator

仓库: rknall/claude-skills
安装量: 51
排名: #14372

安装

npx skills add https://github.com/rknall/claude-skills --skill Newt

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:

  • YAML Configuration Files: Standalone configuration files

  • 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

| name | string | Conditional | Human-readable name | Required unless targets-only

| protocol | string | Conditional | Protocol type (http, tcp, udp) | Required unless targets-only

| full-domain | string | HTTP only | Full domain name | Required for HTTP, must be unique

| proxy-port | number | TCP/UDP only | Port for raw TCP/UDP | Required for TCP/UDP, 1-65535, must be unique

| ssl | boolean | No | Enable SSL/TLS | -

| enabled | boolean | No | Whether resource is enabled | Defaults to true

| host-header | string | No | Custom Host header | -

| tls-server-name | string | No | SNI name for TLS | -

| headers | array | No | Custom headers | Each requires name and value (min 1 char)

| rules | array | No | Access control rules | See Rules section

| auth | object | HTTP only | Authentication config | See Authentication section

| targets | array | Yes | Target endpoints | See Targets section

Target Configuration Properties

| site | string | No | Site identifier | -

| hostname | string | Yes | Target hostname or IP | -

| port | number | Yes | Target port | 1-65535

| method | string | HTTP only | Protocol method (http, https, h2c) | Required for HTTP

| enabled | boolean | No | Whether target is enabled | Defaults to true

| internal-port | number | No | Internal port mapping | 1-65535

| path | string | HTTP only | Path prefix, exact, or regex | -

| path-match | string | HTTP only | Path matching type (prefix, exact, regex) | -

Authentication Properties

Not allowed on TCP/UDP resources.

| pincode | number | No | 6-digit PIN | Must be exactly 6 digits

| password | string | No | Password for access | -

| basic-auth | object | No | Basic auth config | Requires user and password

| sso-enabled | boolean | No | Enable SSO | Defaults to false

| sso-roles | array | No | Allowed SSO roles | Cannot include "Admin" role

| sso-users | array | No | Allowed SSO user emails | Must be valid emails

| whitelist-users | array | No | Whitelisted user emails | Must be valid emails

Rules Configuration Properties

| action | string | Yes | Rule action (allow, deny, pass) | -

| match | string | Yes | Match type (cidr, path, ip, country) | -

| value | string | Yes | Value to match | Format depends on match type

Client Resources Properties

| name | string | Yes | Human-readable name | 2-100 characters

| protocol | string | Yes | Protocol type (tcp, udp) | -

| proxy-port | number | Yes | Port accessible to clients | 1-65535, must be unique

| hostname | string | Yes | Target hostname or IP | 1-255 characters

| internal-port | number | Yes | Port on target system | 1-65535

| site | string | No | Site identifier | 2-100 characters

| enabled | boolean | No | Whether resource is enabled | Defaults to true

Validation Rules and Constraints

Resource-Level Validations

  • Targets-Only Resources: A resource can contain only targets field, making name and protocol optional

  • 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

  • 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

  • Domain Uniqueness: full-domain values must be unique across all proxy resources

  • 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:

  • 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)

  • Select Format:

Use YAML for standalone configurations or API deployment

  • Use Docker Labels for containerized applications

  • 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

  • Generate Configuration:

Create well-structured YAML or Docker Compose file

  • Include helpful comments explaining each section

  • Follow naming conventions (kebab-case for resource IDs)

  • 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

  • Resource IDs: Use descriptive, kebab-case identifiers (e.g., web-app-prod, database-backup)

  • Target Organization: Group related targets under the same resource ID

  • Security First: Enable authentication for sensitive HTTP resources

  • Port Management: Document port assignments to avoid conflicts

  • Site Assignment: Explicitly specify site for multi-site deployments

  • Path Matching: Use prefix for broad matches, exact for specific endpoints

  • Headers: Add custom headers for backend requirements (e.g., X-Forwarded-* headers)

  • Rules: Order rules from most specific to least specific

  • Validation: Always validate configurations before deployment

  • Documentation: Include comments in YAML or Docker Compose files explaining non-obvious choices

Resources

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

← 返回排行榜