mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-10 07:58:15 -05:00
Add concepts section to secrets mgmt docs
This commit is contained in:
Tuan Dang
@@ -386,6 +386,32 @@
|
||||
"group": "Secrets Management",
|
||||
"pages": [
|
||||
"documentation/platform/secrets-mgmt/overview",
|
||||
{
|
||||
"group": "Concepts",
|
||||
"pages": [
|
||||
"documentation/platform/secrets-mgmt/concepts/secrets-mgmt",
|
||||
"documentation/platform/secrets-mgmt/concepts/access-control",
|
||||
"documentation/platform/secrets-mgmt/concepts/secrets-delivery",
|
||||
"documentation/platform/secrets-mgmt/concepts/secrets-rotation",
|
||||
"documentation/platform/secrets-mgmt/concepts/dynamic-secrets"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
"documentation/guides/introduction",
|
||||
"documentation/guides/local-development",
|
||||
"documentation/guides/node",
|
||||
"documentation/guides/python",
|
||||
"documentation/guides/nextjs-vercel",
|
||||
"documentation/guides/microsoft-power-apps"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Product Reference",
|
||||
"pages": [
|
||||
"documentation/platform/secrets-mgmt/project",
|
||||
"documentation/platform/folder",
|
||||
{
|
||||
@@ -430,17 +456,6 @@
|
||||
"documentation/platform/dynamic-secrets/kubernetes",
|
||||
"documentation/platform/dynamic-secrets/vertica"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
"documentation/guides/introduction",
|
||||
"documentation/guides/local-development",
|
||||
"documentation/guides/node",
|
||||
"documentation/guides/python",
|
||||
"documentation/guides/nextjs-vercel",
|
||||
"documentation/guides/microsoft-power-apps"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -464,7 +479,7 @@
|
||||
"group": "Agent",
|
||||
"pages": [
|
||||
"integrations/platforms/infisical-agent",
|
||||
"integrations/platforms/docker-swarm-with-agent",
|
||||
"integrations/platforms/docker-swarm-with-agent",
|
||||
"integrations/platforms/ecs-with-agent"
|
||||
]
|
||||
},
|
||||
@@ -634,9 +649,7 @@
|
||||
"groups": [
|
||||
{
|
||||
"group": "Secret Scanning",
|
||||
"pages": [
|
||||
"documentation/platform/secret-scanning/overview"
|
||||
]
|
||||
"pages": ["documentation/platform/secret-scanning/overview"]
|
||||
},
|
||||
{
|
||||
"group": "Datasources",
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Scoping Secrets"
|
||||
description: "Learn how access to secrets is controlled in Infisical."
|
||||
---
|
||||
|
||||
## Secret Hierarchy
|
||||
|
||||
Every secret in Infisical is scoped to an environment and a path.
|
||||
|
||||
- An environment separates where secrets are used, such as `development`, `staging`, or `production`.
|
||||
- A path is an (optional) namespace within an environment that groups related secrets such as `/postgres`, `/redis`, or per-service paths like `/service-a`.
|
||||
|
||||
This structure makes it easy to organize secrets by team, service, or environment, and sets the foundation for controlling who can access what.
|
||||
|
||||
## Access Control
|
||||
|
||||
Access control determines who (or what) can access a secret and under what conditions. Without clear policies, even securely stored secrets can be misused or exposed.
|
||||
|
||||
To control access to secrets, you configure role-based permissions at the project level. These permissions determine which environments and paths a user or machine identity with that role can access. For example, an engineer might have a role that allows them to read secrets in the `development` environment but not those in the `production` environment.
|
||||
|
||||
This model follows the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) such that each user or machine identity has access only to the secrets it needs — and nothing more.
|
||||
|
||||
## Advanced Capabilities
|
||||
|
||||
Beyond basic role assignments, Infisical includes additional access control mechanisms for more advanced use cases:
|
||||
|
||||
- Access approvals: Users can request access to specific environments or paths. Access can be temporary and reviewed before it is granted, reducing long-term exposure.
|
||||
|
||||
- Secret change approvals: Updates to sensitive secrets can require approval before taking effect. This adds control in environments where unreviewed changes pose risk.
|
||||
|
||||
- Attribute-based access control (ABAC): Permissions can be matched against metadata on a user or machine identity — such as team, service, or environment — enabling dynamic access rules without manual role changes.
|
||||
|
||||
All access and approval actions are logged, so it’s always possible to trace who accessed what, when, and under what conditions.
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Dynamic Secrets"
|
||||
description: "Understand what dynamic secrets are, why they're useful, and how Infisical enables them."
|
||||
---
|
||||
|
||||
## What is a Dynamic Secret?
|
||||
|
||||
A _dynamic secret_ is a time-bound credential generated on demand for a specific user or system. Unlike _static secrets_, which are created and stored ahead of time, or rotated credentials, which are periodically replaced, dynamic secrets don’t exist until they’re requested — and automatically expire shortly after use.
|
||||
|
||||
Each secret is unique to the identity that requested it, reducing the risk of reuse, long-term exposure, or accidental leaks. Because they are short-lived and tightly scoped, dynamic secrets are well suited for high-security environments, automated systems, and ephemeral workloads where access needs to be both temporary and auditable.
|
||||
|
||||
By limiting the lifespan and visibility of credentials, dynamic secrets offer a strong alternative to managing long-lived secrets manually.
|
||||
|
||||
## Dynamic Secrets in Infisical
|
||||
|
||||
Infisical generates dynamic secrets in real time when a user or machine identity requests access. Each secret is uniquely scoped to the requesting identity, valid just-in-time only for a limited duration, and automatically revoked after it expires.
|
||||
|
||||
Because they are short-lived and identity-specific, dynamic secrets reduce the risk of credential reuse, accidental exposure, or long-term persistence across environments.
|
||||
|
||||
When supported for a given integration, using dynamic secrets is strongly recommended. Infisical currently supports dynamic secret templates for commonly used systems including [PostgreSQL](/documentation/platform/dynamic-secrets/postgresql), [MySQL](/documentation/platform/dynamic-secrets/mysql), [Microsoft SQL Server](/documentation/platform/dynamic-secrets/mssql), [MongoDB Atlas](/documentation/platform/dynamic-secrets/mongo-db), [Redis](/documentation/platform/dynamic-secrets/redis), [AWS IAM](/documentation/platform/dynamic-secrets/aws-iam), [GCP IAM](/documentation/platform/dynamic-secrets/gcp-iam), [Azure Entra ID](/documentation/platform/dynamic-secrets/azure-entra-id), and more.
|
||||
|
||||
To learn more, refer to the [dynamic secrets documentation](/documentation/platform/dynamic-secrets/overview).
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: "Delivering Secrets"
|
||||
description: "Learn how to get secrets out of Infisical and into the systems, applications, and environments that need them."
|
||||
---
|
||||
|
||||
Once secrets are stored and scoped in Infisical, the next step is delivering them securely to the systems and applications that need them.
|
||||
|
||||
Infisical supports multiple delivery methods to match a wide range of environments — from [local development](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#local-development%2C-scripts%2C-and-one-off-tasks) to [Kubernetes workloads](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#kubernetes-workloads), [CI/CD pipelines](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#ci%2Fcd-pipelines), [infrastructure-as-code tools](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#infrastructure-as-code-and-automation-tools), and more.
|
||||
|
||||
The right delivery method depends on how your infrastructure runs and how secrets are expected to be consumed.
|
||||
|
||||
The table below provides a quick overview of which delivery method to use based on your environment and how secrets are consumed:
|
||||
|
||||
| Use Case / Environment | Recommended Method(s) | Consumes Secrets As | Notes |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------ |
|
||||
| Local development or scripting | [`infisical run`](/cli/commands/run), [CLI](/cli/overview) | Environment variables | Easiest way to inject secrets during local dev or debugging |
|
||||
| Application code fetching at runtime | [SDKs](/sdks/overview), [HTTP API](/api-reference/overview/introduction) | In-memory / API call | Full control in app code; supports dynamic or ephemeral fetching |
|
||||
| VMs, containers, or CI jobs needing preloaded secrets | [Infisical Agent](/integrations/platforms/infisical-agent) | Env vars or files | Good for non-interactive workloads; avoids inline secret fetch |
|
||||
| GitHub Actions | [Secrets Action](https://github.com/Infisical/secrets-action), [Secret Syncs](/integrations/secret-syncs/github) | Env vars or files | Use Action for dynamic fetch; use Syncs to preload into GitHub |
|
||||
| GitLab CI, Jenkins, other CI | [CLI](/cli/overview), [Agent](/integrations/platforms/infisical-agent), [Secret Syncs](/integrations/secret-syncs/gitlab) | Env vars or files | Choose based on timing — fetch at runtime vs. pre-populate ahead |
|
||||
| Kubernetes (declarative secrets) | [Kubernetes Operator](/integrations/platforms/kubernetes/overview) | Kubernetes Secrets | Syncs from Infisical into native Kubernetes Secrets |
|
||||
| Kubernetes (ESO-based workflows) | [ESO](/integrations/platforms/external-secrets) | Kubernetes Secrets | Reuses existing ESO setup; Infisical acts as a provider |
|
||||
| Kubernetes (file-based, no K8s secrets) | [Agent Injector](/integrations/platforms/kubernetes-injector) | Mounted files | Injects secrets via init container into volume at pod startup |
|
||||
| Kubernetes (file-based, with rotation) | [CSI Provider](/integrations/platforms/kubernetes-csi) | Mounted files | Uses CSI driver to mount secrets as files with automatic rotation |
|
||||
| Image builds (VMs or containers) | [Packer Plugin](/integrations/frameworks/packer) | Env vars or files | Inject secrets at image build time |
|
||||
| Ansible automation | [Ansible Collection](/integrations/platforms/ansible) | Variables | Runtime secret fetching in playbooks using lookup plugin |
|
||||
| Terraform / Pulumi | [Terraform Provider](/integrations/frameworks/terraform), [Pulumi](/integrations/frameworks/pulumi) | Inputs / ephemeral resources | Use ephemeral for security; avoids storing secrets in state |
|
||||
| Third-party platforms (GitHub, AWS, etc.) | [Secret Syncs](/integrations/secret-syncs/overview) | Preloaded secrets | Push secrets to platforms that can't fetch directly from Infisical |
|
||||
|
||||
From here, you can explore the delivery method that best matches your environment:
|
||||
|
||||
## Local Development, Scripts, and One-Off Tasks
|
||||
|
||||
For local development, one-off scripts, or basic automation, the [Infisical CLI](/cli/overview) is a quick and flexible option.
|
||||
|
||||
Instead of using a `.env` file, you can use [`infisical run`](/cli/commands/run) to inject secrets as environment variables directly into your development process. This provides a cleaner and more secure workflow. You can also use [`infisical secrets`](/cli/commands/secrets#infisical-secrets) to perform CRUD operations on secrets from the command line, which works well for debugging, local tooling, and lightweight scripting.
|
||||
|
||||
To learn more, refer to the [CLI quickstart](cli/usage).
|
||||
|
||||
## Applications and Services
|
||||
|
||||
When secrets need to be accessed directly from within application code, Infisical provides SDKs for [Node.js](https://github.com/Infisical/node-sdk-v2), [Python](https://github.com/Infisical/python-sdk-official), [Go](/sdks/languages/go), [Java](https://github.com/Infisical/java-sdk), [.NET](https://github.com/Infisical/infisical-dotnet-sdk), [C++](https://github.com/Infisical/infisical-cpp-sdk), [Rust](https://github.com/Infisical/rust-sdk), and [Ruby](/sdks/languages/ruby).
|
||||
|
||||
These SDKs let services fetch secrets at runtime or startup. For unsupported languages or if you prefer direct integration, you can use the fully documented [HTTP API](/api-reference/overview/introduction) to fetch secrets within your application logic.
|
||||
|
||||
This approach gives you fine-grained control but also requires managing authentication and caching.
|
||||
|
||||
## Virtual Machines(VMs), Containers, and CI Environments
|
||||
|
||||
For systems that shouldn’t fetch secrets themselves — such as production VMs, Docker containers, or CI jobs — the [Infisical Agent](/integrations/platforms/infisical-agent) can be used to sync secrets into the local environment on their behalf.
|
||||
|
||||
The agent runs as a lightweight background process and supports injecting secrets into files, environment variables, or application config formats. It's especially useful for non-interactive workloads that expect secrets to already exist at runtime.
|
||||
|
||||
You can run the agent as a standalone binary, as a Docker sidecar, or embedded in automation scripts. It works well in environments like:
|
||||
|
||||
- VMs that need secrets provisioned at startup.
|
||||
- [Docker Swarm](/integrations/platforms/docker-swarm-with-agent) services using shared volumes.
|
||||
- [ECS tasks](/integrations/platforms/ecs-with-agent) using EFS for shared secret delivery.
|
||||
|
||||
## CI/CD Pipelines
|
||||
|
||||
For CI/CD pipelines, the right method depends on the platform.
|
||||
|
||||
- On GitHub Actions, the [Infisical Secrets Action](https://github.com/Infisical/secrets-action) provides a native integration that injects secrets as environment variables or `.env` files during workflows. It supports authentication via [AWS IAM](/documentation/platform/identities/aws-auth), [OIDC](/documentation/platform/identities/oidc-auth/github), or [Universal Auth](/documentation/platform/identities/universal-auth) using a Machine Identity.
|
||||
- On other CI platforms like GitLab CI, CircleCI, or Jenkins, the CLI or Agent may be used depending on how secrets are consumed — whether at runtime or during setup.
|
||||
|
||||
Some CI/CD systems also support [Secret Syncs](/integrations/secret-syncs/overview) as an alternative. Instead of fetching secrets dynamically, you can configure Infisical to forward secrets into GitHub Actions, GitLab CI, and similar platforms ahead of time — allowing them to be used as native environment secrets during jobs.
|
||||
|
||||
## Kubernetes Workloads
|
||||
|
||||
Infisical supports multiple options for delivering secrets into Kubernetes, each designed to match different operational models and consumption patterns:
|
||||
|
||||
- [Infisical Kubernetes Operator](/integrations/platforms/kubernetes/overview): A set of CRDs that sync secrets from Infisical into Kubernetes Secrets, push secrets from Kubernetes back to Infisical, and manage dynamic secrets with automatic leases. Best suited for teams using declarative workflows and wanting to treat secrets as part of infrastructure code.
|
||||
|
||||
- [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical/): Enables syncing Infisical secrets into Kubernetes by defining ExternalSecret resources. Ideal if your team already uses ESO as a centralized way to fetch secrets from multiple providers.
|
||||
|
||||
- [Infisical Agent Injector](/integrations/platforms/kubernetes-injector): A Kubernetes mutating admission webhook that injects an init container into your pods. The injected container syncs secrets from Infisical into a shared volume at startup, making them available as files. Useful for workloads that expect file-based secrets and where avoiding Kubernetes Secrets entirely is preferred.
|
||||
|
||||
- [Infisical CSI Provider](/integrations/platforms/kubernetes-csi): Integrates with the Kubernetes Secrets Store CSI Driver to mount secrets as files in pods. Supports automatic rotation and fine-grained control over how secrets are structured and updated. Suitable for environments that require file-based secret delivery with rotation, without persisting Kubernetes Secrets.
|
||||
|
||||
These methods provide secure, declarative integrations with Kubernetes-native workflows.
|
||||
|
||||
## Forwarding to Third-Party Platforms
|
||||
|
||||
In some cases, secrets must be delivered into systems that can’t fetch them from Infisical directly.
|
||||
|
||||
[Secret Syncs](/integrations/secret-syncs/overview) allow you to forward secrets to platforms such as [GitHub](/integrations/secret-syncs/github), [GitLab](/integrations/secret-syncs/gitlab), [AWS Secrets Manager](/integrations/secret-syncs/aws-secrets-manager), [Vercel](/integrations/secret-syncs/vercel), and more.
|
||||
|
||||
This is useful when external systems require secrets to be available ahead of time or expect them in a specific location.
|
||||
|
||||
## Infrastructure-as-Code and Automation Tools
|
||||
|
||||
Infisical integrates with common IaC and automation tools to help you securely inject secrets into your infrastructure provisioning workflows:
|
||||
|
||||
- [Terraform](/integrations/frameworks/terraform): Use the official Infisical Terraform provider to fetch secrets either as ephemeral resources (never written to state files) or as traditional data sources. Ideal for managing cloud infrastructure while keeping secrets secure and version-safe.
|
||||
- [Pulumi](/integrations/frameworks/pulumi): Integrate Infisical into Pulumi projects using the Terraform Bridge, allowing you to fetch and manage secrets in TypeScript, Go, Python, or C# — without changing your existing workflows.
|
||||
- [Ansible](/integrations/platforms/ansible): Retrieve secrets from Infisical at runtime using the official Ansible Collection and lookup plugin. Works well for dynamic configuration during playbook execution.
|
||||
- [Packer](/integrations/frameworks/packer): Inject secrets into VM or container images at build time using the Infisical Packer Plugin — useful for provisioning base images that require secure configuration values.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Secrets Management"
|
||||
description: "Learn what is secrets management and why it matters for building secure systems."
|
||||
---
|
||||
|
||||
## What is Secret?
|
||||
|
||||
A _secret_ is a confidential value used by an application such as database credential, API key, or other configuration.
|
||||
|
||||
In most cases, secrets allow applications to access systems and control how they behave across the development cycle — for example, an application might use a database password stored in an environment variable like `DB_PASSWORD` to connect to production data. These secrets must be kept secure to protect infrastructure and data.
|
||||
|
||||
## What is Secrets Management?
|
||||
|
||||
As infrastructure scales and systems become more distributed, [secrets sprawl](https://infisical.com/blog/what-is-secret-sprawl). Without consistent security practices, secrets get hardcoded in source code, exposed in environment variables, left unrotated for long periods, and scattered across systems without clear visibility into who can access them.
|
||||
|
||||
To solve secret sprawl, organizations rely on [secrets management](https://infisical.com/blog/what-is-secrets-management): the practice of centralizing secrets and managing them through well-defined workflows. This includes secure storage, fine-grained access controls, automatic rotation, audit logging, and support for dynamic, short-lived credentials.
|
||||
|
||||
A consistent approach makes it easier to keep secrets safe, reduce risk, and operate reliably across environments.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Secrets Rotation"
|
||||
description: "Understand what secrets rotation is, why it matters, and how Infisical enables it."
|
||||
---
|
||||
|
||||
## What is Secrets Rotation?
|
||||
|
||||
Secrets rotation is the process of regularly replacing credentials like API keys, database passwords, and tokens to reduce the risk of long-term exposure. Even if a secret is compromised, frequent rotation limits how long it can be used.
|
||||
|
||||
Without rotation, secrets often go unchanged for months or years — hardcoded in codebases, embedded in CI pipelines, or shared across environments. Over time, this increases the risk of leaks, misuse, and operational blind spots.
|
||||
|
||||
## Secrets Rotation in Infisical
|
||||
|
||||
Infisical automates rotation using a rolling lifecycle model where new credentials are issued on a fixed schedule with previous ones remaining temporarily valid to give systems time to update without disruption. Each secret moves through three phases: active, inactive, and eventually revoked. This ensures that applications continue to function smoothly throughout the rotation process.
|
||||
|
||||
When rotation is applicable for a given secret type, using it is strongly recommended. Infisical supports configuring automatic rotation for a growing set of use cases including [PostgreSQL](/documentation/platform/secret-rotation/postgres-credentials), [MySQL](/documentation/platform/secret-rotation/mysql-credentials), [Microsoft SQL Server](/documentation/platform/secret-rotation/mssql-credentials), [OracleDB](/documentation/platform/secret-rotation/oracledb-credentials), [LDAP](/documentation/platform/secret-rotation/ldap-password), [AWS IAM users](/documentation/platform/secret-rotation/aws-iam-user-secret), [Azure](/documentation/platform/secret-rotation/azure-client-secret) and [Okta](/documentation/platform/secret-rotation/okta-client-secret) client secrets, and more.
|
||||
|
||||
To learn more, refer to the [secrets rotation documentation](/documentation/platform/secret-rotation/overview).
|
||||
@@ -12,6 +12,6 @@ Core capabilities include:
|
||||
|
||||
- Secret Stores: Secure, versioned storage scoped by [project](/documentation/platform/secrets-mgmt/project), [environment](/documentation/platform/secrets-mgmt/project#project-environments), and [path](/documentation/platform/folder).
|
||||
- [Access Control](/documentation/platform/access-controls/overview): Fine-grained, identity-aware permissions for users and machines
|
||||
- Secret Delivery: Access secrets via [CLI](/cli/overview), [SDKs](/sdks/overview) (Go, Node.js, Python, etc.), [HTTP API](/api-reference/overview/introduction), [agents](/integrations/platforms/infisical-agent), [Kubernetes Operator](/integrations/platforms/kubernetes/overview), [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical), and more.
|
||||
- Lifecycle Automation: Automate [secret rotation](/documentation/platform/secret-rotation/overview), generate [dynamic secrets](/documentation/platform/dynamic-secrets/overview), and enforce [approval-based workflows](/documentation/platform/pr-workflows).
|
||||
- [Secret Delivery](/documentation/platform/secrets-mgmt/concepts/secrets-delivery): Access secrets via [CLI](/cli/overview), [SDKs](/sdks/overview) (Go, Node.js, Python, etc.), [HTTP API](/api-reference/overview/introduction), [agents](/integrations/platforms/infisical-agent), [Kubernetes Operator](/integrations/platforms/kubernetes/overview), [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical), and more.
|
||||
- Lifecycle Automation: Automate [secret rotation](/documentation/platform/secrets-mgmt/concepts/secrets-rotation), generate [dynamic secrets](/documentation/platform/secrets-mgmt/concepts/dynamic-secrets), and enforce [approval-based workflows](/documentation/platform/pr-workflows).
|
||||
- [Secrets Syncs](/integrations/secret-syncs/overview): Push secrets to external services like [GitHub](/integrations/secret-syncs/github), [GitLab](/integrations/secret-syncs/gitlab), [AWS Secrets Manager](/integrations/secret-syncs/aws-secrets-manager), [Vercel](/integrations/secret-syncs/vercel), and more.
|
||||
|
||||
Reference in New Issue
Block a user