Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
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.pngindex a3e0a39fb6..f8df47d4bd 100644Binary files a/docs/images/app-connections/portainer/step-1.png and b/docs/images/app-connections/portainer/step-1.png differdiff --git a/docs/images/app-connections/portainer/step-2.png b/docs/images/app-connections/portainer/step-2.pngindex c1d4f5bf34..c0edfed4d9 100644Binary files a/docs/images/app-connections/portainer/step-2.png and b/docs/images/app-connections/portainer/step-2.png differdiff --git a/docs/images/app-connections/portainer/step-3.png b/docs/images/app-connections/portainer/step-3.pngindex eb320c3f9a..dd3d7d9ebb 100644Binary files a/docs/images/app-connections/portainer/step-3.png and b/docs/images/app-connections/portainer/step-3.png differdiff --git a/docs/images/secret-syncs/portainer/step-1.png b/docs/images/secret-syncs/portainer/step-1.pngindex da80cf3e60..2e2d9d466b 100644Binary files a/docs/images/secret-syncs/portainer/step-1.png and b/docs/images/secret-syncs/portainer/step-1.png differdiff --git a/docs/images/secret-syncs/portainer/step-2.png b/docs/images/secret-syncs/portainer/step-2.pngindex 452c981e2d..7939cb302b 100644Binary files a/docs/images/secret-syncs/portainer/step-2.png and b/docs/images/secret-syncs/portainer/step-2.png differdiff --git a/docs/images/secret-syncs/portainer/step-3.png b/docs/images/secret-syncs/portainer/step-3.pngindex 362f9794cc..8e6f7a9d21 100644Binary files a/docs/images/secret-syncs/portainer/step-3.png and b/docs/images/secret-syncs/portainer/step-3.png differdiff --git a/docs/images/secret-syncs/portainer/step-4.png b/docs/images/secret-syncs/portainer/step-4.pngindex d88052ff70..a2ca1ec8a8 100644Binary files a/docs/images/secret-syncs/portainer/step-4.png and b/docs/images/secret-syncs/portainer/step-4.png differdiff --git a/docs/images/secret-syncs/portainer/step-5.png b/docs/images/secret-syncs/portainer/step-5.pngindex 6425ac399f..eb179a9ccf 100644Binary files a/docs/images/secret-syncs/portainer/step-5.png and b/docs/images/secret-syncs/portainer/step-5.png differdiff --git a/docs/images/secret-syncs/portainer/step-6.png b/docs/images/secret-syncs/portainer/step-6.pngindex e072aa17cb..80c599a994 100644Binary files a/docs/images/secret-syncs/portainer/step-6.png and b/docs/images/secret-syncs/portainer/step-6.png differdiff --git a/docs/images/secret-syncs/portainer/step-7.png b/docs/images/secret-syncs/portainer/step-7.pngindex 421b7fa2d6..6cf066d8b8 100644Binary files a/docs/images/secret-syncs/portainer/step-7.png and b/docs/images/secret-syncs/portainer/step-7.png differdiff --git a/docs/images/secret-syncs/portainer/step-8.png b/docs/images/secret-syncs/portainer/step-8.pngindex ae7dc4cf5e..1fa4f99055 100644Binary files a/docs/images/secret-syncs/portainer/step-8.png and b/docs/images/secret-syncs/portainer/step-8.png differdiff --git a/docs/integrations/app-connections/portainer.mdx b/docs/integrations/app-connections/portainer.mdxindex 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 aboveSelect **Connect to Portainer**.-- <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 PortainerConnection](/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 Requestdiff --git a/docs/integrations/secret-syncs/portainer.mdx b/docs/integrations/secret-syncs/portainer.mdxindex 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**.- - **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**.- - **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**.