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

# Orchestration Configuration

> Configure the Xloud Orchestration service — key settings, stack domain setup, default quotas, and XDeploy integration for production deployments.

## Overview

The Orchestration service is configured through XDeploy global variables and
service-specific configuration files. Key configuration areas include the stack domain
(used for trust delegation), engine worker settings, quota defaults, and integration
with the CloudWatch-compatible alarm endpoint.

<Warning>
  **Administrator Access Required** — This operation requires the `admin` role. Contact your
  Xloud administrator if you do not have sufficient permissions.
</Warning>

***

## Key Configuration Options

The following settings control core Orchestration service behavior. All settings are
managed through XDeploy.

| Setting                                    | Default      | Description                                                |
| ------------------------------------------ | ------------ | ---------------------------------------------------------- |
| `enable_heat`                              | `"no"`       | Enable the Orchestration service                           |
| `heat_engine_workers`                      | `4`          | Number of engine worker processes per controller node      |
| `heat_api_workers`                         | `4`          | Number of API worker processes per controller node         |
| `heat_max_stacks_per_tenant`               | `100`        | Maximum stacks per project                                 |
| `heat_max_resources_per_stack`             | `1000`       | Maximum resources in a single stack                        |
| `heat_max_nested_stack_depth`              | `5`          | Maximum depth for nested stack hierarchies                 |
| `heat_convergence_engine`                  | `true`       | Enable convergence mode for parallel resource provisioning |
| `heat_default_deployment_signal_transport` | `CFN_SIGNAL` | Default signal transport for `WaitCondition` resources     |

<Note>
  Enable the Orchestration service by setting `enable_heat: "yes"` in
  `/etc/xavs/globals.d/_50_orchestration.yml` and running `xavs-ansible deploy -t heat`.
</Note>

***

## Enable the Service

<Tabs>
  <Tab title="XDeploy" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Navigate to Configuration" icon="settings">
        In XDeploy, navigate to **Configuration → Services → Orchestration**.
      </Step>

      <Step title="Enable the service" icon="toggle-right">
        Set **Enable Orchestration** to **Yes** and configure the engine worker count
        appropriate for your controller node capacity (typically 2–4 workers per CPU core).
      </Step>

      <Step title="Apply configuration" icon="play">
        Click **Save** and then **Deploy → Orchestration** to apply the configuration.

        <Check>
          The Orchestration API is accessible at `http://<controller-ip>:8004/v1`.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    <Steps titleSize="h3">
      <Step title="Create configuration override" icon="file-code">
        ```bash title="Create orchestration globals" theme={null}
        cat > /etc/xavs/globals.d/_50_orchestration.yml << 'EOF'
        enable_heat: "yes"
        heat_engine_workers: 4
        heat_api_workers: 4
        heat_max_stacks_per_tenant: 100
        EOF
        ```
      </Step>

      <Step title="Deploy the service" icon="play">
        ```bash title="Deploy Orchestration" theme={null}
        xavs-ansible deploy -t heat
        ```
      </Step>

      <Step title="Verify the service" icon="circle-check">
        ```bash title="Check Orchestration endpoint" theme={null}
        openstack orchestration service list
        ```

        <Check>All engine and API services show status `up`.</Check>
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Stack Domain Setup

The stack domain is a dedicated Xloud Identity domain used for trust delegation.
When a template creates resources that require credentials (e.g., `WaitCondition`
signals, auto-scaling webhooks), the engine uses a stack domain user — scoped to
the stack's project — rather than the submitting user's credentials.

<Warning>
  The stack domain must be configured before deploying stacks that use
  `WaitCondition` or scaling policy resources. Stacks using only basic compute
  and network resources do not require the stack domain.
</Warning>

Stack domain configuration is handled automatically by XDeploy during the
Orchestration deployment. The following variables control the domain:

| Setting                      | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `heat_domain_name`           | Name of the stack domain in Xloud Identity (default: `heat`)    |
| `heat_domain_admin`          | Admin user for the stack domain                                 |
| `heat_domain_admin_password` | Password for the stack domain admin (stored in `passwords.yml`) |

***

## Default Quotas

Orchestration quotas limit per-project resource consumption. Defaults are set
cluster-wide; you can override them per-project.

| Quota       | Default | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `stacks`    | 100     | Maximum stacks per project                      |
| `resources` | 1000    | Maximum resources across all stacks per project |

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    Navigate to the admin quota settings to adjust global
    quota defaults. For per-project overrides, navigate to **Identity > Projects** (admin view),
    select a project, and click **Manage Quota**.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Show orchestration quotas for a project" theme={null}
    openstack quota show --project <PROJECT_ID>
    ```

    ```bash title="Update stack quota for a project" theme={null}
    openstack quota set --stacks 200 <PROJECT_ID>
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Scaling the Service" href="/services/orchestration/scaling" color="#197560">
    Configure multiple engine workers for high-throughput deployments
  </Card>

  <Card title="Security" href="/services/orchestration/security" color="#197560">
    Stack domain trust, policy configuration, and template injection prevention
  </Card>

  <Card title="Architecture" href="/services/orchestration/architecture" color="#197560">
    Understand service components and request processing flow
  </Card>

  <Card title="Admin Troubleshooting" href="/services/orchestration/admin-troubleshooting" color="#197560">
    Diagnose configuration errors and engine startup failures
  </Card>
</CardGroup>