mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
386 lines
20 KiB
Plaintext
386 lines
20 KiB
Plaintext
---
|
|
title: "Infisical Agent"
|
|
description: "This page describes how to manage secrets using Infisical Agent."
|
|
---
|
|
|
|
Infisical Agent is a client daemon that simplifies the adoption of Infisical by providing a more scalable and user-friendly approach for applications to interact with Infisical.
|
|
It eliminates the need to modify application logic by enabling clients to decide how they want their secrets rendered through the use of templates.
|
|
|
|
|
|
|
|
### Key features:
|
|
|
|
- Token renewal: Automatically authenticates with Infisical and deposits renewed access tokens at specified path for applications to consume
|
|
- Templating: Renders secrets via user provided templates to desired formats for applications to consume
|
|
|
|
### Token renewal
|
|
|
|
The Infisical agent can help manage the life cycle of access tokens. The token renewal process is split into two main components: a `Method`, which is the authentication process suitable for your current setup, and `Sinks`, which are the places where the agent deposits the new access token whenever it receives updates.
|
|
|
|
When the Infisical Agent is started, it will attempt to obtain a valid access token using the authentication method you have configured. If the agent is unable to fetch a valid token, the agent will keep trying, increasing the time between each attempt.
|
|
|
|
Once a access token is successfully fetched, the agent will make sure the access token stays valid, continuing to renew it before it expires.
|
|
|
|
Every time the agent successfully retrieves a new access token, it writes the new token to the Sinks you've configured.
|
|
|
|
<Info>
|
|
Access tokens can be utilized with Infisical SDKs or directly in API requests
|
|
to retrieve secrets from Infisical
|
|
</Info>
|
|
|
|
### Templating
|
|
|
|
The Infisical agent can help deliver formatted secrets to your application in a variety of environments. To achieve this, the agent will retrieve secrets from Infisical, format them using a specified template, and then save these formatted secrets to a designated file path.
|
|
|
|
Templating process is done through the use of Go language's [text/template feature](https://pkg.go.dev/text/template).You can refer to the available secret template functions [here](#available-secret-template-functions). Multiple template definitions can be set in the agent configuration file to generate a variety of formatted secret files.
|
|
|
|
When the agent is started and templates are defined in the agent configuration file, the agent will attempt to acquire a valid access token using the set authentication method outlined in the agent's configuration.
|
|
If this initial attempt is unsuccessful, the agent will momentarily pauses before continuing to make more attempts.
|
|
|
|
Once the agent successfully obtains a valid access token, the agent proceeds to fetch the secrets from Infisical using it.
|
|
It then formats these secrets using the user provided templates and writes the formatted data to configured file paths.
|
|
|
|
## Agent configuration file
|
|
|
|
To set up the authentication method for token renewal and to define secret templates, the Infisical agent requires a YAML configuration file containing properties defined below.
|
|
While specifying an authentication method is mandatory to start the agent, configuring sinks and secret templates are optional.
|
|
|
|
| Field | Description |
|
|
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `infisical.address` | The URL of the Infisical service. Default: `"https://app.infisical.com"`. |
|
|
| `auth.type` | The type of authentication method used. Available options: `universal-auth`, `kubernetes`, `azure`, `gcp-id-token`, `gcp-iam`, `aws-iam` |
|
|
| `auth.config.identity-id` | The file path where the machine identity id is stored<br/><br/>This field is required when using any of the following auth types: `kubernetes`, `azure`, `gcp-id-token`, `gcp-iam`, or `aws-iam`. |
|
|
| `auth.config.service-account-token` | Path to the Kubernetes service account token to use (optional)<br/><br/>Default: `/var/run/secrets/kubernetes.io/serviceaccount/token` |
|
|
| `auth.config.service-account-key` | Path to your GCP service account key file. This field is required when using `gcp-iam` auth type.<br/><br/>Please note that the file should be in JSON format. |
|
|
| `auth.config.client-id` | The file path where the universal-auth client id is stored. |
|
|
| `auth.config.client-secret` | The file path where the universal-auth client secret is stored. |
|
|
| `auth.config.remove_client_secret_on_read` | This will instruct the agent to remove the client secret from disk. |
|
|
| `sinks[].type` | The type of sink in a list of sinks. Each item specifies a sink type. Currently, only `"file"` type is available. |
|
|
| `sinks[].config.path` | The file path where the access token should be stored for each sink in the list. |
|
|
| `templates[].source-path` | The path to the template file that should be used to render secrets. |
|
|
| `templates[].template-content` | The inline secret template to be used for rendering the secrets. |
|
|
| `templates[].destination-path` | The path where the rendered secrets from the source template will be saved to. |
|
|
| `templates[].config.polling-interval` | How frequently to check for secret changes. Default: `5 minutes` (optional) |
|
|
| `templates[].config.execute.command` | The command to execute when secret change is detected (optional) |
|
|
| `templates[].config.execute.timeout` | How long in seconds to wait for command to execute before timing out (optional) |
|
|
|
|
## Authentication
|
|
|
|
The Infisical agent supports multiple authentication methods. Below are the available authentication methods, with their respective configurations.
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Universal Auth">
|
|
The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical.
|
|
|
|
<ParamField query="config" type="UniversalAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="client-id" type="string" required>
|
|
Path to the file containing the universal auth client ID.
|
|
</ParamField>
|
|
<ParamField query="client-secret" type="string" required>
|
|
Path to the file containing the universal auth client secret.
|
|
</ParamField>
|
|
<ParamField query="remove_client_secret_on_read" type="boolean" optional>
|
|
Instructs the agent to remove the client secret from disk after reading
|
|
it.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create a universal auth machine identity">
|
|
To create a universal auth machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/universal-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method, client ID, and client secret. In the snippet below you can see a sample configuration of the `auth` field when using the Universal Auth method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "universal-auth"
|
|
config:
|
|
client-id: "./client-id" # Path to the file containing the client ID
|
|
client-secret: "./client" # Path to the file containing the client secret
|
|
remove_client_secret_on_read: false # Optional field, instructs the agent to remove the client secret from disk after reading it
|
|
```
|
|
</Step>
|
|
|
|
</Steps>
|
|
</Accordion>
|
|
<Accordion title="Native Kubernetes">
|
|
The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.
|
|
|
|
{" "}
|
|
|
|
<ParamField query="config" type="KubernetesAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="identity-id" type="string" required>
|
|
Path to the file containing the machine identity ID.
|
|
</ParamField>
|
|
<ParamField query="service-account-token" type="string" optional>
|
|
Path to the Kubernetes service account token to use. Default:
|
|
`/var/run/secrets/kubernetes.io/serviceaccount/token`.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create a Kubernetes machine identity">
|
|
To create a Kubernetes machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/kubernetes-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method, identity ID, and service account token. In the snippet below you can see a sample configuration of the `auth` field when using the Kubernetes method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "kubernetes"
|
|
config:
|
|
identity-id: "./identity-id" # Path to the file containing the machine identity ID
|
|
service-account-token: "/var/run/secrets/kubernetes.io/serviceaccount/token" # Optional field, custom path to the Kubernetes service account token to use
|
|
```
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
</Accordion>
|
|
<Accordion title="Native Azure">
|
|
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
|
|
|
|
<ParamField query="config" type="AzureAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="identity-id" type="string" required>
|
|
Path to the file containing the machine identity ID.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create an Azure machine identity">
|
|
To create an Azure machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/azure-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method and identity ID. In the snippet below you can see a sample configuration of the `auth` field when using the Azure method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "azure"
|
|
config:
|
|
identity-id: "./identity-id" # Path to the file containing the machine identity ID
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Accordion>
|
|
<Accordion title="Native GCP ID Token">
|
|
The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.
|
|
|
|
<ParamField query="config" type="GCPIDTokenAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="identity-id" type="string" required>
|
|
Path to the file containing the machine identity ID.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create a GCP machine identity">
|
|
To create a GCP machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/gcp-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method and identity ID. In the snippet below you can see a sample configuration of the `auth` field when using the GCP ID Token method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "gcp-id-token"
|
|
config:
|
|
identity-id: "./identity-id" # Path to the file containing the machine identity ID
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Accordion>
|
|
<Accordion title="GCP IAM">
|
|
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
|
|
|
|
<ParamField query="config" type="GCPIAMAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="identity-id" type="string" required>
|
|
Path to the file containing the machine identity ID.
|
|
</ParamField>
|
|
<ParamField query="service-account-key" type="string" required>
|
|
Path to your GCP service account key file.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create a GCP machine identity">
|
|
To create a GCP machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/gcp-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method, identity ID, and service account key. In the snippet below you can see a sample configuration of the `auth` field when using the GCP IAM method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "gcp-iam"
|
|
config:
|
|
identity-id: "./identity-id" # Path to the file containing the machine identity ID
|
|
service-account-key: "./service-account-key.json" # Path to your GCP service account key file
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Accordion>
|
|
<Accordion title="Native AWS IAM">
|
|
The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.
|
|
|
|
<ParamField query="config" type="AWSIAMAuthConfig">
|
|
<Expandable title="properties">
|
|
<ParamField query="identity-id" type="string" required>
|
|
Path to the file containing the machine identity ID.
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
<Steps>
|
|
<Step title="Create an AWS machine identity">
|
|
To create an AWS machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/aws-auth).
|
|
</Step>
|
|
<Step title="Configure the agent">
|
|
Update the agent configuration file with the specified auth method and identity ID. In the snippet below you can see a sample configuration of the `auth` field when using the AWS IAM method.
|
|
|
|
```yaml example-auth-config.yaml
|
|
auth:
|
|
type: "aws-iam"
|
|
config:
|
|
identity-id: "./identity-id" # Path to the file containing the machine identity ID
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Quick start Infisical Agent
|
|
|
|
To install the Infisical agent, you must first install the [Infisical CLI](/cli/overview) in the desired environment where you'd like the agent to run. This is because the Infisical agent is a sub-command of the Infisical CLI.
|
|
|
|
Once you have the CLI installed, you will need to provision programmatic access for the agent via [Universal Auth](/documentation/platform/identities/universal-auth). To obtain a **Client ID** and a **Client Secret**, follow the step by step guide outlined [here](/documentation/platform/identities/universal-auth).
|
|
|
|
Next, create agent config file as shown below. The example agent configuration file defines the token authentication method, one sink location, and a secret template.
|
|
|
|
```yaml example-agent-config-file.yaml
|
|
infisical:
|
|
address: "https://app.infisical.com"
|
|
auth:
|
|
type: "universal-auth"
|
|
config:
|
|
client-id: "./client-id"
|
|
client-secret: "./client-secret"
|
|
remove_client_secret_on_read: false
|
|
sinks:
|
|
- type: "file"
|
|
config:
|
|
path: "/some/path/to/store/access-token/file-name"
|
|
templates:
|
|
- source-path: my-dot-ev-secret-template
|
|
destination-path: /some/path/.env
|
|
config:
|
|
polling-interval: 60s
|
|
execute:
|
|
timeout: 30
|
|
command: ./reload-app.sh
|
|
```
|
|
|
|
The secret template below will be used to render the secrets with the key and the value separated by `=` sign. You'll notice that a custom function named `secret` is used to fetch the secrets.
|
|
This function takes the following arguments: `secret "<project-id>" "<environment-slug>" "<secret-path>"`.
|
|
|
|
```text my-dot-ev-secret-template
|
|
{{- with secret "6553ccb2b7da580d7f6e7260" "dev" "/" }}
|
|
{{- range . }}
|
|
{{ .Key }}={{ .Value }}
|
|
{{- end }}
|
|
{{- end }}
|
|
```
|
|
|
|
After defining the agent configuration file, run the command below pointing to the path where the agent configuration file is located.
|
|
|
|
```bash
|
|
infisical agent --config example-agent-config-file.yaml
|
|
```
|
|
|
|
### Available secret template functions
|
|
|
|
<Accordion title="listSecrets">
|
|
```bash
|
|
listSecrets "<project-id>" "environment-slug" "<secret-path>" "<optional-modifier>"
|
|
```
|
|
```bash example-template-usage-1
|
|
{{- with listSecrets "6553ccb2b7da580d7f6e7260" "dev" "/" `{"recursive": false, "expandSecretReferences": true}` }}
|
|
{{- range . }}
|
|
{{ .Key }}={{ .Value }}
|
|
{{- end }}
|
|
{{- end }}
|
|
```
|
|
```bash example-template-usage-2
|
|
{{- with secret "da8056c8-01e2-4d24-b39f-cb4e004b8d44" "staging" "/" `{"recursive": true, "expandSecretReferences": true}` }}
|
|
{{- range . }}
|
|
{{- if eq .SecretPath "/"}}
|
|
{{ .Key }}={{ .Value }}
|
|
{{- else}}
|
|
{{ .SecretPath }}/{{ .Key }}={{ .Value }}
|
|
{{- end}}
|
|
{{- end }}
|
|
{{- end }}
|
|
```
|
|
|
|
|
|
|
|
**Function name**: listSecrets
|
|
|
|
**Description**: This function can be used to render the full list of secrets within a given project, environment and secret path.
|
|
|
|
An optional JSON argument is also available. It includes the properties `recursive`, which defaults to false, and `expandSecretReferences`, which defaults to true and expands the returned secrets.
|
|
|
|
|
|
**Returns**: A single secret object with the following keys `Key, WorkspaceId, Value, SecretPath, Type, ID, and Comment`
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="getSecretByName">
|
|
```bash
|
|
getSecretByName "<project-id>" "<environment-slug>" "<secret-path>" "<secret-name>"
|
|
```
|
|
|
|
```bash example-template-usage
|
|
{{ with getSecretByName "d821f21d-aa90-453b-8448-8c78c1160a0e" "dev" "/" "POSTHOG_HOST"}}
|
|
{{ if .Value }}
|
|
password = "{{ .Value }}"
|
|
{{ end }}
|
|
{{ end }}
|
|
```
|
|
|
|
**Function name**: getSecretByName
|
|
|
|
**Description**: This function can be used to render a single secret by it's name.
|
|
|
|
**Returns**: A list of secret objects with the following keys `Key, WorkspaceId, Value, Type, ID, and Comment`
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="dynamic_secret">
|
|
```bash
|
|
dynamic_secret "<project-slug>" "<environment-slug>" "<secret-path>" "<dynamic-secret-name>" "<lease-ttl>"
|
|
```
|
|
|
|
```bash example-redis-dynamic-secret
|
|
{{ with dynamic_secret "aaa-o7en-s5qm" "dev" "/" "redis" "1m" }}
|
|
{{ .DB_USERNAME }}={{ .DB_PASSWORD }}
|
|
{{- end }}
|
|
|
|
**Function Name**: dynamic_secret
|
|
|
|
**Description**: This function can be used to render a dynamic secret lease credentials. The credentials are automatically renewed before they expire, ensuring that the rendered credentials are always up-to-date.
|
|
|
|
**Returns**: An object with keys corresponding to the dynamic secret lease credentials.
|
|
```
|
|
</Accordion> |