alt-orchestra/talos
2
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update getting started

Browse Source 
Fixed typos, added info about how to detect disks, simplified.

Signed-off-by: Steve Francis <steve.francis@talos-systems.com>
This commit is contained in:
Steve Francis
2022-11-23 15:39:54 -08:00
committed by Tim Jones
parent 260684a930
commit c27adbe541
4 changed files with 293 additions and 344 deletions
Download Patch File Download Diff File Expand all files Collapse all files

368
website/content/v1.2/introduction/getting-started.md
View File

@ -5,10 +5,9 @@ description: "A guide to setting up a Talos Linux cluster on multiple machines."
---
This document will walk you through installing a full Talos Cluster.
You may wish to try the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster on your workstation.
If this is your first use of Talos Linux, we recommend the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster on your workstation.
Regardless of where you run Talos, there is a pattern to deploying it.
In general you need to:
Regardless of where you run Talos, in general you need to:
- acquire the installation image
- decide on the endpoint for Kubernetes
@ -21,11 +20,10 @@ In general you need to:
### `talosctl`
`talosctl` is a CLI tool which interfaces with the Talos API in
`talosctl` is a CLI tool which interfaces with the Talos API in
an easy manner.
It also includes a number of useful options for creating and managing clusters.
You should install `talosctl` before continuing:
Install `talosctl` before continuing:
#### `amd64`
@ -36,7 +34,7 @@ chmod +x /usr/local/bin/talosctl
#### `arm64`
For `linux` and `darwin` operating systems `talosctl` is also available for the `arm64` processor architecture.
For `linux` and `darwin` operating systems `talosctl` is also available for the `arm64` architecture.
```bash
curl -Lo /usr/local/bin/talosctl https://github.com/siderolabs/talos/releases/download/{{< release >}}/talosctl-$(uname -s | tr "[:upper:]" "[:lower:]")-arm64
@ -45,14 +43,14 @@ chmod +x /usr/local/bin/talosctl
## Acquire the installation image
The easiest way to install Talos is to use the ISO image.
The most general way to install Talos is to use the ISO image (note there are easier methods for some platforms, such as pre-built AMIs for AWS - check the specific [Installation Guides]({{< relref "../talos-guides/install/" >}}).)
The latest ISO image can be found on the Github [Releases](https://github.com/siderolabs/talos/releases) page:
- X86: [https://github.com/siderolabs/talos/releases/download/{{< release >}}/talos-amd64.iso](https://github.com/siderolabs/talos/releases/download/{{< release >}}/talos-amd64.iso)
- ARM64: [https://github.com/siderolabs/talos/releases/download/{{< release >}}/talos-arm64.iso](https://github.com/siderolabs/talos/releases/download/{{< release >}}/talos-arm64.iso)
When booted from the ISO, Talos will run in RAM, and it will not install itself
When booted from the ISO, Talos will run in RAM, and will not install itself
until it is provided a configuration.
Thus, it is safe to boot the ISO onto any machine.
@ -68,7 +66,7 @@ Please see the [kernel]({{< relref "../reference/kernel" >}}) docs for more info
## Decide the Kubernetes Endpoint
In order to configure Kubernetes and bootstrap the cluster, Talos needs to know
In order to configure Kubernetes, Talos needs to know
what the endpoint (DNS name or IP address) of the Kubernetes API Server will be.
The endpoint should be the fully-qualified HTTP(S) URL for the Kubernetes API
@ -80,35 +78,34 @@ Thus, the format of the endpoint may be something like:
- `https://kube.mycluster.mydomain.com:6443`
- `https://[2001:db8:1234::80]:6443`
Because the Kubernetes controlplane is meant to be highly
available, we must also choose how to bind the API server endpoint to the servers
themselves.
The Kubernetes API Server endpoint, in order to be highly available, should be configured in a way that functions off all available control plane nodes.
There are three common ways to do this:
### Dedicated Load-balancer
If you are using a cloud provider or have your own load-balancer available (such
If you are using a cloud provider or have your own load-balancer (such
as HAProxy, nginx reverse proxy, or an F5 load-balancer), using
a dedicated load balancer is a natural choice.
Create an appropriate frontend matching the endpoint, and point the backends at each of the addresses of the Talos controlplane nodes.
Create an appropriate frontend matching the endpoint, and point the backends at the addresses of each of the Talos control plane nodes.
(Note that given we have not yet created the control plane nodes, the IP addresses of the backends may not be known yet.
We can bind the backends to the frontend at a later point.)
### Layer 2 Shared IP
Talos has integrated support for serving Kubernetes from a shared (sometimes
called "virtual") IP address.
This method relies on OSI Layer 2 connectivity between controlplane Talos nodes.
Talos has integrated support for serving Kubernetes from a shared/virtual IP address.
This method relies on Layer 2 connectivity between control plane Talos nodes.
In this case, we choose an IP address on the same subnet as the Talos
controlplane nodes which is not otherwise assigned to any machine.
For instance, if your controlplane node IPs are:
In this case, we choose an unused IP address on the same subnet as the Talos
control plane nodes.
For instance, if your control plane node IPs are:
- 192.168.0.10
- 192.168.0.11
- 192.168.0.12
you could choose the ip `192.168.0.15` as your shared IP address.
Just make sure that `192.168.0.15` is not used by any other machine and that your DHCP
will not serve it to any other machine.
(Make sure that `192.168.0.15` is not used by any other machine and that your DHCP server
will not serve it to any other machine.)
Once chosen, form the full HTTPS URL from this IP:
@ -116,7 +113,7 @@ Once chosen, form the full HTTPS URL from this IP:
https://192.168.0.15:6443
```
You are free to set a DNS record to this IP address to identify the Kubernetes API endpoint, but you will need to use the IP address itself, not the DNS name, to configure the shared IP (`machine.network.interfaces[].vip.ip`) in the Talos configuration.
If you create a DNS record for this IP, note you will need to use the IP address itself, not the DNS name, to configure the shared IP (`machine.network.interfaces[].vip.ip`) in the Talos configuration.
For more information about using a shared IP, see the related
[Guide]({{< relref "../talos-guides/network/vip" >}})
@ -125,7 +122,7 @@ For more information about using a shared IP, see the related
If neither of the other methods work for you, you can use DNS records to
provide a measure of redundancy.
In this case, you would add multiple A or AAAA records (one for each controlpane node) to a DNS name.
In this case, you would add multiple A or AAAA records (one for each control plane node) to a DNS name.
For instance, you could add:
@ -143,157 +140,173 @@ https://kube.cluster1.mydomain.com:6443
## Decide how to access the Talos API
Since Talos is entirely API-driven, Talos comes with a number of mechanisms to make accessing the API easier.
Many administrative tasks are performed by calling the Talos API on Talos Linux control plane nodes.
Controlplane nodes can proxy requests for worker nodes.
This means that you only need access to the controlplane nodes in order to access
the rest of the network.
This is useful for security (your worker nodes do not need to have
public IPs or be otherwise connected to the Internet), and it also makes working
with highly-variable clusters easier, since you only need to know the
controlplane nodes in advance.
We recommend accessing the control plane nodes directly from the `talosctl` client, if possible (i.e. set your `endpoints` to the IP addresses of the control plane nodes).
This requires your control plane nodes to be reachable from the client IP.
Even better, the `talosctl` tool will automatically load balance requests and fail over
between all of your controlplane nodes, so long as it is informed of the
controlplane node IPs.
If the control plane nodes are not directly reachable from the workstation where you run `talosctl`, then configure a load balancer for TCP port 50000 to be forwarded to the control plane nodes.
Do not use Talos Linux's built in VIP support for accessing the Talos API, as it will not function in the event of an etcd failure, and you will not be able to access the Talos API to fix things.
This means you need to tell your client (`talosctl`) how to communicate with the controlplane nodes, which is done by defining the `endpoints`.
In general, it is recommended that these point to the set of control plane
nodes, either directly or through a reverse proxy or load balancer, similarly to accessing the Kubernetes API.
The difference is that the Talos API listens on port `50000/tcp`.
Whichever way you wish to access the Talos API, be sure to note the IP(s) or
hostname(s) so that you can configure your `talosctl` tool's `endpoints` below.
**NOTE**: The [Virtual IP]({{< relref "../talos-guides/network/vip.md" >}}) method is not recommended when accessing the Talos API as it requires etcd to be bootstrapped and functional.
This can make debugging any issues via the Talos API more difficult as issues with Talos configuration may result in etcd not achieving quorum, and therefore the Virtual IP not being available.
In this case setting the endpoints to the IP or hostnames of the control plane nodes themselves is preferred.
If you create a load balancer to forward the Talos API calls, make a note of the IP or
hostname so that you can configure your `talosctl` tool's `endpoints` below.
## Configure Talos
When Talos boots without a configuration, such as when using the Talos ISO, it
enters a limited maintenance mode and waits for a configuration to be provided.
Alternatively, the Talos installer can be booted with the `talos.config` kernel
In other installation methods, a configuration can be passed in on boot.
For example, Talos can be booted with the `talos.config` kernel
commandline argument set to an HTTP(s) URL from which it should receive its
configuration.
In cases where a PXE server can be available, this is much more efficient than
Where a PXE server is available, this is much more efficient than
manually configuring each node.
If you do use this method, just note that Talos does require a number of other
If you do use this method, note that Talos requires a number of other
kernel commandline parameters.
See the [required kernel parameters]({{< relref "../reference/kernel" >}}) for more information.
See [required kernel parameters]({{< relref "../reference/kernel" >}}).
If creating [EC2 kubernetes clusters]({{< relref "../talos-guides/install/cloud-platforms/aws/" >}}), the configuration file can be passed in as `--user-data` to the `aws ec2 run-instances` command.
In either case, we need to generate the configuration which is to be provided.
Luckily, the `talosctl` tool comes with a configuration generator for exactly
this purpose.
In any case, we need to generate the configuration which is to be provided:
```sh
talosctl gen config "cluster-name" "cluster-endpoint"
talosctl gen config cluster-name cluster-endpoint
```
Here, `cluster-name` is an arbitrary name for the cluster which will be used
Here, `cluster-name` is an arbitrary name for the cluster, used
in your local client configuration as a label.
It does not affect anything in the cluster itself, but it should be unique in the configuration on your local workstation.
It should be unique in the configuration on your local workstation.
The `cluster-endpoint` is where you insert the Kubernetes Endpoint you
The `cluster-endpoint` is the Kubernetes Endpoint you
selected from above.
This is the Kubernetes API URL, and it should be a complete URL, with `https://`
and port.
(The default port is `6443`.)
(The default port is `6443`, but you may have configured your load balancer to forward a different port.)
For example:
When you run this command, you will receive a number of files in your current
```sh
talosctl gen config my-cluster https://192.168.64.15:6443
generating PKI and tokens
created /Users/taloswork/controlplane.yaml
created /Users/taloswork/worker.yaml
created /Users/taloswork/talosconfig
```
When you run this command, a number of files are created in your current
directory:
- `controlplane.yaml`
- `worker.yaml`
- `talosconfig`
The `.yaml` files are what we call Machine Configs.
They are installed onto the Talos servers, and they provide their complete configuration,
describing everything from what disk Talos should be installed to, to what
sysctls to set, to what network settings it should have.
In the case of the `controlplane.yaml`, it even describes how Talos should form its Kubernetes cluster.
The `.yaml` files are Machine Configs.
They provide Talos Linux servers their complete configuration,
describing everything from what disk Talos should be installed on, to network settings.
The `controlplane.yaml` file describes how Talos should form a Kubernetes cluster.
The `talosconfig` file (which is also YAML) is your local client configuration
file.
The `talosconfig` file (which is also YAML) is your local client configuration file.
### Controlplane and Worker
The two types of Machine Configs correspond to the two roles of Talos nodes.
The Controlplane Machine Config describes the configuration of a Talos server on
which the Kubernetes Controlplane should run.
The Worker Machine Config describes everything else: workload servers.
The two types of Machine Configs correspond to the two roles of Talos nodes, control plane (which run both the Talos and Kubernetes control planes) and worker nodes (which run the workloads).
The main difference between Controlplane Machine Config files and Worker Machine
Config files is that the former contains information about how to form the
Kubernetes cluster.
### Templates
### Modifying the Machine configs
The generated Machine Configs have defaults that work for many cases.
They use DHCP for interface configuration, and install to `/dev/sda`.
If the defaults work for your installation, you may use them as is.
Sometimes, you will need to modify the generated files so they work with your systems.
A common example is needing to change the default installation disk.
If you try to to apply the machine config to a node, and get an error like the below, you need to specify a different installation disk:
```sh
talosctl apply-config --insecure -n 192.168.64.8 --file controlplane.yaml
error applying new configuration: rpc error: code = InvalidArgument desc = configuration validation failed: 1 error occurred:
* specified install disk does not exist: "/dev/sda"
```
You can verify which disks your nodes have by using the `talosctl disks --insecure` command.
> Insecure mode is needed at this point as the PKI infrastructure has not yet been set up.
For example:
```sh
talosctl -n 192.168.64.8 disks --insecure
DEV MODEL SERIAL TYPE UUID WWID MODALIAS NAME SIZE BUS_PATH
/dev/vda - - HDD - - virtio:d00000002v00001AF4 - 69 GB /pci0000:00/0000:00:06.0/virtio2/
```
In this case, you would modiy the `controlplane.yaml` and `worker.yaml` and edit the line:
```yaml
install:
disk: /dev/sda # The disk used for installations.
```
to reflect `vda` instead of `sda`.
#### Machine Configs as Templates
Individual machines may need different settings: for instance, each may have a
different [static IP address]({{< relref "../advanced/advanced-networking/#static-addressing" >}}).
The generated files can be thought of as templates.
Individual machines may need specific settings (for instance, each may have a
different static IP address).
When different files are needed for machines of the same type, simply
copy the source template (`controlplane.yaml` or `worker.yaml`) and make whatever
modifications need to be done.
modifications are needed.
For instance, if you had three controlplane nodes and three worker nodes, you
For instance, if you had three control plane nodes and three worker nodes, you
may do something like this:
```bash
for i in $(seq 0 2); do
cp controlplane.yaml cp$i.yaml
end
for i in $(seq 0 2); do
cp worker.yaml w$i.yaml
end
for i in $(seq 0 2); do
cp controlplane.yaml cp$i.yaml
end
for i in $(seq 0 2); do
cp worker.yaml w$i.yaml
end
```
In cases where there is no special configuration needed, you may use the same
file for each machine of the same type.
Then modify each file as needed.
### Apply Configuration
After you have generated each machine's Machine Config, you need to load them
into the machines themselves.
For that, you need to know their IP addresses.
To apply the Machine Configs, you need to know the machines' IP addresses.
If you have access to the console or console logs of the machines, you can read
them to find the IP address(es).
Talos will print them out during the boot process:
Talos will print out the IP addresses of the machines on the console during the boot process:
```log
[ 4.605369] [talos] task loadConfig (1/1): this machine is reachable at:
[ 4.607358] [talos] task loadConfig (1/1): 192.168.0.2
[ 4.608766] [talos] task loadConfig (1/1): server certificate fingerprint:
[ 4.611106] [talos] task loadConfig (1/1): xA9a1t2dMxB0NJ0qH1pDzilWbA3+DK/DjVbFaJBYheE=
[ 4.613822] [talos] task loadConfig (1/1):
[ 4.614985] [talos] task loadConfig (1/1): upload configuration using talosctl:
[ 4.616978] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --file <config.yaml>
[ 4.620168] [talos] task loadConfig (1/1): or apply configuration using talosctl interactive installer:
[ 4.623046] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --mode=interactive
[ 4.626365] [talos] task loadConfig (1/1): optionally with node fingerprint check:
[ 4.628692] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --cert-fingerprint 'xA9a1t2dMxB0NJ0qH1pDzilWbA3+DK/DjVbFaJBYheE=' --file <config.yaml>
[4.605369] [talos] task loadConfig (1/1): this machine is reachable at:
[4.607358] [talos] task loadConfig (1/1): 192.168.0.2
[4.608766] [talos] task loadConfig (1/1): server certificate fingerprint:
[4.611106] [talos] task loadConfig (1/1): xA9a1t2dMxB0NJ0qH1pDzilWbA3+DK/DjVbFaJBYheE=
[4.613822] [talos] task loadConfig (1/1):
[4.614985] [talos] task loadConfig (1/1): upload configuration using talosctl:
[4.616978] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --file <config.yaml>
[4.620168] [talos] task loadConfig (1/1): or apply configuration using talosctl interactive installer:
[4.623046] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --mode=interactive
[4.626365] [talos] task loadConfig (1/1): optionally with node fingerprint check:
[4.628692] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --cert-fingerprint 'xA9a1t2dMxB0NJ0qH1pDzilWbA3+DK/DjVbFaJBYheE=' --file <config.yaml>
```
If you do not have console access, the IP address may also be discoverable from
your DHCP server.
If you do not have console access, the IP address may also be discoverable from your DHCP server.
Once you have the IP address, you can then apply the correct configuration.
```sh
talosctl apply-config --insecure \
--nodes 192.168.0.2 \
--file cp0.yaml
--file controlplane.yaml
```
The insecure flag is necessary at this point because the PKI infrastructure has
not yet been made available to the node.
Note that the connection _will_ be encrypted, it is just unauthenticated.
If you have console access, though, you can extract the server
certificate fingerprint and use it for an additional layer of validation:
The insecure flag is necessary because the PKI infrastructure has not yet been made available to the node.
Note: the connection _will_ be encrypted, it is just unauthenticated.
If you have console access you can extract the server certificate fingerprint and use it for an additional layer of validation:
```sh
talosctl apply-config --insecure \
@ -302,40 +315,31 @@ certificate fingerprint and use it for an additional layer of validation:
--file cp0.yaml
```
Using the fingerprint allows you to be sure you are sending the configuration to
the right machine, but it is completely optional.
Using the fingerprint allows you to be sure you are sending the configuration to the correct machine, but it is completely optional.
After the configuration is applied to a node, it will reboot.
Repeat this process for each of the nodes in your cluster.
You may repeat this process for each of the nodes in your cluster.
## Understand talosctl, endpoints and nodes
## Configure your talosctl client
Now that the nodes are running Talos with its full PKI security suite, you need
to use that PKI to talk to the machines.
That means configuring your client, and that is what that `talosconfig` file is for.
It is important to understand the concept of `endpoints` and `nodes`.
In short: `endpoints` are the nodes that `talosctl` sends commands to, but `nodes` are the nodes that the command operates on.
The endpoint will forward the command to the nodes, if needed.
### Endpoints
Endpoints are the communication endpoints to which the client directly talks.
These can be load balancers, DNS hostnames, a list of IPs, etc.
In general, it is recommended that these point to the set of control plane
nodes, either directly or through a reverse proxy or load balancer.
Endpoints are the IP addresses to which the `talosctl` client directly talks.
These should be the set of control plane nodes, either directly or through a load balancer.
Each endpoint will automatically proxy requests destined to another node through
it, so it is not necessary to change the endpoint configuration just because you
wish to talk to a different node within the cluster.
Each endpoint will automatically proxy requests destined to another node in the cluster.
This means that you only need access to the control plane nodes in order to access the rest of the network.
Endpoints _do_, however, need to be members of the same Talos cluster as the
target node, because these proxied connections reply on certificate-based
authentication.
`talosctl` will automatically load balance requests and fail over between all of your endpoints.
We need to set the `endpoints` in your `talosconfig`.
`talosctl` will automatically load balance and fail over among the endpoints,
so no external load balancer or DNS abstraction is required
(though you are free to use them).
You can pass in `--endpoints <IP Address1>,<IP Address2>` as a comma separated list of IP/DNS addresses to the current `talosctl` command.
You can also set the `endpoints` in your `talosconfig`, by calling `talosctl config endpoint <IP Address1> <IP Address2>`.
Note: these are space separated, not comma separated.
As an example, if the IP addresses of our controlplane nodes are:
As an example, if the IP addresses of our control plane nodes are:
- 192.168.0.2
- 192.168.0.3
@ -350,47 +354,27 @@ We would set those in the `talosconfig` with:
### Nodes
The node is the target node on which you wish to perform the API call.
The node is the target you wish to perform the API call on.
Keep in mind, when specifying nodes, their 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.
> When specifying nodes, their 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.
Some people also like to set a default set of nodes in the `talosconfig`.
This can be done in the same manner, replacing `endpoint` with `node`.
If you do this, however, know that you could easily reboot the wrong machine
by forgetting to declare the right one explicitly.
Worse, if you set several nodes as defaults, you could, with one `talosctl upgrade`
command upgrade your whole cluster all at the same time.
It's a powerful tool, and with that comes great responsibility.
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.
The author of this document generally sets a single controlplane node to be the
default node, which provides the most flexible default operation while limiting
the scope of the disaster should a command be entered erroneously:
```sh
talosctl --talosconfig=./talosconfig \
config node 192.168.0.2
```
You may simply provide `-n` or `--nodes` to any `talosctl` command to
supply the node or (comma-delimited) nodes on which you wish to perform the
operation.
Supplying the commandline parameter will override any default nodes
in the configuration file.
To verify default node(s) you're currently configured to use, you can run:
For example, to see the containers running on node 192.168.0.200:
```bash
$ talosctl version
Client:
...
Server:
NODE: <node>
...
talosctl -n 192.168.0.200 containers
```
For a more in-depth discussion of Endpoints and Nodes, please see
[talosctl]({{< relref "../learn-more/talosctl" >}}).
To see the etcd logs on *both* nodes 192.168.0.10 and 192.168.0.11:
```bash
talosctl -n 192.168.0.10,192.168.0.11 logs etcd
```
It is possible to set a default set of nodes in the `talosconfig` file, but our recommendation is to explicitly pass in the node or nodes to be operated on with each `talosctl` command.
For a more in-depth discussion of Endpoints and Nodes, please see [talosctl]({{< relref "../learn-more/talosctl" >}}).
### Default configuration file
@ -401,63 +385,55 @@ You _can_ reference which configuration file to use directly with the `--talosco
--nodes 192.168.0.2 version
```
However, `talosctl` comes with tooling to help you integrate and merge this
configuration into the default `talosctl` configuration file.
However, `talosctl` comes with tooling to help you integrate and merge this configuration into the default `talosctl` configuration file.
This is done with the `merge` option.
```sh
talosctl config merge ./talosconfig
```
This will merge your new `talosconfig` into the default configuration file
(`$XDG_CONFIG_HOME/talos/config.yaml`), creating it if necessary.
Like Kubernetes, the `talosconfig` configuration files has multiple "contexts"
which correspond to multiple clusters.
This will merge your new `talosconfig` into the default configuration file (`$XDG_CONFIG_HOME/talos/config.yaml`), creating it if necessary.
Like Kubernetes, the `talosconfig` configuration files has multiple "contexts" which correspond to multiple clusters.
The `<cluster-name>` you chose above will be used as the context name.
## Kubernetes Bootstrap
All of your machines are configured, and your `talosctl` client is set up.
Now, you are ready to bootstrap your Kubernetes cluster.
If that sounds daunting, you haven't used Talos before.
Bootstrapping your Kubernetes cluster with Talos is as simple as:
```sh
talosctl bootstrap --nodes 192.168.0.2
```
**IMPORTANT**: the bootstrap operation should only be called **ONCE** and only on a **SINGLE**
controlplane node!
>The bootstrap operation should only be called **ONCE** and only on a **SINGLE** control plane node!
The IP can be any of your controlplanes (or the loadbalancer, if you have
one).
It should only be issued once.
The IP can be any of your control planes (or the loadbalancer, if used for the Talos API endpoint).
At this point, Talos will form an `etcd` cluster, generate all of the core
Kubernetes assets, and start the Kubernetes controlplane components.
At this point, Talos will form an `etcd` cluster, generate all of the core Kubernetes assets, and start the Kubernetes control plane components.
After a few moments, you will be able to download your Kubernetes client
configuration and get started:
After a few moments, you will be able to download your Kubernetes client configuration and get started:
```sh
talosctl kubeconfig
```
Running this command will add (merge) you new cluster into you local Kubernetes
configuration in the same way as `talosctl config merge` merged the Talos client
configuration into your local Talos client configuration file.
Running this command will add (merge) you new cluster into your local Kubernetes configuration.
If you would prefer for the configuration to _not_ be merged into your default
Kubernetes configuration file, simple tell it 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
```
If all goes well, you should now be able to connect to Kubernetes and see your
nodes:
You should now be able to connect to Kubernetes and see your nodes:
```sh
kubectl get nodes
```
And use talosctl to explore your cluster:
```sh
talosctl -n <NODEIP> dashboard
```
For a list of all the commands and operations that `talosctl` provides, see the [CLI reference]({{< relref "../reference/cli/#talosctl" >}}).

6
website/content/v1.2/talos-guides/install/bare-metal-platforms/matchbox.md
View File

@ -41,7 +41,7 @@ worker.yaml is valid for metal mode
#### Publishing the Machine Configuration Files
In bare-metal setups it is up to the user to provide the configuration files over HTTP(S).
A special kernel parameter (`talos.config`) must be used to inform Talos about _where_ it should retreive its' configuration file.
A special kernel parameter (`talos.config`) must be used to inform Talos about _where_ it should retrieve its configuration file.
To keep things simple we will place `controlplane.yaml`, and `worker.yaml` into Matchbox's `assets` directory.
This directory is automatically served by Matchbox.
@ -149,8 +149,8 @@ Now, create the following groups, and ensure that the `selector`s are accurate f
### Boot the Machines
Now that we have our configuraton files in place, boot all the machines.
Talos will come up on each machine, grab its' configuration file, and bootstrap itself.
Now that we have our configuration files in place, boot all the machines.
Talos will come up on each machine, grab its configuration file, and bootstrap itself.
### Bootstrap Etcd

257
website/content/v1.3/introduction/getting-started.md
View File

@ -5,7 +5,7 @@ description: "A guide to setting up a Talos Linux cluster on multiple machines."
---
This document will walk you through installing a full Talos Cluster.
If this is your first use of Talos Linux, we recommend the the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster on your workstation.
If this is your first use of Talos Linux, we recommend the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster on your workstation.
Regardless of where you run Talos, in general you need to:
@ -43,7 +43,7 @@ chmod +x /usr/local/bin/talosctl
## Acquire the installation image
The most general way to install Talos is to use the ISO image (but note there are easer methods for some platforms, such as pre-built AMIs for AWS - check the specific [Installation Guides]({{< relref "../talos-guides/install/" >}}).)
The most general way to install Talos is to use the ISO image (note there are easier methods for some platforms, such as pre-built AMIs for AWS - check the specific [Installation Guides]({{< relref "../talos-guides/install/" >}}).)
The latest ISO image can be found on the Github [Releases](https://github.com/siderolabs/talos/releases) page:
@ -66,7 +66,7 @@ Please see the [kernel]({{< relref "../reference/kernel" >}}) docs for more info
## Decide the Kubernetes Endpoint
In order to configure Kubernetes and bootstrap the cluster, Talos needs to know
In order to configure Kubernetes, Talos needs to know
what the endpoint (DNS name or IP address) of the Kubernetes API Server will be.
The endpoint should be the fully-qualified HTTP(S) URL for the Kubernetes API
@ -78,27 +78,26 @@ Thus, the format of the endpoint may be something like:
- `https://kube.mycluster.mydomain.com:6443`
- `https://[2001:db8:1234::80]:6443`
The Kubernetes API Server endpoint, in order to be highly availabile, should be configured in a way that functions off all available control plane nodes.
The Kubernetes API Server endpoint, in order to be highly available, should be configured in a way that functions off all available control plane nodes.
There are three common ways to do this:
### Dedicated Load-balancer
If you are using a cloud provider or have your own load-balancer available (such
If you are using a cloud provider or have your own load-balancer (such
as HAProxy, nginx reverse proxy, or an F5 load-balancer), using
a dedicated load balancer is a natural choice.
Create an appropriate frontend matching the endpoint, and point the backends at each of the addresses of the Talos controlplane nodes.
Note that given we have not yet created the control plane nodes, the IP addresses of the backends may not be known yet.
We can bind the backends to the frontend at a later point.
At this stage, we just need the IP and Port of the frontend to be created, for use later on.
Create an appropriate frontend matching the endpoint, and point the backends at the addresses of each of the Talos control plane nodes.
(Note that given we have not yet created the control plane nodes, the IP addresses of the backends may not be known yet.
We can bind the backends to the frontend at a later point.)
### Layer 2 Shared IP
Talos has integrated support for serving Kubernetes from a shared/virtual IP address.
This method relies on Layer 2 connectivity between controlplane Talos nodes.
This method relies on Layer 2 connectivity between control plane Talos nodes.
In this case, we choose an IP address on the same subnet as the Talos
controlplane nodes which is not otherwise assigned to any machine.
For instance, if your controlplane node IPs are:
In this case, we choose an unused IP address on the same subnet as the Talos
control plane nodes.
For instance, if your control plane node IPs are:
- 192.168.0.10
- 192.168.0.11
@ -123,7 +122,7 @@ For more information about using a shared IP, see the related
If neither of the other methods work for you, you can use DNS records to
provide a measure of redundancy.
In this case, you would add multiple A or AAAA records (one for each controlpane node) to a DNS name.
In this case, you would add multiple A or AAAA records (one for each control plane node) to a DNS name.
For instance, you could add:
@ -141,12 +140,12 @@ https://kube.cluster1.mydomain.com:6443
## Decide how to access the Talos API
Much of the power of Talos Linux comes from the API calls that can be made against control plane nodes.
Many administrative tasks are performed by calling the Talos API on Talos Linux control plane nodes.
We recommend accessing the control plane nodes directly from the `talosctl` client, if possible (i.e. set your `endpoints` to the IP addresses of the control plane nodes).
This requires your controlplane nodes to be reachable from the client IP.
This requires your control plane nodes to be reachable from the client IP.
If your control plane nodes are not directly reachable from your workstation where you run `talosctl`, then configure a load balancer for TCP port 50000 to be forwarded to the controlplane nodes.
If the control plane nodes are not directly reachable from the workstation where you run `talosctl`, then configure a load balancer for TCP port 50000 to be forwarded to the control plane nodes.
Do not use Talos Linux's built in VIP support for accessing the Talos API, as it will not function in the event of an etcd failure, and you will not be able to access the Talos API to fix things.
If you create a load balancer to forward the Talos API calls, make a note of the IP or
@ -154,8 +153,6 @@ hostname so that you can configure your `talosctl` tool's `endpoints` below.
## Configure Talos
Talos Linux needs to be given configuration information to know how to form a Kubernetes cluster.
When Talos boots without a configuration, such as when using the Talos ISO, it
enters a limited maintenance mode and waits for a configuration to be provided.
@ -170,83 +167,118 @@ kernel commandline parameters.
See [required kernel parameters]({{< relref "../reference/kernel" >}}).
If creating [EC2 kubernetes clusters]({{< relref "../talos-guides/install/cloud-platforms/aws/" >}}), the configuration file can be passed in as `--user-data` to the `aws ec2 run-instances` command.
In any case, we need to generate the configuration which is to be provided.
`talosctl` can do exactly this:
In any case, we need to generate the configuration which is to be provided:
```sh
talosctl gen config "cluster-name" "cluster-endpoint"
talosctl gen config cluster-name cluster-endpoint
```
Here, `cluster-name` is an arbitrary name for the cluster which will be used
Here, `cluster-name` is an arbitrary name for the cluster, used
in your local client configuration as a label.
It does not affect anything in the cluster itself, but it should be unique in the configuration on your local workstation.
It should be unique in the configuration on your local workstation.
The `cluster-endpoint` is the Kubernetes Endpoint you
selected from above.
This is the Kubernetes API URL, and it should be a complete URL, with `https://`
and port.
(The default port is `6443`, but you may have configured your load balancer to forward a different port.)
For example:
When you run this command, you will receive a number of files in your current
```sh
talosctl gen config my-cluster https://192.168.64.15:6443
generating PKI and tokens
created /Users/taloswork/controlplane.yaml
created /Users/taloswork/worker.yaml
created /Users/taloswork/talosconfig
```
When you run this command, a number of files are created in your current
directory:
- `controlplane.yaml`
- `worker.yaml`
- `talosconfig`
The `.yaml` files are what we call Machine Configs.
They provide the Talos servers their complete configuration,
describing everything from what disk Talos should be installed to, to what
sysctls to set, to network settings.
The `.yaml` files are Machine Configs.
They provide Talos Linux servers their complete configuration,
describing everything from what disk Talos should be installed on, to network settings.
The `controlplane.yaml` file describes how Talos should form a Kubernetes cluster.
The `talosconfig` file (which is also YAML) is your local client configuration
file.
The `talosconfig` file (which is also YAML) is your local client configuration file.
### Controlplane and Worker
The two types of Machine Configs correspond to the two roles of Talos nodes, controlplane (which run both the Talos and Kubernetes control planes) and worker nodes (which run the workloads).
The two types of Machine Configs correspond to the two roles of Talos nodes, control plane (which run both the Talos and Kubernetes control planes) and worker nodes (which run the workloads).
The main difference between Controlplane Machine Config files and Worker Machine
Config files is that the former contains information about how to form the
Kubernetes cluster.
### Machine Configs as Templates
### Modifying the Machine configs
The generated files can be thought of as templates.
Individual machines may need specific settings: for instance, each may have a
The generated Machine Configs have defaults that work for many cases.
They use DHCP for interface configuration, and install to `/dev/sda`.
If the defaults work for your installation, you may use them as is.
Sometimes, you will need to modify the generated files so they work with your systems.
A common example is needing to change the default installation disk.
If you try to to apply the machine config to a node, and get an error like the below, you need to specify a different installation disk:
```sh
talosctl apply-config --insecure -n 192.168.64.8 --file controlplane.yaml
error applying new configuration: rpc error: code = InvalidArgument desc = configuration validation failed: 1 error occurred:
* specified install disk does not exist: "/dev/sda"
```
You can verify which disks your nodes have by using the `talosctl disks --insecure` command.
> Insecure mode is needed at this point as the PKI infrastructure has not yet been set up.
For example:
```sh
talosctl -n 192.168.64.8 disks --insecure
DEV MODEL SERIAL TYPE UUID WWID MODALIAS NAME SIZE BUS_PATH
/dev/vda - - HDD - - virtio:d00000002v00001AF4 - 69 GB /pci0000:00/0000:00:06.0/virtio2/
```
In this case, you would modiy the `controlplane.yaml` and `worker.yaml` and edit the line:
```yaml
install:
disk: /dev/sda # The disk used for installations.
```
to reflect `vda` instead of `sda`.
#### Machine Configs as Templates
Individual machines may need different settings: for instance, each may have a
different [static IP address]({{< relref "../advanced/advanced-networking/#static-addressing" >}}).
By default, interfaces are set to DHCP.
When different files are needed for machines of the same type, simply
copy the source template (`controlplane.yaml` or `worker.yaml`) and make whatever
modifications need to be done.
modifications are needed.
For instance, if you had three controlplane nodes and three worker nodes, you
For instance, if you had three control plane nodes and three worker nodes, you
may do something like this:
```bash
for i in $(seq 0 2); do
cp controlplane.yaml cp$i.yaml
end
for i in $(seq 0 2); do
cp worker.yaml w$i.yaml
end
for i in $(seq 0 2); do
cp controlplane.yaml cp$i.yaml
end
for i in $(seq 0 2); do
cp worker.yaml w$i.yaml
end
```
Then modify each file as needed.
In cases where there is no special configuration needed, you may use the same
file for all machines of the same type.
### Apply Configuration
If you have booted into maintenance mode, then after you have generated the Machine Configs, you need to load them
into the machines themselves.
For that, you need to know their IP addresses.
To apply the Machine Configs, you need to know the machines' IP addresses.
If you have access to the console logs of the machines, you can read
them to find the IP address(es).
Talos will print them out during the boot process:
Talos will print out the IP addresses of the machines on the console during the boot process:
```log
[4.605369] [talos] task loadConfig (1/1): this machine is reachable at:
@ -262,23 +294,19 @@ Talos will print them out during the boot process:
[4.628692] [talos] task loadConfig (1/1): talosctl apply-config --insecure --nodes 192.168.0.2 --cert-fingerprint 'xA9a1t2dMxB0NJ0qH1pDzilWbA3+DK/DjVbFaJBYheE=' --file <config.yaml>
```
If you do not have console access, the IP address may also be discoverable from
your DHCP server.
If you do not have console access, the IP address may also be discoverable from your DHCP server.
Once you have the IP address, you can then apply the correct configuration.
```sh
talosctl apply-config --insecure \
--nodes 192.168.0.2 \
--file cp0.yaml
--file controlplane.yaml
```
The insecure flag is necessary at this point because the PKI infrastructure has
not yet been made available to the node.
The insecure flag is necessary because the PKI infrastructure has not yet been made available to the node.
Note: the connection _will_ be encrypted, it is just unauthenticated.
If you have console access you can extract the server
certificate fingerprint and use it for an additional layer of validation:
If you have console access you can extract the server certificate fingerprint and use it for an additional layer of validation:
```sh
talosctl apply-config --insecure \
@ -287,48 +315,31 @@ certificate fingerprint and use it for an additional layer of validation:
--file cp0.yaml
```
Using the fingerprint allows you to be sure you are sending the configuration to
the correct machine, but it is completely optional.
Using the fingerprint allows you to be sure you are sending the configuration to the correct machine, but it is completely optional.
After the configuration is applied to a node, it will reboot.
Repeat this process for each of the nodes in your cluster.
## Configure your talosctl client
## Understand talosctl, endpoints and nodes
Now that the nodes are running Talos with its full PKI security suite, you need
to use that PKI to talk to the machines.
That is what that `talosconfig` file is for.
It is important to understand the conecpt of `endpoints` and `nodes`.
It is important to understand the concept of `endpoints` and `nodes`.
In short: `endpoints` are the nodes that `talosctl` sends commands to, but `nodes` are the nodes that the command operates on.
The endpoint will forward the command to the nodes, if needed.
### Endpoints
Endpoints are the IP addresses to which the `talosctl` client directly talks.
It is recommended that these point to the set of control plane
nodes, either directly or through a load balancer.
You tell your client (`talosctl`) to communicate with the controlplane nodes by defining the `endpoints`.
These should be the set of control plane nodes, either directly or through a load balancer.
Each endpoint will automatically proxy requests destined to another node, so it is not necessary to change the endpoint configuration just to talk to a different node within the cluster.
This means that you only need access to the controlplane nodes in order to access
the rest of the network.
This is useful for security (worker nodes do not need to have
public IPs, and can still be queried by `talosctl`), and it also makes working
with highly-variable clusters easier, since you only need to know the
controlplane nodes in advance.
Each endpoint will automatically proxy requests destined to another node in the cluster.
This means that you only need access to the control plane nodes in order to access the rest of the network.
Endpoints _do_ need to be members of the same Talos cluster as the
target node, because these proxied connections reply on certificate-based
authentication.
`talosctl` will automatically load balance requests and fail over between all of your endpoints.
`talosctl` will automatically load balance requests and fail over
between all of your endpoints.
You can pass in `--endpoints <IP Address1>,<IP Address2>` as a comma separated list of IP/DNS addresses to affect the endpoints used by the current `talosctl` command.
You can pass in `--endpoints <IP Address1>,<IP Address2>` as a comma separated list of IP/DNS addresses to the current `talosctl` command.
You can also set the `endpoints` in your `talosconfig`, by calling `talosctl config endpoint <IP Address1> <IP Address2>`.
Note: these are space separated, not comma separated.
As an example, if the IP addresses of our controlplane nodes are:
As an example, if the IP addresses of our control plane nodes are:
- 192.168.0.2
- 192.168.0.3
@ -348,23 +359,7 @@ The node is the target you wish to perform the API call on.
> When specifying nodes, their 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.
Some people also like to set a default set of nodes in the `talosconfig`.
This can be done in the same manner, replacing `endpoint` with `node`.
```sh
talosctl --talosconfig=./talosconfig \
config node 192.168.0.2
```
If you do this, however, you could easily reboot the wrong machine, or multiple machines,
by forgetting to declare the right one explicitly.
Our recommendation is to leave `nodes` empty in the talosconfig file, and explicitly pass in the node or nodes to be operated on with each `talosctl` command.
You may provide `-n` or `--nodes` to any `talosctl` command to
supply the node or (comma-delimited) nodes on which you wish to perform the
operation.
Supplying the commandline parameter will override any default nodes
in the configuration file.
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.
For example, to see the containers running on node 192.168.0.200:
@ -378,19 +373,8 @@ To see the etcd logs on *both* nodes 192.168.0.10 and 192.168.0.11:
talosctl -n 192.168.0.10,192.168.0.11 logs etcd
```
To verify default node(s) you're currently configured to use, you can run:
```bash
$ talosctl version
Client:
...
Server:
NODE: <node>
...
```
For a more in-depth discussion of Endpoints and Nodes, please see
[talosctl]({{< relref "../learn-more/talosctl" >}}).
It is possible to set a default set of nodes in the `talosconfig` file, but our recommendation is to explicitly pass in the node or nodes to be operated on with each `talosctl` command.
For a more in-depth discussion of Endpoints and Nodes, please see [talosctl]({{< relref "../learn-more/talosctl" >}}).
### Default configuration file
@ -401,59 +385,46 @@ You _can_ reference which configuration file to use directly with the `--talosco
--nodes 192.168.0.2 version
```
However, `talosctl` comes with tooling to help you integrate and merge this
configuration into the default `talosctl` configuration file.
However, `talosctl` comes with tooling to help you integrate and merge this configuration into the default `talosctl` configuration file.
This is done with the `merge` option.
```sh
talosctl config merge ./talosconfig
```
This will merge your new `talosconfig` into the default configuration file
(`$XDG_CONFIG_HOME/talos/config.yaml`), creating it if necessary.
Like Kubernetes, the `talosconfig` configuration files has multiple "contexts"
which correspond to multiple clusters.
This will merge your new `talosconfig` into the default configuration file (`$XDG_CONFIG_HOME/talos/config.yaml`), creating it if necessary.
Like Kubernetes, the `talosconfig` configuration files has multiple "contexts" which correspond to multiple clusters.
The `<cluster-name>` you chose above will be used as the context name.
## Kubernetes Bootstrap
All of your machines are configured, and your `talosctl` client is set up.
Now, you are ready to bootstrap your Kubernetes cluster.
Bootstrapping your Kubernetes cluster with Talos is as simple as:
```sh
talosctl bootstrap --nodes 192.168.0.2
```
The bootstrap operation should only be called **ONCE** and only on a **SINGLE**
controlplane node!
>The bootstrap operation should only be called **ONCE** and only on a **SINGLE** control plane node!
The IP can be any of your controlplanes (or the loadbalancer, if used for the Talos API endpoint).
The IP can be any of your control planes (or the loadbalancer, if used for the Talos API endpoint).
At this point, Talos will form an `etcd` cluster, generate all of the core
Kubernetes assets, and start the Kubernetes controlplane components.
At this point, Talos will form an `etcd` cluster, generate all of the core Kubernetes assets, and start the Kubernetes control plane components.
After a few moments, you will be able to download your Kubernetes client
configuration and get started:
After a few moments, you will be able to download your Kubernetes client configuration and get started:
```sh
talosctl kubeconfig
```
Running this command will add (merge) you new cluster into you local Kubernetes
configuration in the same way as `talosctl config merge` merged the Talos client
configuration into your local Talos client configuration file.
Running this command will add (merge) you new cluster into your local Kubernetes configuration.
If you would prefer for the configuration to _not_ be merged into your default
Kubernetes configuration file, tell it 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
```
You should now be able to connect to Kubernetes and see your
nodes:
You should now be able to connect to Kubernetes and see your nodes:
```sh
kubectl get nodes
@ -464,3 +435,5 @@ And use talosctl to explore your cluster:
```sh
talosctl -n <NODEIP> dashboard
```
For a list of all the commands and operations that `talosctl` provides, see the [CLI reference]({{< relref "../reference/cli/#talosctl" >}}).

6
website/content/v1.3/talos-guides/install/bare-metal-platforms/matchbox.md
View File

@ -41,7 +41,7 @@ worker.yaml is valid for metal mode
#### Publishing the Machine Configuration Files
In bare-metal setups it is up to the user to provide the configuration files over HTTP(S).
A special kernel parameter (`talos.config`) must be used to inform Talos about _where_ it should retreive its' configuration file.
A special kernel parameter (`talos.config`) must be used to inform Talos about _where_ it should retrieve its configuration file.
To keep things simple we will place `controlplane.yaml`, and `worker.yaml` into Matchbox's `assets` directory.
This directory is automatically served by Matchbox.
@ -149,8 +149,8 @@ Now, create the following groups, and ensure that the `selector`s are accurate f
### Boot the Machines
Now that we have our configuraton files in place, boot all the machines.
Talos will come up on each machine, grab its' configuration file, and bootstrap itself.
Now that we have our configuration files in place, boot all the machines.
Talos will come up on each machine, grab its configuration file, and bootstrap itself.
### Bootstrap Etcd