Octopus Deploy provides a powerful, flexible platform for automating deployments and runbook execution. However, there are times when you may encounter challenges that require troubleshooting. In this post, we’ll walk through some of the most common issues that users may run into and provide guidance on how to resolve them.
Tentacle communication issues
Deployment targets and workers running the Octopus Tentacle agent are key to Octopus infrastructure. If Tentacles cannot communicate with your Octopus Server, deployments and runbooks will fail. Some of the issues we commonly see when setting up a new Tentacle agent include: firewall restrictions, network connectivity issues, SSL offloading, and misconfigured certificates.
Our Troubleshooting Tentacles documentation is a comprehensive guide for troubleshooting Tentacle communication issues. It covers:
- Verifying that Tentacle services are running
- Checking firewall rules
- Ensuring correct thumbprints are configured
- Debugging connectivity with Octopus diagnostic tools
Calamari issues and antivirus exclusions
If you ever run into an error message in your logs that includes:
Bootstrapper did not return the bootstrapper service messageThis normally indicates that antivirus or other security software is interfering with an Octopus task (such as a deployment or runbook).
Octopus tasks are powered by Calamari, a lightweight deployment bootstrapper invoked for each deployment or runbook step. It’s automatically installed and updated as needed in the Tools folder of the Tentacle home directory. Additionally, steps for a given task are processed in a temporary folder inside of the Work folder, also residing in the Tentacle home directory.
Sometimes, antivirus or endpoint protection software can lock or quarantine files in these folders, causing deployments to fail. To prevent this, we recommend working with your security team to add exclusions as necessary for these directories. For additional information, please review our Hardening Octopus documentation.
Polling tentacles over port 443 (HTTPS)
In some environments, firewall policies can make it difficult or impossible to open additional ports. Octopus supports configuring Polling Tentacles over port 443, which allows communication through a port that is typically already allowed in enterprise networks.
This option simplifies network configuration and can reduce the setup burden in restrictive environments. This also allows for Octopus instances that communicate with other organizations or network environments to have a path for Tentacle communication that may otherwise not be possible.
Variable snapshots in Projects and Runbooks
Octopus variables are a seemingly simple, but common point of confusion that we often help our users with. Octopus leverages project releases and runbooks snapshots to preserve an immutable set of information to make deployments and runbooks repeatable and predictable.
You can view the variable values associated with a release by selecting the [Show Snapshot] option in the Variable Snapshot section of a release or runbook. This can be a helpful step for confirming the variable values for a given release or runbook.
Project variables and associated library variable set variables are captured in a snapshot when a release or runbook snapshot is created. In order for variable updates to take effect, you must also do the following in an associated project or runbook:
For projects:
- Create a new release so that the variable snapshot updates, or
- Update an existing release’s variable snapshot
For runbooks:
- Create and publish a new runbook snapshot
The exception to the above is changes to Tenant variables.
From our Tenant Variables documentation:
[…] we don’t take a snapshot of tenant variables. This enables you to add new tenants at any time and deploy to them without creating a new release. This means any changes you make to tenant-variables will take immediate effect.
Debugging variables with variable logging
When deployments or runbooks don’t behave as expected, variable issues are a common culprit. Octopus provides the ability to debug variables by enabling variable logging and viewing the raw task log.
By turning on variable logging, you can:
- Inspect the evaluated values of your variables
- Verify scoping and precedence rules
- Export raw task logs for detailed review
- Save significant troubleshooting time when debugging complex variable configurations
Alternatively, you may now enable Debug Mode for Octopus deployments and runbooks. For project deployments, this option is available on the “deploy” screen:
When running a runbook, you must click the Show advanced button to reveal Debug mode:
Resources for custom API scripts
Octopus Deploy features a powerful REST API. Many Octopus users extend their automation by writing custom scripts that interact with Octopus programmatically. You can find API examples in our documentation. We also offer a public GitHub repository with many scripts that may fit your needs as written or provide a good baseline to iterate and customize for your needs.
If you can’t find what you need or would like additional inspiration, our Octopus Community Slack channel is a great place to interact with other Octopus users and Octopus employees who can help!
Conclusion
Octopus Deploy is a powerful deployment tool that can handle many complex and scaled scenarios. If you need additional help, contact Octopus Support.
