Neph
Neph (from ancient Greek néphos, meaning cloud) is a Lyceum-internal tool for interacting with our infrastructure. In essence its purpose is to simplify common tasks when working with Terraform, Ansible, Kubernetes... that are either Lyceum-specific or frequently required.
Warning
Neph can operate on all of our deploy environments (via the --env option)
including production! Only make modifications to the latter if you're
absolutely sure what you're doing.
Installation
Neph is a Python program that is part of the monorepo and thus managed by uv.
I.e. from within the monorepo you can always execute it via uv run neph ....
Configuration
Neph automatically reads config key-value pairs from
/infra/inventory/*/config.yml whenever it needs a config value. Internally,
it uses SOPS for reading encrypted values.
It also provides convenience commands for working with config key-value pairs:
List all known config keys:
neph config list --env <deploy-env>
Get a specific config value:
neph config get LYC_<...> --env <deploy-env>
Finally we can dump all config key-value pairs with:
neph config dump --env <deploy-env>
The dump command also accepts --output shell to emit shell-compatible
exports, or --output github to emit lines suitable for $GITHUB_ENV in a
GitHub Actions workflow.
For example, in your shell:
. <(neph config dump --env <deploy-env> --output shell)
Or in a GitHub Actions workflow:
run: neph config dump --env <deploy-env> --output github >> "$GITHUB_ENV"
Terraform
TODO
Ansible
TODO
Kubernetes
The main way to interact with our k3s clusters is via kubectl. To bootstrap
that, Neph can automatically create a kubeconfig file for you:
neph k8s fetch-kubeconfig --env <deploy-env> (--file <file>) (--overwrite)
If --file is not specified, the kubeconfig is written to ~/.kube/config. If
you already have that file it is automatically updated to include the k3s
cluster. By default, existing entries for a cluster will not be overwritten; If
the cluster is recreated or the cert is rotated, you'll have to specify
--overwrite to do so.
You can then switch to the cluster with:
kubectl config use-context lyceum-k3s-<deploy-env>
Interacting with Databases
Neph can be used to quickly drop into a psql session for one of our
databases. To do this simply run:
neph db connect <db-name> --env <deploy-env> (--admin-access)
--admin-access should typically not be required unless you e.g. need to
delete from or drop tables and the default database user does not have the
privileges to do so.
You can also run DB migrations with:
neph db migrate <db-name> --env <deploy-env> (--force-version <force-version>)
If --force-version is set, migrations will continue from the next version
after the specified one or the very first if --force-version is set to zero.
Billing
In order to simplify testing, Neph can access some of Croesus' (TODO(Timo Nicolai): Add link) internal endpoints. Since billing happens on an org basis, personal org IDs have to be supplied to interact with the billing accounts of specific users.
Supported operations are:
neph billing org-info <org-id> --env <deploy-env>
which returns info about the org's current balance and suspension status, and:
neph billing (credit-org|debit-org|reset-org-balance) <org-id> <amount> --env <deploy-env>
where <amount> must be a valid decimal number.