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

Merge pull request #736 from Infisical/revamp-docs

Browse Source 
Revamp core docs
This commit is contained in:
Maidul Islam
2023-07-12 01:29:10 -04:00
committed by GitHub
parent 88ec55fc49 0a9adf33c8
commit 0fc4f96773
8 changed files with 181 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/cli/overview.mdx
View File

@@ -3,9 +3,7 @@ title: 'Install'
description: "Infisical's CLI is one of the best way to manage environments and secrets. Install it here"
---
Prerequisite: Set up an account with [Infisical Cloud](https://app.infisical.com) or via a [self-hosted installation](/self-hosting/overview).
The Infisical CLI provides a way to inject environment variables from the platform into your apps and infrastructure.
The Infisical CLI can be used to access secrets across various environments, whether it's local development, CI/CD, staging, or production.
## Installation
@@ -100,49 +98,3 @@ The Infisical CLI provides a way to inject environment variables from the platfo
</Tab>
</Tabs>
### Log in to the Infisical CLI
```bash
infisical login
```
<Accordion title="Optional: point CLI to self-hosted">
The CLI is set to connect to Infisical Cloud by default, but if you're running your own instance of Infisical, you can direct the CLI to it using one of the methods provided below.
#### Method 1: Use the updated CLI
Beginning with CLI version V0.4.0, it is now possible to choose between logging in through the Infisical cloud or your own self-hosted instance. Simply execute the `infisical login` command and follow the on-screen instructions.
#### Method 2: Export environment variable
You can point the CLI to the self hosted Infisical instance by exporting the environment variable `INFISICAL_API_URL` in your terminal.
<Tabs>
<Tab title="Linux/MacOs">
```bash
# Set backend host
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api"
# Remove backend host
unset INFISICAL_API_URL
```
</Tab>
<Tab title="Windows Powershell">
```bash
# Set backend host
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api"
# Remove backend host
setx INFISICAL_API_URL ""
# NOTE: Once set or removed, please restart powershell for the change to take effect
```
</Tab>
</Tabs>
#### Method 3: Set manually on every command
Another option to point the CLI to your self hosted Infisical instance is to set it via a flag on every command you run.
```bash
# Example
infisical <any-command> --domain="https://your-self-hosted-infisical.com/api"
```
</Accordion>

154
docs/cli/usage.mdx
View File

@@ -1,77 +1,137 @@
---
title: "Usage"
description: "How to manage you secrets with Infisical's CLI?"
title: "Quick usage"
description: "Manage secrets with Infisical CLI"
---
Prerequisite: [Install the CLI](/cli/overview)
The CLI is designed for a verity of applications, ranging from local secret management to CI/CD and production scenarios.
The distinguishing factor, however, is the authentication method used.
## Authenticate
<Tabs>
<Tab title="Local development">
To use the Infisical CLI in your development environment, you can run the command below.
This will allow you to access the features and functionality provided by the CLI.
To use the Infisical CLI in your development environment, simply run the following command and follow the interactive guide.
```bash
infisical login
```
<Note>
If you are in a containerized environment such as WSL 2 or Codespaces, run `infisical login -i` to avoid browser based login
</Note>
## Initialize Infisical for your project
```bash
# navigate to your project
cd /path/to/project
# initialize infisical
infisical init
```
This will create `.infisical.json` file at the location the command was executed. This file contains your [local project settings](./project-config). It does not contain any sensitive data.
</Tab>
<Tab title="Infisical Token">
To use Infisical CLI in environments where you cannot run the `infisical login` command, you can authenticate via a
Infisical Token instead. Learn more about [Infisical Token](/documentation/platform/token).
<Tab title="CI/CD, Production usage, etc">
To use Infisical for non local development scenarios, please create a [service token](../documentation/platform/token). The service token will allow you to authenticate and interact with Infisical.
Once you have created a service token with the required permissions, you'll need to feed the token to the CLI.
#### Pass as flag
You may use the --token flag to set the token
```
infisical export --token=<>
infisical secrets --token=<>
infisical run --token=<> -- npm run dev
```
#### Pass via shell environment variable
The CLI is configured to look for an environment variable named `INFISICAL_TOKEN`. If set, it'll attempt to use it for authentication.
```
export INFISICAL_TOKEN=<>
```
</Tab>
</Tabs>
## Initialize Infisical for your project
```bash
# navigate to your project
cd /path/to/project
# initialize infisical
infisical init
```
## Inject environment variables
<Tabs>
<Tab title="Feed secrets to your application">
```bash
infisical run -- [your application start command]
<Accordion title="Injecting environment variables directly" defaultOpen="true">
```bash
# inject environment variables into app
infisical run -- [your application start command]
```
</Accordion>
# example with node (nodemon)
infisical run --env=dev --path=/apps/firefly -- nodemon index.js
<Accordion title="Injecting environment variables in custom aliases">
Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias `yd` in `custom.sh` that runs `yarn dev` and needs the secrets provided by Infisical.
```bash
#!/bin/sh
# example with flask
infisical run -- flask run
yd() {
yarn dev
}
```
# example with spring boot - maven
infisical run -- ./mvnw spring-boot:run --quiet
```
</Tab>
<Tab title="Feed secrets via custom aliases (advanced)">
Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias `yd` in `custom.sh` that runs `yarn dev` and needs the secrets provided by Infisical.
```bash
#!/bin/sh
To make the secrets available from Infisical to `yd`, you can run the following command:
yd() {
yarn dev
}
```
```bash
infisical run --command="source custom.sh && yd"
```
</Accordion>
To make the secrets available from Infisical to `yd`, you can run the following command:
```bash
infisical run --command="source custom.sh && yd"
```
</Tab>
</Tabs>
View all available options for `run` command [here](./commands/run)
## Examples:
## Connect CLI to self hosted Infisical
```bash
# example with node
infisical run -- node index.js
<Accordion title="Optional: point CLI to self-hosted">
The CLI is set to connect to Infisical Cloud by default, but if you're running your own instance of Infisical, you can direct the CLI to it using one of the methods provided below.
# example with node (nodemon)
infisical run -- nodemon index.js
#### Method 1: Use the updated CLI
Beginning with CLI version V0.4.0, it is now possible to choose between logging in through the Infisical cloud or your own self-hosted instance. Simply execute the `infisical login` command and follow the on-screen instructions.
# example with node (nodemon) pulling in secrets from test environment
infisical run --env=test -- nodemon index.js
#### Method 2: Export environment variable
You can point the CLI to the self hosted Infisical instance by exporting the environment variable `INFISICAL_API_URL` in your terminal.
# example with flask
infisical run -- flask run
<Tabs>
<Tab title="Linux/MacOs">
```bash
# Set backend host
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api"
# Remove backend host
unset INFISICAL_API_URL
```
</Tab>
<Tab title="Windows Powershell">
```bash
# Set backend host
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api"
# Remove backend host
setx INFISICAL_API_URL ""
# NOTE: Once set or removed, please restart powershell for the change to take effect
```
</Tab>
</Tabs>
#### Method 3: Set manually on every command
Another option to point the CLI to your self hosted Infisical instance is to set it via a flag on every command you run.
```bash
# Example
infisical <any-command> --domain="https://your-self-hosted-infisical.com/api"
```
</Accordion>

46
docs/documentation/platform/folder.mdx
View File

@@ -1,48 +1,30 @@
---
title: "Folder"
description: "How Infisical structures secrets into folders"
title: "Folders"
description: "Organize your secrets with folders"
---
Folders can be used to group secrets into multiple levels, which can help organize secrets in monorepos or microservice-based architectures. For example, you could create a folder for each environment, such as production, staging, and development.
Folders provide a powerful and intuitive way to structure your secrets.
They offer a streamlined and intuitive system to keep your secrets organized and easily accessible, which becomes increasingly important as your collection of secrets grow.
Within each environment folder, you could create subfolders for different types of secrets, such as database credentials, API keys, and SSH keys. This can help to keep your secrets organized and easy to find.
With folders in Infisical, you can now create a hierarchy of folders to organize your secrets, mirroring your application's architecture or any logical grouping that suits your needs.
Whether you follow a microservices architecture or work with monorepos, folders make it simpler to locate, manage and collaborate between teams.
## Dashboard
![dashboard with folders](../../images/dashboard-folders.png)
## Creating a folder
Only alphabets, numbers, and dashes are allowed in folder names. You can create a folder for each environment from the dashboard.
To create a folder, head over to the environment where you'd like to create the folder. Once there, click the `Add folder` button as shown below.
If you wish to create nested folders, simply click into the folder of choice and click `Add folder` button again.
![dashboard add folders](../../images/dashboard-add-folder.png)
To create a nested folder or access the secrets of a folder, click on an existing folder to open it. You will then be able to modify the secrets of that folder and create new folders inside it.
<Info>
Folder names can only contain alphabets, numbers, and dashes
</Info>
## Dashboard Secret Overview
## Compare folders across environments
The overview screen provides a comprehensive view of all your secrets and folders, organized by environment.
![dashboard secret overview with folders](../../images/dashboard-folder-overview.png)
When you click on a folder, the overview will be updated to show only the secrets and folders in that folder. This makes it easy to find the information you need, no matter how deeply nested it is.
## Integrations
You can easily scope injected secrets to a folder during integrations by providing the secret path option.
![integrations scoped with folders](../../images/integration-folders.png)
For more information on integrations, [refer infisical integration](/integrations/overview)
## Service Tokens
You can scope the secrets that can be read and written using an Infisical token by providing the secret path option when creating the token.
You can provide the folder path as glob if you want to have access to multiple folders and the tokens do support multi-environment.
![folder scoped service token](../../images/project-folder-token.png)
For more information, [refer infisical token section.](./token)
## Point-In-Time Recovery
For more information on how PIT recovery works on folders, [please refer to this section.](./pit-recovery)
When you click on a folder, the overview will be updated to show only the secrets and folders in that folder. This allows you to compare secrets across environment regardless of how deeply nested your folders are.

20
docs/documentation/platform/pit-recovery.mdx
View File

@@ -3,28 +3,26 @@ title: "Point-in-Time Recovery"
description: "How to rollback secrets and configs to any commit with Infisical."
---
Point-in-time recovery allows environment variables to be rolled back to any point in time. It's powered by snapshots that get captured after mutations to environment variables.
Point-in-time recovery allows secrets to be rolled back to any point in time.
It's powered by snapshots that get created after every mutations to a secret within a given [folder](./folder) and environment.
## Commits
Similar to Git, a commit in Infisical is a snapshot of your project's secrets at a specific point in time. You can browse and view your project's snapshots via the "Point-in-Time Recovery" sidebar.
Similar to Git, a commit in Infisical is a snapshot of your project's secrets at a specific point in time scoped to the environment and [folder](./folder) it is in. You can browse and view your project's snapshots via the "Point-in-Time Recovery" sidebar.
![PIT commits](../../images/pit-commits.png)
![PIT snapshots](../../images/pit-snapshots.png)
## Rolling back
Environment variables can be rolled back to any point in time via the "Rollback to this snapshot" button.
Secrets can be rolled back to any point in time via the "Rollback to this snapshot" button. This will roll back the changes within the given [folder](./folder) and environment to the chosen time.
It's important to note that this rollback action is localized and does not affect other folders within the same environment. This means each [folder](./folder) maintains its own independent history of changes, offering precise and isolated control over rollback actions.
In essence, every [folder](./folder) possesses a distinct and separate timeline, providing granular control when managing your secrets.
![PIT snapshot](../../images/pit-snapshot.png)
<Note>
Rolling back environment variables to a past snapshot creates a new commit and
snapshot at the top of the stack and updates secret versions.
Rolling back secrets to a past snapshot creates a new commit,
creates a snapshot at the top of the stack and updates secret versions.
</Note>
## Folders
Any folder operation, such as creating, updating, or deleting a folder, will create a new commit.
When you roll back the contents of a folder, the folder will be restored to its latest snapshot. The nested folders will also be restored to their respective latest versions.

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

@@ -3,24 +3,35 @@ title: "Reference Secrets"
description: "How to use reference secrets in Infisical"
---
You can use the interpolation syntax to reference a secret in the same environment, another folder, or another environment
The interpolation syntax is a way of referencing a secret by using a special placeholder. The placeholder is the name of the secret, followed by the environment or folder name, separated by a colon.
Secret referencing is a powerful feature that allows you to create a secret whose value is linked to one or more other secrets.
This is useful when you need to use a single secret's value across multiple other secrets.
For example, to reference a secret named mysecret in the same environment, you would use the placeholder `${mysecret}`.
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.
While for another environment like `test` would be `${test.mysecret}`
## Referencing syntax
<img src="../../images/example-secret-referencing.png" />
Some more examples of referencing are
Secret referencing relies on interpolation syntax. This syntax allows you to reference a secret in any environment or [folder](./folder).
| Syntax | Environment | Folder | Secret Key |
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}`.
Here are a few more examples to help you understand how to reference secrets in different contexts:
| Reference syntax | Environment | Folder | Secret Key |
| --------------------- | ----------- | ------------ | ---------- |
| `${KEY1}` | same env | ssame folder | KEY1 |
| `${dev.KEY2}` | dev | / | KEY2 |
| `${test.frontend.KEY2}` | test | /frontend | KEY2 |
| `${KEY1}` | same env | same folder | KEY1 |
| `${dev.KEY2}` | `dev` | `/` (root of dev environment) | KEY2 |
| `${prod.frontend.KEY2}` | `prod` | `/frontend` | KEY2 |
# Permission system for reference
## Fetching fully constructed values
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.
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.
When you use the infisical CLI to log in, the permission system will work the same way as your user permissions.
This means that if you have permission to access other environments, your references to those environments will be resolved.
When using the Infisical CLI with a service token, the service token must have permissions to the referenced environment and folder path.

36
docs/documentation/platform/token.mdx
View File

@@ -1,21 +1,37 @@
---
title: "Infisical Token"
description: "Use the Infisical Token as one of the authentication methods."
title: "Service token"
description: "Infisical service tokens allows you to programmatically interact with Infisical"
---
An Infisical Token is useful for:
Service tokens play an integral role in allowing programmatic interactions with an Infisical project, functioning as digital token that open access to specific project resources such as secrets.
- Authenticating the [Infisical CLI](/cli/overview) when there isn't an easy way to input your login credentials.
- Granting the [Infisical SDKs](/sdks/overview) access to secrets scoped to a project and environment.
When you generate a service token, you can define its access level, not only by specifying the paths and environments it can interact with, but also by determining the level of mutation it can perform, such as read-only, write, or both.
It's also useful for CI/CD environments and integrations such as [Docker](/integrations/platforms/docker) and [Docker Compose](/integrations/platforms/docker-compose).
This level of control not only ensures maximum flexibility but also significantly enhances security as it allows you to define fine grained access to project resources.
## Creating a service token
To generate the the token, head over to your project settings as shown below. On creating a service token you can scope it to a path to limit the access.
![token add](../../images/project-token-add.png)
## Feeding Infisical Token to the CLI
### Service token permissions
![token add](../../images/service-token-permissions.png)
The Infisical CLI checks for the presence of an environment variable called `INFISICAL_TOKEN`.
If it detects this variable in the terminal where it is being run, it will use it to authenticate and retrieve the environment variables that the token is authorized to access.
This allows you to use the CLI in environments where you are unable to run the `infisical login` command.
Service tokens can be scoped to multiple environments and paths. To add a new permission, choose the environment you want to give access to and then choose the path you'd like to give access to within that environment.
Permissions for paths are powered by [Glob pattern](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/). This means you can create advanced folder permissions with a simple Glob patterns.
**Examples of common Glob pattens**
<Accordion title="Examples of common Glob pattens">
1. `/**`: This pattern matches all folders at any depth in the directory structure. For example, it would match folders like `/folder1/`, `/folder1/subfolder/`, and so on.
2. `/*`: This pattern matches all immediate subfolders in the current directory. It does not match any folders at a deeper level. For example, it would match folders like `/folder1/`, `/folder2/`, but not `/folder1/subfolder/`.
3. `/*/*`: This pattern matches all subfolders at a depth of two levels in the current directory. It does not match any folders at a shallower or deeper level. For example, it would match folders like `/folder1/subfolder/`, `/folder2/subfolder/`, but not `/folder1/` or `/folder1/subfolder/subsubfolder/`.
4. `/folder1/*`: This pattern matches all immediate subfolders within the `/folder1/` directory. It does not match any folders outside of `/folder1/`, nor does it match any subfolders within those immediate subfolders. For example, it would match folders like `/folder1/subfolder1/`, `/folder1/subfolder2/`, but not `/folder2/subfolder/`.
</Accordion>

BIN
docs/images/example-secret-referencing.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 246 KiB

BIN
docs/images/service-token-permissions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 652 KiB