> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minenet.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurations and YAML

> Learn how deployment configurations are structured and how to design clean, maintainable desired state.

A deployment configuration stores your desired infrastructure state as YAML.

Think of it as your source of truth.

## What a configuration contains

A saved configuration includes:

* `name` and optional `description`
* raw `yaml`
* a normalized spec hash used internally for safe reconciliation
* latest pushed version metadata used by apply runs

## Why stable resource IDs are critical

Each resource in YAML has an `id`.

Minenet uses that `id` to map desired resources to live resources.

If IDs stay stable, Minenet can update safely.
If IDs change unexpectedly, Minenet may treat resources as new and create/replace instead.

## Basic structure

```yaml theme={null}
apiVersion: minenet.pro/v1alpha1
kind: Deployment
metadata:
  name: production
spec:
  resources:
    - id: main-server
      type: server
      name: Main Server
      region: dallas
      resources:
        memoryGb: 8
        storageGb: 40
      software:
        install:
          type: paper
          minecraftVersion: latest
          java: auto

    - id: edge-proxy
      type: proxy-velocity
      name: Edge Proxy
      region: dallas
      resources:
        memoryGb: 2
        storageGb: 10
      velocity:
        version: latest

    - id: main-db
      type: swiftbase
      name: main-db
      location: ash
      serverType: cpx21
```

## Empty desired state (delete-all behavior)

You can set:

```yaml theme={null}
spec:
  resources: []
```

This means your desired state is "no resources" for that configuration.

<Warning>
  Applying an empty resource list is destructive. Confirm this is intentional before applying.
</Warning>

## Practical authoring tips

* Use human-readable, stable IDs (`main-server`, `edge-proxy`, `main-db`).
* Keep one logical environment per configuration when possible.
* Keep names user-friendly, but do not use names as identity. IDs are identity.
* Keep changes small and explicit for easier reviews.

## Create/update/push/apply flow

1. Create a configuration with name + YAML.
2. Update YAML over time as requirements change.
3. Push a version (`POST /deployments/configurations/{configurationId}/push`).
   : `push_message` is optional and max length is `1000` characters.
4. Optionally review changes with versions + diff endpoints.
5. Apply to queue reconciliation from the latest pushed version.

If no pushed version exists yet, apply returns `409 NO_PUSHED_VERSION`.

## What is validated before save/push/apply

Minenet validates configuration content and enforces ownership/policy rules during apply.

This helps prevent invalid shape changes and accidental drift.

## Next step

If you need full field-level details, read [YAML spec reference](/guides/deployments/yaml-spec-reference).

Then continue to [Run lifecycle and monitoring](/guides/deployments/run-lifecycle-and-monitoring).