Managed Containers
This is a detailed guide for Managed Containers. For an overview of all runtime types and how to choose between them, see Runtimes Overview. To understand the differences between Reactives and Managed Containers, also see Codesphere Reactives.
Managed Containers allow you to bring your own OCI images to Codesphere while leveraging the platform's orchestration, networking, and monitoring capabilities. This runtime type uses the same underlying infrastructure as Codesphere Reactives, but allows you to define custom images and pre-bake dependencies via OCI images.
Overview
Managed Containers bridge the gap between the simplicity of Codesphere Reactives and the flexibility of custom container images:
| Feature | Codesphere Reactives | Managed Containers |
|---|---|---|
| Base Image | Shared Codesphere Ubuntu (customizable for private cloud) | Your own OCI image |
| Startup Time | Milliseconds | Seconds (depends on image size) |
| Dependencies | Local (npm packages, Python packages, etc.) or Nix | Pre-baked in OCI image |
| OS Distribution | Ubuntu or set by organization admin | Any (Alpine, Debian, etc.) |
| Image Registry | N/A | Docker Hub, ECR, private registries |
| Orchestration | Full platform features | Full platform features |
| Filesystem Access | Customizable shared network filesystem | Customizable shared network filesystem |
| Off-when-unused | Yes | Yes |
| Scaling & Load Balancing | Yes | Yes |
| Platform Integration | Built-in | At runtime |
Architecture
Managed Containers use the same orchestration platform as Reactives, with the key difference being the container image source:
Key Components
1. Custom Container Image
- Define your own base image via Dockerfile
- Pull from Docker Hub, ECR, GCR, or private registries
- Pre-bake all system dependencies and packages
- Complete control over OS distribution and version
2. Platform Orchestration
- Same Kubernetes-based orchestration as Reactives
- Health monitoring, load balancing, and auto-scaling
- Off-when-unused capabilities for resource efficiency
- Codesphere agent integrated at runtime for platform features
3. Shared Network Filesystem
- Identical filesystem access as Reactives
- Mount any file or directory to any destination in your container
- Default mount at
/home/user/appfor persistent storage - Same best practices apply (write to app directory, avoid concurrent writes)
4. Image Pull & Startup
- Container images pulled from registry on first start
- Subsequent starts may use cached images (depends on cluster state)
- Startup time typically in seconds vs milliseconds for Reactives
- Trade-off for complete image customization
When to Use Managed Containers
Managed Containers are ideal for:
- Existing OCI Images/Dockerfiles - Reuse existing container definitions
- Specific base OS requirements - Alpine, Debian, custom distributions
- Complex dependencies - System-level packages best managed via Dockerfile
- Open source projects - Already containerized applications
- Registry-based workflows - CI/CD that pushes images to registries
Consider Codesphere Reactives instead when:
- You don't need a specific base image
- Faster startup time is critical
- You prefer runtime dependency installation via Nix
- You're starting a new greenfield project
Commonalities with Codesphere Reactives
Both runtime types share the same underlying platform capabilities:
| Capability | Both Runtimes |
|---|---|
| Filesystem Access | Shared network filesystem at /home/user/app |
| Off-when-unused | Automatic resource deallocation during idle periods |
| Scaling | Horizontal (replicas) and vertical (plans) |
| Load Balancing | Automatic via Landscape Router |
| Health Monitoring | Configurable health checks and auto-restart |
| Private Networking | Secure internal service communication |
| Secret Management | Vault integration for sensitive data |
| Monitoring | Logs, metrics, and request tracing |
| Platform Integration | Codesphere agent for platform features |
Configuration & Lifecycle
Managed Containers are configured through the ci.yml file in your repository. For comprehensive guides on configuring and managing Managed Containers, see:
- Configuring a Landscape - Complete guide to landscape configuration
- Configuring CI Pipeline - Detailed pipeline setup including prepare and run stages
- Landscape Lifecycle - Understanding deployment, scaling, and lifecycle management
- Environment Variables - Managing environment configuration
- Secret Management - Secure handling of sensitive data
- CI Profiles - Managing different configurations for dev, staging, and production