# !random

The `!random` Atmos YAML function generates a cryptographically secure random integer within a specified range.
This is particularly useful for generating random port numbers, IDs, or other numeric values in your devcontainer and stack configurations.

## Usage

The `!random` function accepts 0, 1, or 2 parameters for maximum flexibility:

```yaml
  # Generate a random integer between 0 and 65535 (default range)
  !random

  # Generate a random integer between 0 and max
  !random <max>

  # Generate a random integer between min and max
  !random <min> <max>
```

## Arguments

- **`min` (optional)**

  Minimum value (inclusive). Must be an integer less than `max`. Defaults to 0 if not specified.
- **`max` (optional)**

  Maximum value (inclusive). Must be an integer greater than `min`. Defaults to 65535 if not specified.

The function generates a cryptographically secure random integer in the range `[min, max]` (both bounds inclusive).

**Default Behavior:**

- `!random` → Random number from 0 to 65535
- `!random 100` → Random number from 0 to 100
- `!random 1024 65535` → Random number from 1024 to 65535

## Examples

### Simple Random Values

Use `!random` without arguments for quick random number generation:

```yaml
vars:
  # Generate any random number in the full range
  random_id: !random

  # Generate random number from 0 to 100
  percentage: !random 100

  # Generate random number from 1 to 10
  priority: !random 1 10
```

### Random Port Numbers

Generate random ports for devcontainer configurations:

```yaml
components:
  devcontainer:
    backend-api:
      spec:
        image: mcr.microsoft.com/devcontainers/go:1.24
        forwardPorts:
          - !random 1024 65535  # Specific range
          - !random 9999        # 0 to 9999
        workspaceFolder: /workspace
```

### Random Ports in Stack Configurations

```yaml
vars:
  # Generate a random ephemeral port
  app_port: !random 49152 65535

  # Generate a random port in registered port range
  service_port: !random 1024 49151

  # Generate a random ID
  worker_id: !random 1000 9999
```

## Common Use Cases

### DevContainer Port Forwarding

Automatically assign random ports to avoid conflicts when running multiple devcontainer instances:

```yaml
components:
  devcontainer:
    geodesic:
      spec:
        image: cloudposse/geodesic:latest
        forwardPorts:
          - !random 8080 8099  # Web server
          - !random 3000 3099  # Dev server
          - !random 5432 5442  # Database
        workspaceFolder: /workspace
```

:::tip Viewing Actual Devcontainer Ports
When using `!random` for devcontainer port forwarding, the container is created with specific random ports that remain fixed for that container's lifetime. To see which ports your running container is actually using:

```bash
# Shows actual runtime ports for running containers
atmos devcontainer list

# Or use docker/podman directly
docker ps
```

The `atmos devcontainer config` command shows the configuration (which regenerates random values), not the actual runtime ports.
:::

### Load Balancer Configuration

Generate random ports for backend services:

```yaml
vars:
  backend_ports:
    api: !random 10000 10999
    metrics: !random 11000 11999
    health: !random 12000 12999
```

## Port Ranges

Common port ranges for different purposes:

- **System Ports**: 0-1023 (requires root/admin privileges)
- **Registered Ports**: 1024-49151 (commonly used application ports)
- **Ephemeral Ports**: 49152-65535 (typically used for dynamic/private port allocation)

For devcontainers and local development, use registered or ephemeral port ranges to avoid privilege requirements and conflicts with system services.

## Cryptographic Security

The `!random` function uses Go's `crypto/rand` package to generate cryptographically secure random numbers. This ensures:

- **Unpredictability**: Values cannot be guessed or predicted
- **No collisions**: Multiple calls produce different values (statistically)
- **Suitable for security**: Safe for generating ports, tokens, or other security-sensitive values

## Error Handling

The function will fail with a clear error message if:

- Less than 2 arguments provided
- More than 2 arguments provided
- Arguments are not valid integers
- `min` >= `max`

Example error:

```
invalid number of arguments. The function requires exactly 2 arguments (min max): !random 1024
```

:::warning Important: Values Are Not Persisted
The `!random` function generates a **new random value every time** Atmos processes your configuration. This means:

- **Not saved:** Random values are never persisted to disk
- **Regenerated:** Each `atmos` command generates new random values
- **Devcontainer ports:** When using `!random` for devcontainer ports:
  - The container is created with specific port values at creation time
  - Running `atmos devcontainer list` shows the **actual runtime ports** the container is using
  - Running `atmos devcontainer config` shows **new random values** (not the ones the container uses)
  - To see which ports a running container is using, use `atmos devcontainer list` or `docker ps`

**For consistent values:** Use `!env` with a pre-generated value or hardcode specific ports in your configuration.
:::