BUILDING Parts of this page describe what is not built yet, and each says so.

Secrets

A reference is a name that points at a secret in your own store. A secret that a reference names stays in your store: RunningLake keeps the name and what it has found out about it, and no call that reads or writes a reference carries a value. This page says what a reference is, how to propose one, what a check says, who can read the record of checks, and which parts do not exist.

Where a secret lives

A secret that a reference names lives in your own store, in your own cloud account. The reference names it so that a data plane in that account is the one that looks for it; the control plane never reads it. RunningLake holds no store of its own for the secrets a reference names: a reference that names runninglake as its store is refused by name.

An organisation that is on its trial is offered no secrets. Its list of references is refused as a whole, in the console, with rl secret list and in the API, with one sentence: “Secrets are not offered on the shared trial plane. A secret is read only by a plane in your own cloud, from your own store.”

A reference

A reference is a file in your project’s repository, like a table or a pipeline. Save this as secretreferences/payroll-warehouse-reader.yaml:

apiVersion: runninglake.io/v1alpha1
kind: SecretReference
metadata:
  name: payroll-warehouse-reader
spec:
  store: customer
  provider: aws-secrets-manager
  path: payroll/warehouse-reader
  key: password

store is customer: your own store.
provider is the kind of store: aws-secrets-manager. Leave it out when the plane has exactly one.
path is the secret’s name in your store, never its ARN. A name with a colon is refused, and so is one that begins RL_ or with a slash, or that reads like a secret value rather than a name.
key is the name of a field inside a secret that holds a JSON object. Leave it out for a secret that is a plain string.
version is an optional pin: a version id, or AWSCURRENT or AWSPREVIOUS. It is declared and recorded. The last section of this page says where that stands.

A reference holds no value, and the gate refuses a file that has one where a name goes. rl diff checks the file offline, exactly as the control plane would. A Source names a reference by its name, in credentials.secretRef. The SecretReference kind lists every field.

Propose a reference

A reference is a change like any other, so it is proposed as one. With rl, add the file and run rl plan and rl deploy as Start here does for a table; the change set is reviewed and applied as Review and approval describes.

In the console, Secrets lists the references an environment declares, and Propose a reference opens an editor for the reference’s name, the store, the secret’s name in the store, an optional key and the version choice. There is no control that takes a value. Check this draft asks the plane the same question as a check, about a name you have typed, and it creates neither a reference nor a proposal. Propose this reference opens the Changes page with the file filled in, and writes nothing until you plan it there.

Proposing needs config.propose, which owners, admins and engineers hold, and the console draws the button only for a role that holds it. Listing and reading references needs config.read, which every role holds, a viewer included.

Check it

A check asks the plane your environment is bound to to ask your own store for the version of the secret a reference names, and tells you what the store answered. It never reads the value. These are the words a check has for what the store answered:

Found is the word for a plane that found a version, and the answer carries the time it did.
Not found, Deleted in your store, Access denied and Name refused are the words for a reference that will not be found as declared. Not found is a secret your store holds with no current version. Access denied is a store that refused the plane’s reader role, and a store may give the same answer for a name that does not exist. Name refused is a name the plane keeps for itself, which no project may read.
Plane not connected, Plane cannot check yet, Could not reach your store and Store is rate-limiting are the words for a check that could not be made, which says nothing about the secret. They print no version and never say anything was read.

A plane answers a check only once its Terraform module has created the reader role and its release carries that role’s ARN; a plane that has neither ends a check Plane cannot check yet or Plane not connected.

A reference is checked at most once a minute, and a check needs source.connect, which owners, admins and engineers hold. In the console it is the Check card on the reference’s page. With rl the exit code is the verdict:

# Exit 0: the plane found the secret. Exit 1: it will not be found as declared.
# Exit 3: the check could not be made, which says nothing about the secret.
rl secret check -project payments -env dev payroll-warehouse-reader

The command-line reference has the whole table. A 1 is only ever a finding about the reference: a credential that may not check, or a request the control plane refuses, is a 2. A script that retries on 3 is safe, and a word rl has never read is a 3 and not a 0.

Who checked it

A reference’s page has a Reads tab, and rl secret reads prints the same record, newest first: when, who or what made the check, the outcome and the plane. Today every entry is a check: nobody resolves a reference at run time, so run, task, attempt and version are always empty. It holds ids and words only, never a name in your store, a key or a value. A check that the plane answers is recorded in your audit log, with ids and a word only.

Both say where the window starts, from the start you ask for or the control plane’s own.

Reading the record needs secret.reads.list, which owners, admins and engineers hold; an analyst or a viewer does not. It is not audit.read, which owners and admins hold, so an engineer who makes a check can see that it was recorded without being given the audit log. No role holds secret.read, the permission that would return a value.

From the command line

rl secret list -project payments -env dev
rl secret get -project payments -env dev payroll-warehouse-reader
rl secret reads -project payments -env dev -since 2026-10-01T00:00 payroll-warehouse-reader

rl secret list lists the references of an environment, rl secret get reads one, and rl secret reads prints the record of its checks. A figure that has not been reported is a dash or not reported, never a zero. None of them prints a name in your store, a key, a pinned version or a value; the declaration is the file, and rl get SecretReference reads it back. rl secret set does nothing and exits 2, because a value that a reference names never goes through RunningLake: put it in your own store, declare a reference to it, and propose that.

rl key list and rl key get read the encryption keys of your projects as the control plane recorded them, and a key reads Not checked until RunningLake has tried to ask AWS KMS about it. rl key check asks whether the control plane can use a key you supplied, and does not record the answer. The command-line reference lists each command, the permission it needs and its exit codes.

Let your plane check a secret

For your plane’s reader role to check a secret in your own store, the secret must carry two tags and should carry a third. In the console’s Propose editor, Get the access statement asks the control plane for them: the answer is the three tags with their values and the name of the reader role. Put them on the secret:

rl:plane is the identifier of your plane, which starts with pl_.
rl:project is the identifier of the project, which starts with prj_.
rl:environment is the name of the environment. It is optional; read the paragraph below before you leave it off.

The reader role may describe a secret only when rl:plane names your plane and rl:project names the project that is asking, and, if the secret carries rl:environment, the environment that is asking. These tags decide it: there is no policy to attach, and a policy that names the reader role without those conditions would let it check that secret for every project. The secret must be in the same account and region as your plane: the reader looks only there. The rl:environment tag is optional, and leaving it off is not neutral: a secret without it can be checked by every environment of the project, and a secret with it only by the environment the tag names, so add it to any production secret and leave it off only when you mean one secret to be shared. A tag you have just added may not count at once, so a check straight after tagging can say Access denied; try again in a moment. A plane that has not reported that it can read a secret is refused the statement, and so is an organisation on the shared trial plane.

Not built yet

These are the things you might expect of secrets that do not exist.

Nothing resolves a secret reference yet, so no job is given the secret and nothing follows or pins a version.
Values mounted into a job are not removed from its log yet.
A plane answers a check only once its Terraform module has created the reader role and its release carries that role’s ARN; a plane that has neither ends a check Plane cannot check yet or Plane not connected.
A Vault reference can be declared and cannot be checked yet.

Back to Security