Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(secret-sync): retake portainer screenshots at 2x and describe gateway and redeploy behavior

Yeongjin Leef165eba74288
diff --git a/docs/images/app-connections/portainer/step-1.png b/docs/images/app-connections/portainer/step-1.png
index a3e0a39fb6..f8df47d4bd 100644
Binary files a/docs/images/app-connections/portainer/step-1.png and b/docs/images/app-connections/portainer/step-1.png differ
diff --git a/docs/images/app-connections/portainer/step-2.png b/docs/images/app-connections/portainer/step-2.png
index c1d4f5bf34..c0edfed4d9 100644
Binary files a/docs/images/app-connections/portainer/step-2.png and b/docs/images/app-connections/portainer/step-2.png differ
diff --git a/docs/images/app-connections/portainer/step-3.png b/docs/images/app-connections/portainer/step-3.png
index eb320c3f9a..dd3d7d9ebb 100644
Binary files a/docs/images/app-connections/portainer/step-3.png and b/docs/images/app-connections/portainer/step-3.png differ
diff --git a/docs/images/secret-syncs/portainer/step-1.png b/docs/images/secret-syncs/portainer/step-1.png
index da80cf3e60..2e2d9d466b 100644
Binary files a/docs/images/secret-syncs/portainer/step-1.png and b/docs/images/secret-syncs/portainer/step-1.png differ
diff --git a/docs/images/secret-syncs/portainer/step-2.png b/docs/images/secret-syncs/portainer/step-2.png
index 452c981e2d..7939cb302b 100644
Binary files a/docs/images/secret-syncs/portainer/step-2.png and b/docs/images/secret-syncs/portainer/step-2.png differ
diff --git a/docs/images/secret-syncs/portainer/step-3.png b/docs/images/secret-syncs/portainer/step-3.png
index 362f9794cc..8e6f7a9d21 100644
Binary files a/docs/images/secret-syncs/portainer/step-3.png and b/docs/images/secret-syncs/portainer/step-3.png differ
diff --git a/docs/images/secret-syncs/portainer/step-4.png b/docs/images/secret-syncs/portainer/step-4.png
index d88052ff70..a2ca1ec8a8 100644
Binary files a/docs/images/secret-syncs/portainer/step-4.png and b/docs/images/secret-syncs/portainer/step-4.png differ
diff --git a/docs/images/secret-syncs/portainer/step-5.png b/docs/images/secret-syncs/portainer/step-5.png
index 6425ac399f..eb179a9ccf 100644
Binary files a/docs/images/secret-syncs/portainer/step-5.png and b/docs/images/secret-syncs/portainer/step-5.png differ
diff --git a/docs/images/secret-syncs/portainer/step-6.png b/docs/images/secret-syncs/portainer/step-6.png
index e072aa17cb..80c599a994 100644
Binary files a/docs/images/secret-syncs/portainer/step-6.png and b/docs/images/secret-syncs/portainer/step-6.png differ
diff --git a/docs/images/secret-syncs/portainer/step-7.png b/docs/images/secret-syncs/portainer/step-7.png
index 421b7fa2d6..6cf066d8b8 100644
Binary files a/docs/images/secret-syncs/portainer/step-7.png and b/docs/images/secret-syncs/portainer/step-7.png differ
diff --git a/docs/images/secret-syncs/portainer/step-8.png b/docs/images/secret-syncs/portainer/step-8.png
index ae7dc4cf5e..1fa4f99055 100644
Binary files a/docs/images/secret-syncs/portainer/step-8.png and b/docs/images/secret-syncs/portainer/step-8.png differ
diff --git a/docs/integrations/app-connections/portainer.mdx b/docs/integrations/app-connections/portainer.mdx
index 49e97724f8..81f82b26b2 100644
--- a/docs/integrations/app-connections/portainer.mdx
+++ b/docs/integrations/app-connections/portainer.mdx
@@ -6,6 +6,11 @@ description: "Learn how to configure a Portainer Connection for Infisical."
Infisical supports connecting to Portainer using an **API Token**.
+## Prerequisites
+
+- A Portainer user whose permissions cover the environments and stacks you want to sync to
+- If your Portainer instance isn't reachable from the internet, a [Gateway](/documentation/platform/gateways/overview) with network access to it
+
## Generate a Portainer API token
<Steps>
@@ -21,8 +26,7 @@ Infisical supports connecting to Portainer using an **API Token**.
**Add access token**.
<Note>
- An access token inherits the permissions of the user that created it. Create it with a user
- that can read environments and update the stacks you intend to sync to.
+ An access token inherits the permissions of the user that created it.
</Note>
</Step>
<Step title="Copy the API token">
@@ -46,15 +50,12 @@ Infisical supports connecting to Portainer using an **API Token**.
- A descriptive **Name** for the connection (must be slug-friendly)
- An optional **Description** for future reference
- The **Method** (**API Token**)
+ - The **Gateway** to route requests through, if the instance isn't reachable from the internet
- The **Portainer Instance URL** (e.g., `https://portainer.example.com`)
- The **Portainer API Token** you generated above
Select **Connect to Portainer**.
![Portainer Connection Form](/images/app-connections/portainer/step-2.png)
-
- <Note>
- The instance URL must be reachable from your Infisical instance.
- </Note>
</Step>
<Step title="Connection Created">
Your **Portainer Connection** is established and ready to use with your Infisical project.
@@ -66,6 +67,9 @@ Infisical supports connecting to Portainer using an **API Token**.
To create a Portainer Connection, make an API request to the [Create Portainer
Connection](/api-reference/endpoints/app-connections/portainer/create) API endpoint.
+ If the instance isn't reachable from the internet, include the ID of a Gateway that can reach it as
+ `gatewayId`, or the ID of a Gateway pool as `gatewayPoolId`.
+
### Sample request
```bash Request
diff --git a/docs/integrations/secret-syncs/portainer.mdx b/docs/integrations/secret-syncs/portainer.mdx
index e830112235..1ee66a702f 100644
--- a/docs/integrations/secret-syncs/portainer.mdx
+++ b/docs/integrations/secret-syncs/portainer.mdx
@@ -13,15 +13,29 @@ Infisical syncs secrets to the environment variables of a Portainer stack.
<Note>
**How the stack is updated depends on its type.**
- - **Git-backed stacks**: variables are written to the stack's Git configuration. The running
- containers are left untouched, and the new values take effect on the stack's next deployment
- (either an auto-update poll or a manual redeploy).
- - **File-based stacks**: Portainer requires the compose file on every update, so Infisical
- resubmits the current file unchanged along with the variables. This re-deploys the stack.
+ **Git-backed stacks:** Infisical writes the variables to the stack's Git settings. The running
+ containers are left untouched, and the new values take effect on the stack's next deployment
+ (an auto-update poll, a webhook, or a manual redeploy).
+
+ **File-based stacks:** Portainer requires the compose file on every update, so Infisical
+ resubmits the current file unchanged along with the variables, and Portainer redeploys the
+ stack. Infisical skips the update if the stack already has exactly these variables. Otherwise
+ Infisical waits for the redeploy to finish, and if Portainer reports that the redeploy failed,
+ the sync fails with Portainer's error message.
+
+ **Kubernetes stacks:** Portainer doesn't apply environment variables to Kubernetes stacks, so
+ Infisical doesn't list them as a destination and fails a sync that targets one.
If you need variables to land without restarting anything, use a Git-backed stack.
</Note>
+<Note>
+ Portainer stores a Compose stack's variables in an env file with one line per variable. If a
+ value contains line breaks, such as a PEM certificate, Infisical stores the value in double quotes
+ with each line break escaped as `\n`, and Portainer restores the line breaks when it deploys the
+ stack. Swarm stacks receive multiline values as-is.
+</Note>
+
<Tabs>
<Tab title="Infisical UI">
1. Navigate to **Project** > **Integrations** and select the **Secret Syncs** tab. Select **Add Sync**, then select **Portainer** as the destination.
@@ -32,6 +46,7 @@ Infisical syncs secrets to the environment variables of a Portainer stack.
- **Environment**: The project environment to retrieve secrets from.
- **Secret Path**: The folder path to retrieve secrets from.
+ - **Include secrets from all subfolders**: If enabled, secrets in every folder beneath the path are synced too.
<Tip>
If you need to sync secrets from multiple folder locations, check out [secret imports](/documentation/platform/secret-reference#secret-imports).
@@ -47,22 +62,22 @@ Infisical syncs secrets to the environment variables of a Portainer stack.
4. Configure the **Initial Sync Behavior** to determine how Infisical should resolve the first sync, then select **Continue**.
![Configure Initial Sync](/images/secret-syncs/portainer/step-4.png)
- - **Overwrite Destination Secrets**: Infisical writes its secrets to the stack. No variables are imported back.
- - **Import Destination Secrets - Prioritize Infisical Values**: Existing stack variables are imported into Infisical first; where a key exists on both sides, the Infisical value wins.
- - **Import Destination Secrets - Prioritize Portainer Values**: Same as above, but the stack's value wins on conflicts.
+ - **Overwrite Portainer**: Infisical writes its secrets to the stack. No variables are imported back.
+ - **Import from Portainer, prioritize Infisical**: Existing stack variables are imported into Infisical first; where a key exists on both sides, the Infisical value wins.
+ - **Import from Portainer, prioritize Portainer**: Same as above, but the stack's value wins on conflicts.
5. Configure the **Sync Options** to control how secrets are written, then select **Continue**.
![Configure Sync Options](/images/secret-syncs/portainer/step-5.png)
- - **Disable Secret Deletion**: If enabled, Infisical will not remove variables from the stack during a sync. Enable this if you intend to manage some variables manually outside of Infisical.
- - **Auto-Sync on Changes**: If enabled, secrets are automatically synced whenever they change in the source. Turn off to sync manually only.
- - **Customize Key Names**: Add a prefix or suffix so Infisical can identify which variables in the stack it manages — anything else is left untouched.
+ - **Prevent secret deletion**: If enabled, Infisical never removes variables from the stack during a sync. Enable this if you manage some variables manually outside of Infisical.
+ - **Auto-sync on changes**: If enabled, secrets are synced automatically whenever they change in the source. Turn off to sync manually only.
+ - **Customize key names**: Add a prefix or suffix so Infisical can identify which variables in the stack it manages. Anything else is left untouched.
<Warning>
A Portainer stack stores its variables as a single list, so a sync rewrites that whole list.
Without a key schema, every existing variable on the stack is treated as managed by this sync
- and may be removed once it leaves the source. Use **Customize Key Names** or **Disable Secret
- Deletion** to preserve variables set outside of Infisical.
+ and may be removed once it leaves the source. Use **Customize key names** or **Prevent secret
+ deletion** to preserve variables set outside of Infisical.
</Warning>
6. Configure the **Details** of your Portainer Sync, then select **Continue**.