philipp/uncloud
1
0
Fork 0
mirror of https://github.com/psviderski/uncloud.git synced 2026-08-26 19:13:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Initial support for Compose configs (#116)

Browse Source
This commit is contained in:
Anton Ovchinnikov
2025-09-26 21:24:10 +10:00
committed by GitHub
parent 337c15de35
commit 63c4de512e
18 changed files with 1368 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/docs/3-concepts/5-compose/1-support-matrix.md
+107
View File
@@ -0,0 +1,107 @@
# Compose support matrix
Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some extensions and limitations.
The following table shows the support status for main Compose features:
| Feature | Support Status | Notes |
| ------------------ | ------------------- | --------------------------------------------------- |
| **Services** | | |
| `build` | ✅ Supported | Build context and Dockerfile |
| `command` | ✅ Supported | Override container command |
| `configs` | ✅ Supported | File-based and inline configs |
| `cpus` | ✅ Supported | CPU limit |
| `depends_on` | ❌ Not supported | Services start independently |
| `dns` | ❌ Not supported | Built-in service discovery |
| `dns_search` | ❌ Not supported | Built-in service discovery |
| `entrypoint` | ✅ Supported | Override container entrypoint |
| `env_file` | ✅ Supported | Environment file |
| `environment` | ✅ Supported | Environment variables |
| `image` | ✅ Supported | Container image specification |
| `init` | ✅ Supported | Run init process in container |
| `labels` | ❌ Not supported | Not currently needed |
| `links` | ❌ Not supported | Use service names for communication |
| `logging` | ✅ Supported | Uses Docker daemon logging |
| `mem_limit` | ✅ Supported | Memory limit |
| `mem_reservation` | ✅ Supported | Memory reservation |
| `mem_swappiness` | ❌ Not supported | |
| `memswap_limit` | ❌ Not supported | |
| `networks` | ❌ Not supported | All containers share cluster network |
| `ports` | ⚠️ Limited | Basic port publishing. Use `x-ports` for HTTP/HTTPS |
| `privileged` | ✅ Supported | Run containers in privileged mode |
| `pull_policy` | ✅ Supported | always, missing, never |
| `secrets` | ❌ Not supported | Use configs or environment variables |
| `security_opt` | ❌ Not supported | |
| `storage_opt` | ❌ Not supported | |
| `user` | ✅ Supported | Set container user |
| `volumes` | ✅ Supported | Named volumes, bind mounts, tmpfs |
| **Deploy** | | |
| `labels` | ❌ Not supported | Not needed |
| `mode` | ⚠️ Limited | Only `replicated` supported |
| `placement` | ❌ Not supported | Use `x-machines` extension |
| `replicas` | ✅ Supported | Number of container replicas |
| `resources` | ⚠️ Limited | CPU and memory limits only |
| `restart_policy` | ❌ Not supported | Services auto-restart |
| **Volumes** | | |
| Named volumes | ✅ Supported | Docker volumes |
| Bind mounts | ✅ Supported | Host path binding |
| Tmpfs mounts | ✅ Supported | In-memory filesystems |
| Volume labels | ✅ Supported | Custom labels |
| External volumes | ⚠️ Limited | Must exist before deployment |
| Volume drivers | ⚠️ Limited | Local driver only |
| **Configs** | | |
| File-based configs | ✅ Supported | Read from file |
| Inline configs | ✅ Supported | Defined in compose file |
| External configs | ❌ Not supported | Not supported |
| Short syntax | ❌ Not supported | Use long syntax only |
| **Extensions** | | |
| `x-caddy` | ✅ Uncloud-specific | Custom Caddy configuration |
| `x-machines` | ✅ Uncloud-specific | Machine placement constraints |
| `x-ports` | ✅ Uncloud-specific | HTTP/HTTPS port publishing |
### Legend
- ✅ **Supported**: Feature works as documented
- ⚠️ **Limited**: Partial support or with restrictions
- ❌ **Not supported**: Feature is not (yet) available
## Uncloud Extensions
Uncloud provides several custom extensions to enhance the Compose experience:
### `x-ports`
Define HTTP/HTTPS endpoints for services:
```yaml
services:
web:
image: nginx
x-ports:
- 80/https
- example.com:80/https
```
### `x-caddy`
Custom Caddy reverse proxy configuration:
```yaml
services:
web:
image: nginx
x-caddy: |
example.com {
reverse_proxy {{ upstreams 80 }}
}
```
### `x-machines`
Specify on what machines the service should run:
```yaml
services:
web:
image: nginx
x-machines: ["web-1", "web-2"]
```
website/docs/3-concepts/5-compose/5-configs.md
+236
View File
@@ -0,0 +1,236 @@
# Configs
Uncloud supports [Compose configs](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) for managing configuration files in your services. Configs allow you to store non-sensitive configuration data separately from your container images and mount them into containers at runtime.
See also [Docker Compose documentation](https://docs.docker.com/reference/compose-file/configs/) for the same feature.
## Overview
Configs provide a way to:
- Store configuration files outside of container images
- Share configuration between multiple services
- Update configuration without rebuilding images
- Version control your configuration separately
## Defining Configs
Configs are defined in two places in your `compose.yaml`:
1. **Top-level `configs` section**: Define the config content
2. **Service-level `configs` section**: Mount configs into containers
## Top-level Configs
Define configs using either file-based or inline content:
### File-based Configs
Read configuration from a file on the (local/control) host where `uc deploy` is run:
```yaml
configs:
nginx_config:
file: ./nginx.conf
app_config:
file: ./config/app.properties
```
The file path is relative to the compose file location.
### Inline Configs
Define configuration content directly in the compose file:
```yaml
configs:
app_config:
content: |
database_url=postgres://localhost:5432/myapp
redis_url=redis://localhost:6379
# Variable interpolation is supported
log_level=${LOG_LEVEL:-info}
```
When using inline configs, [environment variable interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) is supported so that you can customize configuration based on your deployment environment. Variables are resolved from the environment where `uc deploy` is executed.
## Service-level Config Mounts
Mount configs into containers using the long syntax:
```yaml
services:
web:
image: nginx:alpine
configs:
- source: nginx_config
target: /etc/nginx/nginx.conf
mode: 0644
- source: app_config
target: /app/config.properties
uid: "1000"
gid: "1000"
mode: 0600
```
### Config Mount Options
| Option | Description | Default |
| -------- | ------------------------------------------------- | ---------- |
| `source` | Name of the config (from top-level configs) | Required |
| `target` | Path where the config is mounted in the container | Required |
| `mode` | File permissions (octal format) | `0644` |
| `uid` | User ID that owns the file | Root user |
| `gid` | Group ID that owns the file | Root group |
## Complete Examples
### Example 1: Web Server with Custom Configuration
```yaml
services:
web:
image: nginx:alpine
configs:
- source: nginx_conf
target: /etc/nginx/nginx.conf
x-ports:
- 80/https
configs:
nginx_conf:
file: ./nginx.conf
```
Create `nginx.conf` in the same directory as your compose file:
```nginx
events {
worker_connections 1024;
}
http {
server {
listen 80;
location / {
return 200 'Hello from Uncloud!\n';
add_header Content-Type text/plain;
}
}
}
```
### Example 2: Application with Multiple Config Files
```yaml
services:
app:
image: node:18-alpine
command: ["node", "server.js"]
configs:
- source: app_config
target: /app/config.json
mode: 0644
- source: database_config
target: /app/database.json
uid: "1000"
gid: "1000"
mode: 0600
environment:
NODE_ENV: production
configs:
app_config:
content: |
{
"port": 3000,
"logLevel": "info",
"features": {
"analytics": true,
"cache": true
}
}
database_config:
file: ./configs/database.json
```
## Implementation details
Here are the key characteristics of the configs feature implementation:
- **Client-side processing**: When you run `uc deploy`, the Uncloud CLI reads config files from your local machine and includes their content in the service specification.
- **Content transfer**: Config content (both file-based and inline) is sent to the Uncloud daemon via gRPC as part of the deployment request.
- **Container deployment**: During container creation, configs are copied inside the container.
- **File lifecycle**: Config files exist only for the lifetime of the container. When a container is removed, its config files are cleaned up automatically.
- **Per-container isolation**: Each container gets its own copy of config files.
- **Atomic updates**: Config changes require redeployment, ensuring consistency across all replicas.
## Best Practices
### Security Considerations
- **Sensitive Data**: Don't put secrets in configs. Use environment variables or external secret management
- **File Permissions**: Set appropriate `mode`, `uid`, and `gid` for sensitive config files
- **Version Control**: Be careful about committing sensitive configuration files to git
### Config Sharing
Configs can be shared across multiple services:
```yaml
services:
web:
image: nginx
configs:
- source: shared_config
target: /etc/app/config.yaml
api:
image: myapi
configs:
- source: shared_config
target: /app/config.yaml
configs:
shared_config:
content: |
environment: production
debug: false
```
## Limitations
- **External configs**: Not supported. All configs must be defined in the compose file
- **Short syntax**: Not yet supported. Use the long syntax with `source` and `target`
- **Config updates**: Changing config content requires redeployment to take effect
## Troubleshooting
### Config File Not Found
If you get an error about config file not found:
1. Check the file path is correct relative to the compose file
2. Ensure the file exists and is readable
3. Verify file permissions
### Permission Denied
If containers can't read config files:
1. Check the `mode` setting allows read access
2. Verify `uid` and `gid` match the container's user
3. Ensure the container user has permission to access the target directory
### Config Not Updating
If config changes don't take effect:
1. Run `uc deploy` to redeploy with new config content
2. Check that you're modifying the correct config file
3. Verify the config is properly mounted in the container with `docker exec <service> cat <config-path>` on the remote machine
website/docs/3-concepts/5-compose/_category_.yaml
+4
View File
@@ -0,0 +1,4 @@
label: Compose features
collapsed: true # keep the category closed by default
link:
type: generated-index