Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

zsc update #133

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

zsc update #133

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2f97e9c
zsc update
fxck Dec 22, 2024
2e444f0
Update zsc.mdx
fxck Dec 22, 2024
ba6d22d
Update zsc.mdx
fxck Dec 22, 2024
f1959c4
Update zsc.mdx
fxck Dec 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
255 changes: 136 additions & 119 deletions apps/docs/content/references/zsc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 and more. It's available in both runtime and build environments without any additional setup needed.

```sh
zsc --help
Expand All @@ -24,9 +15,7 @@ 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
Expand All @@ -42,165 +31,193 @@ Available Commands:

Flags:
-h, --help help for zsc

Use "zsc [command] --help" for more information about a command.
```

## Available Commands
## Command Overview

### backup-create and backup-current
### Backup Commands

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.
#### backup-create
Create backup of a specified stack:

```sh
# Create backup of a specified stack
```bash
zsc backup-create
```

Backup captures:
- Stack configuration
- Service data
- Environment settings
- Deployment state

# Create backup of the current stack you're working in
zsc backup-current

### 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
```

:::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.
:::
**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

### connectSharedStorage
#### execOnce
Ensure single execution across HA setups:

This command lets you connect a shared storage volume to your service for persistent data storage.
```bash
zsc execOnce "operation-key" "your-command"
```

```sh
Common use cases:
- Database migrations
- One-time initialization tasks
- Configuration updates

### Storage & Environment

#### connectSharedStorage
Connect shared storage volumes:

```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 <host>:<port> [options]

```sh
zsc execOnce "db-migration" "php artisan migrate"
# Options:
--timeout <duration> # Maximum test duration (default: 30s)
--dialTimeout <duration> # 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
- [email protected]
run:
os: ubuntu
base: nodejs@22
prepareCommands:
- zsc install [email protected]
```

### 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.
### Task Management

### scale
This command dynamically adjusts CPU or memory resources for the current container.
#### crontab
Manage scheduled tasks defined in zerops.yml:

:::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.
:::

```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

# 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 <host>:<port> [--timeout <duration>] [--dialTimeout <duration>] [-4] [-6]
```

- **`<host>`**: Server address to connect to
- **`<port>`**: Port number to connect to
- **`--timeout <duration>`**: Maximum test duration (default: 30s)
- **`--dialTimeout <duration>`**: Single attempt timeout (default: 2s)
- **`-4`**: Force IPv4
- **`-6`**: Force IPv6
2. **High Availability**
- Use `execOnce` for migrations
- Test failover with `fail-me`
- Implement proper timeout handling

Example:
```sh
zsc test tcp database:5432 --timeout 1m
```
3. **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`
Loading