Install & Compatibility
Where this runs
tested against v6.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.871s · 108.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.8s · import 0.805s · 109MB
116MB installed
● package 116MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from designateclient.v2 import client
✗ from designateclient import client
Always import the v2 client explicitly as v1 APIs are older and may be deprecated or have different functionality.
Password
✓ from keystoneauth1.identity import generic
✗ from keystoneclient.auth.identity import v3
While v3 is still functional, `keystoneauth1.identity.generic` is the recommended and more flexible way to handle password-based authentication for OpenStack SDKs and clients.
This quickstart demonstrates how to authenticate with an OpenStack cloud using environment variables and then initialize the Designate v2 client. It proceeds to list existing DNS zones. Ensure your OpenStack environment variables (OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_PROJECT_DOMAIN_NAME, OS_USER_DOMAIN_NAME) are set for authentication.
import os
from keystoneauth1.identity import generic
from keystoneauth1 import session as keystone_session
from designateclient.v2 import client
# OpenStack credentials from environment variables
auth_url = os.environ.get('OS_AUTH_URL', 'https://your-openstack-cloud.com:5000/v3')
username = os.environ.get('OS_USERNAME', 'your-username')
password = os.environ.get('OS_PASSWORD', 'your-password')
project_name = os.environ.get('OS_PROJECT_NAME', 'your-project')
project_domain_name = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
user_domain_name = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
if not all([auth_url, username, password, project_name, project_domain_name, user_domain_name]):
print("Please set OpenStack environment variables (OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_PROJECT_DOMAIN_NAME, OS_USER_DOMAIN_NAME)")
exit(1)
# Authenticate with Keystone
auth = generic.Password(
auth_url=auth_url,
username=username,
password=password,
project_name=project_name,
project_domain_name=project_domain_name,
user_domain_name=user_domain_name
)
session = keystone_session.Session(auth=auth)
# Initialize Designate client
desig_client = client.Client(session=session)
try:
# List all zones
zones = desig_client.zones.list()
print(f"Found {len(zones)} DNS zones:")
for zone in zones:
print(f" - {zone.name} (ID: {zone.id})")
# Example: Create a new zone (replace with your domain and email)
# new_zone_name = 'example.com.'
# new_zone_email = 'admin@example.com'
# new_zone = desig_client.zones.create(new_zone_name, email=new_zone_email)
# print(f"Created new zone: {new_zone.name} (ID: {new_zone.id})")
except Exception as e:
print(f"An error occurred: {e}")
designate --version
Debug
Known issues
breakingThe `python-neutronclient` dependency for accessing Neutron has been replaced by `openstacksdk` in Designate releases starting from 2023.2. Direct usage of `python-neutronclient` within Designate's internal operations is now deprecated.fixEnsure `openstacksdk` is installed instead of `python-neutronclient` if you are managing Designate's dependencies for Neutron interaction. For programmatic use, prefer `openstacksdk` directly.
affects: >=2023.2 (OpenStack release series)
gotchaAuthentication with OpenStack services requires careful handling of credentials, often involving environment variables or a `clouds.yaml` file. Incorrect or missing authentication details will lead to `Unauthorized` errors or client initialization failures.fixAlways verify that `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, `OS_PROJECT_DOMAIN_NAME`, and `OS_USER_DOMAIN_NAME` (or equivalent `clouds.yaml` configuration) are correctly set and accessible to your application. Test connectivity using `openstack token issue` or similar before running Designate client code.
affects: All versions
deprecatedThe Designate v1 API and its corresponding client bindings are considered older and their usage is generally discouraged in favor of the v2 API, which offers more features and active development.fixAlways import and use the v2 client explicitly: `from designateclient.v2 import client`. Refer to the official OpenStack Designate API documentation for current v2 API specifications.
affects: All versions (v1 client features)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'keystoneauth1'
The `keystoneauth1` library, which provides OpenStack authentication mechanisms, is not installed.
fixInstall the required dependency: `pip install keystoneauth1`
HTTP 401 Unauthorized: The request you have made requires authentication.
The credentials provided for OpenStack Keystone authentication are incorrect, expired, or missing, preventing the client from obtaining a valid token.
fixDouble-check your OpenStack environment variables (`OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, etc.) or `clouds.yaml` configuration. Ensure your user has the necessary permissions within the specified project and domain. Try authenticating via the `openstack` CLI tool first (e.g., `openstack token issue`).
TypeError: 'NoneType' object is not subscriptable
An API call likely failed to retrieve the expected resource and returned `None` instead of an object or dictionary. Subsequent attempts to access attributes (like `zone['id']`) on this `None` object result in this error.
fixAdd explicit checks for `None` or empty responses after API calls that might fail. For example, `zone = desig_client.zones.get(zone_id); if zone is None: print("Zone not found.")` AttributeError: 'Client' object has no attribute 'zones'
This error often occurs if you've incorrectly initialized the client or attempted to access a service object (like `zones`) before it's properly available on the client instance, or if using a wrong client version.
fixEnsure you are importing the correct client for the Designate v2 API: `from designateclient.v2 import client`. Verify the client object is successfully instantiated after authentication before accessing its service methods. Check the `designateclient` source code or documentation for available service attributes.
Upgrade
Version history
6.4.0latest on PyPI · released Feb 24, 2026
Audit
Dependencies
keystoneauth1requiredRequired for authentication with OpenStack Keystone to obtain an authenticated session for the Designate client.
openstacksdkoptionalReplaced python-neutronclient for accessing Neutron in recent Designate releases, providing a unified SDK for OpenStack services.