OpenStack SDK for Python

Warnings

• breaking Major breaking changes were introduced in `openstacksdk` versions `0.99.0` and `1.0.0`. The `Connection` interface now consistently utilizes `Resource` interfaces under the hood, and many API responses, which previously returned `Munch` objects, now return standard Python dictionaries. Additionally, many keys in the returned data were renamed.
  Fix: Update your code to expect dictionary-like access for resource properties and adjust to new key names. Refer to the official release notes for `0.99.0` and `1.0.0` for detailed changes. For example, use `.to_dict()` if you explicitly need a dictionary representation from a resource object.
• gotcha OpenStack services often use 'microversions' for their APIs. If not explicitly specified, `openstacksdk` will default to the lowest API version supported by the service. This can lead to missing features or unexpected behavior if you expect a newer API version's functionality.
  Fix: For services supporting microversions, explicitly specify the desired API version via connection parameters (e.g., `compute_api_version='2.latest'`) or service proxy arguments. Consult the OpenStack API reference for service-specific microversion details.
• gotcha Some resource attributes in `openstacksdk` are lazy-loaded, meaning they are not populated immediately when a resource object is created or returned from a list operation. For example, `block_device_mapping` or `networks` for a `Server` object might only be present after a `server.fetch()` call.
  Fix: If you require specific attributes that might be lazy-loaded, ensure you call the `fetch()` method on the resource object to retrieve its full details from the OpenStack API before accessing those attributes.
• gotcha Authentication and configuration can be a common source of errors. Incorrect `clouds.yaml` file formats, missing environment variables, or mixing OpenStack Identity API versions (v2 vs. v3) in configuration can lead to authentication failures.
  Fix: Carefully review your `clouds.yaml` file (if used) and environment variables for correctness. Ensure `auth_url` points to the correct Identity API version endpoint (e.g., `/v3`). The SDK will try to detect the API version, but explicit configuration helps. `openstack.enable_logging(debug=True)` can provide verbose authentication debug information.
• deprecated `openstacksdk` utilizes a warnings infrastructure (e.g., `openstack.warnings.OpenStackDeprecationWarning`, `RemovedInSDK50Warning`, `RemovedInSDK60Warning`) to signal deprecated features, resources, or behavior. By default, `DeprecationWarning` messages are silenced in Python.
  Fix: Enable Python's deprecation warnings during development and testing using the `-Wa` command-line option (`python -Wa your_script.py`) or by setting the `PYTHONWARNINGS` environment variable (e.g., `export PYTHONWARNINGS=default`). This helps identify code that needs updating before deprecated features are removed.

Install

• pip install openstacksdk Install OpenStack SDK

Imports

• openstack

  import openstack

  This is the primary and recommended import for accessing the SDK's functionality, including connection management and service proxies.
• Connection

  from openstack import connection

  While technically possible, direct import of `Connection` is less common. The `openstack.connect()` factory function is the idiomatic way to create a connection instance, returning a `Connection` object.
• Server

  conn.compute.servers()

  Directly using `Resource` classes from submodules like `openstack.compute.v2.server` is a lower-level pattern. The recommended approach is to use the service proxies available through the `Connection` object (e.g., `conn.compute.servers()`) for higher-level operations.

Quickstart

This quickstart demonstrates how to establish a connection to an OpenStack cloud, list images and flavors, and then optionally create and delete a compute instance (server). It uses environment variables for authentication and resource naming for simplicity. For production, `clouds.yaml` is recommended. Ensure `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, and optionally `OS_CLOUD` are set in your environment, along with `OS_TEST_IMAGE`, `OS_TEST_FLAVOR`, `OS_TEST_NETWORK`, and `OS_TEST_KEYPAIR` for server creation.

import os
import openstack
import time

# Configure connection via environment variables for a quickstart
# In a real application, consider using a clouds.yaml file for more robust configuration.
# Example: export OS_CLOUD='devstack' or set individual OS_ prefixed variables.
# You can also pass auth parameters directly to openstack.connect()

# Initialize and turn on debug logging (optional, but useful for troubleshooting)
openstack.enable_logging(debug=True)

try:
    # Establish a connection to your OpenStack cloud
    # 'envvars' tells openstacksdk to look for OS_CLOUD or individual OS_ prefixed environment variables
    conn = openstack.connect(cloud='envvars')

    print("Successfully connected to OpenStack!")

    # List available images
    print("\nAvailable images:")
    for image in conn.image.images():
        print(f"  ID: {image.id}, Name: {image.name}")

    # List available flavors (instance types)
    print("\nAvailable flavors:")
    for flavor in conn.compute.flavors():
        print(f"  ID: {flavor.id}, Name: {flavor.name}, RAM: {flavor.ram}MB, VCPUs: {flavor.vcpus}")

    # --- Example: Create a new server (instance) --- 
    # Requires an existing image, flavor, network, and keypair in your OpenStack cloud.
    # Replace with actual values from your environment or obtained from the above listings.
    IMAGE_NAME = os.environ.get('OS_TEST_IMAGE', 'cirros')
    FLAVOR_NAME = os.environ.get('OS_TEST_FLAVOR', 'm1.tiny')
    NETWORK_NAME = os.environ.get('OS_TEST_NETWORK', 'private') # Or 'public' if applicable
    KEYPAIR_NAME = os.environ.get('OS_TEST_KEYPAIR', 'my_keypair')
    SERVER_NAME = f"test-sdk-server-{int(time.time())}"

    # Find the image, flavor, and network by name
    image = conn.image.find_image(IMAGE_NAME)
    flavor = conn.compute.find_flavor(FLAVOR_NAME)
    network = conn.network.find_network(NETWORK_NAME)
    keypair = conn.compute.find_keypair(KEYPAIR_NAME)

    if not all([image, flavor, network, keypair]):
        print("\nError: One or more required resources (image, flavor, network, keypair) not found. Skipping server creation.")
    else:
        print(f"\nCreating server '{SERVER_NAME}'...")
        server = conn.compute.create_server(
            name=SERVER_NAME,
            image_id=image.id,
            flavor_id=flavor.id,
            networks=[{"uuid": network.id}],
            key_name=keypair.name
        )
        print(f"Server '{SERVER_NAME}' created (ID: {server.id}). Waiting for active status...")
        conn.compute.wait_for_server(server)
        print(f"Server '{SERVER_NAME}' is now {server.status}.")
        print(f"Access IPv4: {getattr(server, 'access_ipv4', 'N/A')}")

        # Cleanup: Delete the created server
        print(f"\nDeleting server '{SERVER_NAME}' (ID: {server.id})...")
        conn.compute.delete_server(server.id)
        conn.compute.wait_for_delete(server)
        print(f"Server '{SERVER_NAME}' deleted.")

except openstack.exceptions.SDKException as e:
    print(f"An OpenStack SDK error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")