terraform-provider-portainer Updates & Release Notes

v2.0.1

Fixed

Stacks left in Error can be updated again (#147)

A stack whose deployment had failed refused every further apply, in a fraction of a second and without sending a request. The only way out was starting the stack by hand in the Portainer UI. Fixing the compose file and re-applying now recovers the stack. A deployment that this provider itself started and that fails is still reported as a failure.

portainer_stack_delete_by_name now works at all

Every call failed with 400 Invalid query parameter: namespace. Portainer requires a namespace query parameter that its API specification does not document, so the resource never sent it.

portainer_registry_connection now works at all

Every check failed with 400 Username and password are required. Portainer demands credentials for all registry types, including public ones, so the data source never reached the connection test it exists to run. GitHub registries (type = 8) are also accepted now; the type was capped at 7.

Action required

Both fixes add a required argument to something that could not have been in working use, so no running configuration changes behaviour - but configurations that reference these two will now fail at plan time until they are updated:

resource "portainer_stack_delete_by_name" "example" {
  name = "legacy-app"
  namespace = "legacy-apps" # new, required
  endpoint_id = 4
}

data "portainer_registry_connection" "example" {
  url = "registry.example.com"
  type = 3
  username = "robot" # new, required
  password = var.password # new, required
}

Release v2.0.0

Business Edition API coverage

This release roughly doubles what the provider can manage: 81 new resources and data sources covering the Business Edition API, alongside fixes for a stack deployment failure on Portainer 2.45 and a blocker that prevented Edge Agent environments from being created at all.

Nothing was removed or renamed. Every configuration valid on v1.35.0 is still valid, but read "Behaviour changes" before upgrading - one of them can replace an environment.

Behaviour changes

Edge Agent environments are replaced when their address changes. Portainer bakes the address into the edge key when the environment is created and never regenerates it, so an in-place update never actually took effect. Until now the provider emitted a warning and reported success, leaving the running agent on the old address. It now forces replacement instead, which issues a new edge key and means the agent has to be redeployed with it.

This only triggers for environment types 4 and 7, only when the address really changed, and not when the difference is the URL scheme alone. That last exclusion matters: Portainer normalises endpoint.URL down to the bare host, so environments created by older provider versions hold a scheme-less address in state and would otherwise be replaced on every apply.

Run terraform plan against your edge environments before upgrading.

Failed API calls that used to pass silently now fail. One internal HTTP helper returned the body of a 403 or a 500 as though it were data. Several resources then either stored an error page in state or reported a confusing parse failure. Those calls now fail with what the server actually said. An apply that appeared to succeed against a misconfigured or unauthorised Portainer may now stop and tell you why.

Webhooks still behave as before by default. Business Edition can move a webhook to another resource in place, keeping its token and every URL already handed out. That is available through the new reassign_on_change argument and is off by default, because Portainer CE has no reassign endpoint. Without it, changing resource_id or webhook_type replaces the webhook exactly as it always has.

Fixes

Creating a stack no longer fails with a 409 (#145). Portainer 2.45 deploys stacks asynchronously and holds a per-stack lock until the deploy finishes. The provider's follow-up call landed inside that window and was rejected, tainting a stack that had in fact deployed fine, so every subsequent apply destroyed and recreated it. The provider now waits for the deployment to settle first. A deployment that fails is reported as a failure rather than retried into a false success. Covers both standalone and swarm stacks.

Edge Agent environments can be created on Portainer 2.43 and newer again. Portainer rejects TLS outright for edge types, and the provider was sending the TLS fields unconditionally. They are now omitted for types 4 and 7. This retires the known issue from v1.35.0: tls_enabled = false is no longer needed.

portainer_endpoint_relations no longer clears what it was not asked to change. Portainer reads an empty array as "remove everything", so an unconfigured field was wiping an environment's tags or edge groups. Each field is now omitted unless it is set.

portainer_kubernetes_cluster reads again. Portainer's API specification types the dashboard response as a list while the server returns an object, and the mismatch took the whole data source down. Both shapes are now accepted.

portainer_user_api_key explains itself. Portainer accepts this call only from a session and only for the calling user's own account. With an API key it answered 401 Auth not supported, which said nothing useful. The provider now refuses before sending and names the arguments to use instead.

Credentials no longer reach diagnostics or state. Errors carried the full request URL, and one endpoint takes a service account key as a query parameter. Sensitive query parameters are now redacted from error messages, and the data sources that store a failure reason keep only what the server said.

New resources

• Add-on store: portainer_addon, portainer_addon_access, portainer_addon_config, portainer_addon_repair
• Omni / Talos: portainer_omni_cluster, portainer_omni_node_reboot
• GitOps: portainer_gitops_workflow
• Backup: portainer_backup_azure_settings, portainer_backup_azure_execute, portainer_backup_azure_restore, portainer_backup_local_settings, portainer_backup_local_run, portainer_backup_s3_restore
• Kubernetes: portainer_kubernetes_pod_security_rule, portainer_kubernetes_cluster_upgrade
• Alerting: portainer_alerting_rule_groups, portainer_alerting_rule_tiers
• Settings and security: portainer_settings_default_registry, portainer_settings_additional_functionality, portainer_ssrf_allowlist
• Environments and users: portainer_endpoint_trust, portainer_user_memberships_sync

New data sources

• Add-on store: portainer_addons, portainer_addon_chart_source
• Omni / Talos: portainer_omni_machines, portainer_omni_machine, portainer_omni_machine_logs, portainer_omni_talos_versions, portainer_omni_upgrade_status, portainer_omni_service_account
• Kubernetes storage: portainer_kubernetes_storage_classes, portainer_kubernetes_storage_class, portainer_kubernetes_persistent_volume_claims, portainer_kubernetes_persistent_volume_claim, portainer_kubernetes_volumes, portainer_kubernetes_volume
• Kubernetes workloads: portainer_kubernetes_cron_jobs, portainer_kubernetes_endpoints, portainer_kubernetes_service_account, portainer_kubernetes_application, portainer_kubernetes_resource_counts, portainer_kubernetes_gpu
• Kubernetes custom resources: portainer_kubernetes_custom_resource_definitions, portainer_kubernetes_custom_resource_definition, portainer_kubernetes_custom_resources, portainer_kubernetes_custom_resource
• Edge: portainer_edge_waiting_room, portainer_edge_mtls_ca_certificate, portainer_edge_mtls_certificate, portainer_endpoint_mtls_certificate, portainer_endpoint_mtls_certificate_error, portainer_edge_configuration_files, portainer_edge_stack_stagger_status, portainer_edge_update_schedule_info, portainer_edge_update_previous_versions, portainer_edge_update_schedules_active, portainer_agent_versions
• Identity: portainer_ldap_users, portainer_ldap_groups, portainer_ldap_admin_groups, portainer_ldap_login_test, portainer_user_namespaces, portainer_current_user_authorizations
• Observability and policy: portainer_alerting_connectivity, portainer_alerting_rule_environments, portainer_environment_logs, portainer_environment_metrics, portainer_policy_metadata, portainer_policy_conflicts, portainer_policy_observability_test
• Docker: portainer_docker_snapshot, portainer_docker_snapshot_containers, portainer_docker_snapshot_container, portainer_image_status
• Other: portainer_licenses_info, portainer_recommendations, portainer_auto_updates, portainer_stack_conversion, portainer_backup_azure_connection, portainer_gitops_repo_file_search, portainer_gitops_helm_values

Edge Stack from a Helm repository

portainer_edge_stack gained a helm_config block, a fourth deployment source alongside an inline file, an uploaded file and a git repository. Setting it deploys the stack from a Helm chart repository. Note that leaving chart_version unset lets Portainer resolve the newest published version at apply time, so pin it where that matters.

Deliberately not covered

Some endpoints exist in the API but do not belong in Terraform, and are left out on purpose rather than overlooked:

• The add-on store's own configuration API (/addon-store/v1/*) and the edge configuration state endpoint. Both are called by an add-on or an agent reporting its own progress. Terraform is neither, and writing to them would falsify the rollout state.
• Deleting Kubernetes custom resources and custom resource definitions. The API offers no way to create them, so a resource that could only delete what something else made has no lifecycle Terraform can manage. Apply manifests with portainer_kubernetes_manifest instead.
• Cancelling an Omni provision in flight. It is an interactive escape hatch; Terraform's answer to a provision that will not finish is to destroy the resource.
• Websocket endpoints, CSV exports, the support bundle and /system/update.

Known limitations

The Business Edition resources have not been exercised against a live Business Edition instance. Their tests are built from Portainer's published API specification and verify the shape of every request, not the server's behaviour. CI runs Community Edition, so it cannot cover them either. Treat the first apply of a Business Edition resource as the real test, and please report anything that does not match.

portainer_omni_cluster cannot detect drift in its machine list. Portainer reports a cluster's spec and status but not the machines it was built from, so a node removed outside Terraform will not appear in a plan.

portainer_kubernetes_pod_security_rule reads back only its switches. The list sections are normalised and reordered by Portainer, so reading them into state would make a stable configuration churn. They are driven entirely by the configuration.

portainer_user_api_key needs api_user and api_password. Portainer only lets a user create a key for themselves, from a session. A key for a user Terraform creates in the same configuration needs two separate applies.

Release v1.35.0

Support for Portainer 2.45.0 LTS, full coverage of the Portainer API, and two Edge Agent fixes.

The provider grows from 120 to 172 resources and data sources.

Portainer 2.45 support

2.45 introduced native Portainer APIs for Kubernetes alongside the kube-apiserver proxy. An audit of every route between 2.44.0 and 2.45.0 found the API delta is confined to the Kubernetes handler; everything else that changed upstream is internal refactoring with no payload change.

New resources:

• portainer_kubernetes_node_drain - drain a node with all six kubectl drain options (force, timeout, grace period, ignore DaemonSets, delete emptyDir data, disable eviction)
• portainer_kubernetes_deployment_scale - manage a deployment's replica count, with drift detection
• portainer_kubernetes_deployment_rollback - roll a deployment back to an earlier revision
• portainer_kubernetes_persistent_volume - pin a PersistentVolume's reclaim policy

New data sources: portainer_kubernetes_manifest_dry_run (validate manifests server-side before anything is applied), portainer_kubernetes_ingress_classes, portainer_kubernetes_resource_quotas, portainer_kubernetes_replicasets, portainer_kubernetes_deployments, portainer_kubernetes_pods, portainer_kubernetes_pod_logs.

Existing Kubernetes resources keep using the kube-apiserver proxy, so nothing changes for users on older Portainer versions.

GitOps

GitOps Sources & Workflows was the largest gap in API coverage - an entire Portainer feature with nothing but two repository helpers reachable from Terraform. Now covered by portainer_gitops_source (full lifecycle plus import) and five data sources: portainer_gitops_source, portainer_gitops_sources, portainer_gitops_workflow, portainer_gitops_workflows and portainer_gitops_source_connection.

Edge Agent fixes

edge_id is no longer empty (#142). Portainer only assigns an Edge ID at creation while the EnforceEdgeID setting is on; otherwise it stays empty until an agent connects, so there was nothing to template PORTAINER_EDGE_ID from and the agent could not be deployed from Terraform at all. The provider now generates one at create time, exactly as Portainer's own UI wizard does, and Portainer adopts it when the agent first checks in.

environment_address no longer drifts (#136). Portainer stores an edge endpoint's URL as a bare host, dropping the scheme, the port and the path, so http://portainer:9000 came back as portainer and showed a change on every plan. The address is now recovered from the edge key, which keeps it verbatim.

Editing the address of an existing Edge Agent environment now warns instead of looking like a successful apply: Portainer bakes it into the edge key at creation and never regenerates it, so the resource has to be replaced.

Known issues

Two things to be aware of when managing Edge Agent environments. Neither is new in this release.

Creating an Edge Agent environment needs tls_enabled = false on Portainer 2.43 and newer. Portainer rejects the request with TLS is not supported for Edge Agent environments, because the provider sends the TLS flags on create and tls_enabled defaults to true. Set it explicitly until this is fixed:

resource "portainer_environment" "edge" {
name = "edge-device"
environment_address = "https://portainer.example.com"
type = 4
tls_enabled = false # required on Portainer >= 2.43
}

Changing environment_address on an existing Edge Agent environment does not converge. The apply warns and the plan keeps showing the change, because Portainer bakes the address into the edge key at creation and the provider reads it back from there. Replace the environment (terraform apply -replace=...) to move it, then redeploy the agent with the new edge key.

Complete API coverage

Every path in Portainer 2.45's API is now reachable, except fifteen left out by design: interactive websocket streams, edge-agent-facing polling endpoints, binary upload into a container, session and auth flows, the host upgrade, bulk environment delete, the edge stack status an agent reports, and the multipart stack create that the existing string variant already covers.

Closing the remaining gaps added, among others:

• portainer_user_api_key - API keys can finally be revoked and rotated, not only created
• portainer_endpoint_group_membership - place a single environment in a group
• portainer_registry_configure and portainer_registry_connection - registry configuration and a pre-flight reachability check
• portainer_ldap_check - validate LDAP settings before committing them
• portainer_restore - the counterpart of portainer_backup
• portainer_endpoint_relations, portainer_stack_delete_by_name, portainer_edge_job_task_logs
• portainer_resource_control can now create a control, which makes every resource type other than stacks usable
• Read-only data sources for the instance itself (portainer_system, portainer_settings_public, portainer_motd), access auditing (portainer_user_access, portainer_team_memberships), the Kubernetes cluster (portainer_kubernetes_cluster, _nodes, _events, _describe, _persistent_volumes, _config, _pod_metrics, _node_metrics, _application_resources), Docker (portainer_docker_dashboard, _images, _container_gpus), templates (portainer_app_templates, portainer_helm_chart), stored files and portainer_endpoints_summary

portainer_system.server_version is the one to reach for if you need to gate configuration on the Portainer release - several of the resources above require 2.45 or newer.

Notes on sensitive data

Two of the new data sources touch credentials, and both are deliberate about it:

• portainer_kubernetes_config returns a kubeconfig carrying a bearer token for the calling user. It is marked sensitive, but it still lands in Terraform state.
• portainer_endpoint_registries does not expose the password or access token that Portainer returns with every registry object, on purpose.

Maintenance

Go 1.27 (from 1.26). Building from source now needs Go 1.27+; the released binaries are unaffected.

go-openapi/runtime 0.32.1 → 0.33.1, go-openapi/strfmt 0.26.2 → 0.27.0, plus 25 indirect modules, picking up their CVE fixes. terraform-plugin-sdk/v2 and portainer/client-api-go/v2 were already current.

Contributors: make lint now installs golangci-lint v2 (pinned to v2.13.2) and .golangci.yml is in the v2 format. The v1 line cannot read Go 1.27 export data.

Release v1.34.3

Bug Fixes

• portainer_stack: active = false now persists on repository stacks (#139) -
  the update path stopped the stack before the git redeploy, which restarted it,
  so active = false never took effect (perpetual true -> false diff). The stop
  now runs after the redeploy.

• portainer_environment: type = 4 creates a Docker Edge Agent, not Kubernetes
  (#140) - an Edge Agent create now sends ContainerEngine=docker, so Portainer
  provisions the requested Docker edge (type 4) instead of a Kubernetes edge (type 7).

Release v1.34.0

Features

Proxy support: the provider now honors the standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment variables when connecting to the Portainer endpoint. No-op when unset, so existing setups are unaffected. (#131)

portainer_stack: new source_id attribute for Portainer 2.43 STS, which replaced shared Git credentials with the Sources model. Both source_id (2.43+) and repository_git_credential_id (< 2.43) are sent, so one configuration works against old and new Portainer. (#132)

Fixes

portainer_stack: deploying a Git stack against Portainer 2.43 STS no longer fails with "Password must be specified when authentication is enabled"; set source_id (or fall back to inline repository_username/password). (#132)

Internal / Maintenance

Centralized duplicated auth-header and d.Set handling into shared helpers (setAuthHeader, setFields); no behavior change.

Raised unit-test coverage from ~77% to 85%.

Release v1.34.1

Bug Fixes

• portainer_stack: honor active = false on create (#134) — a stack created
  with active = false is now stopped right after deployment instead of coming up
  running. Previously the flag was only applied on update, so a new stack always
  started, and with ignore_changes = [active] it never stopped at all.

Internal / Maintenance

• Unify direct-HTTP call sites behind a single doJSON helper (auth + status +
  JSON decode) across 97 files, with typed API errors and 404 handling.
• Add a table-driven CRUD test harness (crudCase).
• Add a schema↔docs drift-check linter as a new CI guard.
• Parallelize the e2e CI pipeline (shared composite setup action + split
  docker/kubernetes/swarm, edge and ssl jobs).

Documentation

• Document previously-missing schema fields: portainer_edge_stack.always_clone,
  portainer_settings.black_listed_labels, portainer_settings.edge_portainer_url.

Release v1.33.0

Highlights

Kubernetes brownfield adoption - terraform import and drift/deletion detection are now available for all 17 Kubernetes resources.

Fix: portainer_stack Kubernetes deployments no longer fail with Object not found (key=0) after a successful create (#130).

Added

Read + Importer implemented for all 17 Kubernetes resources: application, clusterrole, clusterrolebinding, configmap, cronjob, helm, ingress, job, namespace, namespace_system, role, rolebinding, secret, service, serviceaccount, storage, volume. This enables importing existing infrastructure and detects out-of-band deletion (404 → resource is recreated on the next plan). A shared k8sConfirmExistsByGET helper backs the 13 manifest-based resources.

Fixed

portainer_stack with deployment_type = "kubernetes" failed during the finalize step with 404 Object not found (key=0) when Portainer's create response did not include a usable stack Id (observed on Portainer 2.21.x). The provider now resolves the real stack ID by name + endpoint before finalizing.

Changed

Bump go.mongodb.org/mongo-driver 1.17.6 -> 1.17.7.

Upgrade notes

Read for the Kubernetes resources intentionally does not refresh the authored manifest / values / spec fields (the K8s API returns server-expanded objects that would cause permanent diffs and, since Update is delete+recreate, churn workloads). After terraform import, set those fields in config to match the live object, otherwise the next apply will recreate it.

Per-resource import IDs and the fields you must set are documented in each resource's docs page.

Release v1.32.0

Bug fixes

edge_stack: non-destructive brownfield import. Read now populates the full state from GET /edge_stacks/{id} (git config, edge groups, deployment metadata, AutoUpdate/webhook fields) instead of only ~6 of ~20 returned fields, so terraform import no longer forces a destroy + recreate. repository_reference_name is no longer ForceNew (the git endpoint updates it in place); other git fields keep ForceNew. Verified live: import now yields No changes, and a ref-name change plans as ~ update in-place.

docker_secret: stable driver/templating on refresh. Read now flattens the API's {Name, Options} shape back into the flat map schema, fixing a refresh-time type error and state drift.

Internal modernization & quality (no breaking config changes)

Migrated all resources and data sources to context-aware CRUD (CreateContext/ReadContext/UpdateContext/DeleteContext returning diag.Diagnostics).

HTTP requests now honor Terraform's context (cancellation / timeouts) via http.NewRequestWithContext.

Importer.State → StateContext (dropped deprecated ImportStatePassthrough) and removed the -SA1019 staticcheck suppression.

Re-enabled errcheck on d.Set so schema-mapping bugs surface instead of being silently ignored.

Enabled 9 additional golangci-lint linters and fixed the fallout.

Raised unit-test coverage 66% → ~78% (+350 tests).

Bumped Go toolchain to 1.26.4 (resolves govulncheck GO-2026-5037 / GO-2026-5039).

Release 1.30.0

Fixes three broken resources, marks credential fields as sensitive, and updates the Go toolchain and dependencies.

Action required

Several token/credential fields are now Sensitive. If you expose any of them in an output, add sensitive = true or terraform apply will fail:

portainer_user.api_key_raw

portainer_webhook.token (resource and data source)

portainer_webhook_execute.token

portainer_cloud_credentials.credentials

portainer_settings → oauth_settings.kube_secret_key

output "generated_api_key" {
value = portainer_user.ci.api_key_raw
sensitive = true # now required
}

No state migration needed - values stay in state, just masked in CLI output.

Bug fixes

portainer_edge_configurations: fix "Missing form data value" on update against Portainer 2.39+ (correct multipart form fields). (#119)

portainer_shared_git_credential: fix create always failing with HTTP 500 ... key=0 (response envelope is now unwrapped). (#120)

portainer_open_amt: fix a doubled endpoint URL that prevented the resource from working.

Security & dependencies

Resolve all govulncheck findings (Go stdlib + golang.org/x/net).

Build with Go 1.26.3; bump terraform-plugin-sdk/v2 to v2.40.1 and refresh go-cty, go-openapi, and golang.org/x/net.

Documentation & examples

Added an Import section to every importable resource's docs page.

Populated a description for every schema attribute (resources and data sources), improving the generated registry documentation.

Added example projects for every data source and the remaining resources.