platform-tools

platform-tools provides reusable command-line helpers used across the platform project repositories.

Canonical repository: https://codeberg.org/rch/platform-tools

All shared platform helper tools live in this repository. The platform repositories are split by responsibility so provisioning, configuration, deployment, runtime tooling, private operator config, template building, and shared helpers can evolve independently.

Platform Repositories

Tools

Install

Clone the canonical tools repository and install maintained CLI helpers into ~/.local/bin:

git clone https://codeberg.org/rch/platform-tools
cd platform-tools
make install

Use another install directory when needed. PKI helpers also install shared library and template assets under SHARE_DIR:

make install \
 INSTALL_DIR="$PWD/.tools/bin" \
 SHARE_DIR="$PWD/.tools/share/platform-tools"

Ensure the install directory is on PATH when using tools by command name.

Requirements

Core local requirements:

• bash
• make
• standard Unix tools such as awk, cmp, cp, date, find, grep, mkdir, mktemp, sed, stat, and tar

PKI helpers require:

• openssl
• GNU date for certificate expiry calculations
• tar with --no-wildcards support for safe PKI backup exclusions
• age for encrypted platform-pki-backup output; plain .tar.gz backup requires explicit --allow-plain-backup

SSH and Proxmox helpers require:

• ssh for remote execution modes
• pveum on the Proxmox host for platform-proxmox-token-init
• qm on the Proxmox host for platform-proxmox-vm-cleanup
• jq on the Proxmox host when platform-proxmox-token-init --write-token-file is used over SSH

Bastion policy helpers require:

• python3
• PyYAML

Optional verification tools:

• shellcheck for make shellcheck
• gitleaks for local secret scanning

Verify

Run syntax checks for maintained scripts:

make verify

Run ShellCheck when it is available:

make shellcheck

Run maintained behavior tests:

make test

Quick Usage

Create a purpose-specific SSH key directly:

platform-ssh-init \
 --key-path ~/.ssh/platform-example_ed25519 \
 --comment "platform example" \
 --print-public-key

Or use a config file from private operator config:

platform-ssh-init ../platform-private/infra/ssh/production-cloud-init.env --print-public-key

Collect facts from a VM:

sudo platform-vm-env-collect

Create the outside-Git local secret namespace with infra/, config/, and pki/:

platform-config-init

Bootstrap the Proxmox API token identity over SSH:

platform-proxmox-token-init \
 --ssh root@<proxmox-ip> \
 --proxmox-user tofu@pve \
 --token-id platform \
 --role Administrator \
 --path / \
 --write-token-file ~/.config/platform-infrastructure/infra/proxmox.token

Check Proxmox token bootstrap prerequisites first:

platform-proxmox-token-init --ssh root@<proxmox-ip> --write-token-file ~/.config/platform-infrastructure/infra/proxmox.token --check

Clean up one Proxmox VM by VMID after verifying the printed target:

platform-proxmox-vm-cleanup --ssh root@<proxmox-ip> --vmid 9900

Initialize PKI state and issue a test service certificate from inventory:

platform-pki-init
platform-pki-root-create --name "Platform Example Root CA" --org "Platform Example" --country "PL"
platform-pki-intermediate-create --name "Platform Example Intermediate CA" --org "Platform Example" --country "PL"
platform-pki-service-issue platform-example
platform-pki-service-verify platform-example
platform-pki-list-expiry

For non-interactive PKI automation with encrypted CA keys, pass restricted passphrase files such as --root-pass-file /run/secrets/platform-pki-root-pass and --intermediate-pass-file /run/secrets/platform-pki-intermediate-pass. See docs/pki-openssl.md for the full flow and safety rules.

Validate and render a Kubernetes bastion access policy:

POLICY_OUT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/bastion-policy.XXXXXX")"
platform-bastion-policy validate \
 --input ../platform-private/config/files/k8s-bastion/dev/access-policy.yaml
platform-bastion-policy render-host \
 --input ../platform-private/config/files/k8s-bastion/dev/access-policy.yaml \
 --output "$POLICY_OUT_DIR/access-policy.yaml"
platform-bastion-policy render-csr-configmap \
 --input ../platform-private/config/files/k8s-bastion/dev/access-policy.yaml \
 --name bastion-csr-policy \
 --namespace bastion-system \
 --output "$POLICY_OUT_DIR/bastion-csr-policy.configmap.yaml"

Add a name guard and non-interactive confirmation for automation:

platform-proxmox-vm-cleanup \
 --ssh root@<proxmox-ip> \
 --identity-file ~/.ssh/platform-template-builder_ed25519 \
 --vmid 9900 \
 --name platform-template-smoke-9900 \
 --yes

If running directly from a checkout before install:

sudo ./bin/platform-vm-env-collect
./bin/platform-config-init
./bin/platform-proxmox-token-init --ssh root@<proxmox-ip>
./bin/platform-proxmox-vm-cleanup --ssh root@<proxmox-ip> --identity-file ~/.ssh/platform-template-builder_ed25519 --vmid 9900
./bin/platform-pki-init
./bin/platform-bastion-policy validate --input examples/bastion-policy/access-policy.example.yaml

Documentation

Security

Keep real secrets outside Git. Do not commit VM collection output, generated archives, SSH keys, private .env files, token files, PKI CA material, service private keys, issued real certificates, PKI exports, PKI backups, or copied private configuration.

Use ~/.config/platform-infrastructure/ for local secret material. Private but non-secret operator configuration belongs in private Git, such as platform-private.

Collected VM reports and PKI exports can contain sensitive environment details even when they do not contain obvious passwords. Review generated files before sharing them.

PKI passphrase files are plaintext secrets. Keep them outside Git, restrict them to mode 600 or stricter, use a first-line passphrase of at least 16 characters with non-whitespace content, and prefer temporary secret-manager mounts over long-lived files.

PKI Ansible exports contain service private keys. Custom export directories must be absolute paths with current-user-owned parents that are not group- or world-writable and do not contain symlink components.

Real bastion access policies can reveal users, groups, cluster endpoints, and access intent. Keep real policies in platform-private; only fake examples belong in this repository.

License

This project is licensed under the MIT License. See LICENSE for details.