heat — Interactions

Interactions — heat — branch stable/2026.2

Branch stable/2026.2 @ 5872396e548c (27.0.1) — repository https://opendev.org/openstack/heat — analysed on 2026-10-29

1. RabbitMQ

1.1 Topology

Transport defaults set the control exchange to **heat** (heat/common/messaging.py:83). All RPC uses the oslo.messaging topic exchange; the JSON payload serialiser wraps a context serialiser that sends RequestContext.to_dict() (heat/common/messaging.py:29-61, heat/common/context.py:140-154). Remote exceptions are re-raised on the caller side only for classes of heat.common.exception (allowed_remote_exmods, heat/common/messaging.py:84); anything else arrives as RemoteError.

Notifications are sent on the notification transport with publisher_id = orchestration.<host> (or [DEFAULT]/default_publisher_id) and event_type = orchestration.<…> (heat/engine/notification/__init__.py, notify).

1.2 RPC methods (API → engine, topic engine)

Generated from [_rewrite/rpc-contract_stable-2026.2.json](_rewrite/rpc-contract_stable-2026.2.json) (_rewrite/tools/heat_rpc.py). Every server method except get_revision, list_resource_types, list_template_versions, list_template_functions, resource_schema and generate_template is wrapped by @context.request_context, which turns a HeatException into an expected remote error, i.e. no server-side traceback log (heat/common/context.py:362-369). The reply is the method's return value, JSON-serialised.

stack_identity is the dict form of HeatIdentifier: {"tenant": "<project id>", "stack_name": "s", "stack_id": "<uuid>", "path": ""} (heat/common/identifier.py:30-119). args is the dict of the API body minus the known keys (heat/api/openstack/v1/stacks.py:164-167): timeout_mins, disable_rollback, adopt_stack_data, tags, existing, clear_parameters, converge (heat/rpc/api.py:17-31).

validate_template returns either the validation result or {"Error": "<message>"}; for "No Template provided." and invalid ignore_errors codes it **returns a webob.exc.HTTPBadRequest object** through RPC (heat/engine/service.py:1337-1347), which the JSON serialiser turns into a string — a quirk the API never sees in practice because it always sends a template.

1.3 Engine ↔ engine

check_resource.data is {"input_data": {"tuple:(<id>, True, 'resource')": <node data> | <resource id> | null, ...}} — see § 2.4 and 05 § 2.4. accumulated_failures is {"<resource name>": "<reason>"} or null.

1.4 Sample frame [reconstructed]

check_resource cast as published on the heat exchange, routing key engine_worker (oslo.messaging "message envelope" v2.0; oslo.message is a JSON string, shown decoded):

{"oslo.version": "2.0",
 "oslo.message": {
   "method": "check_resource",
   "args": {"resource_id": 42, "current_traversal": "1d0c…", "is_update": true,
            "data": {"input_data": {"tuple:(41, True, 'resource')": {
                "id": 41, "name": "a", "uuid": "8b2e…", "reference_id": "a-xyz", "action": "CREATE", "status": "COMPLETE",
                "attrs": {"output": "one", "tuple:('show', 'value')": "one"}}}},
            "adopt_stack_data": null, "converge": false, "skip_propagate": false,
            "accumulated_failures": null, "node_type": "resource", "abandon": false},
   "namespace": null, "version": "1.9",
   "_context_user_id": "…", "_context_project_id": "…", "_context_auth_token": "gAAAA…",
   "_context_auth_token_info": {"token": {"…": "full Keystone token body, catalog included"}},
   "_context_trust_id": null, "_context_password": null, "_context_aws_creds": null,
   "_context_username": "demo", "_context_project_name": "demo", "_context_roles": ["member", "reader"],
   "_context_is_admin": false, "_context_request_id": "req-…", "_context_auth_url": "http://keystone/v3",
   "_context_region_name": null, "_context_trustor_user_id": null}}

• The context carries credentials: the user's token and its full Keystone body (auth_token_info, catalog included) on every message, and the clear-text password when deferred_auth_method = password (heat/common/context.py:140-154). Workers use this token to call the other services (heat/common/context.py:214-251); only signal handling, scaling and token-refresh paths switch to the stored trust (heat/engine/service.py:1986, heat/engine/stack.py:324-350). RabbitMQ access must be treated as credential access.
• A large stack makes large casts: each check_resource carries the resolved attributes of all its predecessors.

1.5 Notifications

2. Database

2.1 Tables

Schema: [_rewrite/schema-sqlite-migrated_stable-2026.2.sql](_rewrite/schema-sqlite-migrated_stable-2026.2.sql) (Alembic head 97b2a986f922, heat/db/migrations/versions/97b2a986f922_make_snapshot_state_aware.py); the ORM models match the migrations (0 differences, [_rewrite/schema-diff_stable-2026.2.md](_rewrite/schema-diff_stable-2026.2.md)). JSON columns use heat.db.types.Json/List: jsonutils.dumps into LONGTEXT on MySQL, TEXT elsewhere; None is stored as the string null (heat/db/types.py:35-65).

2.2 Notable statements [reconstructed from the ORM]

-- stack state change in convergence (heat/db/api.py:1003-1028): compare-and-swap on the traversal
UPDATE stack SET action=?, status=?, status_reason=?, updated_at=?
 WHERE id=? AND deleted_at IS NULL
   AND (tenant=? OR stack_user_project_id=?)          -- non-admin contexts only
   AND current_traversal=?;                           -- 0 rows => another traversal took over

-- resource lock acquire / release (heat/db/api.py:536-546, heat/engine/resource.py:2159-2183)
UPDATE resource SET action='UPDATE', status='IN_PROGRESS', engine_id=:me, atomic_key=:n+1, …
 WHERE id=:rid AND engine_id IS NULL AND atomic_key=:n;
UPDATE resource SET status='COMPLETE', engine_id=NULL, atomic_key=:n+2, …
 WHERE id=:rid AND engine_id=:me AND atomic_key=:n+1;

-- replacement, one transaction (heat/db/api.py:287-309)
INSERT INTO resource (stack_id, name, replaces, action, status, current_template_id, requires, …)
 VALUES (?, ?, :old, 'INIT', 'COMPLETE', ?, ?, …);
UPDATE resource SET replaced_by=:new, atomic_key=:n+1 WHERE id=:old AND engine_id IS NULL AND atomic_key=:n;
-- 0 rows => UpdateInProgress, the INSERT is rolled back

-- sync point merge (heat/db/api.py:2120-2135)
SELECT * FROM sync_point WHERE entity_id=? AND traversal_id=? AND is_update=?;
UPDATE sync_point SET input_data=?, extra_data=?, atomic_key=:n+1
 WHERE entity_id=? AND traversal_id=? AND is_update=? AND atomic_key=:n;

-- engines holding resource locks of a stack (heat/db/api.py:374-380)
SELECT DISTINCT engine_id FROM resource WHERE stack_id=? AND engine_id IS NOT NULL;

-- legacy stack lock (heat/db/api.py:1151-1198)
INSERT INTO stack_lock (stack_id, engine_id) VALUES (?, ?);            -- DBDuplicateEntry => read holder
UPDATE stack_lock SET engine_id=:new WHERE stack_id=? AND engine_id=:old;   -- steal
DELETE FROM stack_lock WHERE stack_id=? AND engine_id=?;                  -- release

• Writers that use @retry_on_db_error are retried on deadlock and disconnect ([database]/db_max_retries, heat/db/api.py:143-155).
• status_reason is truncated to 65535 UTF-8 bytes on MySQL before writing (heat/db/api.py:100-136); event.resource_status_reason to 255 characters (heat/db/models.py:228-230).
• Stack name uniqueness is not a database constraint: stack_create inserts, then re-reads the earliest live stack of that name in the project and deletes its own row if it is not the earliest (heat/db/api.py:982-998).
• heat-manage purge_deleted <age> hard-deletes soft-deleted stacks and their events, resources, templates and credentials in batches (heat/db/api.py:1827-2090).

2.3 Encrypted columns

heat/common/crypt.py:

• encrypt() uses Fernet with key base64(auth_encryption_key[:32]) (the key is doubled when shorter than 32 characters) and records decrypt_method = "cryptography_decrypt_v1" (heat/common/crypt.py, encrypt / cryptography_decrypt_v1).
• Rows written by older releases may name oslo_decrypt_v1 (AES-256-CBC with the 32-character key, IV prefix, ANSI X9.23 padding, last plaintext byte dropped) or heat_decrypt (AES-CFB, IV prefix): the method name stored in the row is a function name looked up by getattr at read time (heat/common/crypt.py, decrypt). A rewrite must implement all three to read existing databases; vectors are in [_rewrite/crypt-vectors_stable-2026.2.json](_rewrite/crypt-vectors_stable-2026.2.json).
• Encrypted: user_creds.password and user_creds.trust_id, resource_data.value when redact, hidden template parameters and resource_properties_data.data when [DEFAULT]/encrypt_parameters_and_properties (heat/db/api.py:2138-2306, heat-manage update_params).

3. Keystone

Without stack_user_domain_* configured, Heat falls back to creating stack users in the user's own project and domain with the user's token (heat/engine/clients/os/keystone/heat_keystoneclient.py:354-357, :437-442); a deployment for OpenKeel must configure the domain.

4. Other services (resource plugins)

• One client plugin per service, loaded through the heat.clients entry points (20 plugins, [_rewrite/client-plugins_stable-2026.2.json](_rewrite/client-plugins_stable-2026.2.json)). Endpoints come from the token's catalog: service_type of the plugin, interface [clients_<name>]/endpoint_type (default publicURL from [clients]), region context.region_name or [DEFAULT]/region_name_for_services, or region_name_for_shared_services for the shared services list (heat/engine/clients/client_plugin.py:89-125).
• A resource type is offered only if its service is in the catalog (is_service_available, heat/engine/resource.py:785-828); otherwise templates using it fail validation with ResourceTypeUnavailable (400, error code 99001).
• Retries: [DEFAULT]/client_retry_limit (2) connection retries for keystoneauth sessions; resource plugins poll their resource in check_<action>_complete with the scheduler's back-off; 404 on delete is ignored through each plugin's ignore_not_found.
• The full per-type list, with the porting verdict for OpenKeel, is [_rewrite/resource-types_stable-2026.2.json](_rewrite/resource-types_stable-2026.2.json) and 07 § 3.

5. Other exchanges

• template_url / get_file / template resources by URL: GET with requests, http and https only, timeout template_fetch_timeout (60 s), streaming stopped at max_template_size (DownloadLimitExceeded) (heat/common/urlfetch.py:38-84). The fetch for template_url happens in heat-api; for nested template URLs in heat-engine.
• Swift: files_container objects (heat/engine/template_files.py), signal TempURLs and containers, server metadata TempURLs (PUT from the engine, heat/engine/service_software_config.py:139-147).
• Zaqar: signal queues, metadata queues, the zaqar-queue event sink (absent in OpenKeel).
• Instance agents → Heat: os-collect-config / heat-config-notify / cfn-signal call heat-api-cfn (DescribeStackResource, /v1/signal, /v1/waitcondition), heat-api (…/metadata, …/signal), or Swift/Zaqar, with the stack-domain user's credentials (05 § 5).

Source: reverse-spec-heat/03-interactions_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.