From 2f97e9cbef9bca3b4fd2651cc2f112562838e6bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1?= Date: Sun, 22 Dec 2024 10:36:03 +0100 Subject: [PATCH 1/4] zsc update --- apps/docs/content/references/zsc.mdx | 265 +++++++++++++++------------ 1 file changed, 151 insertions(+), 114 deletions(-) diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index 2c5c43d5..79a941ca 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -1,20 +1,11 @@ --- -title: Using Zerops Setup Control(Zsc) -description: Interacting with zerops containers by connecting to the project network via zcli vpn with wireguard. +title: Using Zerops Setup Control (zsc) +description: Command-line utility for managing Zerops containers, providing functionality for scaling, backups, environment management, and runtime operations --- -import Image from '/src/components/Image'; +# zsc (Zerops Setup Control) -Zerops Setup Control(Zsc) is a cli tool / helper installed to all containers, runtime and build, -which allows some direct modifications, like triggering scaling from inside the container, -adding new technologies, making sure that commands (like migration) run only once (even when -staring some high available setup with 3 containers) - -:::info -Zsc is automatically installed in all containers and is available both in runtime and build environments. -::: - -## Command Overview +Zsc is a management tool that comes pre-installed in all Zerops containers, providing functionality for container management, scaling, backups, and more. It's available in both runtime and build environments without any additional setup needed. ```sh zsc --help @@ -42,78 +33,141 @@ Available Commands: Flags: -h, --help help for zsc +``` + +## Command Overview + +### Core Management + +#### scale +Adjust container resources dynamically: + +```bash +# CPU Scaling +zsc scale cpu auto # Reset to automatic scaling +zsc scale cpu 5 1h # Set to 5 CPU cores for 1 hour +zsc scale cpu +2 30m # Add 2 CPU cores for 30 minutes + +# Memory Scaling +zsc scale memory auto # Reset to automatic scaling +zsc scale memory 5GB 1h # Set to 5GB RAM for 1 hour +zsc scale memory +2.5GB 600s # Add 2.5GB RAM for 600 seconds +``` -Use "zsc [command] --help" for more information about a command. +**Important Scaling Notes:** +- Changes take effect within ~10 seconds +- Minimum duration: 10 minutes +- Supported values: "auto", "min", "max", or numeric values +- RAM requires units (KiB, MiB, GiB) +- CPU values must be integers +- Use "+" prefix for relative scaling + +#### action +Execute predefined container actions: + +```bash +zsc action [action-name] ``` -## Available Commands +#### execOnce +Ensure single execution across HA setups: -### backup-create and backup-current +```bash +zsc execOnce "operation-key" "your-command" +``` -The `backup-create` command lets you create a backup of any specified stack in your project, while `backup-current` command creates a backup of the stack you're currently working in. +Common use cases: +- Database migrations +- One-time initialization tasks +- Configuration updates -```sh -# Create backup of a specified stack +### Backup Commands + +#### backup-create +Create backup of a specified stack: + +```bash zsc backup-create +``` + +#### backup-current +Create backup of the current stack: -# Create backup of the current stack you're working in +```bash zsc backup-current ``` -:::info -Backups include all the data and configurations of the stack at the time of backup creation. These can be used for recovery or creating duplicate environments. -::: +Both commands capture: +- Stack configuration +- Service data +- Environment settings +- Deployment state -### connectSharedStorage +### Storage & Environment -This command lets you connect a shared storage volume to your service for persistent data storage. +#### connectSharedStorage +Connect shared storage volumes: -```sh +```bash zsc connectSharedStorage ``` -### crontab -This command lets you manage scheduled tasks that are defined in your zerops.yml configuration. +#### setSecretEnv +Manage environment variables: -```sh -zsc crontab +```bash +# Direct value assignment +zsc setSecretEnv SECRET_KEY "your-secret-value" + +# Input from stdin +echo "your-secret-value" | zsc setSecretEnv SECRET_KEY - ``` -### execOnce +### Testing & Debugging -:::info -This command is particularly useful in high-availability setups to ensure commands (like database migrations) run only once, even when starting multiple containers. -::: +#### test +Run various tests including network connectivity: -This command lets you execute a command exactly once across all containers in a service. Useful for database migrations in high-availability setups. +```bash +# TCP connectivity test +zsc test tcp : [options] -```sh -zsc execOnce "db-migration" "php artisan migrate" +# Options: +--timeout # Maximum test duration (default: 30s) +--dialTimeout # Single attempt timeout (default: 2s) +-4 # Force IPv4 +-6 # Force IPv6 ``` -### fail-me -This command lets you deliberately fail the current container for testing purposes. +#### fail-me +Deliberately fail the current container (useful for testing failover scenarios): -```sh +```bash zsc fail-me ``` -### install -You can install additional base technologies in your runtime container that weren't specified in the initial configuration. +#### noop +Keep container alive for debugging: + +```bash +zsc noop [--silent] +``` + +Features: +- Prevents container termination +- Enables investigation time +- Silent mode available +- Terminates on SIGTERM + +### Installation & Setup -:::info -The `install` command allows you to add technologies that weren't specified in the initial base configuration. -::: +#### install +Add technologies to your runtime container: -Example usage in `zerops.yml`: ```yaml +# Example in zerops.yml zerops: - setup: nodejsapp - build: - os: ubuntu - base: - - nodejs@22 - - python@3.7 run: os: ubuntu base: nodejs@22 @@ -121,86 +175,69 @@ zerops: - zsc install python@3.7 ``` -### noop -An infinitely blocking command that does nothing and keeps the container alive so that it doesn't end because of an error. The command runs indefinitely until it receives a SIGTERM signal. - -:::info -The `noop` command is particularly useful for debugging build failures by keeping the container alive for investigation. -::: +#### completion +Generate shell autocompletion scripts: -```sh -zsc noop [--silent] +```bash +zsc completion [bash|zsh|fish|powershell] ``` -The `--silent` flag suppresses any output from the command. - -### scale -This command dynamically adjusts CPU or memory resources for the current container. - -:::caution -If there aren't enough resources available on the current node, using `scale` may trigger a container move to another node. This will reset the scale duration. -::: +### Task Management -```sh -# Scale CPU -zsc scale cpu auto # Reset to automatic scaling -zsc scale cpu 5 1h # Scale to 5 CPU cores for 1 hour -zsc scale cpu +2 30m # Add 2 CPU cores for 30 minutes +#### crontab +Manage scheduled tasks defined in zerops.yml: -# Scale Memory -zsc scale memory auto # Reset to automatic scaling -zsc scale memory 5GB 1h # Scale to 5GB RAM for 1 hour -zsc scale memory +2.5GB 600s # Add 2.5GB RAM for 600 seconds +```bash +zsc crontab ``` -:::info -- Scaling takes effect within ~10 seconds -- Duration must be at least 10 minutes -- Supported values: "auto", "min", "max", or numeric values -- RAM values require units (KiB, MiB, GiB) -- CPU values must be integers without units -- Use "+" prefix for relative scaling -::: +## Best Practices -### test tcp -This command verifies TCP connectivity to a specified host and port. +1. **Resource Scaling** + - Use relative scaling for temporary adjustments + - Monitor resource usage after scaling + - Consider node capacity when scaling -```sh -zsc test tcp : [--timeout ] [--dialTimeout ] [-4] [-6] -``` +2. **High Availability** + - Use `execOnce` for migrations + - Test failover with `fail-me` + - Implement proper timeout handling -- **``**: Server address to connect to -- **``**: Port number to connect to -- **`--timeout `**: Maximum test duration (default: 30s) -- **`--dialTimeout `**: Single attempt timeout (default: 2s) -- **`-4`**: Force IPv4 -- **`-6`**: Force IPv6 +3. **Backup Management** + - Schedule regular backups + - Verify backup integrity + - Document backup contents -Example: -```sh -zsc test tcp database:5432 --timeout 1m -``` +4. **Debugging** + - Use `noop` for investigation + - Implement proper logging + - Monitor container states -### setSecretEnv -This command sets a secret environment variable in the current stack context. +## Common Use Cases -```sh -zsc setSecretEnv [key] [content] [flags] +### Database Migration in HA Setup +```bash +zsc execOnce "migrate-v2" "php artisan migrate" ``` -Examples: -```sh -# Direct value -zsc setSecretEnv SECRET_KEY "new_value" - -# From stdin -echo "new_value" | zsc setSecretEnv SECRET_KEY - +### Temporary Resource Boost +```bash +zsc scale cpu +2 1h +zsc scale memory +1GB 1h ``` -### version -This command displays the current version of Zsc CLI. +### Testing HA Failover +```bash +zsc fail-me # On one container +zsc test tcp other-service:80 # Verify connectivity after failover +``` -```sh -zsc version +### Secret Management +```bash +zsc setSecretEnv API_KEY "$(generate_api_key)" ``` +## Additional Information + +- View all commands and options with `zsc --help` +- Check version information with `zsc version` From 2e444f097d57759d8c8c9a44648d75dd5b589312 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1?= Date: Sun, 22 Dec 2024 10:57:01 +0100 Subject: [PATCH 2/4] Update zsc.mdx --- apps/docs/content/references/zsc.mdx | 34 +--------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index 79a941ca..27e67915 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -5,7 +5,7 @@ description: Command-line utility for managing Zerops containers, providing func # zsc (Zerops Setup Control) -Zsc is a management tool that comes pre-installed in all Zerops containers, providing functionality for container management, scaling, backups, and more. It's available in both runtime and build environments without any additional setup needed. +Zsc is a management tool that comes pre-installed in all Zerops containers, providing functionality for container management, scaling and more. It's available in both runtime and build environments without any additional setup needed. ```sh zsc --help @@ -15,9 +15,6 @@ Usage: zsc [command] Available Commands: - action Perform specific predefined actions within the container - backup-create creates a new backup of the specified stack - backup-current Create a new backup of the current stack completion Generate the autocompletion script for the specified shell connectSharedStorage Connect shared storage to the container crontab Perform crontab actions defined in zerops.yml @@ -62,13 +59,6 @@ zsc scale memory +2.5GB 600s # Add 2.5GB RAM for 600 seconds - CPU values must be integers - Use "+" prefix for relative scaling -#### action -Execute predefined container actions: - -```bash -zsc action [action-name] -``` - #### execOnce Ensure single execution across HA setups: @@ -81,28 +71,6 @@ Common use cases: - One-time initialization tasks - Configuration updates -### Backup Commands - -#### backup-create -Create backup of a specified stack: - -```bash -zsc backup-create -``` - -#### backup-current -Create backup of the current stack: - -```bash -zsc backup-current -``` - -Both commands capture: -- Stack configuration -- Service data -- Environment settings -- Deployment state - ### Storage & Environment #### connectSharedStorage From ba6d22d93d70c25d711df36d9e22bc1d5446b8b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1?= Date: Sun, 22 Dec 2024 11:14:54 +0100 Subject: [PATCH 3/4] Update zsc.mdx --- apps/docs/content/references/zsc.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index 27e67915..aeed33ec 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -15,6 +15,7 @@ Usage: zsc [command] Available Commands: + backup-create creates a new backup of the specified stack completion Generate the autocompletion script for the specified shell connectSharedStorage Connect shared storage to the container crontab Perform crontab actions defined in zerops.yml @@ -34,6 +35,22 @@ Flags: ## Command Overview +### Backup Commands + +#### backup-create +Create backup of a specified stack: + +```bash +zsc backup-create +``` + +Backup captures: +- Stack configuration +- Service data +- Environment settings +- Deployment state + + ### Core Management #### scale From f1959c455b20cd7b70e600e25e813a5c1035e44c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1?= Date: Sun, 22 Dec 2024 11:15:49 +0100 Subject: [PATCH 4/4] Update zsc.mdx --- apps/docs/content/references/zsc.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index aeed33ec..9e62f320 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -188,12 +188,7 @@ zsc crontab - Test failover with `fail-me` - Implement proper timeout handling -3. **Backup Management** - - Schedule regular backups - - Verify backup integrity - - Document backup contents - -4. **Debugging** +3. **Debugging** - Use `noop` for investigation - Implement proper logging - Monitor container states