Create Ephemeral Environment

Overview

This workflow creates a new ephemeral environment in the Blueberry IDP for testing pull requests or feature branches. The environment is automatically provisioned with all required services and is accessible via a unique URL.

Prerequisites

• [ ] Access Requirements
• Valid Firebase authentication token
• Permission to create environments (default for authenticated users)

• Access to the target Git repository

• [ ] Tools and Software

• curl or httpie for API calls
• kubectl (optional, for verification)

• Web browser for UI access

• [ ] Knowledge Requirements

• Understanding of environment naming conventions
• Familiarity with Helm values structure
• Basic knowledge of Kubernetes namespaces

Steps

1. Authenticate with the API

Obtain a valid authentication token:

# Using the web UI
# 1. Navigate to https://blueberry.example.com
# 2. Click "Login" and authenticate
# 3. Go to Settings > API Tokens
# 4. Create or copy an existing token

# Set the token as an environment variable
export BLUEBERRY_TOKEN="your-token-here"

2. Prepare Environment Configuration

Create the environment request payload:

{
  "name": "pr-123",
  "ttl": "24h",
  "backend_image_tag": "latest",
  "git_commit_sha": "abc123def456",
  "config_set_id": "default-config",
  "pr_number": 123,
  "pr_branch": "feature/new-feature"
}

Note: The name must be unique and follow the pattern pr-{number} or a custom alphanumeric string.

3. Create the Environment

Submit the environment creation request:

curl -X POST https://blueberry.example.com/api/environments \
  -H "Authorization: Bearer $BLUEBERRY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pr-123",
    "ttl": "24h",
    "backend_image_tag": "latest",
    "git_commit_sha": "abc123def456"
  }'

Expected Response:

{
  "id": "env-abc123",
  "name": "pr-123",
  "namespace": "ephemeral-pr-123",
  "status": "creating",
  "url": "https://pr-123.dev.example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-16T10:30:00Z"
}

4. Monitor Environment Creation

Check the environment status:

# Via API
curl -X GET https://blueberry.example.com/api/environments/pr-123 \
  -H "Authorization: Bearer $BLUEBERRY_TOKEN"

# Via UI
# Navigate to https://blueberry.example.com/environments/pr-123

The environment will transition through these states:
- creating → provisioning → ready

5. Access the Environment

Once ready, access your environment:

# Get the environment URL
curl -X GET https://blueberry.example.com/api/environments/pr-123 \
  -H "Authorization: Bearer $BLUEBERRY_TOKEN" \
  | jq -r '.url'

# Open in browser
open https://pr-123.dev.example.com

Validation

After creation, verify the environment is working correctly:

1. Check ArgoCD Application
   bash kubectl get application -n argocd env-pr-123

2. Verify Namespace Resources
   bash kubectl get all -n ephemeral-pr-123

3. Test Application Endpoints
   bash curl https://pr-123.dev.example.com/health

4. Review Logs
   bash kubectl logs -n ephemeral-pr-123 -l app=backend --tail=50

Troubleshooting

Common Issues

Environment Stuck in Creating State

Symptoms:
- Status remains "creating" for more than 5 minutes
- No resources appear in Kubernetes

Cause:
ArgoCD application sync failed

Solution:

# Check ArgoCD application status
kubectl describe application -n argocd env-pr-123

# Force sync if needed
kubectl patch application -n argocd env-pr-123 --type merge -p '{"spec":{"syncPolicy":null}}'

DNS Not Resolving

Symptoms:
- Environment URL returns DNS lookup failure
- Ingress created but not accessible

Cause:
DNS propagation delay or missing DNS entry

Solution:
1. Wait 2-3 minutes for DNS propagation
2. Check ingress status:
bash kubectl get ingress -n ephemeral-pr-123
3. Verify DNS record in Cloud DNS

Pod Failures

Symptoms:
- Pods in CrashLoopBackOff
- Services not responding

Cause:
Configuration errors or missing secrets

Solution:

# Check pod logs
kubectl logs -n ephemeral-pr-123 [pod-name] --previous

# Verify secrets exist
kubectl get secrets -n ephemeral-pr-123

# Check resource limits
kubectl describe pod -n ephemeral-pr-123 [pod-name]

Debug Commands

# Full environment status
curl -X GET https://blueberry.example.com/api/environments/pr-123/status \
  -H "Authorization: Bearer $BLUEBERRY_TOKEN"

# ArgoCD sync status
kubectl get application -n argocd env-pr-123 -o yaml | grep -A 10 status:

# Pod health
kubectl get pods -n ephemeral-pr-123 -o wide

# Recent events
kubectl get events -n ephemeral-pr-123 --sort-by='.lastTimestamp'

Rollback Procedure

To delete an environment:

1. Via API
   bash curl -X DELETE https://blueberry.example.com/api/environments/pr-123 \ -H "Authorization: Bearer $BLUEBERRY_TOKEN"

2. Verify Deletion
   ```bash
   # Check namespace is removed
   kubectl get namespace ephemeral-pr-123

# Verify ArgoCD application deleted
kubectl get application -n argocd env-pr-123
```

Security Considerations

• Environments are isolated in separate Kubernetes namespaces
• Network policies prevent cross-namespace communication
• Secrets are automatically generated per environment
• Firebase authentication required for all operations
• Environments auto-expire based on TTL

Performance Impact

• Expected Duration: 2-3 minutes for full provisioning
• Resource Usage:
• 2 vCPU, 4GB RAM (default)
• Can be customized via config sets
• Downtime: None - each environment is independent

Related Workflows

• Update Environment Configuration
• Delete Environment
• Manage Environment TTL
• Create Config Set

References

• Environment API Reference
• Configuration Override Guide
• ArgoCD Application Structure

Last Updated: 2024-01-15
Author: Platform Team
Review Status: Approved