Portainer icon

Portainer

Interact with Portainer via API

Actions190

Edge Stacks → Edge Stack Create File

AI-generated

Overview

This node operation allows you to create a new Edge Stack file in Portainer, a container management platform. An Edge Stack is a deployment configuration that can be pushed to one or more edge groups (clusters of edge devices). This operation is useful for automating the deployment of containerized applications or services to distributed edge environments.

Typical use cases include:

  • Deploying Docker Compose or Kubernetes manifests to edge devices managed by Portainer.
  • Automating updates and rollouts of container stacks across multiple edge groups.
  • Managing container registries and deployment options programmatically.

For example, you might use this node to deploy a new version of a microservice stack defined in a Docker Compose file to all your edge clusters with a single workflow.

Properties

Name Meaning
Name Name of the stack. Must start with a letter or number and contain only lowercase alphanumeric characters, hyphens, or underscores.
File Content of the stack file (e.g., Docker Compose YAML or Kubernetes manifest)
Edge Groups JSON stringified array of Edge Group IDs where the stack will be deployed
Deployment Type Deployment type: 0 for 'compose' stacks, 1 for 'kubernetes' stacks
Registries JSON stringified array of Registry IDs to use for this stack
Use Manifest Namespaces Boolean flag indicating whether to use namespaces defined in the manifest instead of the default namespace (relevant for Kubernetes deployments)
Pre Pull Image Boolean flag to pre-pull container images before deployment
Retry Deploy Boolean flag to retry deployment if it fails
Additional Fields Collection of optional additional parameters; currently supports:
- Dryrun If true, validates settings without creating the stack (non-persistent check)

Output

The node outputs JSON data representing the created Edge Stack object as returned by the Portainer API. This typically includes details such as the stack ID, name, deployment status, associated edge groups, and other metadata.

No binary data output is expected from this operation.

Dependencies

  • Requires an active connection to a Portainer instance via its API.
  • Needs an API authentication token or key configured in n8n credentials to authorize requests.
  • The Portainer API base URL must be set correctly in the credentials.
  • The node uses the Portainer API endpoint /api to send the stack creation request.

Troubleshooting

  • Invalid Stack Name: Ensure the stack name follows the naming rules (lowercase alphanumeric, hyphens, underscores, starting with letter/number). Violations may cause API errors.
  • Malformed JSON Strings: The Edge Groups and Registries properties require JSON stringified arrays. Invalid JSON will cause request failures.
  • Authentication Errors: Verify that the API key/token and base URL are correct and have sufficient permissions.
  • Deployment Type Mismatch: Using the wrong deployment type (compose vs kubernetes) for the stack file content may cause deployment errors.
  • Dryrun Misuse: Setting dryrun to true will not create the stack but only validate inputs; ensure this is intended.
  • Network Issues: Connectivity problems to the Portainer server will prevent stack creation.

Common error messages usually come from the Portainer API and relate to validation failures, unauthorized access, or malformed requests. Checking the API response message and verifying input formats usually resolves these issues.

Links and References

Discussion