A server often needs a value from Secrets, such as a database password. Don’t paste the value into user data: it’s readable from the instance, and whoever writes it has to see the value. Instead, attach a bot that may read only that secret, and let the instance fetch the value itself. The user data then names the secret, never its value, and you or an agent can set up the server without reading it.
1. Create a bot that can read only that secret
Reading values needs only secrets.versions.access. Allow it on the secret’s resource name, and on
nothing else. ezgh secrets get prod/db shows the resource name, which holds the organization,
project and secret IDs the script below uses:
{
"statements": [
{
"effect": "allow",
"actions": ["secrets.versions.access"],
"resources": ["ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:sec_a1b2c3d4e5f6"]
}
]
}ezgh iam policies create read-prod-db --document @read-prod-db.json
ezgh iam bots create web-servers
ezgh iam policies attach read-prod-db --bot web-serversThe bot can read every version of that secret, and nothing else, not even the secret’s metadata. See Bots and Policies.
2. Fetch the value at boot
This user data writes a script that gets a key for the bot from the
metadata service, reads the password
field of the secret’s latest version with AccessSecretField,
and writes it to a file only root can read. It runs the script at first boot. It uses curl and
python3, and the metadata service’s IPv6 address, which works on instances without IPv4.
#cloud-config
write_files:
- path: /usr/local/bin/fetch-db-password
permissions: "0755"
content: |
#!/bin/sh
set -eu
ORG=org_k3f9a0x2m7qp
PROJECT=prj_g7h8i9j0k1l2
SECRET=sec_a1b2c3d4e5f6
MD=http://[fd65:7a67:6800::254]/ezgh/v1
TOKEN=$(curl -fsS -X PUT -H "EZGH-Metadata: true" -H "EZGH-Metadata-Token-TTL-Seconds: 60" "$MD/token")
KEY=$(curl -fsS -H "EZGH-Metadata: true" -H "EZGH-Metadata-Token: $TOKEN" "$MD/credentials" |
python3 -c 'import json, sys; print(json.load(sys.stdin)["apiKey"])')
umask 077
mkdir -p /etc/myapp
curl -fsS -H "Authorization: Bearer $KEY" \
"https://secrets.ezghcloud.com/v1/organizations/$ORG/projects/$PROJECT/secrets/$SECRET/versions/latest/fields/password" |
python3 -c 'import json, sys; print(json.load(sys.stdin)["value"], end="")' > /etc/myapp/db-password.new
mv /etc/myapp/db-password.new /etc/myapp/db-password
runcmd:
- [/usr/local/bin/fetch-db-password]Launch the instance with the bot:
ezgh compute instances launch web-1 --instance-type gs-1.large --image linux/ubuntu:26.04 \
--ssh-key laptop --bot bot_a1b2c3d4e5f6 --user-data user-data.yamlThe value is now in /etc/myapp/db-password, mode 0600. Point your application at the file, or
change the script to write the value where the application expects it, such as an environment file
for its systemd unit.
- To read every field of a version at once, use
AccessSecretVersion (
…/versions/latest/value), which answers{ "version", "fields" }. - A binary value comes back as
{ "base64": "…" }; decode it before writing it. - A wrong ID, or a secret the bot may not read, answers
404or403, and the script stops without changing the file.
Rotate the value
Write a new version of the secret. The instance gets it the next time the script runs, because it
reads latest. Run the script again before your application starts, for example from its systemd
unit, then restart the application:
[Service]
ExecStartPre=/usr/local/bin/fetch-db-passwordTo stay on one version until you choose to move, put its number in place of latest in the URL.
A managed database’s password
A database’s admin password is in a secret in the database’s project, with the fields
username and password. ezgh databases get shows it as Admin Secret (sec_…), and
ezgh secrets get sec_… its resource name. Use them in the policy and the script above.
ezgh databases rotate-admin-password writes a new version, which the instance picks up as
described in Rotate the value.
For an application, prefer a database user with only the
access it needs. Its secret has the same fields plus host, port, database, engine and
uri, and you read it the same way: fetch the uri field for a connection URI.
Who can read it
- Everything running on the instance can fetch the bot’s keys, and so read the secret. See Who can use the bot’s access.
- Each read is a billed read, and Trails records it as an
AccessSecretFieldevent (orAccessSecretVersion) by the bot, with the instance as its source. The value is never recorded. - To stop the instance reading the secret, detach the policy from the bot, which takes effect on the next request. Removing the bot from the instance leaves a key it already fetched working for at most 10 minutes.