{"id":8552,"library":"python-heatclient","title":"OpenStack Heat Orchestration API Client Library","description":"The `python-heatclient` library provides a Python API and a command-line interface for interacting with the OpenStack Heat orchestration service. It allows users to programmatically manage Heat stacks, which orchestrate complex cloud applications using templates. The library is actively maintained as part of the OpenStack project, with its current version being 5.1.0, requiring Python >=3.10.","status":"active","version":"5.1.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/python-heatclient","tags":["OpenStack","orchestration","cloud","client","API","automation"],"install":[{"cmd":"pip install python-heatclient","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Command line interface framework","package":"python-cliff"},{"reason":"ISO 8601 date parsing","package":"python-iso8601"},{"reason":"OpenStack Identity authentication library","package":"python-keystoneauth1"},{"reason":"Integration with the unified OpenStack CLI","package":"python-openstackclient"},{"reason":"OpenStack client library utilities","package":"python-osc-lib"},{"reason":"Internationalization support for OpenStack projects","package":"python-oslo-i18n"},{"reason":"Serialization utilities for OpenStack projects","package":"python-oslo-serialization"},{"reason":"Common utilities for OpenStack projects","package":"python-oslo-utils"},{"reason":"Setuptools enhancements for OpenStack projects","package":"python-pbr"},{"reason":"Formatted table output","package":"python-prettytable"},{"reason":"HTTP library for making API calls","package":"python-requests"},{"reason":"OpenStack Object Storage (Swift) client (optional, for specific Heat features)","package":"python-swiftclient"},{"reason":"YAML parsing for templates","package":"python-yaml"}],"imports":[{"note":"Common practice to alias the client module for clarity, as 'client' is a generic name.","wrong":"import heatclient.client","symbol":"Client","correct":"from heatclient import client as heat_client"},{"note":"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.","wrong":"from keystoneclient.v3 import Client as Keystone_Client","symbol":"Session","correct":"from keystoneauth1.session import Session"},{"note":"Used to dynamically load authentication plugins (e.g., 'password', 'v3password') without hardcoding classes.","symbol":"get_plugin_loader","correct":"from keystoneauth1.loading import get_plugin_loader"}],"quickstart":{"code":"import os\nfrom keystoneauth1 import loading\nfrom keystoneauth1.session import Session\nfrom heatclient import client as heat_client\n\n# --- Authentication --- (replace with your OpenStack credentials or environment variables)\n# For production, consider using environment variables (OS_AUTH_URL, OS_USERNAME, etc.)\n# and 'keystoneauth1.loading.load_auth_from_options' or 'load_from_env'.\n# For simplicity, using hardcoded values for quickstart, but highly discouraged in production.\n\nAUTH_URL = os.environ.get('OS_AUTH_URL', 'http://your-openstack-ip/identity/v3')\nUSERNAME = os.environ.get('OS_USERNAME', 'admin')\nPASSWORD = os.environ.get('OS_PASSWORD', 'your-password')\nPROJECT_NAME = os.environ.get('OS_PROJECT_NAME', 'admin')\nUSER_DOMAIN_NAME = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')\nPROJECT_DOMAIN_NAME = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')\n\n# Load the password authentication plugin\nloader = loading.get_plugin_loader('password')\nauth = loader.load_from_options(\n    auth_url=AUTH_URL,\n    username=USERNAME,\n    password=PASSWORD,\n    project_name=PROJECT_NAME,\n    user_domain_name=USER_DOMAIN_NAME,\n    project_domain_name=PROJECT_DOMAIN_NAME\n)\n\n# Create a Keystone session\nsess = Session(auth=auth)\n\n# Create a Heat client\n# API version '1' is commonly used. 'public' endpoint type is standard.\nheat_client_instance = heat_client.Client(\n    '1', \n    session=sess, \n    endpoint_type='public',\n    service_type='orchestration'\n)\n\n# --- Example Usage: List Stacks ---\ntry:\n    print('Listing Heat stacks:')\n    for stack in heat_client_instance.stacks.list():\n        print(f\"  - Name: {stack.stack_name}, Status: {stack.stack_status}, ID: {stack.id}\")\nexcept Exception as e:\n    print(f\"Error listing stacks: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment uses Python 3.10 or a compatible newer version. Upgrade your Python interpreter if necessary.","message":"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`.","severity":"breaking","affected_versions":"<=1.x (Python 2.7), >=2.x (Python 3.6+), Current 5.1.0 (Python 3.10+)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when integrating with `python-openstackclient` (especially newer OpenStack releases)"},{"fix":"Always use `keystoneauth1.loading` and `keystoneauth1.session.Session` to create an authenticated session and pass this session object to `heatclient.Client`.","message":"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.","severity":"gotcha","affected_versions":"All versions, increasingly critical in newer OpenStack deployments"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install python-heatclient` to install the library.","cause":"The `python-heatclient` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'heatclient'"},{"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()`.","cause":"The authentication credentials (username, password, project, domain, auth URL) provided to `keystoneauth1` are incorrect, expired, or missing.","error":"heatclient.common.exception.Unauthorized: The request you have made requires authentication. (HTTP 401)"},{"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.","cause":"The Heat service endpoint could not be discovered or is unavailable/misconfigured in the OpenStack service catalog.","error":"heatclient.common.exception.ClientException: Could not find resource for service type orchestration."},{"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)`.","cause":"You are attempting to pass an authentication token directly to `heatclient.Client`, which expects a `keystoneauth1.session.Session` object.","error":"TypeError: Client() got an unexpected keyword argument 'auth_token'"}]}