Skip to content

docs: fix confusing loopback IPs in environment setup#827

Open
jkomg wants to merge 1 commit into
k0rdent:mainfrom
jkomg:clarify-kcm-machine-ips
Open

docs: fix confusing loopback IPs in environment setup#827
jkomg wants to merge 1 commit into
k0rdent:mainfrom
jkomg:clarify-kcm-machine-ips

Conversation

@jkomg

@jkomg jkomg commented Jul 8, 2026

Copy link
Copy Markdown

Currently, the "Setup Environment" code block defines MACHINE_0_ADDRESS and MACHINE_1_ADDRESS using loopback addresses (127.0.0.1). This is causing confusion for developers who assume these are valid defaults or that the step applies to a local deployment. Furthermore, these variables are not used in the Secret generation block below them.

This PR updates the documentation to use explicit, non-routable documentation IP addresses (192.0.2.x) and adds a comment explicitly telling developers to replace them.

Changes to the Documentation Page
Change this:

# Setup Environment
KEY_PATH=~/.ssh/id_ed25519
PRIVATE_SSH_KEY_B64=$(cat $KEY_PATH | base64 -w 0)
SECRET_NAME=remote-ssh-key
KCM_SYSTEM_NS=kcm-system
CREDENTIAL_NAME=remote-cred
RESOURCE_TEMPLATE_NAME=remote-ssh-key-resource-template
CLUSTER_DEPLOYMENT_NAME=my-remote-clusterdeployment1
MACHINE_0_ADDRESS=127.0.0.1
MACHINE_1_ADDRESS=127.0.0.2
# Setup Environment
KEY_PATH=~/.ssh/id_ed25519
PRIVATE_SSH_KEY_B64=$(cat $KEY_PATH | base64 -w 0)
SECRET_NAME=remote-ssh-key
KCM_SYSTEM_NS=kcm-system
CREDENTIAL_NAME=remote-cred
RESOURCE_TEMPLATE_NAME=remote-ssh-key-resource-template
CLUSTER_DEPLOYMENT_NAME=my-remote-clusterdeployment1

# REPLACE THESE: Target IP addresses of your actual remote nodes
MACHINE_0_ADDRESS=192.0.2.10
MACHINE_1_ADDRESS=192.0.2.11

Why this fix works better:

The Comment Flag: Adding # REPLACE THESE explicitly tells a developer scanning the code that action is required on their part.

RFC 5737 Documentation IPs: Using 192.0.2.X addresses is the industry standard for documentation. They are explicitly reserved for examples and are completely unroutable, meaning if a developer accidentally copy-pastes them, the script will instantly fail cleanly with a "network unreachable" or "timeout" error, rather than behaving strangely on localhost.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant