awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Finish update for platform docs

Browse Source
This commit is contained in:
Tuan Dang
2023-10-04 10:25:54 +01:00
parent cf4eb629f2
commit 34273b30f2
62 changed files with 170 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/documentation/platform/secret-reference.mdx
View File

@@ -1,23 +1,39 @@
---
title: "Reference and Import Secrets"
title: "Secret Referencing / Importing"
description: "How to use reference secrets in Infisical"
---
Secret referencing is a powerful feature that allows you to values of other secrets. This way, you just need to update the secret value once for it to be propagated to all the references.
## Secret Referencing
Consider a scenario where you have a database password. In order to utilize this password, you may need to incorporate it into a database connection string.
With secret referencing, you can easily construct these more intricate secrets by directly referencing the base secret.
This centralizes the management of your base secret, as any updates made to it will automatically propagate to all the secrets that depend on it.
Infisical's secret referencing feature lets you reference the value of a "base" secret when defining the value of another secret.
This means that updating the value of a base secret propagates directly to other secrets whose values depend on the base secret.
## Referencing syntax
<img src="../../images/example-secret-referencing.png" />
<Note>
Currently, the secret referencing feature is only supported by the
[Infisical CLI](/cli/overview) and [native integrations](/integrations/overview).
Secret referencing relies on interpolation syntax. This syntax allows you to reference a secret in any environment or [folder](./folder).
We intend to add support for it to the [Node SDK](https://github.com/Infisical/infisical-node)
and [Python SDK](https://github.com/Infisical/infisical-python) this quarter.
</Note>
To reference a secret named 'mysecret' in the same [folder](./folder) and environment, you'd use `${mysecret}`.
However, to reference the same secret at the root of a different environment, for instance `dev` environment, you'd use `${dev.mysecret}`.
![secret referencing](../../images/platform/secret-references-imports/secret-reference.png)
Here are a few more examples to help you understand how to reference secrets in different contexts:
Since secret referencing works by reconstructing values back on the client side, the client, be it a user or service token, fetching back secrets
must be permissioned access to all base and dependent secrets.
For example, to access some secret `A` whose values depend on secrets `B` and `C` from different scopes, a client must have `read` access to the scopes of secrets `A`, `B`, and `C`.
### Syntax
When defining a secret reference, interpolation syntax is used to define references to secrets in other environments and [folders](./folder).
Suppose you have some secret `MY_SECRET` at the root of some environment and want to reference part of its value from another base secret `BASE_SECRET` located elsewhere.
Then consider the following scenarios:
- If `BASE_SECRET` is in the same environment and folder as `MY_SECRET`, then you'd reference it using `${BASE_SECRET}`.
- If `BASE_SECRET` is at the root of another environment with the slug `dev`, then you'd reference it using `${dev.MY_SECRET}`.
Here are a few more helpful examples for how to reference secrets in different contexts:
| Reference syntax | Environment | Folder | Secret Key |
| --------------------- | ----------- | ------------ | ---------- |
@@ -25,29 +41,29 @@ Here are a few more examples to help you understand how to reference secrets in
| `${dev.KEY2}` | `dev` | `/` (root of dev environment) | KEY2 |
| `${prod.frontend.KEY2}` | `prod` | `/frontend` | KEY2 |
## Fetching fully constructed values
## Secret Imports
Secret referencing combines multiple secrets into one unified value, reconstructed only on the client side. To retrieve this value, you need access to read the environment and [folder](./folder) from where the secrets originate.
For instance, to access a secret 'A' composed of secrets 'B' and 'C' from different environments, you must have read access to both 'A' and 'B'
Infisical's secret imports feature lets you import the items of another environment or folder into the current folder context.
This can be useful if you have common secrets that need to be available across multiple environments/folders.
When using [service tokens](./token) to fetch referenced secrets, ensure the service token has read access to all referenced environments and folders.
Without proper permissions, the final secret value may be incomplete.
To add a secret import, press the downward chevron to the right of the **Add Secret** button; then press on the **Add Import** button.
## Import entire folders/environments
![add secret import](../../images/platform/secret-references-imports/secret-import-add.png)
While secret referencing effectively minimizes duplication, there might be instances where you need to import or replicate an entire folder's secrets into another. This can be achieved using the 'Import' feature.
Once added, a secret import will show up with a green import icon on the secrets dashboard.
In the example below, you can see that the items in the path `/some-folder` are being imported into
the current folder context.
This feature allows you to link secrets from one environment/folder into another environment/folder. It proves beneficial when you have common secrets that need to be available across multiple environments/folders.
![added secret import](../../images/platform/secret-references-imports/secret-import-added.png)
To add an import, simply click on the `Add import` button and provide the environment and secret path from where the secrets should be imported.
To delete a secret import, hover over it and press the **X** button that appears on the right side.
![secret import change order](../../images/secret-import-add.png)
![delete secret import](../../images/platform/secret-references-imports/secret-import-delete.png)
The hierarchy of importing secrets is governed by a "last-one-wins" rule. This means the sequence in which you import matters - the final folder imported will override secrets from any prior folders.
Additionally, any secrets you define directly in your environment will override any secrets that are imported with the same name.
Lastly, note that the order of secret imports matters. If two secret imports contain secrets with the same name, then the secret value from the bottom-most secret import is taken — "the last one wins."
You can modify the order of folders to control overrides using the `Change Order` drag handle.
To reorder a secret import, hover over it and drag the arrows handle to the position you want.
![secret import change order](../../images/secret-import-change-order.png)
![reorder secret import](../../images/platform/secret-references-imports/secret-import-reorder.png)
<iframe width="560" height="315" src="https://www.youtube.com/embed/o11bMU0pXRs?si=dCprt3xLWPrSOJxy" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>