Skip to main content

How to create and configure an Infrahub client

This guide shows you how to create and configure an Infrahub client using the Python SDK. You'll learn how to set up authentication, configure proxy settings, and customize client behavior for your infrastructure automation workflows.

At the end of this guide, you'll have a fully configured client ready to interact with your Infrahub instance.

TL;DR;

If you prefer to jump right in, check out the "Hello World" example at the end of this guide for a quick reference implementation.

Prerequisites​

  • Python 3.9 or higher
  • Infrahub SDK installed (pip install infrahub-sdk or uv add infrahub-sdk)
  • Access to an Infrahub instance (local or remote)
  • Valid credentials (API token or username/password) if authentication is required

Step 1: Create a client instance​

Asynchronous vs. Synchronous Clients

The SDK offers both asynchronous and synchronous client implementations. Choose the one that best fits your application architecture:

  • Asynchronous client (InfrahubClient): Ideal for modern async applications using Python's async/await syntax
  • Synchronous client (InfrahubClientSync): Better for traditional synchronous workflows or scripts

Create an InfrahubClient for async/await workflows:

from infrahub_sdk import InfrahubClient

# Connect to local Infrahub instance
client = InfrahubClient()

Step 2: Configure authentication and address​

Next, configure the address of your Infrahub instance and set up authentication credentials. Infrahub supports two authentication methods: API tokens and username/password.

Configuration Methods

You can configure the client in two ways:

  1. Environment variables: Ideal for sensitive information
  2. Config object: Better for explicit configuration in code

You can also combine both methods, where the Config object takes precedence over environment variables.

You can find the full list of configuration options in the SDK configuration reference.

Using API tokens​

API tokens provide secure, long-lived authentication and are the recommended method for most use cases, especially for automation scripts and non-interactive applications.

We can set the address and API token directly in the Config object:

from infrahub_sdk import Config, InfrahubClient
client = InfrahubClient(config=Config(address="http://localhost:8000", api_token="token"))

Using username/password​

For interactive authentication, use username and password. The SDK automatically handles JWT token generation and refresh.

We can set the address, username and password directly in the Config object:

from infrahub_sdk import Config, InfrahubClient
client = InfrahubClient(config=Config(address="http://localhost:8000", username="admin", password="infrahub"))
success

Your client is now configured and ready to use!

Step 3: Set the default branch (optional)​

Configure your client to work with a specific Infrahub branch instead of the default main branch. This is particularly useful when working on feature branches or experimental changes, as it eliminates the need to specify the branch name in every method call.

from infrahub_sdk import InfrahubClient, Config
config = Config(address="http://localhost:8000", api_token="token", default_branch="other-branch")
client_other_branch = InfrahubClient(config=config)

tag_other_branch = await client_other_branch.get(kind="BuiltinTag", name__value="RED")
tag_main_branch = await client_other_branch.get(kind="BuiltinTag", name__value="RED", branch="main")
Branch Configuration

Your client is now configured to use the specified default branch instead of main. Remember that you can always override this setting by explicitly passing the branch argument to any method call.

Hello world example​

Let's create a simple "Hello World" example to verify your client configuration works correctly. This example will connect to your Infrahub instance and query the available accounts.

  1. Create a new file called hello_world.py:
touch hello_world.py
File Naming

Avoid naming your script test.py as this name could conflict with Python's testing modules.

  1. Add the following code to hello_world.py:
import asyncio

from infrahub_sdk import Config, InfrahubClient


async def hello_world():
    client = InfrahubClient(config=Config(address="http://localhost:8000"))

    # Try to query accounts to validate connection
    try:
        accounts = await client.all(kind="CoreAccount")
        print(f"Successfully connected to Infrahub! Found {len(accounts)} account(s)")
    except Exception as e:
        print(f"Something went wrong: {e}")


asyncio.run(hello_world())
  1. Export the necessary environment variables:
export INFRAHUB_API_TOKEN="06438eb2-8019-4776-878c-0941b1f1d1ec" # This is the default token
  1. Run the script:
python hello_world.py

If everything is configured correctly, you should see:

success

Successfully connected to Infrahub! Found 1 account(s)

Advanced use cases​

Enable debug logging​

When developing or troubleshooting, you can enable GraphQL query logging to see exactly what requests are being sent to Infrahub:

from infrahub_sdk import Config, InfrahubClient
config = Config(echo_graphql_queries=True)
client = InfrahubClient(config=config)

Configure proxy settings​

When operating in environments with restricted network access or behind corporate firewalls, you can configure the client to route requests through HTTP/HTTPS proxies.

Single proxy for all requests​

To route all traffic through the same proxy server, use the INFRAHUB_PROXY environment variable or the proxy configuration parameter:

from infrahub_sdk import Config, InfrahubClient
config = Config(proxy="http://proxy.example.com:8080")
client = InfrahubClient(config=config)

# Or using environment variable
# export INFRAHUB_PROXY=http://proxy.example.com:8080
client = InfrahubClient()

Separate proxies for HTTP and HTTPS​

In some network environments, you might need to route HTTP and HTTPS traffic through different proxy servers. Use the INFRAHUB_PROXY_MOUNTS_HTTP and INFRAHUB_PROXY_MOUNTS_HTTPS environment variables for this purpose:

export INFRAHUB_PROXY_MOUNTS_HTTP=http://http-proxy.example.com:8080
export INFRAHUB_PROXY_MOUNTS_HTTPS=http://https-proxy.example.com:8080
from infrahub_sdk import InfrahubClient
# Proxy configuration is read from environment variables
client = InfrahubClient()
Using both proxy and proxy_mounts

The proxy and proxy_mounts configurations are mutually exclusive and cannot be used together. Specifying both will cause a ValueError to be raised when the client is initialized.

Next steps​

Now that you have a fully configured Infrahub client, you're ready to start working with your infrastructure data. Here's what you can explore next: