diff --git a/docs/explanation/robot-support.md b/docs/explanation/robot-support.md index 0895865e..b72c17ac 100644 --- a/docs/explanation/robot-support.md +++ b/docs/explanation/robot-support.md @@ -54,20 +54,8 @@ If you absolutely need to use different names in Robot & Hostname, you can also ## Credentials -Robot API credentials (`ROBOT_USER` / `ROBOT_PASSWORD`) are **optional**. They control which features are available: - -### With Credentials - -All features described above are available: the Node Controller sets labels and addresses from the Robot API, the Node Lifecycle Controller manages shutdown detection and node deletion, and the Service Controller adds Robot servers as Load Balancer targets. +Robot API credentials (`ROBOT_USER` / `ROBOT_PASSWORD`) are required for full functionality. All features described above — Node Controller labels and addresses, Node Lifecycle Controller shutdown detection, and Service Controller Load Balancer targets — depend on Robot API access. If you only plan to use a single Robot server, you can also use an "Admin login" (see the `Admin login` tab on the [server administration page](https://robot.hetzner.com/server)) for this server instead of the account credentials. -### Without Credentials - -When `robot.enabled` is set to `true` but no `ROBOT_USER` / `ROBOT_PASSWORD` are provided, the HCCM operates in a limited mode: - -- **Service Controller (Load Balancers)**: Fully functional. Robot servers with `hrobot://` provider IDs are added as IP targets using their `InternalIP` from the Kubernetes Node object. This is ideal for setups where Robot servers are connected via a vSwitch and only the Load Balancer integration is needed. -- **Node Controller**: Must be disabled (`--controllers=*,-cloud-node,-cloud-node-lifecycle`), as it requires the Robot API to fetch server metadata. -- **Node Lifecycle Controller**: Must be disabled (same flag as above). - -This mode is useful when you manage nodes externally (e.g., via Talos or another provisioning tool) and only need the CCM for Load Balancer target management. It avoids exposing account-wide Robot API credentials to the cluster. +> **Running without credentials:** If you manage nodes externally (e.g., via Talos) and only need the Load Balancer controller, you can omit Robot API credentials. The HCCM will derive targets from the Kubernetes Node's `InternalIP` instead. This requires `use-private-ip` and disabling the node controllers. See the [LB-only without credentials guide](../guides/robot/lb-only-without-credentials.md) for setup instructions. diff --git a/docs/guides/robot/README.md b/docs/guides/robot/README.md index 71265372..b2be7cbd 100644 --- a/docs/guides/robot/README.md +++ b/docs/guides/robot/README.md @@ -4,4 +4,5 @@ In this folder, you should find guides for you to accomplish specific tasks with - [Quickstart](quickstart.md) - [Private Networks](private-networks.md) +- [Load Balancer Only Without Credentials](lb-only-without-credentials.md) - [Migrating from Syself](migrating-from-syself.md) diff --git a/docs/guides/robot/lb-only-without-credentials.md b/docs/guides/robot/lb-only-without-credentials.md new file mode 100644 index 00000000..36f3d1c2 --- /dev/null +++ b/docs/guides/robot/lb-only-without-credentials.md @@ -0,0 +1,45 @@ +# Load Balancer-Only Setup Without Robot API Credentials + +If you manage Robot nodes externally (e.g., via Talos or another provisioning tool) and only need the HCCM to add Robot servers as Load Balancer IP targets, you can run without Robot API credentials. This avoids exposing account-wide Robot API credentials to the cluster. + +In this mode, the HCCM derives Load Balancer targets from the Kubernetes Node's `InternalIP` instead of querying the Robot API. The Node Controller and Node Lifecycle Controller are not available, as they require the Robot API to fetch server metadata. + +## Prerequisites + +- Nodes must be initialized with a provider ID +- Robot servers must be connected to a vSwitch with an `InternalIP` configured on each Node. +- The node controllers must be disabled, as they will fail without Robot API access. + +## Setup + +1. Create a secret without Robot credentials: + +```bash +export HCLOUD_TOKEN= +export HCLOUD_NETWORK= +kubectl -n kube-system create secret generic hcloud \ + --from-literal=token=$HCLOUD_TOKEN \ + --from-literal=network=$HCLOUD_NETWORK +``` + +2. Install the Helm chart with Robot enabled, node and route controllers disabled, and private IPs configured: + +```bash +helm repo add hcloud https://charts.hetzner.cloud +helm repo update hcloud +helm install hcloud/hcloud-cloud-controller-manager \ + --set robot.enabled=true \ + --set networking.enabled=false \ + --set env.HCLOUD_NETWORK_ROUTES_ENABLED.value="false" \ + --set env.HCLOUD_NETWORK.valueFrom.secretKeyRef.name=hcloud \ + --set env.HCLOUD_NETWORK.valueFrom.secretKeyRef.key=network \ + --set args='{--controllers=*\,-cloud-node\,-cloud-node-lifecycle}' +``` + +3. Verify that your Robot Nodes have an `InternalIP`: + +```bash +kubectl get nodes -o json | jq ".items.[].status.addresses" +``` + +4. Annotate your Services with `load-balancer.hetzner.cloud/use-private-ip: "true"` to use the `InternalIP` as the Load Balancer target. See the [Private Networks guide](./private-networks.md) for more details. diff --git a/docs/guides/robot/private-networks.md b/docs/guides/robot/private-networks.md index f5705185..2c7cf837 100644 --- a/docs/guides/robot/private-networks.md +++ b/docs/guides/robot/private-networks.md @@ -6,9 +6,9 @@ As a result, the annotation `load-balancer.hetzner.cloud/use-private-ip` can be ## Prerequisite -Enable Robot support as outlined in the [Robot setup guide](./quickstart.md). For a Robot server we pass along configured InternalIPs, that do not appear as an ExternalIP and are within the configured address family. Check with `kubectl get nodes -o json | jq ".items.[].status.addresses"` if you have configured an InternalIP. +Enable Robot support as outlined in the [Robot setup guide](./quickstart.md). As mentioned there, for a Robot server we pass along configured InternalIPs, that do not appear as an ExternalIP and are within the configured address family. Check with `kubectl get nodes -o json | jq ".items.[].status.addresses"` if you have configured an InternalIP. -Robot API credentials (`ROBOT_USER` / `ROBOT_PASSWORD`) are optional for this use case. When credentials are not provided, the HCCM derives IP targets directly from the Kubernetes Node's `InternalIP` instead of querying the Robot API. This requires disabling the node controllers: `--controllers=*,-cloud-node,-cloud-node-lifecycle`. See the [Robot Support explanation](../../explanation/robot-support.md#without-credentials) for details. +> If you don't need Robot API credentials for this setup, see the [LB-only without credentials guide](./lb-only-without-credentials.md). ## Configuration