Cerberus Python Client

Warnings

• breaking The official GitHub repository for `cerberus-python-client` (Nike-Inc/cerberus-python-client) was archived by its owner on January 12, 2024, and is now read-only. This indicates that active development and maintenance have ceased. While existing versions remain available on PyPI, no new features, bug fixes, or official support are expected.
  Fix: Be aware that the library is no longer actively maintained. For critical projects, consider the implications of using an unmaintained library or explore alternative secret management solutions.
• gotcha This library (`cerberus-python-client`) is distinct from the general-purpose Python data validation library `Cerberus`. They share a similar name but serve entirely different purposes. Importing or referring to the wrong library can lead to unexpected errors.
  Fix: Always use `pip install cerberus-python-client` for the client library and `from cerberus.client import CerberusClient`. For the data validation library, use `pip install Cerberus` and `from cerberus import Validator`.
• gotcha When uploading files to Cerberus, ensure that the file is opened in binary mode (`'rb'`). Failure to do so can result in incorrect size calculations and corrupted uploads.
  Fix: Always open files for upload using `with open('your_file.txt', 'rb') as f: ...`
• gotcha Cerberus is generally not recommended for storing secrets directly accessed by AWS Lambda functions, due to potential issues with scale (thousands of requests per second) and additional latency introduced by authentication and secret retrieval.
  Fix: For Lambda functions, consider using AWS Secrets Manager or Parameter Store for better integration, scale, and performance.
• gotcha Prior to version 2.5.2, users might encounter issues if the `cerberus_url` passed to `CerberusClient` had an inconsistent trailing slash. Version 2.5.2 introduced a fix to remove the trailing slash during initialization, making the client more robust to user input.
  Fix: Upgrade to `cerberus-python-client` version 2.5.2 or newer to automatically handle trailing slashes in the Cerberus URL. If using an older version, manually ensure the URL does not end with a trailing slash.

Install

• pip install cerberus-python-client Install latest version

Imports

• CerberusClient

  from cerberus.client import CerberusClient

Quickstart

This quickstart demonstrates how to initialize the `CerberusClient` using IAM Role or User authentication and then retrieve secrets and files. For IAM Role authentication, ensure the execution environment has the necessary AWS IAM permissions. For User authentication, set `CERBERUS_USERNAME` and `CERBERUS_PASSWORD` environment variables.

import os
from cerberus.client import CerberusClient

CERBERUS_URL = os.environ.get('CERBERUS_URL', 'https://cerberus.example.com')
# For local development, you might set these via environment variables or pass directly
CERBERUS_USERNAME = os.environ.get('CERBERUS_USERNAME', '')
CERBERUS_PASSWORD = os.environ.get('CERBERUS_PASSWORD', '')

try:
    # Example 1: IAM Role Authentication (typical for EC2, ECS, Lambda)
    # Requires appropriate IAM role attached to the execution environment
    client_iam = CerberusClient(CERBERUS_URL)
    print(f"IAM Client initialized: {client_iam.cerberus_url}")

    # Example 2: User Authentication (for local development or specific use cases)
    if CERBERUS_USERNAME and CERBERUS_PASSWORD:
        client_user = CerberusClient(CERBERUS_URL, CERBERUS_USERNAME, CERBERUS_PASSWORD)
        print(f"User Client initialized: {client_user.cerberus_url}")

    # Example: Reading a secret (replace with your actual secret path)
    secret_path = 'app/my-application/my-secret-key'
    try:
        secret_data = client_iam.get_secret(secret_path)
        print(f"Retrieved secret from {secret_path}: {secret_data}")
    except Exception as e:
        print(f"Error retrieving secret {secret_path}: {e}")

    # Example: Reading a file (replace with your actual file path)
    file_path = 'app/my-application/path/to/my-file.txt'
    try:
        file_content = client_iam.get_file(file_path)
        print(f"Retrieved file from {file_path}, content type: {type(file_content)}")
        # If it's text, you can decode:
        # print(f"File content: {file_content.decode('utf-8')}")
    except Exception as e:
        print(f"Error retrieving file {file_path}: {e}")

except Exception as e:
    print(f"Failed to initialize CerberusClient: {e}")
    print("Ensure CERBERUS_URL and appropriate authentication (IAM role or credentials) are configured.")