From 0b4a9777fc2ddcc61430db23837455ff383ba1a3 Mon Sep 17 00:00:00 2001 From: Justin Garrison Date: Fri, 24 May 2024 08:40:22 -0700 Subject: [PATCH] docs: update talosctl install instructions for 1.8 Pulled changes from 1.7 docs Signed-off-by: Justin Garrison --- .../v1.7/talos-guides/install/talosctl.md | 4 +- .../v1.8/introduction/getting-started.md | 30 +++++++------ .../install/local-platforms/qemu.md | 6 ++- .../install/local-platforms/virtualbox.md | 6 ++- .../v1.8/talos-guides/install/talosctl.md | 39 ++++++++++++++++ .../install/virtualized-platforms/proxmox.md | 45 +++++++++++++++++-- 6 files changed, 107 insertions(+), 23 deletions(-) create mode 100644 website/content/v1.8/talos-guides/install/talosctl.md diff --git a/website/content/v1.7/talos-guides/install/talosctl.md b/website/content/v1.7/talos-guides/install/talosctl.md index 94afe968ae..8ce2cd65de 100644 --- a/website/content/v1.7/talos-guides/install/talosctl.md +++ b/website/content/v1.7/talos-guides/install/talosctl.md @@ -1,6 +1,6 @@ --- title: "talosctl" -description: "Install talos cli client." +description: "Install Talos Linux CLI" --- ## Recommended @@ -32,7 +32,7 @@ It supports amd64 and arm64 architecture. ## Manual and Windows install -All versions can be manually downloaded from the [talos releases page](https://github.com/siderolabs/talos/releases/) including Linux, macOs, and Windows. +All versions can be manually downloaded from the [talos releases page](https://github.com/siderolabs/talos/releases/) including Linux, macOS, and Windows. You will need to add the binary to a folder part of your executable `$PATH` to use it without providing the full path to the executable. diff --git a/website/content/v1.8/introduction/getting-started.md b/website/content/v1.8/introduction/getting-started.md index 0548aaaaa8..ff4220be3c 100644 --- a/website/content/v1.8/introduction/getting-started.md +++ b/website/content/v1.8/introduction/getting-started.md @@ -8,7 +8,7 @@ This document will walk you through installing a simple Talos Cluster with a sin > If this is your first use of Talos Linux, we recommend the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster in containers on your workstation. > ->For a production cluster, extra steps are needed - see [Production Notes]({{< relref "prodnotes" >}}). +> For a production cluster, extra steps are needed - see [Production Notes]({{< relref "prodnotes" >}}). Regardless of where you run Talos, the steps to create a Kubernetes cluster are: @@ -25,13 +25,15 @@ Regardless of where you run Talos, the steps to create a Kubernetes cluster are: `talosctl` is a CLI tool which interfaces with the Talos API. Talos Linux has no SSH access: `talosctl` is the tool you use to interact with the operating system on the machines. -Install `talosctl` before continuing: +You can download `talosctl` an MacOS and Linux via: ```bash -curl -sL https://talos.dev/install | sh +brew install siderolabs/tap/talosctl ``` -> Note: If you boot systems off the ISO, Talos on the ISO image runs in RAM and acts as an installer. +For manually installation and other platform please see the [talosctl installation guide]({{< relref "../talos-guides/install/talosctl.md" >}}). + +> Note: If you boot systems off the ISO, Talos on the ISO image runs in RAM and acts as an installer. > The version of `talosctl` that is used to create the machine configurations controls the version of Talos Linux that is installed on the machines - NOT the image that the machines are initially booted off. > For example, booting a machine off the Talos 1.3.7 ISO, but creating the initial configuration with `talosctl` binary of version 1.4.1, will result in a machine running Talos Linux version 1.4.1. > @@ -93,9 +95,9 @@ When Talos boots without a configuration, such as when booting off the Talos ISO enters maintenance mode and waits for a configuration to be provided. > A configuration can be passed in on boot via kernel parameters or metadata servers. -See [Production Notes]({{< relref "prodnotes#configure-talos" >}}). +> See [Production Notes]({{< relref "prodnotes#configure-talos" >}}). -Unlike traditional Linux, Talos Linux is *not* configured by SSHing to the server and issuing commands. +Unlike traditional Linux, Talos Linux is _not_ configured by SSHing to the server and issuing commands. Instead, the entire state of the machine is defined by a `machine config` file which is passed to the server. This allows machines to be managed in a declarative way, and lends itself to GitOps and modern operations paradigms. The state of a machine is completely defined by, and can be reproduced from, the machine configuration file. @@ -178,12 +180,12 @@ install: to reflect `vda` instead of `sda`. -> For information on customizing your machine configurations (such as to specify the version of Kubernetes), using [machine configuration patches]({{< relref "../talos-guides/configuration/patching" >}}), or customizing configurations for individual machines (such as setting static IP addresses), see the [Production Notes]({{< relref "prodnotes#customizing-machine-configuration" >}}). +> For information on customizing your machine configurations (such as to specify the version of Kubernetes), using [machine configuration patches]({{< relref "../talos-guides/configuration/patching" >}}), or customizing configurations for individual machines (such as setting static IP addresses), see the [Production Notes]({{< relref "prodnotes#customizing-machine-configuration" >}}). ## Understand talosctl, endpoints and nodes It is important to understand the concept of `endpoints` and `nodes`. -In short: `endpoints` are where `talosctl` *sends* commands to, but the command *operates* on the specified `nodes`. +In short: `endpoints` are where `talosctl` _sends_ commands to, but the command _operates_ on the specified `nodes`. The endpoint will forward the command to the nodes, if needed. ### Endpoints @@ -201,7 +203,7 @@ In this tutorial setup, the endpoint will always be the single control plane nod Nodes are the target(s) you wish to perform the operation on. -> When specifying nodes, the IPs and/or hostnames are *as seen by the endpoint servers*, not as from the client. +> When specifying nodes, the IPs and/or hostnames are _as seen by the endpoint servers_, not as from the client. > This is because all connections are proxied through the endpoints. You may provide `-n` or `--nodes` to any `talosctl` command to supply the node or (comma-separated) nodes on which you wish to perform the operation. @@ -212,7 +214,7 @@ For example, to see the containers running on node 192.168.0.200, by routing the talosctl -e 192.168.0.2 -n 192.168.0.200 containers ``` -To see the etcd logs on *both* nodes 192.168.0.10 and 192.168.0.11: +To see the etcd logs on _both_ nodes 192.168.0.10 and 192.168.0.11: ```bash talosctl -e 192.168.0.2 -n 192.168.0.10,192.168.0.11 logs etcd @@ -243,7 +245,7 @@ Apply the `controlplane.yaml` file to the control plane node, and the `worker.ya ``` The `--insecure` flag is necessary because the PKI infrastructure has not yet been made available to the node. -Note: the connection *will* be encrypted, but not authenticated. +Note: the connection _will_ be encrypted, but not authenticated. When using the `--insecure` flag, it is not necessary to specify an endpoint. @@ -271,8 +273,8 @@ talosctl bootstrap --nodes 192.168.0.2 --endpoints 192.168.0.2 \ --talosconfig=./talosconfig ``` ->The bootstrap operation should only be called **ONCE** on a **SINGLE** control plane node. -(If you have multiple control plane nodes, it doesn't matter which one you issue the bootstrap command against.) +> The bootstrap operation should only be called **ONCE** on a **SINGLE** control plane node. +> (If you have multiple control plane nodes, it doesn't matter which one you issue the bootstrap command against.) At this point, Talos will form an `etcd` cluster, and start the Kubernetes control plane components. @@ -284,7 +286,7 @@ After a few moments, you will be able to download your Kubernetes client configu Running this command will add (merge) you new cluster into your local Kubernetes configuration. -If you would prefer the configuration to *not* be merged into your default Kubernetes configuration file, pass in a filename: +If you would prefer the configuration to _not_ be merged into your default Kubernetes configuration file, pass in a filename: ```sh talosctl kubeconfig alternative-kubeconfig --nodes 192.168.0.2 --endpoints 192.168.0.2 diff --git a/website/content/v1.8/talos-guides/install/local-platforms/qemu.md b/website/content/v1.8/talos-guides/install/local-platforms/qemu.md index 43212c6ef4..dd39af069b 100644 --- a/website/content/v1.8/talos-guides/install/local-platforms/qemu.md +++ b/website/content/v1.8/talos-guides/install/local-platforms/qemu.md @@ -41,12 +41,14 @@ apt install qemu-system-x86 qemu-kvm ### Install talosctl -Download `talosctl` via +You can download `talosctl` an MacOS and Linux via: ```bash -curl -sL https://talos.dev/install | sh +brew install siderolabs/tap/talosctl ``` +For manually installation and other platform please see the [talosctl installation guide]({{< relref "../talosctl.md" >}}). + ## Install Talos kernel and initramfs QEMU provisioner depends on Talos kernel (`vmlinuz`) and initramfs (`initramfs.xz`). diff --git a/website/content/v1.8/talos-guides/install/local-platforms/virtualbox.md b/website/content/v1.8/talos-guides/install/local-platforms/virtualbox.md index c8f6f07be9..5874a699b6 100644 --- a/website/content/v1.8/talos-guides/install/local-platforms/virtualbox.md +++ b/website/content/v1.8/talos-guides/install/local-platforms/virtualbox.md @@ -26,12 +26,14 @@ apt install virtualbox ### Install talosctl -You can download `talosctl` via +You can download `talosctl` an MacOS and Linux via: ```bash -curl -sL https://talos.dev/install | sh +brew install siderolabs/tap/talosctl ``` +For manually installation and other platform please see the [talosctl installation guide]({{< relref "../talosctl.md" >}}). + ### Download ISO Image Download the ISO image from the Talos release page. diff --git a/website/content/v1.8/talos-guides/install/talosctl.md b/website/content/v1.8/talos-guides/install/talosctl.md new file mode 100644 index 0000000000..8ce2cd65de --- /dev/null +++ b/website/content/v1.8/talos-guides/install/talosctl.md @@ -0,0 +1,39 @@ +--- +title: "talosctl" +description: "Install Talos Linux CLI" +--- + +## Recommended + +The client can be installed and updated via the [Homebrew package manager](https://brew.sh/) for macOS and Linux. +You will need to install `brew` and then you can install `talosctl` from the Sidero Labs tap. + +```bash +brew install siderolabs/tap/talosctl +``` + +This will also keep your version of `talosctl` up to date with new releases. +This homebrew tap also has formulae for `omnictl` if you need to install that package. + +> Note: Your `talosctl` version should match the version of Talos Linux you are running on a host. +> To install a specific version of `talosctl` with `brew` you can follow [this github issue](https://github.com/siderolabs/homebrew-tap/issues/75). + +## Alternative install + +You can automatically install the correct version of `talosctl` for your operating system and architecture with an installer script. +This script won't keep your version updated with releases and you will need to re-run the script to download a new version. + +```bash +curl -sL https://talos.dev/install | sh +``` + +This script will work on macOS, Linux, and WSL on Windows. +It supports amd64 and arm64 architecture. + +## Manual and Windows install + +All versions can be manually downloaded from the [talos releases page](https://github.com/siderolabs/talos/releases/) including Linux, macOS, and Windows. + +You will need to add the binary to a folder part of your executable `$PATH` to use it without providing the full path to the executable. + +Updating the binary will be a manual process. diff --git a/website/content/v1.8/talos-guides/install/virtualized-platforms/proxmox.md b/website/content/v1.8/talos-guides/install/virtualized-platforms/proxmox.md index c6605543d4..f562c11ab5 100644 --- a/website/content/v1.8/talos-guides/install/virtualized-platforms/proxmox.md +++ b/website/content/v1.8/talos-guides/install/virtualized-platforms/proxmox.md @@ -22,12 +22,14 @@ Visit the [Proxmox](https://www.proxmox.com/en/downloads) downloads page if nece ### Install talosctl -You can download `talosctl` via +You can download `talosctl` an MacOS and Linux via: ```bash -curl -sL https://talos.dev/install | sh +brew install siderolabs/tap/talosctl ``` +For manually installation and other platform please see the [talosctl installation guide]({{< relref "../talosctl.md" >}}). + ### Download ISO Image In order to install Talos in Proxmox, you will need the ISO image from the Talos release page. @@ -36,7 +38,7 @@ You can download `metal-amd64.iso` via ```bash mkdir -p _out/ -curl https://github.com/siderolabs/talos/releases/download//metal-.iso -L -o _out/metal-.iso +curl https://github.com/siderolabs/talos/releases/download/{{< release >}}/metal-.iso -L -o _out/metal-.iso ``` For example version `{{< release >}}` for `linux` platform: @@ -46,6 +48,32 @@ mkdir -p _out/ curl https://github.com/siderolabs/talos/releases/download/{{< release >}}/metal-amd64.iso -L -o _out/metal-amd64.iso ``` +### QEMU guest agent support (iso) + +- If you need the QEMU guest agent so you can do guest VM shutdowns of your Talos VMs, then you will need a custom ISO +- To get this, navigate to https://factory.talos.dev/ +- Scroll down and select your Talos version (`{{< release >}}` for example) +- Then tick the box for `siderolabs/qemu-guest-agent` and submit +- This will provide you with a link to the bare metal ISO +- The lines we're interested in are as follows + +```text +Metal ISO + +amd64 ISO + https://factory.talos.dev/image/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515/{{< release >}}/metal-amd64.iso +arm64 ISO + https://factory.talos.dev/image/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515/{{< release >}}/metal-arm64.iso + +Installer Image + +For the initial Talos install or upgrade use the following installer image: +factory.talos.dev/installer/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515:{{< release >}} +``` + +- Download the above ISO (this will most likely be `amd64` for you) +- Take note of the `factory.talos.dev/installer` URL as you'll need it later + ## Upload ISO From the Proxmox UI, select the "local" storage and enter the "Content" section. @@ -172,6 +200,17 @@ This will create several files in the `_out` directory: `controlplane.yaml`, `wo > > Update `controlplane.yaml` and `worker.yaml` config files to point to the correct disk location. +### QEMU guest agent support + +For QEMU guest agent support, you can generate the config with the custom install image: + +```bash +talosctl gen config talos-proxmox-cluster https://$CONTROL_PLANE_IP:6443 --output-dir _out --installer-image factory.talos.dev/installer/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515:{{< release >}} +``` + +- In Proxmox, go to your VM --> Options and ensure that `QEMU Guest Agent` is `Enabled` +- The QEMU agent is now configured + ## Create Control Plane Node Using the `controlplane.yaml` generated above, you can now apply this config using talosctl.