.
This commit is contained in:
commit
08c0e9c107
33 files changed
+4312
No files matched your search
@@ -0,0 +1,439 @@
|
||||
# Machine Env Service
|
||||
|
||||
IMDSv2-compatible local metadata daemon for homelab machines. Each machine runs one daemon, and local processes or containers can fetch machine-scoped metadata and allowlisted Infisical secrets through HTTP without holding Infisical credentials.
|
||||
|
||||
## What It Exposes
|
||||
|
||||
Token endpoint:
|
||||
|
||||
```text
|
||||
PUT /latest/api/token
|
||||
```
|
||||
|
||||
Metadata endpoints require `X-aws-ec2-metadata-token`:
|
||||
|
||||
```text
|
||||
/latest/meta-data/
|
||||
/latest/meta-data/hostname
|
||||
/latest/meta-data/local-hostname
|
||||
/latest/meta-data/local-ipv4
|
||||
/latest/meta-data/mac
|
||||
/latest/meta-data/machine-id
|
||||
/latest/meta-data/environment
|
||||
/latest/meta-data/role
|
||||
/latest/meta-data/tags/
|
||||
/latest/meta-data/tags/<KEY>
|
||||
/latest/meta-data/tags/instance/
|
||||
/latest/meta-data/tags/instance/<KEY>
|
||||
/latest/meta-data/secrets/
|
||||
/latest/meta-data/secrets/<KEY>
|
||||
/latest/dynamic/instance-identity/document
|
||||
/latest/user-data
|
||||
```
|
||||
|
||||
`/latest/meta-data/secrets-bundle` is available only when `ALLOW_SECRETS_BUNDLE=true`.
|
||||
|
||||
## Configuration
|
||||
|
||||
The daemon reads its own dotenv-style config file.
|
||||
|
||||
Default paths:
|
||||
|
||||
```text
|
||||
Linux: /etc/machine-env-service/env
|
||||
macOS: /usr/local/etc/machine-env-service/env
|
||||
```
|
||||
|
||||
Override with:
|
||||
|
||||
```bash
|
||||
MACHINE_ENV_CONFIG=/path/to/env
|
||||
```
|
||||
|
||||
Minimum config:
|
||||
|
||||
```env
|
||||
INFISICAL_ACCESS_TOKEN=
|
||||
INFISICAL_PROJECT_ID=
|
||||
INFISICAL_ENVIRONMENT=prod
|
||||
|
||||
KNOWN_SECRET_KEYS=FOO,BAR
|
||||
METADATA_PORT=8675
|
||||
REFRESH_INTERVAL_SEC=60
|
||||
```
|
||||
|
||||
Optional machine metadata:
|
||||
|
||||
```env
|
||||
MACHINE_ID=
|
||||
MACHINE_HOSTNAME=
|
||||
MACHINE_LOCAL_HOSTNAME=
|
||||
MACHINE_LOCAL_IPV4=
|
||||
MACHINE_MAC=
|
||||
MACHINE_ROLE=homelab-node
|
||||
MACHINE_TAGS=site=home,tier=prod
|
||||
USER_DATA=
|
||||
USER_DATA_FILE=
|
||||
```
|
||||
|
||||
If machine fields are empty, the daemon derives hostname, IPv4, MAC, and machine-id from the OS where possible.
|
||||
|
||||
Secret allowlist variables are checked in this order:
|
||||
|
||||
```text
|
||||
KNOWN_SECRET_KEYS
|
||||
EXPOSED_SECRET_KEYS
|
||||
SECRET_ALLOWLIST
|
||||
SECRET_WHITELIST
|
||||
```
|
||||
|
||||
Values can be comma-separated or whitespace-separated.
|
||||
|
||||
## Local Development
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
Run locally without binding `169.254.169.254:80`:
|
||||
|
||||
```bash
|
||||
NODE_ENV=dev LINK_LOCAL_LISTENER_ENABLED=false npm start
|
||||
```
|
||||
|
||||
Request a token:
|
||||
|
||||
```bash
|
||||
TOKEN=$(
|
||||
curl -fsS -X PUT \
|
||||
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
|
||||
http://127.0.0.1:8675/latest/api/token
|
||||
)
|
||||
```
|
||||
|
||||
Fetch metadata:
|
||||
|
||||
```bash
|
||||
curl -fsS \
|
||||
-H "X-aws-ec2-metadata-token: $TOKEN" \
|
||||
http://127.0.0.1:8675/latest/meta-data/hostname
|
||||
```
|
||||
|
||||
Fetch a secret:
|
||||
|
||||
```bash
|
||||
curl -fsS \
|
||||
-H "X-aws-ec2-metadata-token: $TOKEN" \
|
||||
http://127.0.0.1:8675/latest/meta-data/secrets/FOO
|
||||
```
|
||||
|
||||
Or use:
|
||||
|
||||
```bash
|
||||
METADATA_BASE_URL=http://127.0.0.1:8675 ./examples/fetch-secret.sh FOO
|
||||
```
|
||||
|
||||
## Ubuntu Install
|
||||
|
||||
The included systemd units assume the app lives at `/opt/machine-env-service`.
|
||||
|
||||
Install files:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/machine-env-service
|
||||
sudo chown -R "$USER:$USER" /opt/machine-env-service
|
||||
|
||||
rsync -a \
|
||||
--exclude .git \
|
||||
--exclude node_modules \
|
||||
--exclude dist \
|
||||
--exclude env-vars \
|
||||
./ /opt/machine-env-service/
|
||||
|
||||
cd /opt/machine-env-service
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
Create service user:
|
||||
|
||||
```bash
|
||||
sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin machine-env || true
|
||||
```
|
||||
|
||||
Create config:
|
||||
|
||||
```bash
|
||||
sudo install -d -o machine-env -g machine-env -m 0700 /etc/machine-env-service
|
||||
sudo cp deploy/systemd/machine-env-service.env.example /etc/machine-env-service/env
|
||||
sudo nano /etc/machine-env-service/env
|
||||
sudo chown machine-env:machine-env /etc/machine-env-service/env
|
||||
sudo chmod 0600 /etc/machine-env-service/env
|
||||
```
|
||||
|
||||
Install and start systemd units:
|
||||
|
||||
```bash
|
||||
sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
|
||||
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now machine-env-setup-link-local.service
|
||||
sudo systemctl enable --now machine-env-service.service
|
||||
```
|
||||
|
||||
Check logs:
|
||||
|
||||
```bash
|
||||
systemctl status machine-env-service.service
|
||||
journalctl -u machine-env-service.service -f
|
||||
```
|
||||
|
||||
Test the link-local endpoint:
|
||||
|
||||
```bash
|
||||
TOKEN=$(
|
||||
curl -fsS -X PUT \
|
||||
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
|
||||
http://169.254.169.254/latest/api/token
|
||||
)
|
||||
|
||||
curl -fsS \
|
||||
-H "X-aws-ec2-metadata-token: $TOKEN" \
|
||||
http://169.254.169.254/latest/meta-data/
|
||||
```
|
||||
|
||||
## macOS Install
|
||||
|
||||
The included launchd plists assume:
|
||||
|
||||
```text
|
||||
App path: /opt/machine-env-service
|
||||
Node path: /usr/local/bin/node
|
||||
Config path: /usr/local/etc/machine-env-service/env
|
||||
```
|
||||
|
||||
Check your Node path first:
|
||||
|
||||
```bash
|
||||
command -v node
|
||||
```
|
||||
|
||||
If it is not `/usr/local/bin/node`, either update `deploy/launchd/us.dahyeon.machine-env-service.plist` before installing or create a system-visible symlink:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /usr/local/bin
|
||||
sudo ln -sf "$(command -v node)" /usr/local/bin/node
|
||||
```
|
||||
|
||||
When Node comes from `nvm`, the symlink is the quickest local setup. A Homebrew Node installed at a stable path is usually better for a long-lived daemon.
|
||||
|
||||
Install files:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/machine-env-service
|
||||
sudo chown -R "$(id -un):admin" /opt/machine-env-service
|
||||
|
||||
rsync -a \
|
||||
--exclude .git \
|
||||
--exclude node_modules \
|
||||
--exclude dist \
|
||||
--exclude env-vars \
|
||||
./ /opt/machine-env-service/
|
||||
|
||||
cd /opt/machine-env-service
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
Create config:
|
||||
|
||||
```bash
|
||||
sudo install -d -m 0700 /usr/local/etc/machine-env-service
|
||||
sudo cp deploy/launchd/machine-env-service.env.example /usr/local/etc/machine-env-service/env
|
||||
sudo nano /usr/local/etc/machine-env-service/env
|
||||
sudo chown root:wheel /usr/local/etc/machine-env-service/env
|
||||
sudo chmod 0600 /usr/local/etc/machine-env-service/env
|
||||
```
|
||||
|
||||
Install and start launchd daemons:
|
||||
|
||||
```bash
|
||||
sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
|
||||
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/
|
||||
|
||||
sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
|
||||
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
|
||||
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
|
||||
```
|
||||
|
||||
Check logs:
|
||||
|
||||
```bash
|
||||
sudo launchctl print system/us.dahyeon.machine-env-service
|
||||
tail -f /var/log/machine-env-service.log
|
||||
tail -f /var/log/machine-env-service.err.log
|
||||
```
|
||||
|
||||
Test:
|
||||
|
||||
```bash
|
||||
TOKEN=$(
|
||||
curl -fsS -X PUT \
|
||||
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
|
||||
http://169.254.169.254/latest/api/token
|
||||
)
|
||||
|
||||
curl -fsS \
|
||||
-H "X-aws-ec2-metadata-token: $TOKEN" \
|
||||
http://169.254.169.254/latest/meta-data/hostname
|
||||
```
|
||||
|
||||
Docker Desktop on macOS usually cannot route container traffic to host `169.254.169.254`. Use the LAN listener instead:
|
||||
|
||||
```text
|
||||
http://host.docker.internal:8675/latest/meta-data/...
|
||||
```
|
||||
|
||||
## Update
|
||||
|
||||
Restarting the daemon invalidates issued IMDSv2 tokens. Clients should request a new token after an update.
|
||||
|
||||
If `/opt/machine-env-service` is a git checkout:
|
||||
|
||||
```bash
|
||||
cd /opt/machine-env-service
|
||||
git pull
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
If you deploy from another checkout:
|
||||
|
||||
```bash
|
||||
rsync -a --delete \
|
||||
--exclude .git \
|
||||
--exclude node_modules \
|
||||
--exclude dist \
|
||||
--exclude env-vars \
|
||||
./ /opt/machine-env-service/
|
||||
|
||||
cd /opt/machine-env-service
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
Do not overwrite the machine config file:
|
||||
|
||||
```text
|
||||
Linux: /etc/machine-env-service/env
|
||||
macOS: /usr/local/etc/machine-env-service/env
|
||||
```
|
||||
|
||||
Restart after code-only updates:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart machine-env-service.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
|
||||
```
|
||||
|
||||
If systemd unit files changed:
|
||||
|
||||
```bash
|
||||
sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
|
||||
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart machine-env-setup-link-local.service
|
||||
sudo systemctl restart machine-env-service.service
|
||||
```
|
||||
|
||||
If launchd plist files changed:
|
||||
|
||||
```bash
|
||||
sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
|
||||
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/
|
||||
sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
|
||||
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
|
||||
|
||||
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist 2>/dev/null || true
|
||||
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist 2>/dev/null || true
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
|
||||
```
|
||||
|
||||
Check after updating:
|
||||
|
||||
```bash
|
||||
systemctl status machine-env-service.service
|
||||
journalctl -u machine-env-service.service -n 100
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo launchctl print system/us.dahyeon.machine-env-service
|
||||
tail -n 100 /var/log/machine-env-service.err.log
|
||||
```
|
||||
|
||||
## Operations
|
||||
|
||||
Restart:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart machine-env-service.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
|
||||
```
|
||||
|
||||
Stop:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop machine-env-service.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If `curl http://169.254.169.254/latest/api/token` fails with `Couldn't connect to server`, check the link-local alias and daemon separately:
|
||||
|
||||
```bash
|
||||
ifconfig lo0 | grep 169.254.169.254
|
||||
sudo launchctl print system/us.dahyeon.machine-env-service
|
||||
```
|
||||
|
||||
If launchd shows `last exit code = 78: EX_CONFIG` and the plist points to `/usr/local/bin/node`, verify that Node exists there:
|
||||
|
||||
```bash
|
||||
ls -l /usr/local/bin/node
|
||||
command -v node
|
||||
```
|
||||
|
||||
Fix a missing `/usr/local/bin/node` with:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /usr/local/bin
|
||||
sudo ln -sf "$(command -v node)" /usr/local/bin/node
|
||||
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service
|
||||
```
|
||||
|
||||
Then retry token issuance.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Keep the config file mode at `0600`.
|
||||
- Do not commit `env-vars/*.env`, production config files, or access tokens.
|
||||
- Only allowlist secrets that should be readable by local machine workloads.
|
||||
- Block `METADATA_PORT` from untrusted networks.
|
||||
- Requests with `X-Forwarded-For` are rejected.
|
||||
- Metadata requests require IMDSv2-style tokens; token TTL is `1..21600` seconds.
|
||||
Reference in new issue
Block a user