Newt Blueprint Generator

What this skill does

# 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:
```bash
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:
```bash
newt --docker-socket /var/run/docker.sock <other-args>
```

Or use environment variable:
```bash
DOCKER_SOCKET=/var/run/docker.sock
```

## Resource Types

### Proxy Resources

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

#### HTTP Proxy Resource Example

```yaml
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

```yaml
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:

```yaml
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):

```yaml
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.

```yaml
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:
        - [email protected]
      whitelist-users:
        - [email protected]
```

## Docker Labels Format

### Complete Docker Compose Example

```yaml
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

| Property | Type | Required | Description | Constraints |
|----------|------|----------|-------------|-------------|
| `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

| Property | Type | Required | Description | Constraints |
|----------|------|----------|-------------|-------------|
| `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.**

| Property | Type | Required | Description | Constraints |
|--