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

doc: added docs

Browse Source
This commit is contained in:
Sheen
2025-03-18 14:43:19 +00:00
parent ed6306747a
commit 1ec11d5963
3 changed files with 307 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
docs/cli/commands/bootstrap.mdx Normal file
View File

@@ -0,0 +1,134 @@
---
title: "infisical bootstrap"
description: "Automate the initial setup of a new Infisical instance for headless deployment and infrastructure-as-code workflows"
---
```bash
infisical bootstrap --domain=<domain> --email=<email> --password=<password> --organization=<organization>
```
## Description
The `infisical bootstrap` command is used when deploying Infisical in automated environments where manual UI setup is not feasible. It's ideal for:
- Containerized deployments in Kubernetes or Docker environments
- Infrastructure-as-code pipelines with Terraform or similar tools
- Continuous deployment workflows
- DevOps automation scenarios
The command initializes a fresh Infisical instance by creating an admin user, organization, and instance admin machine identity, enabling subsequent programmatic configuration without human intervention.
**Security Warning**: This command creates an instance admin machine identity with the highest level of privileges. The returned token should be treated with the utmost security, similar to a root credential. Unauthorized access to this token could compromise your entire Infisical instance.
## Flags
<Accordion title="--domain" defaultOpen="true">
The URL of your Infisical instance.
```bash
# Example
infisical bootstrap --domain=https://your-infisical-instance.com
```
This flag is required.
</Accordion>
<Accordion title="--email">
Email address for the admin user account that will be created.
```bash
# Example
infisical bootstrap --email=admin@example.com
```
This flag is required.
</Accordion>
<Accordion title="--password">
Password for the admin user account.
```bash
# Example
infisical bootstrap --password=your-secure-password
```
This flag is required.
</Accordion>
<Accordion title="--organization">
Name of the organization that will be created within the instance.
```bash
# Example
infisical bootstrap --organization=your-org-name
```
This flag is required.
</Accordion>
## Response
The command returns a JSON response with details about the created user, organization, and machine identity:
```json
{
"message": "Successfully initialized instance",
"user": {
"id": "911d6d11-2bf8-4f1b-861d-6a0ec43e7e1a",
"email": "admin@example.com",
"authMethods": [
"email"
],
"superAdmin": true,
"firstName": "Admin",
"lastName": "User",
"isAccepted": true,
"isMfaEnabled": false,
// Additional user properties...
},
"organization": {
"id": "65a54d51-cac9-418a-ae17-20bfc715c6df",
"name": "your-org-name",
"slug": "your-org-name-xxxx",
"createdAt": "2025-03-17T11:11:41.564Z",
"updatedAt": "2025-03-17T11:11:41.564Z",
// Additional organization properties...
},
"identity": {
"id": "4fa39767-39ce-440f-bb00-f6aae64b3dd5",
"name": "Admin Identity",
"authMethod": null,
"createdAt": "2025-03-17T11:11:41.569Z",
"updatedAt": "2025-03-17T11:11:41.569Z",
"credentials": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}
```
## Usage with Automation
For automation purposes, you can extract just the machine identity token from the response:
```bash
infisical bootstrap --domain=https://your-infisical-instance.com --email=admin@example.com --password=your-secure-password --organization=your-org-name | jq ".identity.credentials.token"
```
This extracts only the token, which can be captured in a variable or piped to other commands.
## Example: Capture Token in a Variable
```bash
TOKEN=$(infisical bootstrap --domain=https://your-infisical-instance.com --email=admin@example.com --password=your-secure-password --organization=your-org-name | jq -r ".identity.credentials.token")
# Now use the token for further automation
echo "Token has been captured and can be used for authentication"
```
## Notes
- The bootstrap process can only be performed once on a fresh Infisical instance
- All flags are required for the bootstrap process to complete successfully
- Security controls prevent privilege escalation: instance admin identities cannot be managed by non-instance admin users and identities
- The generated admin user account can be used to log in via the UI if needed

4
docs/mint.json
View File

@@ -311,7 +311,8 @@
"group": "Guides",
"pages": [
"self-hosting/guides/mongo-to-postgres",
"self-hosting/guides/custom-certificates"
"self-hosting/guides/custom-certificates",
"self-hosting/guides/automated-bootstrapping"
]
},
{
@@ -341,6 +342,7 @@
"cli/commands/dynamic-secrets",
"cli/commands/ssh",
"cli/commands/gateway",
"cli/commands/bootstrap",
"cli/commands/export",
"cli/commands/token",
"cli/commands/service-token",

170
docs/self-hosting/guides/automated-bootstrapping.mdx Normal file
View File

@@ -0,0 +1,170 @@
---
title: "Automated Bootstrapping"
description: "Learn how to provision and configure Infisical instances programmatically without UI interaction"
---
Infisical's Automated Bootstrapping feature enables you to provision and configure an Infisical instance without using the UI, allowing for complete automation through static configuration files, API calls, or CLI commands. This is especially valuable for enterprise environments where automated deployment and infrastructure-as-code practices are essential.
## Overview
The Automated Bootstrapping workflow automates the following processes:
- Creating an admin user account
- Initializing an organization for the entire instance
- Establishing an **instance admin machine identity** with full administrative permissions
- Returning the machine identity credentials for further automation
## Key Concepts
- **Instance Initialization**: Infisical requires configuration variables to be set during launch, after which the bootstrap process can be triggered.
- **Instance Admin Machine Identity**: The bootstrapping process creates a machine identity with instance-level admin privileges, which can be used to programmatically manage all aspects of the Infisical instance.
- **Token Auth**: The instance admin machine identity uses [Token Auth](https://infisical.com/docs/documentation/platform/identities/token-auth), providing a JWT token that can be used directly to make authenticated requests to the Infisical API.
## Prerequisites
- An Infisical instance launched with all required configuration variables
- Access to the Infisical CLI or the ability to make API calls to the instance
- Network connectivity to the Infisical instance
## Bootstrap Methods
You can bootstrap an Infisical instance using either the API or the CLI.
### Using the API
Make a POST request to the bootstrap endpoint:
```
POST: http://your-infisical-instance.com/api/v1/admin/bootstrap
{
"email": "admin@example.com",
"password": "your-secure-password",
"organization": "your-org-name"
}
```
Example using curl:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{"email":"admin@example.com","password":"your-secure-password","organization":"your-org-name"}' \
http://your-infisical-instance.com/api/v1/admin/bootstrap
```
### Using the CLI
Use the [Infisical CLI](https://infisical.com/docs/cli/commands/bootstrap) to bootstrap the instance and extract the token for immediate use in automation:
```bash
infisical bootstrap --domain="http://localhost:8080" --email="admin@example.com" --password="your-secure-password" --organization="your-org-name" | jq ".identity.credentials.token"
```
This command pipes the output through `jq` to extract only the machine identity token, making it easy to capture and use directly in automation scripts or export as an environment variable for tools like Terraform.
## API Response Structure
The bootstrap process returns a JSON response with details about the created user, organization, and machine identity:
```json
{
"message": "Successfully initialized instance",
"user": {
"id": "911d6d11-2bf8-4f1b-861d-6a0ec43e7e1a",
"email": "admin@example.com",
"authMethods": [
"email"
],
"superAdmin": true,
"firstName": "Admin",
"lastName": "User",
"isAccepted": true,
"isMfaEnabled": false,
// Additional user properties...
},
"organization": {
"id": "65a54d51-cac9-418a-ae17-20bfc715c6df",
"name": "your-org-name",
"slug": "your-org-name-xxxx",
"createdAt": "2025-03-17T11:11:41.564Z",
"updatedAt": "2025-03-17T11:11:41.564Z",
// Additional organization properties...
},
"identity": {
"id": "4fa39767-39ce-440f-bb00-f6aae64b3dd5",
"name": "Admin Identity",
"authMethod": null,
"createdAt": "2025-03-17T11:11:41.569Z",
"updatedAt": "2025-03-17T11:11:41.569Z",
"credentials": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}
```
## Using the Instance Admin Machine Identity Token
The bootstrap process automatically creates a machine identity with Token Auth configured. The returned token has instance-level admin privileges (the highest level of access) and should be treated with the same security considerations as a root credential.
The token enables full programmatic control of your Infisical instance and can be used in the following ways:
### 1. Infrastructure Automation
Store the token securely for use with infrastructure automation tools. Due to the sensitive nature of this token, ensure it's protected using appropriate secret management practices:
#### Kubernetes Secret (with appropriate RBAC restrictions)
```yaml
apiVersion: v1
kind: Secret
metadata:
name: infisical-admin-credentials
type: Opaque
data:
token: <base64-encoded-token>
```
#### Environment Variable for Terraform (preferably using a secure vault solution)
```bash
export INFISICAL_TOKEN=your-access-token
terraform apply
```
### 2. Programmatic Resource Management
Use the token to authenticate API calls for creating and managing Infisical resources. The token works exactly like any other Token Auth access token in the Infisical API:
```bash
curl -X POST \
-H "Authorization: Bearer ${INFISICAL_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"projectName": "New Project",
"projectDescription": "A project created via API",
"slug": "new-project-slug",
"template": "default",
"type": "SECRET_MANAGER"
}' \
https://your-infisical-instance.com/api/v2/projects
```
## End-to-End Workflow
1. **Configuration**: Launch Infisical with all necessary configuration variables
2. **Bootstrapping**: Initialize the instance using either the API or CLI
- When using CLI, pipe the output to extract just the token: `infisical bootstrap ... | jq ".identity.credentials.token"`
- This extracted token can be directly captured in a script variable or used in a command chain
3. **Automation**: Use the instance admin machine identity for programmatic management:
- Persist the identity credentials securely (Kubernetes secrets, environment variables)
- Configure automation tools (Terraform, Crossplane) to use these credentials
- Manage Infisical resources programmatically through APIs
## Important Notes
- **Security Warning**: The instance admin machine identity has the highest level of privileges in your Infisical deployment. The token should be treated with the utmost security and handled like a root credential. Unauthorized access to this token could compromise your entire Infisical instance.
- Security controls prevent privilege escalation: instance admin identities cannot be managed by non-instance admin users and identities
- The instance admin permission of the generated identity can be revoked later in the server admin panel if needed
- The generated admin user account can still be used for UI access if needed, or can be removed if you prefer to manage everything through the machine identity
- This process is designed to work with future Crossplane providers and the existing Terraform provider for full infrastructure-as-code capabilities
- All necessary configuration variables should be set during the initial launch of the Infisical instance