Skip to content

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

fix(secret-sync): stop tracking portainer deployments and keep the stack's settings on update

Yeongjin Leef71beebcdeca
diff --git a/backend/src/services/app-connection/portainer/portainer-connection-enums.ts b/backend/src/services/app-connection/portainer/portainer-connection-enums.ts
index e3aaedd057..e78eae697e 100644
--- a/backend/src/services/app-connection/portainer/portainer-connection-enums.ts
+++ b/backend/src/services/app-connection/portainer/portainer-connection-enums.ts
@@ -7,10 +7,3 @@ export enum PortainerStackType {
Compose = 2,
Kubernetes = 3
}
-
-export enum PortainerStackStatus {
- Active = 1,
- Inactive = 2,
- Deploying = 3,
- Error = 4
-}
diff --git a/backend/src/services/app-connection/portainer/portainer-connection-types.ts b/backend/src/services/app-connection/portainer/portainer-connection-types.ts
index 933bcfac89..4f51f2c8f3 100644
--- a/backend/src/services/app-connection/portainer/portainer-connection-types.ts
+++ b/backend/src/services/app-connection/portainer/portainer-connection-types.ts
@@ -5,7 +5,7 @@ import { TGatewayV2ServiceFactory } from "@app/ee/services/gateway-v2/gateway-v2
import { DiscriminativePick } from "@app/lib/types";
import { AppConnection } from "../app-connection-enums";
-import { PortainerStackStatus, PortainerStackType } from "./portainer-connection-enums";
+import { PortainerStackType } from "./portainer-connection-enums";
import {
CreatePortainerConnectionSchema,
PortainerConnectionSchema,
@@ -54,11 +54,13 @@ export type TPortainerStackResponse = {
Name: string;
Type: PortainerStackType;
EndpointId: number;
- Status?: PortainerStackStatus;
Env?: TPortainerEnvVar[] | null;
Option?: {
Prune?: boolean;
} | null;
+ // Business Edition only; an update that leaves either of them out clears it
+ Registries?: number[] | null;
+ Webhook?: string | null;
// Set on Portainer 2.45+, where the Git settings live on a Source instead of the stack
WorkflowID?: number;
GitSourceId?: number;
@@ -70,6 +72,10 @@ export type TPortainerStackResponse = {
Authentication?: {
Username?: string;
Password?: string;
+ // A stack that authenticates through a saved credential carries its ID instead of a password
+ GitCredentialID?: number;
+ AuthorizationType?: number;
+ Provider?: number;
} | null;
} | null;
AutoUpdate?: {
@@ -79,9 +85,4 @@ export type TPortainerStackResponse = {
ForceUpdate?: boolean;
ForcePullImage?: boolean;
} | null;
- DeploymentStatus?: {
- Status: PortainerStackStatus;
- Time: number;
- Message?: string;
- }[];
};
diff --git a/backend/src/services/secret-sync/portainer/portainer-sync-fns.test.ts b/backend/src/services/secret-sync/portainer/portainer-sync-fns.test.ts
index f13c7238db..0ad4aada06 100644
--- a/backend/src/services/secret-sync/portainer/portainer-sync-fns.test.ts
+++ b/backend/src/services/secret-sync/portainer/portainer-sync-fns.test.ts
@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument, no-template-curly-in-string */
import { beforeEach, describe, expect, it, vi } from "vitest";
// `vi.mock` factories are hoisted above imports — the spies they reference must come from `vi.hoisted`.
@@ -22,14 +22,13 @@ vi.mock("@app/lib/gateway-v2/gateway-v2", () => ({ withGatewayV2Proxy: vi.fn() }
vi.mock("@app/ee/services/dynamic-secret/dynamic-secret-fns", () => ({
verifyHostInputValidity: vi.fn(async () => ["host"])
}));
-vi.mock("@app/lib/delay", () => ({ delay: vi.fn(async () => {}) }));
// Without a key schema every variable on the stack counts as managed by the sync
vi.mock("@app/services/secret-sync/secret-sync-fns", () => ({
matchesSchema: (_key: string, _environment: string, schema?: string) => !schema
}));
/* eslint-disable import/first */
-import { PortainerStackStatus, PortainerStackType } from "@app/services/app-connection/portainer";
+import { PortainerStackType } from "@app/services/app-connection/portainer";
import { SecretSyncError } from "../secret-sync-errors";
import {
@@ -64,7 +63,6 @@ const fileStack = (overrides: Record<string, unknown> = {}) => ({
Name: "web",
Type: PortainerStackType.Compose,
EndpointId: 1,
- Status: PortainerStackStatus.Active,
Env: [{ name: "A", value: "1" }],
Option: { Prune: true },
...overrides
@@ -79,7 +77,8 @@ const gitStack = (overrides: Record<string, unknown> = {}) =>
...overrides
});
-// Resolves each request by HTTP method and path; later entries for the same key answer later calls
+// Resolves each request by HTTP method and path; later entries for the same key answer later calls,
+// and an Error entry is thrown instead of returned
const respondWith = (responses: Record<string, unknown[]>) => {
const remaining = Object.fromEntries(Object.entries(responses).map(([key, values]) => [key, [...values]]));
@@ -88,10 +87,19 @@ const respondWith = (responses: Record<string, unknown[]>) => {
const queue = remaining[key];
if (!queue?.length) throw new Error(`Unexpected request ${key}`);
- return { data: queue.length > 1 ? queue.shift() : queue[0] };
+ const next = queue.length > 1 ? queue.shift() : queue[0];
+ if (next instanceof Error) throw next;
+
+ return { data: next };
});
};
+const portainerError = (status: number, message: string, details: string) =>
+ Object.assign(new Error(`Request failed with status code ${status}`), {
+ isAxiosError: true,
+ response: { status, data: { message, details } }
+ });
+
type TRequestConfig = { method: string; url: string; params?: Record<string, string>; data?: unknown };
const requestConfigs = () => safeRequestMock.mock.calls.map((call: any[]) => call[0] as TRequestConfig);
@@ -121,17 +129,33 @@ describe("encodePortainerEnvValue / decodePortainerEnvValue", () => {
expect(encodePortainerEnvValue("abc #def", PortainerStackType.Compose)).toBe('"abc #def"');
});
+ it("doubles every dollar sign for a Compose stack so Compose does not expand it", () => {
+ expect(encodePortainerEnvValue("pa$word", PortainerStackType.Compose)).toBe("pa$$word");
+ expect(encodePortainerEnvValue("${HOME}/bin", PortainerStackType.Compose)).toBe("$${HOME}/bin");
+ expect(encodePortainerEnvValue("cost: $5\n", PortainerStackType.Compose)).toBe('"cost: $$5\\n"');
+ expect(encodePortainerEnvValue("pa$word", PortainerStackType.Swarm)).toBe("pa$word");
+
+ for (const value of ["pa$word", "${HOME}/bin", "cost: $5\n", "$", "$$", "a\\$b"]) {
+ const encoded = encodePortainerEnvValue(value, PortainerStackType.Compose);
+
+ expect(decodePortainerEnvValue(encoded, PortainerStackType.Compose)).toBe(value);
+ }
+ });
+
it("leaves single-line values and Swarm stacks untouched", () => {
expect(encodePortainerEnvValue("plain", PortainerStackType.Compose)).toBe("plain");
expect(encodePortainerEnvValue("no#space", PortainerStackType.Compose)).toBe("no#space");
expect(encodePortainerEnvValue("abc #def", PortainerStackType.Swarm)).toBe("abc #def");
expect(encodePortainerEnvValue("line1\nline2", PortainerStackType.Swarm)).toBe("line1\nline2");
expect(decodePortainerEnvValue('"line1\\nline2"', PortainerStackType.Swarm)).toBe('"line1\\nline2"');
+ expect(decodePortainerEnvValue("pa$$word", PortainerStackType.Swarm)).toBe("pa$$word");
});
- it("does not unwrap a single-line value a user quoted by hand", () => {
+ it("does not unwrap a value a user quoted by hand or a reference a user wrote on purpose", () => {
expect(decodePortainerEnvValue('"hello"', PortainerStackType.Compose)).toBe('"hello"');
expect(decodePortainerEnvValue('"C:\\\\new"', PortainerStackType.Compose)).toBe('"C:\\\\new"');
+ expect(decodePortainerEnvValue("$HOME/bin", PortainerStackType.Compose)).toBe("$HOME/bin");
+ expect(decodePortainerEnvValue("pa$$word", PortainerStackType.Compose)).toBe("pa$word");
});
});
@@ -182,7 +206,8 @@ describe("buildPortainerGitUpdatePayload", () => {
Authentication: { Username: "deploy" }
},
AutoUpdate: { Interval: "", Webhook: "" },
- Option: null
+ Option: null,
+ Registries: [1, 2]
});
expect(buildPortainerGitUpdatePayload(stack as any, [])).toEqual({
@@ -190,11 +215,34 @@ describe("buildPortainerGitUpdatePayload", () => {
prune: false,
repositoryReferenceName: "refs/heads/main",
autoUpdate: null,
+ registries: [1, 2],
repositoryAuthentication: true,
repositoryUsername: "deploy",
tlsSkipVerify: true
});
});
+
+ it("echoes a saved credential's ID and authorization type so Portainer keeps cloning with it", () => {
+ const stack = gitStack({
+ WorkflowID: undefined,
+ GitSourceId: undefined,
+ GitConfig: {
+ URL: "https://git.example.com/repo.git",
+ Authentication: { Username: "", GitCredentialID: 2, AuthorizationType: 1 }
+ }
+ });
+
+ const payload = buildPortainerGitUpdatePayload(stack as any, []);
+
+ expect(payload).toMatchObject({
+ repositoryAuthentication: true,
+ repositoryUsername: "",
+ repositoryGitCredentialID: 2,
+ repositoryAuthorizationType: 1
+ });
+ expect(payload).not.toHaveProperty("repositoryProvider");
+ expect(payload).not.toHaveProperty("registries");
+ });
});
describe("PortainerSyncFns", () => {
@@ -224,13 +272,9 @@ describe("PortainerSyncFns", () => {
expect(requestsMade()).toEqual(["GET /api/stacks/4"]);
});
- it("resubmits the compose file with the merged variables and waits for the redeploy to finish", async () => {
+ it("resubmits the compose file with the merged variables and the stack's Business Edition settings", async () => {
respondWith({
- "GET /api/stacks/4": [
- fileStack(),
- fileStack({ Status: PortainerStackStatus.Deploying }),
- fileStack({ Status: PortainerStackStatus.Active })
- ],
+ "GET /api/stacks/4": [fileStack({ Registries: [3], Webhook: "6f0c1c3e-0d3a-4b0e-9d5e-1c2b3a4d5e6f" })],
"GET /api/stacks/4/file": [{ StackFileContent: "services: {}" }],
"PUT /api/stacks/4": [{}]
});
@@ -242,29 +286,22 @@ describe("PortainerSyncFns", () => {
gatewayPoolService
);
- expect(requestsMade()).toEqual([
- "GET /api/stacks/4",
- "GET /api/stacks/4/file",
- "PUT /api/stacks/4?endpointId=1",
- "GET /api/stacks/4",
- "GET /api/stacks/4"
- ]);
+ expect(requestsMade()).toEqual(["GET /api/stacks/4", "GET /api/stacks/4/file", "PUT /api/stacks/4?endpointId=1"]);
const putConfig = requestConfigs().find((config) => config.method === "PUT");
// A is managed by the sync (no key schema) and absent from the source, so it is dropped
expect(putConfig?.data).toEqual({
env: [{ name: "B", value: '"x\\ny"' }],
stackFileContent: "services: {}",
- prune: true
+ prune: true,
+ registries: [3],
+ webhook: "6f0c1c3e-0d3a-4b0e-9d5e-1c2b3a4d5e6f"
});
});
it("keeps a stack variable named like an inherited object property when deletion is disabled", async () => {
respondWith({
- "GET /api/stacks/4": [
- fileStack({ Env: [{ name: "constructor", value: "keep" }] }),
- fileStack({ Status: PortainerStackStatus.Active })
- ],
+ "GET /api/stacks/4": [fileStack({ Env: [{ name: "constructor", value: "keep" }] })],
"GET /api/stacks/4/file": [{ StackFileContent: "services: {}" }],
"PUT /api/stacks/4": [{}]
});
@@ -277,30 +314,31 @@ describe("PortainerSyncFns", () => {
);
const putConfig = requestConfigs().find((config) => config.method === "PUT");
- expect(putConfig?.data).toMatchObject({
+ // A Community Edition stack has no registries or webhook, so neither is sent
+ expect(putConfig?.data).toEqual({
env: [
{ name: "constructor", value: "keep" },
{ name: "A", value: "1" }
- ]
+ ],
+ stackFileContent: "services: {}",
+ prune: true
});
});
- it("fails the sync when Portainer reports the redeploy failed", async () => {
+ it("fails with Portainer's reason when the stack is still being deployed and lets the sync retry", async () => {
respondWith({
- "GET /api/stacks/4": [
- fileStack(),
- fileStack({
- Status: PortainerStackStatus.Error,
- DeploymentStatus: [{ Status: PortainerStackStatus.Error, Time: 1, Message: "image pull failed" }]
- })
- ],
+ "GET /api/stacks/4": [fileStack()],
"GET /api/stacks/4/file": [{ StackFileContent: "services: {}" }],
- "PUT /api/stacks/4": [{}]
+ "PUT /api/stacks/4": [portainerError(409, "Unable to update stack", "Stack deployment is already in progress")]
});
await expect(
PortainerSyncFns.syncSecrets(secretSync, payloadOf({ A: "2" }) as any, gatewayV2Service, gatewayPoolService)
- ).rejects.toMatchObject({ message: expect.stringContaining("image pull failed"), shouldRetry: false });
+ ).rejects.toMatchObject({
+ name: "SecretSyncError",
+ message: expect.stringContaining("Stack deployment is already in progress"),
+ shouldRetry: true
+ });
});
it("updates a Git-backed stack through the git endpoint without touching the compose file", async () => {
@@ -327,11 +365,21 @@ describe("PortainerSyncFns", () => {
);
});
- it("decodes multiline Compose values on import", async () => {
- respondWith({ "GET /api/stacks/4": [fileStack({ Env: [{ name: "PEM", value: '"a\\nb"' }] })] });
+ it("decodes multiline and dollar-escaped Compose values on import", async () => {
+ respondWith({
+ "GET /api/stacks/4": [
+ fileStack({
+ Env: [
+ { name: "PEM", value: '"a\\nb"' },
+ { name: "PASS", value: "pa$$word" }
+ ]
+ })
+ ]
+ });
await expect(PortainerSyncFns.getSecrets(secretSync, gatewayV2Service, gatewayPoolService)).resolves.toEqual({
- PEM: { value: "a\nb" }
+ PEM: { value: "a\nb" },
+ PASS: { value: "pa$word" }
});
});
});
diff --git a/backend/src/services/secret-sync/portainer/portainer-sync-fns.ts b/backend/src/services/secret-sync/portainer/portainer-sync-fns.ts
index e2d39ebc09..3c382eb506 100644
--- a/backend/src/services/secret-sync/portainer/portainer-sync-fns.ts
+++ b/backend/src/services/secret-sync/portainer/portainer-sync-fns.ts
@@ -1,13 +1,12 @@
+import { isAxiosError } from "axios";
+
import { TGatewayPoolServiceFactory } from "@app/ee/services/gateway-pool/gateway-pool-service";
import { TGatewayV2ServiceFactory } from "@app/ee/services/gateway-v2/gateway-v2-service";
-import { delay } from "@app/lib/delay";
import { BadRequestError } from "@app/lib/errors";
import {
getPortainerErrorMessage,
isPortainerGitStack,
- PORTAINER_REQUEST_TIMEOUT_MS,
portainerRequest,
- PortainerStackStatus,
PortainerStackType,
TPortainerEnvVar,
TPortainerGatewayDeps,
@@ -20,9 +19,9 @@ import { TSecretSyncPayload } from "../secret-sync-payload";
import { TSecretMap } from "../secret-sync-types";
import { TPortainerStackFileResponse, TPortainerSyncWithCredentials } from "./portainer-sync-types";
-const PORTAINER_DEPLOYMENT_POLL_INTERVAL_MS = 5_000;
-// The sync job holds a five-minute lock per sync, so the wait has to give up inside that window
-const PORTAINER_DEPLOYMENT_TIMEOUT_MS = 4 * 60_000;
+// Older releases redeploy a file-based stack inside the update request, so it can run for minutes; the sync
+// job holds a five-minute lock per sync, so the request has to give up inside that window
+const PORTAINER_STACK_UPDATE_TIMEOUT_MS = 4 * 60_000;
const DOTENV_ESCAPES: Record<string, string> = { '"': '"', "\\": "\\", n: "\n", r: "\r" };
@@ -30,26 +29,32 @@ const DOTENV_ESCAPES: Record<string, string> = { '"': '"', "\\": "\\", n: "\n",
const needsDotenvQuoting = (value: string) => /[\r\n]|^\s|\s$|\s#|^["']/.test(value);
/**
- * Portainer writes a Compose stack's variables to a `stack.env` file one `NAME=VALUE` line at a time,
- * so a value that the dotenv parser would cut or trim has to use the double-quoted form or it reaches
- * the container changed (or, with line breaks, stops the file from parsing at all). Swarm stacks
- * receive their variables through the process environment, where every value is fine as-is.
+ * Portainer writes a Compose stack's variables to a `stack.env` file one `NAME=VALUE` line at a time and
+ * hands it to Compose, whose dotenv parser expands `$VAR` and `${VAR}` inside every value (only `$$`
+ * reaches the container as a dollar sign) and cuts or trims unquoted values. So every `$` is doubled, and
+ * a value the parser would otherwise alter uses the double-quoted form. Swarm stacks receive their
+ * variables through the process environment, where every value is fine as-is.
*/
export const encodePortainerEnvValue = (value: string, stackType: PortainerStackType) => {
- if (stackType !== PortainerStackType.Compose || !needsDotenvQuoting(value)) return value;
+ if (stackType !== PortainerStackType.Compose) return value;
+
+ const dollarSafe = value.replace(/\$/g, () => "$$");
+ if (!needsDotenvQuoting(value)) return dollarSafe;
- const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+ const escaped = dollarSafe.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n");
return `"${escaped}"`;
};
+const unescapeDotenv = (value: string) => value.replace(/\\(["\\nr])/g, (_, escape: string) => DOTENV_ESCAPES[escape]);
+
export const decodePortainerEnvValue = (value: string, stackType: PortainerStackType) => {
if (stackType !== PortainerStackType.Compose) return value;
- if (value.length < 2 || !value.startsWith('"') || !value.endsWith('"')) return value;
- const decoded = value.slice(1, -1).replace(/\\(["\\nr])/g, (_, escape: string) => DOTENV_ESCAPES[escape]);
+ const isQuoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"');
+ const decoded = (isQuoted ? unescapeDotenv(value.slice(1, -1)) : value).replace(/\$\$/g, () => "$");
- // Only unwrap what the encoder above produces; a value a user quoted by hand is left alone
+ // Only undo what the encoder above produces; a value a user wrote by hand is left alone
return encodePortainerEnvValue(decoded, stackType) === value ? decoded : value;
};
@@ -71,25 +76,32 @@ export const areEnvVarsEqual = (current: TPortainerEnvVar[], next: TPortainerEnv
* The Git update endpoint replaces every setting it carries, so the stack's current settings are echoed
* back alongside the new variables. On Portainer 2.45+ the repository URL and credentials live on a
* Source and only its ID is needed; older releases wipe the stored credentials unless the
- * authentication flags are sent again.
+ * authentication settings are sent again.
*/
export const buildPortainerGitUpdatePayload = (
stack: TPortainerStackResponse & { GitConfig: NonNullable<TPortainerStackResponse["GitConfig"]> },
env: TPortainerEnvVar[]
) => {
- const { GitConfig: gitConfig, AutoUpdate: autoUpdate } = stack;
+ const { GitConfig: gitConfig, AutoUpdate: autoUpdate, Registries: registries } = stack;
const hasAutoUpdate = Boolean(autoUpdate?.Webhook || autoUpdate?.Interval);
+ const auth = gitConfig.Authentication;
return {
env,
prune: stack.Option?.Prune ?? false,
repositoryReferenceName: gitConfig.ReferenceName ?? "",
autoUpdate: hasAutoUpdate ? autoUpdate : null,
+ ...(registries ? { registries } : {}),
...(stack.GitSourceId
? { sourceID: stack.GitSourceId }
: {
- repositoryAuthentication: Boolean(gitConfig.Authentication),
- repositoryUsername: gitConfig.Authentication?.Username ?? "",
+ repositoryAuthentication: Boolean(auth),
+ repositoryUsername: auth?.Username ?? "",
+ // A saved credential is referenced by ID and the stack stores no password for it, so without the
+ // ID Portainer clones with no credentials at all
+ ...(auth?.GitCredentialID ? { repositoryGitCredentialID: auth.GitCredentialID } : {}),
+ ...(auth?.AuthorizationType ? { repositoryAuthorizationType: auth.AuthorizationType } : {}),
+ ...(auth?.Provider ? { repositoryProvider: auth.Provider } : {}),
tlsSkipVerify: gitConfig.TLSSkipVerify ?? false
})
};
@@ -107,23 +119,32 @@ const toSyncError = (error: unknown, message: string) => {
return new SecretSyncError({ error, message: `${message}: ${getPortainerErrorMessage(error, "unknown error")}` });
};
-const fetchPortainerStack = async (secretSync: TPortainerSyncWithCredentials, deps: TPortainerGatewayDeps) => {
+// Portainer refuses to update a stack it is still deploying; the sync's own retries cover a short deployment
+const toStackUpdateError = (error: unknown, stack: TPortainerStackResponse) => {
+ if (isAxiosError(error) && error.response?.status === 409) {
+ return new SecretSyncError({
+ error,
+ message: `Portainer rejected the update of stack '${stack.Name}': ${getPortainerErrorMessage(error, "conflict")}. If the stack is still being deployed, sync again once the deployment has finished.`
+ });
+ }
+
+ return toSyncError(error, `Failed to update the variables of Portainer stack '${stack.Name}'`);
+};
+
+const getPortainerStack = async (secretSync: TPortainerSyncWithCredentials, deps: TPortainerGatewayDeps) => {
const { connection, destinationConfig } = secretSync;
+ const { environmentId, stackId } = destinationConfig;
+ let stack: TPortainerStackResponse;
try {
- return await portainerRequest<TPortainerStackResponse>(
+ stack = await portainerRequest<TPortainerStackResponse>(
connection,
- { method: "GET", path: `/stacks/${destinationConfig.stackId}` },
+ { method: "GET", path: `/stacks/${stackId}` },
deps
);
} catch (error) {
- throw toSyncError(error, `Failed to read Portainer stack with ID '${destinationConfig.stackId}'`);
+ throw toSyncError(error, `Failed to read Portainer stack with ID '${stackId}'`);
}
-};
-
-const getPortainerStack = async (secretSync: TPortainerSyncWithCredentials, deps: TPortainerGatewayDeps) => {
- const { environmentId, stackId } = secretSync.destinationConfig;
- const stack = await fetchPortainerStack(secretSync, deps);
if (stack.EndpointId !== environmentId) {
throw new SecretSyncError({
@@ -142,46 +163,6 @@ const getPortainerStack = async (secretSync: TPortainerSyncWithCredentials, deps
return stack;
};
-// A run may wait twice, before the write for a deployment already in flight and after it for its own,
-// so both waits draw on one budget that starts when the sync does
-const getDeploymentWaitDeadline = () => Date.now() + PORTAINER_DEPLOYMENT_TIMEOUT_MS;
-
-const waitForPortainerDeployment = async (
- secretSync: TPortainerSyncWithCredentials,
- stack: TPortainerStackResponse,
- deps: TPortainerGatewayDeps,
- deadline: number
-) => {
- let current = stack;
-
- while (current.Status === PortainerStackStatus.Deploying) {
- if (Date.now() >= deadline) {
- throw new SecretSyncError({
- message: `Portainer is still deploying stack '${stack.Name}' after ${PORTAINER_DEPLOYMENT_TIMEOUT_MS / 60_000} minutes. Check the stack in Portainer, then sync again.`,
- shouldRetry: false
- });
- }
-
- // eslint-disable-next-line no-await-in-loop
- await delay(PORTAINER_DEPLOYMENT_POLL_INTERVAL_MS);
- // eslint-disable-next-line no-await-in-loop
- current = await fetchPortainerStack(secretSync, deps);
- }
-
- return current;
-};
-
-// Portainer answers a stack update with 409 while a deployment is in flight, so wait for it to settle first
-const getSettledPortainerStack = async (
- secretSync: TPortainerSyncWithCredentials,
- deps: TPortainerGatewayDeps,
- deadline: number
-) => {
- const stack = await getPortainerStack(secretSync, deps);
-
- return waitForPortainerDeployment(secretSync, stack, deps, deadline);
-};
-
const writeGitStackEnv = async (
secretSync: TPortainerSyncWithCredentials,
stack: TPortainerStackResponse,
@@ -209,7 +190,7 @@ const writeGitStackEnv = async (
deps
);
} catch (error) {
- throw toSyncError(error, `Failed to update the variables of Portainer stack '${stack.Name}'`);
+ throw toStackUpdateError(error, stack);
}
};
@@ -217,8 +198,7 @@ const writeFileStackEnv = async (
secretSync: TPortainerSyncWithCredentials,
stack: TPortainerStackResponse,
env: TPortainerEnvVar[],
- deps: TPortainerGatewayDeps,
- deadline: number
+ deps: TPortainerGatewayDeps
) => {
const { connection, destinationConfig } = secretSync;
@@ -240,33 +220,20 @@ const writeFileStackEnv = async (
method: "PUT",
path: `/stacks/${destinationConfig.stackId}`,
params: { endpointId: String(destinationConfig.environmentId) },
- data: { env, stackFileContent, prune: stack.Option?.Prune ?? false },
- // Releases before the background deployer run the redeploy inside this request, so it may take
- // whatever is left of the wait budget (but never less than a normal request)
- timeoutMs: Math.max(deadline - Date.now(), PORTAINER_REQUEST_TIMEOUT_MS)
+ data: {
+ env,
+ stackFileContent,
+ prune: stack.Option?.Prune ?? false,
+ // Business Edition clears the stack's registries and webhook when an update leaves them out
+ ...(stack.Registries ? { registries: stack.Registries } : {}),
+ ...(stack.Webhook ? { webhook: stack.Webhook } : {})
+ },
+ timeoutMs: PORTAINER_STACK_UPDATE_TIMEOUT_MS
},
deps
);
} catch (error) {
- throw toSyncError(error, `Failed to update the variables of Portainer stack '${stack.Name}'`);
- }
-
- // Recent Portainer releases redeploy in the background after answering, so a 200 only means the
- // update was accepted; the stack status tells whether the containers actually came up
- const deployed = await waitForPortainerDeployment(
- secretSync,
- await fetchPortainerStack(secretSync, deps),
- deps,
- deadline
- );
-
- if (deployed.Status === PortainerStackStatus.Error) {
- const reason = [...(deployed.DeploymentStatus ?? [])].reverse().find((entry) => entry.Message)?.Message;
-
- throw new SecretSyncError({
- message: `Portainer failed to redeploy stack '${stack.Name}' with the updated variables${reason ? `: ${reason}` : ""}. The variables are saved on the stack; check the stack in Portainer and redeploy it.`,
- shouldRetry: false
- });
+ throw toStackUpdateError(error, stack);
}
};
@@ -279,21 +246,16 @@ const writeStackEnvIfChanged = async (
secretSync: TPortainerSyncWithCredentials,
stack: TPortainerStackResponse,
env: TPortainerEnvVar[],
- deps: TPortainerGatewayDeps,
- deadline: number
+ deps: TPortainerGatewayDeps
) => {
- const isGitStack = isPortainerGitStack(stack);
- const isUnchanged = areEnvVarsEqual(stack.Env ?? [], env);
+ if (areEnvVarsEqual(stack.Env ?? [], env)) return;
- // A file-based stack whose last deployment failed is redeployed anyway, so the sync reports the real state
- if (isUnchanged && (isGitStack || stack.Status !== PortainerStackStatus.Error)) return;
-
- if (isGitStack) {
+ if (isPortainerGitStack(stack)) {
await writeGitStackEnv(secretSync, stack, env, deps);
return;
}
- await writeFileStackEnv(secretSync, stack, env, deps, deadline);
+ await writeFileStackEnv(secretSync, stack, env, deps);
};
const toEnvVars = (secretMap: TSecretMap, stackType: PortainerStackType): TPortainerEnvVar[] =>
@@ -327,9 +289,8 @@ export const PortainerSyncFns = {
syncOptions: { disableSecretDeletion, keySchema }
} = secretSync;
const deps = getGatewayDeps(gatewayV2Service, gatewayPoolService);
- const deadline = getDeploymentWaitDeadline();
- const stack = await getSettledPortainerStack(secretSync, deps, deadline);
+ const stack = await getPortainerStack(secretSync, deps);
// A plain `in` check would also match inherited names such as "constructor"
const retainedEnv = (stack.Env ?? []).filter(({ name }) => {
@@ -341,13 +302,7 @@ export const PortainerSyncFns = {
return true;
});
- await writeStackEnvIfChanged(
- secretSync,
- stack,
- [...retainedEnv, ...toEnvVars(secretMap, stack.Type)],
- deps,
- deadline
- );
+ await writeStackEnvIfChanged(secretSync, stack, [...retainedEnv, ...toEnvVars(secretMap, stack.Type)], deps);
},
async removeSecrets(
@@ -358,12 +313,11 @@ export const PortainerSyncFns = {
) {
const secretMap = payload.flatten();
const deps = getGatewayDeps(gatewayV2Service, gatewayPoolService);
- const deadline = getDeploymentWaitDeadline();
- const stack = await getSettledPortainerStack(secretSync, deps, deadline);
+ const stack = await getPortainerStack(secretSync, deps);
const remainingEnv = (stack.Env ?? []).filter(({ name }) => !Object.hasOwn(secretMap, name));
- await writeStackEnvIfChanged(secretSync, stack, remainingEnv, deps, deadline);
+ await writeStackEnvIfChanged(secretSync, stack, remainingEnv, deps);
}
};
diff --git a/docs/integrations/app-connections/portainer.mdx b/docs/integrations/app-connections/portainer.mdx
index c612246a06..6ab43b2ad0 100644
--- a/docs/integrations/app-connections/portainer.mdx
+++ b/docs/integrations/app-connections/portainer.mdx
@@ -17,6 +17,7 @@ The token inherits the permissions of the Portainer user who created it, so Infi
## Prerequisites
+- Portainer Community Edition 2.39 or later, or Business Edition 2.42 or later
- 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
diff --git a/docs/integrations/secret-syncs/portainer.mdx b/docs/integrations/secret-syncs/portainer.mdx
index 4ca1fac8c7..c3704c99b4 100644
--- a/docs/integrations/secret-syncs/portainer.mdx
+++ b/docs/integrations/secret-syncs/portainer.mdx
@@ -4,7 +4,6 @@ sidebarTitle: "Portainer"
description: "Learn how to configure a Portainer sync for Infisical."
---
-import GenerateApiToken from "/snippets/app-connections/portainer/generate-api-token.mdx";
import ConnectionFormFields from "/snippets/app-connections/portainer/form-fields.mdx";
A Portainer Secret Sync pushes secrets from Infisical into the environment variables of a Portainer stack, where the stack's compose file reads them. Each Infisical secret becomes one stack variable with the same name unless you customize key names to add a prefix or suffix.
@@ -16,17 +15,10 @@ A Portainer Secret Sync pushes secrets from Infisical into the environment varia
## Prerequisites
- A [project with secrets configured](/documentation/platform/secrets-mgmt/quick-starts/deliver-first-secret)
-- A Portainer user whose permissions cover the environment and the stack you want to sync to
+- A [Portainer app connection](/integrations/app-connections/portainer), or a Portainer API token to create one while you set up the sync
- A Compose or Swarm stack in Portainer (Kubernetes stacks aren't supported, because Portainer doesn't apply environment variables to them)
-- If your Portainer instance isn't reachable from the internet, a [Gateway](/documentation/platform/gateways/overview) with network access to it
-## Step 1: Generate a Portainer API token
-
-Infisical needs an access token to call the Portainer API on your behalf.
-
-<GenerateApiToken />
-
-## Step 2: Set up the sync in Infisical
+## Set up the sync in Infisical
<Tip>
To create the sync using the API, use the [Create Portainer Sync](/api-reference/endpoints/secret-syncs/portainer/create) endpoint.
@@ -141,13 +133,13 @@ Infisical needs an access token to call the Portainer API on your behalf.
<AccordionGroup>
<Accordion title="Does a sync restart my containers?">
- It depends on the stack type. For a Git-backed stack, Infisical writes the variables to the stack's Git settings and leaves the running containers alone; the new values take effect on the stack's next deployment, whether that's an auto-update poll, a webhook, or a manual redeploy. For a file-based stack, 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.
+ It depends on the stack type. For a Git-backed stack, Infisical writes the variables to the stack's Git settings and leaves the running containers alone; the new values take effect on the stack's next deployment, whether that's an auto-update poll, a webhook, or a manual redeploy. For a file-based stack, 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. Infisical doesn't wait for the redeploy or check its result, so check the stack in Portainer if your containers don't come up with the new values. If Portainer is still deploying the stack when a sync runs, it rejects the update and the sync fails with that reason; sync again once the deployment has finished.
</Accordion>
<Accordion title="Can I sync to a Kubernetes stack?">
No. 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.
</Accordion>
<Accordion title="What happens to values with line breaks or special characters?">
- Portainer stores a Compose stack's variables in an env file with one line per variable. If a value contains line breaks, starts or ends with a space, contains a space followed by `#`, or starts with a quote, Infisical stores the value in double quotes with each special character escaped, and Portainer restores the original value when it deploys the stack. Swarm stacks receive their values as-is.
+ Portainer stores a Compose stack's variables in an env file with one line per variable, and Compose expands `$VAR` and `${VAR}` references inside the values. Infisical writes every `$` as `$$`, which Compose turns back into a single `$`, so a value like `pa$word` reaches your containers unchanged. If a value contains line breaks, starts or ends with a space, contains a space followed by `#`, or starts with a quote, Infisical also stores the value in double quotes with each special character escaped. Portainer restores the original value when it deploys the stack, and Infisical undoes the same encoding when it imports variables from the stack. Swarm stacks receive their values as-is.
</Accordion>
</AccordionGroup>
diff --git a/docs/snippets/app-connections/portainer/form-fields.mdx b/docs/snippets/app-connections/portainer/form-fields.mdx
index c507766e95..c3033ceadd 100644
--- a/docs/snippets/app-connections/portainer/form-fields.mdx
+++ b/docs/snippets/app-connections/portainer/form-fields.mdx
@@ -3,4 +3,4 @@
- **Gateway**: The Gateway or Gateway pool to route requests through if your Portainer instance isn't reachable from the internet; otherwise leave it as **Internet Gateway**
- **Method**: **API Token**, the only method the connection supports
- **Portainer Instance URL**: The URL of your Portainer instance, such as `https://portainer.example.com`
-- **Portainer API Token**: The token you copied when [generating a Portainer API token](#step-1-generate-a-portainer-api-token)
+- **Portainer API Token**: The token you copied when [generating a Portainer API token](/integrations/app-connections/portainer#step-1-generate-a-portainer-api-token)