Environments API

The Environments API is the core of the Blueberry IDP, providing endpoints for creating, managing, and monitoring ephemeral environments.

Overview

Environments are temporary, isolated instances of your applications that can be created for testing, development, or review purposes. Each environment:

• Has a unique ID and name
• Runs in its own Kubernetes namespace
• Has configurable TTL (time-to-live)
• Supports multiple application repositories
• Provides real-time status monitoring

Authentication

All environment endpoints require authentication:
- Firebase ID Token: For web UI access
- API Token with ENV_CREATE scope: For CI/CD integration

Endpoints

Create Environment

Create a new ephemeral environment.

POST /api/environments

Request Body

Form Data (for web UI):

Content-Type: application/x-www-form-urlencoded

environment_name=pr-123&
backend_repo=sample-be-1&
backend_branch=main&
backend_commit=abc123&
frontend_repo=sample-fe-1&
frontend_branch=main&
frontend_commit=def456&
ttl=24&
provision_database=true&
auto_generate_secrets=true&
use_shared_api_keys=false&
config_set=default

JSON (for API):

{
  "environment_name": "pr-123",
  "backend_repo": "sample-be-1",
  "backend_branch": "main",
  "backend_commit": "abc123",
  "frontend_repo": "sample-fe-1",
  "frontend_branch": "main",
  "frontend_commit": "def456",
  "ttl": 24,
  "provision_database": true,
  "auto_generate_secrets": true,
  "use_shared_api_keys": false,
  "config_set": "default"
}

Parameters

Response

Success (200):

{
  "status": "success",
  "environment": {
    "id": "dcf85a2b-8e5c-4d3a-9f1b-2c3d4e5f6789",
    "name": "pr-123",
    "status": "creating",
    "urls": {
      "backend": "https://pr-123-backend.ephemeral.blueberry.florenciacomuzzi.com",
      "frontend": "https://pr-123-frontend.ephemeral.blueberry.florenciacomuzzi.com"
    },
    "created_at": "2024-01-01T10:00:00Z",
    "expires_at": "2024-01-02T10:00:00Z",
    "ttl_hours": 24
  }
}

Error (400):

{
  "detail": "Environment name already exists",
  "status_code": 400
}

List Environments

Get a list of all environments accessible to the current user.

GET /api/environments

Query Parameters

Example Request

curl -H "Authorization: Bearer <token>" \
  "https://blueberry.florenciacomuzzi.com/api/environments?status=ready&limit=10"

Response

{
  "environments": [
    {
      "id": "dcf85a2b-8e5c-4d3a-9f1b-2c3d4e5f6789",
      "name": "pr-123",
      "status": "ready",
      "urls": {
        "backend": "https://pr-123-backend.ephemeral.blueberry.florenciacomuzzi.com",
        "frontend": "https://pr-123-frontend.ephemeral.blueberry.florenciacomuzzi.com"
      },
      "created_at": "2024-01-01T10:00:00Z",
      "expires_at": "2024-01-02T10:00:00Z",
      "creator": {
        "email": "developer@example.com",
        "name": "John Developer"
      }
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get Environment

Get detailed information about a specific environment.

GET /api/environments/{environment_id}

Path Parameters

Response

{
  "id": "dcf85a2b-8e5c-4d3a-9f1b-2c3d4e5f6789",
  "name": "pr-123",
  "status": "ready",
  "urls": {
    "backend": "https://pr-123-backend.ephemeral.blueberry.florenciacomuzzi.com",
    "frontend": "https://pr-123-frontend.ephemeral.blueberry.florenciacomuzzi.com"
  },
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:15:00Z",
  "expires_at": "2024-01-02T10:00:00Z",
  "ttl_hours": 24,
  "creator": {
    "email": "developer@example.com",
    "name": "John Developer"
  },
  "repositories": {
    "backend": {
      "repo": "sample-be-1",
      "branch": "main",
      "commit": "abc123def456"
    },
    "frontend": {
      "repo": "sample-fe-1",
      "branch": "feature/new-ui",
      "commit": "def456abc123"
    }
  },
  "kubernetes": {
    "namespace": "pr-123",
    "argocd_app": "env-pr-123"
  },
  "configuration": {
    "config_set": "default",
    "database_provisioned": true,
    "auto_generated_secrets": true
  }
}

Update Environment

Update environment configuration or extend TTL.

PUT /api/environments/{environment_id}

Request Body

{
  "ttl_hours": 48,
  "description": "Extended for additional testing"
}

Parameters

Response

{
  "status": "success",
  "environment": {
    "id": "dcf85a2b-8e5c-4d3a-9f1b-2c3d4e5f6789",
    "expires_at": "2024-01-03T10:00:00Z",
    "ttl_hours": 48
  }
}

Delete Environment

Delete an environment and clean up all resources.

DELETE /api/environments/{environment_id}

Response

Success (200):

{
  "status": "success",
  "message": "Environment deletion initiated"
}

Not Found (404):

{
  "detail": "Environment not found",
  "status_code": 404
}

Reconcile Environment Status

Force a status reconciliation for an environment.

POST /api/environments/{environment_id}/reconcile-status

Response

{
  "status": "success",
  "message": "Status reconciliation initiated"
}

Get Environment Logs

Get logs for environment components.

GET /api/environments/{environment_id}/logs/{component}

Path Parameters

Query Parameters

Response

{
  "component": "backend",
  "logs": [
    {
      "timestamp": "2024-01-01T10:00:00Z",
      "level": "INFO",
      "message": "Application started successfully"
    }
  ],
  "total_lines": 1
}

Check Environment Health

Check the health status of environment URLs.

GET /api/environments/{environment_id}/check-all-urls

Response

{
  "environment_id": "dcf85a2b-8e5c-4d3a-9f1b-2c3d4e5f6789",
  "status": "healthy",
  "details": {
    "backend": {
      "url": "https://pr-123-backend.ephemeral.blueberry.florenciacomuzzi.com",
      "status": "healthy",
      "response_time_ms": 120
    },
    "frontend": {
      "url": "https://pr-123-frontend.ephemeral.blueberry.florenciacomuzzi.com",
      "status": "healthy",
      "response_time_ms": 95
    }
  },
  "checked_at": "2024-01-01T10:30:00Z"
}

Environment States

Error Codes

Examples

Create Environment with CI/CD

#!/bin/bash
# CI/CD script to create environment

ENVIRONMENT_NAME="pr-${CI_MERGE_REQUEST_IID}"
BACKEND_COMMIT="${CI_COMMIT_SHA}"

curl -X POST "https://blueberry.florenciacomuzzi.com/api/environments" \
  -H "Authorization: Bearer ${BLUEBERRY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"environment_name\": \"${ENVIRONMENT_NAME}\",
    \"backend_repo\": \"sample-be-1\",
    \"backend_branch\": \"${CI_COMMIT_REF_NAME}\",
    \"backend_commit\": \"${BACKEND_COMMIT}\",
    \"ttl\": 48
  }"

Monitor Environment Status

import requests
import time

def wait_for_environment_ready(env_id, token, timeout=600):
    """Wait for environment to be ready."""
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(
            f"https://blueberry.florenciacomuzzi.com/api/environments/{env_id}",
            headers={"Authorization": f"Bearer {token}"}
        )

        if response.status_code == 200:
            env = response.json()
            if env['status'] == 'ready':
                return env
            elif env['status'] == 'failed':
                raise Exception("Environment creation failed")

        time.sleep(30)  # Check every 30 seconds

    raise TimeoutError("Environment not ready within timeout")

Clean Up Failed Environments

# Clean up all failed environments
curl -X POST "https://blueberry.florenciacomuzzi.com/api/environments/cleanup-failed" \
  -H "Authorization: Bearer ${BLUEBERRY_API_TOKEN}"

Related Documentation

• Environment Lifecycle Workflow
• Configuration Sets
• Repository Management
• Troubleshooting Environments

Last Updated: January 2024