OpenStack Heat Orchestration API Client Library

Common errors

• ModuleNotFoundError: No module named 'heatclient'

  cause The `python-heatclient` library is not installed in the current Python environment.
  fix Run `pip install python-heatclient` to install the library.

• heatclient.common.exception.Unauthorized: The request you have made requires authentication. (HTTP 401)

  cause The authentication credentials (username, password, project, domain, auth URL) provided to `keystoneauth1` are incorrect, expired, or missing.
  fix Verify your OpenStack credentials and `OS_AUTH_URL`. Ensure all required authentication parameters are correctly configured and passed to `keystoneauth1.loading.get_plugin_loader().load_from_options()`.

• heatclient.common.exception.ClientException: Could not find resource for service type orchestration.

  cause The Heat service endpoint could not be discovered or is unavailable/misconfigured in the OpenStack service catalog.
  fix Check the `OS_AUTH_URL` and ensure the Heat service (orchestration) is registered and accessible in your OpenStack deployment. Verify network connectivity to the Keystone and Heat API endpoints.

• TypeError: Client() got an unexpected keyword argument 'auth_token'

  cause You are attempting to pass an authentication token directly to `heatclient.Client`, which expects a `keystoneauth1.session.Session` object.
  fix Instead of passing `auth_token`, create a `keystoneauth1.session.Session` object with your authentication details and pass it using the `session` keyword argument: `heat_client.Client('1', session=my_session)`.

Warnings

• breaking Python 2.7 support has been officially dropped. `python-heatclient` versions starting from Xena series (e.g., 2.x and later) and specifically the current 5.1.0 version, require Python 3.6 or newer, with the PyPI metadata explicitly stating `>=3.10`.
  Fix: Ensure your environment uses Python 3.10 or a compatible newer version. Upgrade your Python interpreter if necessary.
• gotcha OpenStack CLI commands are progressively consolidating into the unified `python-openstackclient`. While direct `heat` commands still exist, many functionalities are moving to `openstack stack ...` subcommands. Users familiar with older `heat` CLI tools should be aware of this shift.
  Fix: Prefer using `openstack stack` commands when available for new development or scripting, and consult `openstack help stack` for the most up-to-date syntax. `python-heatclient` continues to provide the programmatic API.
• gotcha Authentication for the `heatclient` Python API requires constructing an authenticated session using `keystoneauth1`. Directly passing authentication tokens or credentials to `heatclient.Client` might be deprecated or incorrect in newer versions. Relying solely on shell environment variables (like `OS_USERNAME`) without explicitly loading them via `keystoneauth1` will not work for the programmatic client.
  Fix: Always use `keystoneauth1.loading` and `keystoneauth1.session.Session` to create an authenticated session and pass this session object to `heatclient.Client`.

Install

• pip install python-heatclient Install latest version

Imports

• Client
  wrong:

  import heatclient.client

  correct:

  from heatclient import client as heat_client

  Common practice to alias the client module for clarity, as 'client' is a generic name.
• Session
  wrong:

  from keystoneclient.v3 import Client as Keystone_Client

  correct:

  from keystoneauth1.session import Session

  For authentication, `keystoneauth1.session.Session` is the recommended approach for creating an authenticated session, not direct `keystoneclient` imports which are for the identity API itself.
• get_plugin_loader

  from keystoneauth1.loading import get_plugin_loader

  Used to dynamically load authentication plugins (e.g., 'password', 'v3password') without hardcoding classes.

Quickstart

This quickstart demonstrates how to authenticate with OpenStack Keystone and then initialize the Heat client to list existing Heat stacks. It uses the `keystoneauth1` library for robust authentication, which is essential for interacting with OpenStack services. Replace placeholder credentials with your actual OpenStack environment details.

import os
from keystoneauth1 import loading
from keystoneauth1.session import Session
from heatclient import client as heat_client

# --- Authentication --- (replace with your OpenStack credentials or environment variables)
# For production, consider using environment variables (OS_AUTH_URL, OS_USERNAME, etc.)
# and 'keystoneauth1.loading.load_auth_from_options' or 'load_from_env'.
# For simplicity, using hardcoded values for quickstart, but highly discouraged in production.

AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://your-openstack-ip/identity/v3')
USERNAME = os.environ.get('OS_USERNAME', 'admin')
PASSWORD = os.environ.get('OS_PASSWORD', 'your-password')
PROJECT_NAME = os.environ.get('OS_PROJECT_NAME', 'admin')
USER_DOMAIN_NAME = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
PROJECT_DOMAIN_NAME = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')

# Load the password authentication plugin
loader = loading.get_plugin_loader('password')
auth = loader.load_from_options(
    auth_url=AUTH_URL,
    username=USERNAME,
    password=PASSWORD,
    project_name=PROJECT_NAME,
    user_domain_name=USER_DOMAIN_NAME,
    project_domain_name=PROJECT_DOMAIN_NAME
)

# Create a Keystone session
sess = Session(auth=auth)

# Create a Heat client
# API version '1' is commonly used. 'public' endpoint type is standard.
heat_client_instance = heat_client.Client(
    '1', 
    session=sess, 
    endpoint_type='public',
    service_type='orchestration'
)

# --- Example Usage: List Stacks ---
try:
    print('Listing Heat stacks:')
    for stack in heat_client_instance.stacks.list():
        print(f"  - Name: {stack.stack_name}, Status: {stack.stack_status}, ID: {stack.id}")
except Exception as e:
    print(f"Error listing stacks: {e}")