---
title: "Read a secret on an instance"
description: "Give a compute instance a bot that may read one secret, and fetch the value at boot, so no one has to see the value or put it in user data."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a secret on an instance

A server often needs a value from Secrets, such as a database password. Don't paste the value into
[user data](/compute/user-data-and-metadata#user-data): it's readable from the instance, and
whoever writes it has to see the value. Instead, [attach a bot](/compute/instance-bots) 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:

```json title="read-prod-db.json"
{
  "statements": [
    {
      "effect": "allow",
      "actions": ["secrets.versions.access"],
      "resources": ["ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:sec_a1b2c3d4e5f6"]
    }
  ]
}
```

```sh
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-servers
```

The bot can read every version of that secret, and nothing else, not even the secret's metadata. See [Bots](/iam/bots) and
[Policies](/iam/policies).

## 2. Fetch the value at boot

This user data writes a script that gets a key for the bot from the
[metadata service](/compute/user-data-and-metadata#instance-bot-credentials), reads the `password`
field of the secret's `latest` version with [AccessSecretField](/secrets-api/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.

```yaml title="user-data.yaml"
#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:

```sh
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.yaml
```

The 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](/secrets-api/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 `404` or `403`, 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:

```ini
[Service]
ExecStartPre=/usr/local/bin/fetch-db-password
```

To 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](/databases)'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](#rotate-the-value).

For an application, prefer a [database user](/databases/users-and-logical-databases) 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](/compute/instance-bots#who-can-use-the-bots-access).
- Each read is a billed read, and [Trails](/secrets#trails) records it as an `AccessSecretField`
  event (or `AccessSecretVersion`) 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.

Source: https://docs.ezghcloud.com/secrets/instances/index.mdx
