mirror of
https://github.com/psviderski/uncloud.git
synced 2026-08-26 19:13:34 +00:00
docs: 2 new pages: Connecting to a cluster and CLI configuration file
This commit is contained in:
Pasha Sviderski
@@ -446,6 +446,6 @@ Note: Docker installation was preserved. If you want to completely remove Docker
|
||||
## Further reading
|
||||
|
||||
- **[Add more machines](../9-cli-reference/uc_machine_add.md)**: Scale horizontally by creating a cluster of machines
|
||||
- **[Ingress & HTTP](../3-concepts/1-ingress/1-overview.md)**: Learn how Uncloud handles incoming traffic and how to
|
||||
- **[Ingress & HTTP](../3-concepts/2-ingress/1-overview.md)**: Learn how Uncloud handles incoming traffic and how to
|
||||
expose your services to the internet
|
||||
- **[CLI reference](../9-cli-reference/uc.md)**: Explore all available commands and options
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Connecting to a cluster
|
||||
|
||||
`uc` only needs to reach one machine to work with the entire cluster. That machine acts as an **entry point** and
|
||||
forwards requests to other machines as needed.
|
||||
|
||||
`uc` stores **cluster contexts** and **connection details** in a [configuration file](../../7-cli-config-reference.md)
|
||||
(default location is `~/.config/uncloud/config.yaml`).
|
||||
|
||||
When you initialise a new cluster with `uc machine init` or add a machine to an existing cluster with `uc machine add`,
|
||||
they automatically save the SSH addresses of your machines to the config so you don't have to specify them every time.
|
||||
|
||||
## Cluster contexts
|
||||
|
||||
The [config file](../../7-cli-config-reference.md) organises connections into **contexts**. Each context represents a
|
||||
cluster. It has a name and a list of connection details for the machines in that cluster.
|
||||
|
||||
A context is not the same thing as a cluster. It is your local view of a cluster: which machines you can connect through
|
||||
and in what order to try them. Different people or environments may need to reach the same cluster in different ways.
|
||||
|
||||
You can also manually create multiple contexts for the same cluster. For example, one that connects through
|
||||
a machine with a public IP when you're not in the office, and another that connects through a private machine on the
|
||||
office network when you're on-site to reduce latency. You can switch between them depending on where you are.
|
||||
|
||||
### Managing contexts
|
||||
|
||||
Use these commands to manage the contexts in your config:
|
||||
|
||||
- [`uc ctx`](../../9-cli-reference/uc_ctx.md): Switch contexts using an interactive TUI
|
||||
- [`uc ctx ls`](../../9-cli-reference/uc_ctx_ls.md): List all contexts and see which one is current
|
||||
- [`uc ctx use`](../../9-cli-reference/uc_ctx_use.md): Switch the current context by name
|
||||
- [`uc ctx conn`](../../9-cli-reference/uc_ctx_connection.md): Change the default connection for the current context
|
||||
using an interactive TUI
|
||||
|
||||
You can also set `x-context` in your Compose file to pin a specific context for deployments. See
|
||||
[Deploy to a specific cluster context](../../4-guides/1-deployments/1-deploy-app.md#deploy-to-a-specific-cluster-context)
|
||||
for details.
|
||||
|
||||
## Connection resolution
|
||||
|
||||
When you run a `uc` command, it determines which cluster to connect to using this priority:
|
||||
|
||||
1. If `--connect` is set, `uc` connects directly to that machine and ignores the config file entirely.
|
||||
2. If `--context` is set, `uc` uses that context from the config.
|
||||
3. Otherwise, `uc` uses `current_context` from the config.
|
||||
|
||||
Once the context is resolved, `uc` tries each connection in the context's `connections` list in order until one
|
||||
succeeds.
|
||||
|
||||
## Global flags and environment variables
|
||||
|
||||
These flags are available on every `uc` command. They can also be set with an environment variable. The flag takes
|
||||
priority if both are set.
|
||||
|
||||
| Flag | Environment variable | Description |
|
||||
|--------------------|----------------------|-------------------------------------------------------------------|
|
||||
| `--uncloud-config` | `UNCLOUD_CONFIG` | Path to the config file |
|
||||
| `--context` | `UNCLOUD_CONTEXT` | Use a specific context instead of `current_context` in the config |
|
||||
| `--connect` | `UNCLOUD_CONNECT` | Bypass the config file and connect directly |
|
||||
|
||||
### Connecting directly without a config
|
||||
|
||||
The `--connect` flag or `UNCLOUD_CONNECT` environment variable let you run one-off commands against a cluster without
|
||||
using a config. This is useful for CI pipelines and scripts where you don't want to set up a config file.
|
||||
|
||||
It accepts these formats:
|
||||
|
||||
```shell
|
||||
# System 'ssh' command with full SSH config support
|
||||
uc --connect root@203.0.113.1 ls
|
||||
|
||||
# System 'ssh' command (explicit scheme, same as above)
|
||||
uc --connect ssh://root@203.0.113.1 ls
|
||||
|
||||
# Go's built-in SSH library (no SSH config support, useful when the system ssh is not available)
|
||||
uc --connect ssh+go://root@203.0.113.1 ls
|
||||
|
||||
# Direct connection to machine gRPC API over TCP (for advanced users with custom setups)
|
||||
uc --connect tcp://[fdcc:4439:f545:3ca:5d17:66e5:7c96:40bd]:51000 ls
|
||||
|
||||
# Direct connection to machine gRPC API over a Unix socket (for running uc locally on a cluster machine)
|
||||
uc --connect unix:///run/uncloud/uncloud.sock ls
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
Don't use `--connect` with `uc machine init`. `--connect` is for specifying or overriding the connection to an existing
|
||||
cluster, but `uc machine init` creates a new one and writes the new cluster context to the config file. You can discard
|
||||
the config when initialising a cluster with `--uncloud-config /dev/null` if you don't want to save it.
|
||||
|
||||
:::
|
||||
@@ -0,0 +1,4 @@
|
||||
label: Clusters
|
||||
collapsed: true # keep the category closed by default
|
||||
link:
|
||||
type: generated-index
|
||||
@@ -131,7 +131,7 @@ services:
|
||||
:::info important
|
||||
|
||||
If a health check fails after the deployment, Uncloud automatically removes the unhealthy container from the
|
||||
[Caddy](../../3-concepts/1-ingress/1-overview.md) configuration to prevent routing traffic to that container. But it
|
||||
[Caddy](../../3-concepts/2-ingress/1-overview.md) configuration to prevent routing traffic to that container. But it
|
||||
doesn't automatically restart or roll it back.
|
||||
|
||||
Uncloud automatically adds it back to Caddy when it recovers and becomes healthy again. You can inspect the health
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
# CLI configuration file
|
||||
|
||||
The [`uc`](2-getting-started/1-install-cli.md) CLI stores **cluster connection details** in a YAML configuration file.
|
||||
Every time you run a command like `uc ls` or `uc deploy`, it reads this file to figure out which cluster to connect to
|
||||
and how to reach its machines over SSH.
|
||||
|
||||
You rarely need to edit this file by hand. `uc` creates and updates it automatically when you run commands like
|
||||
`uc machine init`, `uc machine add`, or `uc ctx`.
|
||||
|
||||
## Config location
|
||||
|
||||
The default config file path is `~/.config/uncloud/config.yaml`. You can change this with the `--uncloud-config`
|
||||
global flag or the `UNCLOUD_CONFIG` environment variable:
|
||||
|
||||
```shell
|
||||
# Use a custom config file for this command
|
||||
uc --uncloud-config ./my-config.yaml ls
|
||||
|
||||
# Or set the environment variable to use a custom config file for all commands
|
||||
export UNCLOUD_CONFIG=~/my-uncloud-config.yaml
|
||||
uc ls
|
||||
```
|
||||
|
||||
## Config structure
|
||||
|
||||
Here is an example config file for a setup with two clusters, `prod` and `dev`:
|
||||
|
||||
```yaml title="~/.config/uncloud/config.yaml"
|
||||
current_context: prod
|
||||
contexts:
|
||||
prod:
|
||||
connections:
|
||||
- ssh: user@137.123.45.67
|
||||
- ssh: myserver # host alias from SSH config
|
||||
dev:
|
||||
connections:
|
||||
- ssh: ubuntu@dev.example.com
|
||||
ssh_key_file: ~/.ssh/id_ed25519
|
||||
machine_id: 3f60c88ac6b0f250d8aecb92a090922f
|
||||
```
|
||||
|
||||
The config has two top-level attributes: `current_context` and `contexts`.
|
||||
|
||||
### `current_context`
|
||||
|
||||
The name of the active context. `uc` uses this context by default when you run any command. You can switch to a
|
||||
different context with an interactive [`uc ctx`](9-cli-reference/uc_ctx.md) command, non-interactively with
|
||||
[`uc ctx use`](9-cli-reference/uc_ctx_use.md), or the `--context` flag.
|
||||
|
||||
### `contexts`
|
||||
|
||||
A map of named contexts. Each context represents a cluster and contains a list of machine connections.
|
||||
|
||||
A context is not the same thing as a cluster. It is your local view of a cluster: which machines you can connect through
|
||||
and in what order to try them. Two people on the same team can have different contexts pointing to the same cluster,
|
||||
each with their own preferred connection.
|
||||
|
||||
See [Connecting to a cluster](3-concepts/1-clusters/1-connecting.md#cluster-contexts) for more details and examples.
|
||||
|
||||
### `connections`
|
||||
|
||||
Each connection in the list represents a machine in the cluster. `uc` only needs to reach one machine to work with the
|
||||
entire cluster. That machine acts as an **entry point** and forwards requests to other machines as needed.
|
||||
|
||||
The first connection in the list is the default one that `uc` tries first. If it's unavailable, `uc` moves on to the
|
||||
next one. You can change the default connection with an interactive command
|
||||
[`uc ctx conn`](9-cli-reference/uc_ctx_connection.md).
|
||||
|
||||
Every connection must have exactly one connection type attribute:
|
||||
|
||||
| Attribute | Format | Description |
|
||||
|-----------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `ssh` | `user@host[:port]` | Connect using the system `ssh` command with full SSH config support (default for new connections added with `uc machine init/add`) |
|
||||
| `ssh_go` | `user@host[:port]` | Connect using Go's built-in SSH library (no SSH config support) |
|
||||
| `tcp` | `host:port` | Connect directly to the machine gRPC API over TCP (for advanced users with custom setups) |
|
||||
| `unix` | `/run/uncloud/uncloud.sock` | Connect directly to the machine gRPC API over a Unix socket (for running `uc` locally on the cluster machines) |
|
||||
|
||||
A connection can also have these optional attributes:
|
||||
|
||||
| Attribute | Description |
|
||||
|----------------|-------------------------------------------------------------------------------------------------------------------------|
|
||||
| `ssh_key_file` | Path to the SSH private key for this machine (maps to `-i` in the `ssh` command) |
|
||||
| `machine_id` | Unique identifier of the machine (used to match and remove the connection when removing a machine with `uc machine rm`) |
|
||||
|
||||
## How the config gets created and updated
|
||||
|
||||
You don't typically need to create or edit the config file manually. `uc` creates and manages it for you:
|
||||
|
||||
- [`uc machine init`](9-cli-reference/uc_machine_init.md) creates a file if it doesn't exist and adds a new context with
|
||||
the first machine connection. If you don't specify a context name with `--context`, it uses `default`. If
|
||||
`default` already exists, it auto-increments to `default-1`, `default-2`, and so on. You can rename contexts by
|
||||
editing the config file.
|
||||
- [`uc machine add`](9-cli-reference/uc_machine_add.md) appends a new machine connection to the current context. You can
|
||||
manually edit the connections in the config if needed.
|
||||
- [`uc ctx`](9-cli-reference/uc_ctx.md) or [`uc ctx use`](9-cli-reference/uc_ctx_use.md) updates `current_context` when
|
||||
you switch contexts.
|
||||
- [`uc ctx conn`](9-cli-reference/uc_ctx_connection.md) moves the selected connection to the top of the list to make it
|
||||
the default for that context.
|
||||
|
||||
For example, after initialising a cluster:
|
||||
|
||||
```shell
|
||||
uc machine init root@203.0.113.1 --context prod
|
||||
```
|
||||
|
||||
It creates a config file that looks like this:
|
||||
|
||||
```yaml title="~/.config/uncloud/config.yaml"
|
||||
current_context: prod
|
||||
contexts:
|
||||
prod:
|
||||
connections:
|
||||
- ssh: root@203.0.113.1
|
||||
machine_id: 4e81d368edf48480e5a2efb0915d6e38
|
||||
```
|
||||
@@ -134,7 +134,7 @@ services:
|
||||
- 8080:80/tcp@host
|
||||
```
|
||||
|
||||
See [Publishing services](../3-concepts/1-ingress/2-publishing-services.md) for more details.
|
||||
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
||||
|
||||
### `x-caddy`
|
||||
|
||||
@@ -150,7 +150,7 @@ services:
|
||||
}
|
||||
```
|
||||
|
||||
See [Publishing services](../3-concepts/1-ingress/2-publishing-services.md) for more details.
|
||||
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
||||
|
||||
### `x-machines`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user