# Couchbase Infrastructure
A Python CLI tool and library for automating Couchbase Capella infrastructure setup, including projects, clusters, databases, and AI models.
## Features
- 🚀 **One-Command Setup**: Deploy complete Capella infrastructure with a single command
- 🔧 **CLI & Library**: Use as a command-line tool or import as a Python library
- 🤖 **AI Model Support**: Automated deployment of embedding and LLM models
- 📦 **Sample Data Loading**: Automatically load sample datasets like travel-sample
- 🔐 **Credential Management**: Secure API key and database user management
- ⚙️ **Configurable**: Customize via environment variables or config files
- 🎨 **Rich Output**: Beautiful CLI with progress indicators and colored output
## Installation
### From PyPI
```bash
pip install couchbase-infrastructure
```
### From Source
```bash
git clone https://github.com/couchbase/couchbase-infrastructure.git
cd couchbase-infrastructure
pip install -e .
```
## Prerequisites
Before using this tool, you need:
1. **Couchbase Capella Account**: Sign up at [cloud.couchbase.com](https://cloud.couchbase.com)
2. **Management API Key**: Generate from Capella Console → Settings → API Keys
- Required permissions: Organization Admin
3. **Organization ID** (optional, will auto-detect if not provided)
### Get Your Management API Key
1. Log in to Couchbase Capella Console
2. Navigate to Settings → API Keys
3. Create a new API key with Organization Admin permissions
4. Add your current IP address to the allowlist
5. Copy the API key (you'll only see it once!)
## Quick Start
### 1. Set Environment Variables
Create a `.env` file:
```bash
# Required
MANAGEMENT_API_KEY=your_api_key_here
# Optional (will auto-detect if not provided)
ORGANIZATION_ID=your_org_id_here
# Optional customizations
PROJECT_NAME=agent-app
CLUSTER_NAME=agent-app-cluster
DB_USERNAME=agent_app_user
EMBEDDING_MODEL_NAME=nvidia/nv-embedqa-mistral-7b-v2
LLM_MODEL_NAME=meta/llama3-8b-instruct
```
### 2. Run Full Setup
```bash
couchbase-infra setup --env-file .env
```
This will:
1. ✅ Create or find a Capella project
2. ✅ Deploy a free tier cluster
3. ✅ Configure network access (allowlist)
4. ✅ Load travel-sample dataset
5. ✅ Create database credentials
6. ✅ Deploy embedding and LLM models
7. ✅ Create API key for models
## CLI Usage
### Test Connection
Test your API credentials:
```bash
couchbase-infra test-connection --env-file .env
```
### Full Setup
Deploy complete infrastructure:
```bash
# Basic setup
couchbase-infra setup --env-file .env
# Skip AI model deployment
couchbase-infra setup --env-file .env --skip-models
# Skip sample data loading
couchbase-infra setup --env-file .env --skip-sample-data
# Set custom timeout (in seconds)
couchbase-infra setup --env-file .env --timeout 3600
```
### List Resources
```bash
# List all projects
couchbase-infra list-projects
# List all clusters
couchbase-infra list-clusters
```
### Get Help
```bash
# General help
couchbase-infra --help
# Command-specific help
couchbase-infra setup --help
```
## Programmatic Usage
Use as a Python library in your own scripts:
```python
from couchbase_infrastructure import (
CapellaClient,
CapellaConfig,
create_project,
create_cluster,
deploy_ai_model,
)
# Load configuration from environment
config = CapellaConfig.from_env(".env")
# Initialize client
client = CapellaClient(config)
org_id = client.get_organization_id()
# Test connection
if client.test_connection(org_id):
print("Connected successfully!")
# Create project
project_id = create_project(client, org_id, "My Project")
# Create cluster
cluster_id = create_cluster(client, org_id, project_id, "my-app-cluster", config)
# Deploy AI model
model_id = deploy_ai_model(
client,
org_id,
"nvidia/nv-embedqa-mistral-7b-v2",
"my-embedding-model",
"embedding",
config,
)
```
## Configuration Options
All options can be set via environment variables:
### Required
- `MANAGEMENT_API_KEY`: Your Capella Management API key
### Optional
- `ORGANIZATION_ID`: Organization ID (auto-detected if not provided)
- `API_BASE_URL`: API base URL (default: cloudapi.cloud.couchbase.com)
### Project & Cluster
- `PROJECT_NAME`: Project name (default: agent-app)
- `CLUSTER_NAME`: Cluster name (default: agent-app-cluster)
- `CLUSTER_CLOUD_PROVIDER`: Cloud provider (default: aws)
- `CLUSTER_REGION: AWS region (default: us-east-2)
- `CLUSTER_CIDR`: CIDR block (default: 10.1.30.0/23)
### Database
- `DB_USERNAME`: Database username (default: agent_app_user)
- `SAMPLE_BUCKET`: Sample bucket name (default: travel-sample)
### AI Models
- `EMBEDDING_MODEL_NAME`: Embedding model (default: nvidia/nv-embedqa-mistral-7b-v2)
- `LLM_MODEL_NAME`: LLM model (default: meta/llama3-8b-instruct)
- `AI_MODEL_REGION`: AI model region (default: us-east-1)
- `EMBEDDING_MODEL_CPU`: Embedding CPU cores (default: 4)
- `EMBEDDING_MODEL_GPU_MEMORY`: Embedding GPU memory GB (default: 48)
- `LLM_MODEL_CPU`: LLM CPU cores (default: 4)
- `LLM_MODEL_GPU_MEMORY`: LLM GPU memory GB (default: 48)
### Network & Timeouts
- `ALLOWED_CIDR`: Allowed CIDR for cluster access (default: 0.0.0.0/0)
- `RESOURCE_TIMEOUT`: Timeout in seconds (default: no timeout)
## Model Compute Sizes
Available compute sizes for AI models:
| Size | CPU (vCPUs) | GPU Memory (GB) |
|------|-------------|-----------------|
| Extra Small | 4 | 24 |
| Small | 4 | 48 |
| Medium | 48 | 192 |
| Large | 192 | 320 |
| Extra Large | 192 | 640 |
Note: Extra Large may not be available in sandbox environments.
## Troubleshooting
### Authentication Failed (401)
1. Verify your API key is correct and not expired
2. Check if your current IP is in the API key allowlist
3. Ensure the API key has Organization Admin permissions
Get your current IP:
```bash
curl -s https://api.ipify.org
```
### Free Tier Cluster Already Exists
Capella free tier allows only one cluster. The tool will automatically detect and use the existing cluster.
### Timeout Issues
For slower provisioning, increase the timeout:
```bash
couchbase-infra setup --timeout 7200 # 2 hours
```
Or remove timeout completely (wait indefinitely) by not setting the `--timeout` flag.
### Connection Issues
Test your connection first:
```bash
couchbase-infra test-connection
```
## Development
### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/couchbase/couchbase-infrastructure.git
cd couchbase-infrastructure
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black couchbase_infrastructure/
ruff check couchbase_infrastructure/
# Type check
mypy couchbase_infrastructure/
```
### Project Structure
```
couchbase-infrastructure/
├── couchbase_infrastructure/
│ ├── __init__.py # Package initialization
│ ├── cli.py # CLI interface
│ ├── client.py # API client
│ ├── config.py # Configuration
│ └── resources.py # Resource management
├── tests/ # Unit tests
├── pyproject.toml # Package metadata
└── README.md # Documentation
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
Apache License 2.0. See [LICENSE](LICENSE) for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/couchbase/couchbase-infrastructure/issues)
- **Documentation**: [Couchbase Capella Docs](https://docs.couchbase.com/cloud/)
- **Community**: [Couchbase Forums](https://forums.couchbase.com/)
## Related Projects
- [Couchbase Python SDK](https://github.com/couchbase/couchbase-python-client)
- [Agent Catalog](https://github.com/couchbaselabs/agent-catalog)
- [Capella Management API](https://docs.couchbase.com/cloud/management-api-guide/)
## Changelog
### 0.1.0 (2024-10-15)
- Initial release
- Full infrastructure automation
- CLI and library support
- AI model deployment
- Sample data loading
Raw data
{
"_id": null,
"home_page": null,
"name": "couchbase-infrastructure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "couchbase, capella, infrastructure, automation, cli",
"author": null,
"author_email": "Couchbase <support@couchbase.com>",
"download_url": "https://files.pythonhosted.org/packages/08/b2/d857a0e098775afe586e73f40a462b978ca2bfe985e3e2c62b52d679c068/couchbase_infrastructure-0.1.20.tar.gz",
"platform": null,
"description": "# Couchbase Infrastructure\n\nA Python CLI tool and library for automating Couchbase Capella infrastructure setup, including projects, clusters, databases, and AI models.\n\n## Features\n\n- \ud83d\ude80 **One-Command Setup**: Deploy complete Capella infrastructure with a single command\n- \ud83d\udd27 **CLI & Library**: Use as a command-line tool or import as a Python library\n- \ud83e\udd16 **AI Model Support**: Automated deployment of embedding and LLM models\n- \ud83d\udce6 **Sample Data Loading**: Automatically load sample datasets like travel-sample\n- \ud83d\udd10 **Credential Management**: Secure API key and database user management\n- \u2699\ufe0f **Configurable**: Customize via environment variables or config files\n- \ud83c\udfa8 **Rich Output**: Beautiful CLI with progress indicators and colored output\n\n## Installation\n\n### From PyPI\n\n```bash\npip install couchbase-infrastructure\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/couchbase/couchbase-infrastructure.git\ncd couchbase-infrastructure\npip install -e .\n```\n\n## Prerequisites\n\nBefore using this tool, you need:\n\n1. **Couchbase Capella Account**: Sign up at [cloud.couchbase.com](https://cloud.couchbase.com)\n2. **Management API Key**: Generate from Capella Console \u2192 Settings \u2192 API Keys\n - Required permissions: Organization Admin\n3. **Organization ID** (optional, will auto-detect if not provided)\n\n### Get Your Management API Key\n\n1. Log in to Couchbase Capella Console\n2. Navigate to Settings \u2192 API Keys\n3. Create a new API key with Organization Admin permissions\n4. Add your current IP address to the allowlist\n5. Copy the API key (you'll only see it once!)\n\n## Quick Start\n\n### 1. Set Environment Variables\n\nCreate a `.env` file:\n\n```bash\n# Required\nMANAGEMENT_API_KEY=your_api_key_here\n\n# Optional (will auto-detect if not provided)\nORGANIZATION_ID=your_org_id_here\n\n# Optional customizations\nPROJECT_NAME=agent-app\nCLUSTER_NAME=agent-app-cluster\nDB_USERNAME=agent_app_user\nEMBEDDING_MODEL_NAME=nvidia/nv-embedqa-mistral-7b-v2\nLLM_MODEL_NAME=meta/llama3-8b-instruct\n```\n\n### 2. Run Full Setup\n\n```bash\ncouchbase-infra setup --env-file .env\n```\n\nThis will:\n1. \u2705 Create or find a Capella project\n2. \u2705 Deploy a free tier cluster\n3. \u2705 Configure network access (allowlist)\n4. \u2705 Load travel-sample dataset\n5. \u2705 Create database credentials\n6. \u2705 Deploy embedding and LLM models\n7. \u2705 Create API key for models\n\n## CLI Usage\n\n### Test Connection\n\nTest your API credentials:\n\n```bash\ncouchbase-infra test-connection --env-file .env\n```\n\n### Full Setup\n\nDeploy complete infrastructure:\n\n```bash\n# Basic setup\ncouchbase-infra setup --env-file .env\n\n# Skip AI model deployment\ncouchbase-infra setup --env-file .env --skip-models\n\n# Skip sample data loading\ncouchbase-infra setup --env-file .env --skip-sample-data\n\n# Set custom timeout (in seconds)\ncouchbase-infra setup --env-file .env --timeout 3600\n```\n\n### List Resources\n\n```bash\n# List all projects\ncouchbase-infra list-projects\n\n# List all clusters\ncouchbase-infra list-clusters\n```\n\n### Get Help\n\n```bash\n# General help\ncouchbase-infra --help\n\n# Command-specific help\ncouchbase-infra setup --help\n```\n\n## Programmatic Usage\n\nUse as a Python library in your own scripts:\n\n```python\nfrom couchbase_infrastructure import (\n CapellaClient,\n CapellaConfig,\n create_project,\n create_cluster,\n deploy_ai_model,\n)\n\n# Load configuration from environment\nconfig = CapellaConfig.from_env(\".env\")\n\n# Initialize client\nclient = CapellaClient(config)\norg_id = client.get_organization_id()\n\n# Test connection\nif client.test_connection(org_id):\n print(\"Connected successfully!\")\n\n# Create project\nproject_id = create_project(client, org_id, \"My Project\")\n\n# Create cluster\ncluster_id = create_cluster(client, org_id, project_id, \"my-app-cluster\", config)\n\n# Deploy AI model\nmodel_id = deploy_ai_model(\n client,\n org_id,\n \"nvidia/nv-embedqa-mistral-7b-v2\",\n \"my-embedding-model\",\n \"embedding\",\n config,\n)\n```\n\n## Configuration Options\n\nAll options can be set via environment variables:\n\n### Required\n- `MANAGEMENT_API_KEY`: Your Capella Management API key\n\n### Optional\n- `ORGANIZATION_ID`: Organization ID (auto-detected if not provided)\n- `API_BASE_URL`: API base URL (default: cloudapi.cloud.couchbase.com)\n\n### Project & Cluster\n- `PROJECT_NAME`: Project name (default: agent-app)\n- `CLUSTER_NAME`: Cluster name (default: agent-app-cluster)\n- `CLUSTER_CLOUD_PROVIDER`: Cloud provider (default: aws)\n- `CLUSTER_REGION: AWS region (default: us-east-2)\n- `CLUSTER_CIDR`: CIDR block (default: 10.1.30.0/23)\n\n### Database\n- `DB_USERNAME`: Database username (default: agent_app_user)\n- `SAMPLE_BUCKET`: Sample bucket name (default: travel-sample)\n\n### AI Models\n- `EMBEDDING_MODEL_NAME`: Embedding model (default: nvidia/nv-embedqa-mistral-7b-v2)\n- `LLM_MODEL_NAME`: LLM model (default: meta/llama3-8b-instruct)\n- `AI_MODEL_REGION`: AI model region (default: us-east-1)\n- `EMBEDDING_MODEL_CPU`: Embedding CPU cores (default: 4)\n- `EMBEDDING_MODEL_GPU_MEMORY`: Embedding GPU memory GB (default: 48)\n- `LLM_MODEL_CPU`: LLM CPU cores (default: 4)\n- `LLM_MODEL_GPU_MEMORY`: LLM GPU memory GB (default: 48)\n\n### Network & Timeouts\n- `ALLOWED_CIDR`: Allowed CIDR for cluster access (default: 0.0.0.0/0)\n- `RESOURCE_TIMEOUT`: Timeout in seconds (default: no timeout)\n\n## Model Compute Sizes\n\nAvailable compute sizes for AI models:\n\n| Size | CPU (vCPUs) | GPU Memory (GB) |\n|------|-------------|-----------------|\n| Extra Small | 4 | 24 |\n| Small | 4 | 48 |\n| Medium | 48 | 192 |\n| Large | 192 | 320 |\n| Extra Large | 192 | 640 |\n\nNote: Extra Large may not be available in sandbox environments.\n\n## Troubleshooting\n\n### Authentication Failed (401)\n\n1. Verify your API key is correct and not expired\n2. Check if your current IP is in the API key allowlist\n3. Ensure the API key has Organization Admin permissions\n\nGet your current IP:\n```bash\ncurl -s https://api.ipify.org\n```\n\n### Free Tier Cluster Already Exists\n\nCapella free tier allows only one cluster. The tool will automatically detect and use the existing cluster.\n\n### Timeout Issues\n\nFor slower provisioning, increase the timeout:\n```bash\ncouchbase-infra setup --timeout 7200 # 2 hours\n```\n\nOr remove timeout completely (wait indefinitely) by not setting the `--timeout` flag.\n\n### Connection Issues\n\nTest your connection first:\n```bash\ncouchbase-infra test-connection\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/couchbase/couchbase-infrastructure.git\ncd couchbase-infrastructure\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack couchbase_infrastructure/\nruff check couchbase_infrastructure/\n\n# Type check\nmypy couchbase_infrastructure/\n```\n\n### Project Structure\n\n```\ncouchbase-infrastructure/\n\u251c\u2500\u2500 couchbase_infrastructure/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # CLI interface\n\u2502 \u251c\u2500\u2500 client.py # API client\n\u2502 \u251c\u2500\u2500 config.py # Configuration\n\u2502 \u2514\u2500\u2500 resources.py # Resource management\n\u251c\u2500\u2500 tests/ # Unit tests\n\u251c\u2500\u2500 pyproject.toml # Package metadata\n\u2514\u2500\u2500 README.md # Documentation\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/couchbase/couchbase-infrastructure/issues)\n- **Documentation**: [Couchbase Capella Docs](https://docs.couchbase.com/cloud/)\n- **Community**: [Couchbase Forums](https://forums.couchbase.com/)\n\n## Related Projects\n\n- [Couchbase Python SDK](https://github.com/couchbase/couchbase-python-client)\n- [Agent Catalog](https://github.com/couchbaselabs/agent-catalog)\n- [Capella Management API](https://docs.couchbase.com/cloud/management-api-guide/)\n\n## Changelog\n\n### 0.1.0 (2024-10-15)\n\n- Initial release\n- Full infrastructure automation\n- CLI and library support\n- AI model deployment\n- Sample data loading\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CLI tool and Python library for automating Couchbase Capella infrastructure setup",
"version": "0.1.20",
"project_urls": {
"Bug Tracker": "https://github.com/couchbase/couchbase-infrastructure/issues",
"Documentation": "https://github.com/couchbase/couchbase-infrastructure#readme",
"Homepage": "https://github.com/couchbase/couchbase-infrastructure",
"Repository": "https://github.com/couchbase/couchbase-infrastructure"
},
"split_keywords": [
"couchbase",
" capella",
" infrastructure",
" automation",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0f76ee92ff86b7876be07bb5250f832c232690e8fe7cd9bf3a3569eda5321ef8",
"md5": "e8ad10693bc2608cd0130cba35d53042",
"sha256": "88ee265111ed2f2631a6e6a210ea6eb2ba3bea13d744932ad473ff21c11d4920"
},
"downloads": -1,
"filename": "couchbase_infrastructure-0.1.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8ad10693bc2608cd0130cba35d53042",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21722,
"upload_time": "2025-10-23T00:45:17",
"upload_time_iso_8601": "2025-10-23T00:45:17.906169Z",
"url": "https://files.pythonhosted.org/packages/0f/76/ee92ff86b7876be07bb5250f832c232690e8fe7cd9bf3a3569eda5321ef8/couchbase_infrastructure-0.1.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "08b2d857a0e098775afe586e73f40a462b978ca2bfe985e3e2c62b52d679c068",
"md5": "5bf5f89ead3c0ea153fefcd70ca5e733",
"sha256": "491c18164e8fa97d706d72a569a1a53c03077d8b150ba0411d6d61fe6e97e874"
},
"downloads": -1,
"filename": "couchbase_infrastructure-0.1.20.tar.gz",
"has_sig": false,
"md5_digest": "5bf5f89ead3c0ea153fefcd70ca5e733",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22010,
"upload_time": "2025-10-23T00:45:19",
"upload_time_iso_8601": "2025-10-23T00:45:19.226037Z",
"url": "https://files.pythonhosted.org/packages/08/b2/d857a0e098775afe586e73f40a462b978ca2bfe985e3e2c62b52d679c068/couchbase_infrastructure-0.1.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 00:45:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "couchbase",
"github_project": "couchbase-infrastructure",
"github_not_found": true,
"lcname": "couchbase-infrastructure"
}
JSON
