Infisical Agent

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.

Access tokens can be utilized with Infisical SDKs or directly in API requests to retrieve secrets from Infisical

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.You can refer to the available secret template functions here. 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 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) 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. 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.

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.

config

UniversalAuthConfig

Show properties

client-id

string

required

Path to the file containing the universal auth client ID.

client-secret

string

required

Path to the file containing the universal auth client secret.

remove_client_secret_on_read

boolean

Instructs the agent to remove the client secret from disk after reading it.

1

Create a universal auth machine identity

To create a universal auth machine identity, follow the step by step guide outlined here.

2

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.

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

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.

config

KubernetesAuthConfig

Show properties

identity-id

string

required

Path to the file containing the machine identity ID.

service-account-token

string

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

1

Create a Kubernetes machine identity

To create a Kubernetes machine identity, follow the step by step guide outlined here.

2

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.

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

Native Azure

The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

config

AzureAuthConfig

Show properties

identity-id

string

required

Path to the file containing the machine identity ID.

1

Create an Azure machine identity

To create an Azure machine identity, follow the step by step guide outlined here.

2

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.

example-auth-config.yaml

auth:
  type: "azure"
  config:
    identity-id: "./identity-id" # Path to the file containing the machine identity ID

Native GCP ID Token

The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

config

GCPIDTokenAuthConfig

Show properties

identity-id

string

required

Path to the file containing the machine identity ID.

1

Create a GCP machine identity

To create a GCP machine identity, follow the step by step guide outlined here.

2

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.

example-auth-config.yaml

auth:
  type: "gcp-id-token"
  config:
    identity-id: "./identity-id" # Path to the file containing the machine identity ID

GCP IAM

The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

config

GCPIAMAuthConfig

Show properties

identity-id

string

required

Path to the file containing the machine identity ID.

service-account-key

string

required

Path to your GCP service account key file.

1

Create a GCP machine identity

To create a GCP machine identity, follow the step by step guide outlined here.

2

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.

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

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.

config

AWSIAMAuthConfig

Show properties

identity-id

string

required

Path to the file containing the machine identity ID.

1

Create an AWS machine identity

To create an AWS machine identity, follow the step by step guide outlined here.

2

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.

example-auth-config.yaml

auth:
  type: "aws-iam"
  config:
    identity-id: "./identity-id" # Path to the file containing the machine identity ID

Quick start Infisical Agent

To install the Infisical agent, you must first install the Infisical CLI 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. To obtain a Client ID and a Client Secret, follow the step by step guide outlined here.

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.

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>".

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.

infisical agent --config example-agent-config-file.yaml

Available secret template functions

listSecrets

  listSecrets "<project-id>" "environment-slug" "<secret-path>" "<optional-modifier>"

example-template-usage-1

{{- with listSecrets "6553ccb2b7da580d7f6e7260" "dev" "/" `{"recursive": false, "expandSecretReferences": true}` }}
{{- range . }}
{{ .Key }}={{ .Value }}
{{- end }}
{{- end }}

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

getSecretByName

getSecretByName "<project-id>" "<environment-slug>" "<secret-path>" "<secret-name>"

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