# YAML for distributions

Learn how to configure routing distributions using YAML in Buddy. Map domains, subdomains and paths to tunnels, sandboxes, artifacts or external addresses, per region.

## YAML Parameters

```typescript
interface Distribution {
  /** A human-readable ID of the distribution. */
  distribution: string;
  /** The name of the distribution */
  name?: string;
  /** Indicates if the distribution is disabled */
  disabled?: boolean;
  /** The permissions for the distribution */
  permissions?: PermissionsYaml;
  /** The list of routes associated with the distribution */
  routes?: RouteYaml[];
}
```

## Type Definitions

```typescript
interface PermissionsYaml {
  /** Access level for other workspace members */
  others?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** List of specific users with their access levels */
  users?: object;
  /** List of user groups with their access levels */
  groups?: object;
  /** List of pipelines allowed to access this resource */
  pipelines?: AllowedPipelineYaml[];
  /** List of sandboxes allowed to access this resource */
  sandboxes?: AllowedSandboxYaml[];
}

interface AllowedPipelineYaml {
  /** When true, allow all pipelines to access this resource */
  all?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** Project name containing the allowed pipeline */
  project?: string;
  /** Pipeline identifier that is allowed to access this resource */
  pipeline?: string;
  /** Access level granted to the pipeline */
  access?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface AllowedSandboxYaml {
  /** When true, allow all sandboxes to access this resource */
  all?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** Project name containing the allowed sandbox */
  project?: string;
  /** Sandbox identifier that is allowed to access this resource */
  sandbox?: string;
  /** Access level granted to the sandbox */
  access?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface RouteYaml {
  /** The domain of the route */
  domain: string;
  /** The subdomain of the route */
  subdomain?: string;
  /** The path of the route */
  path?: string;
  /** The type of the route */
  type?: "CACHED_PROXY" | "REDIRECT" | "CLOAKING" | "DIRECT_PROXY";
  /** The single target the route points to. Mutually exclusive with 'regions' */
  target?: RouteTargetYaml;
  /** Per-region targets keyed by region (e.g. Default, a continent, or a country code). Mutually exclusive with 'target' */
  regions?: Record<string, RouteTargetYaml>;
}

interface RouteTargetYaml {
  /** The type of the target */
  endpoint: "EXTERNAL" | "ARTIFACT" | "SANDBOX" | "TUNNEL";
  /** The external URL (for EXTERNAL type) */
  address?: string;
  /** The tunnel configuration (for TUNNEL type) */
  tunnel?: TunnelTargetYaml;
  /** The sandbox configuration (for SANDBOX type) */
  sandbox?: SandboxTargetYaml;
  /** The artifact configuration (for ARTIFACT type) */
  artifact?: ArtifactTargetYaml;
}

interface TunnelTargetYaml {
  /** The ID of the tunnel agent */
  agent: string;
  /** The name of the tunnel on the agent */
  name: string;
}

interface SandboxTargetYaml {
  /** The ID of the sandbox */
  id: string;
  /** The endpoint of the sandbox */
  endpoint?: string;
}

interface ArtifactTargetYaml {
  /** The ID of the artifact */
  id: string;
  /** The version of the artifact to serve */
  version: string;
}

```

## YAML Examples

### Single route to an external backend

```yaml
- distribution: my-distro
  routes:
    - domain: example.com
      target:
        endpoint: EXTERNAL
        address: https://backend.example.com

```

### Distribution with permissions and all target types

```yaml
- distribution: my-distro
  name: My Distribution
  disabled: false
  permissions:
    others: READ_ONLY
    users:
      dev@example.com: MANAGE
    groups:
      admins: MANAGE
  routes:
    - domain: example.com
      subdomain: www
      path: /api
      type: DIRECT_PROXY
      target:
        endpoint: EXTERNAL
        address: https://backend.example.com
    - domain: cdn.example.com
      type: CACHED_PROXY
      target:
        endpoint: SANDBOX
        sandbox:
          id: my-sandbox
          endpoint: web
    - domain: app.example.com
      target:
        endpoint: TUNNEL
        tunnel:
          agent: my-agent
          name: my-tunnel
    - domain: downloads.example.com
      target:
        endpoint: ARTIFACT
        artifact:
          id: my-artifact
          version: 1.0.0

```

### Geolocation routing by region

```yaml
- distribution: geo-distro
  routes:
    - domain: geo.example.com
      type: CLOAKING
      regions:
        Default:
          endpoint: EXTERNAL
          address: https://global.example.com
        Asia:
          endpoint: EXTERNAL
          address: https://asia.example.com
        US:
          endpoint: EXTERNAL
          address: https://us.example.com

```


---
Original source: https://buddy.works/docs/yaml/yaml-distributions