Releases
Releases deploy blueprint changes to a cloud environment via Terraform apply, covering release types, statuses, sign-off, labels, and metadata.
Introduction
A release in Facets is a streamlined, process for deploying changes to a cloud environment. Releases are executed using Terraform apply commands, which perform a three-way comparison of state to determine and deploy the necessary changes to the corresponding cloud environment.
Any kind of changes in a running environment, be it a new Redis or a new application build happens through a Release.
Releases Execution
For any environment, Releases can be scheduled to run periodically, with an option to do Manual release anytime you need. Any changes (disk expansion, new build, changed alert definitions) during the period are accumulated and executed in the next scheduled or manual release.
Queueing
If a release is already in progress, a manually triggered release is added to a queue instead of being rejected, so you can initiate a release without waiting for the current one to complete. Queuing is a status rather than a release type, and a queued release has no release ID until it is dispatched.
Three-Way Comparison
Releases involve a three-way comparison that includes checking:
- Current state of the environment
- State defined in generated Terraform configuration files from blueprint
- Desired end state.
After comparison, the necessary changes to reach the desired state are deployed.
Types of Releases in Facets
The following are the various types of releases available in Facets:
- Full Release: The default release type, this is used for synchronizing all changes in an environment.
- Selective Release: This release type allows for selective deployment of services or changes, commonly used for out-of-turn hotfixes in environments.
- Plan Release: Provides a preview of all changes that will be made during the release, allowing for review and approval before applying changes. A plan can cover the whole environment (Full Plan) or a selected set of resources (Selective Plan), and the reviewed plan is then deployed as an Apply Plan.
- Custom Release: This release type allows power users to issue direct Terraform commands, giving them greater control and flexibility in their deployments.
- Launch Release: Used for launching a new environment for the first time.
- Destroy Release: Used to destroy all resources provisioned by Facets.
- Maintenance Release: Used execute Infrastructure as Code (IaC) upgrades.
- Rollback Plan / Apply Rollback Plan: Previews and then applies a restore of a previous release's deployment context. See Rolling back.
Further release types appear in an environment's release history: UNLOCK_STATE, from the Unlock State button, which releases a held Terraform state lock by lock ID; SCALE_UP and SCALE_DOWN, from the Scale Up and Scale Down actions, and also raised by the schedule of a time-sensitive environment, SCALE_UP on bring-up and SCALE_DOWN on teardown; and TERRAFORM_EXPORT, from the Export Terraform action, which generates the downloadable Terraform configuration. TERRAFORM_EXPORT can also be triggered with raptor create terraform-export -p PROJECT -e ENVIRONMENT.
In addition, Terraform logs are available for power users to view detailed information about the changes made during each release. By using releases in Facets, organisations can have a well-defined and automated process for deploying changes to their cloud environments, which helps reduce the risk of errors and makes it easier to roll back if necessary.
Release Statuses
| Status | Definition |
|---|---|
| SUCCEEDED | Release completed successfully |
| FAILED | Release encountered errors |
| IN_PROGRESS | Release is currently executing |
| QUEUED | Release is waiting to execute |
| PENDING_APPROVAL | Release requires approval before proceeding |
| ABORTED | Release was manually stopped |
| REJECTED | Release approval was denied |
| TIMED_OUT | Release exceeded execution time limit |
| STOPPED | Release was terminated |
Release Management Actions
Signing Off Deployments
Sign-off marks a release as approved for production deployment.
To sign off a release:
- Open the release from the Releases tab
- Review the changes and ensure the release succeeded
- Click Sign Off
- Confirm the action
Warning: Sign-off typically gates production deployments. Ensure the release has been thoroughly validated before signing off.
Attaching Labels to Releases
Categorize and filter releases by attaching labels.
To attach labels:
- Open the release
- Click Attach Labels
- Select labels from the available list
- Click Apply
Labels enable filtering and categorization in release searches.
Uploading Release Metadata
Upload custom metadata as JSON files for integration with external systems.
To upload metadata:
- Open the release
- Click Upload Metadata
- Select your JSON file
- Click Upload
The metadata is processed and stored in S3 for later retrieval.
Two Praxis agents assist with releases.
- Release Debugger diagnoses a failed release, analyzing logs to report the root cause and the fix steps.
- Release Approval covers the pre-release hook that gates a release behind manual approval.
Troubleshooting
| Problem | Solution |
|---|---|
| Null release type error during deployment creation | Ensure release type is specified. IllegalArgumentException is thrown when release type is null. |
| BadRequestException, ProdReleaseDisabled, or ReleasePausedException | Check environment configuration and release permissions. These exceptions halt release creation. |
| Deployment ID not found | Verify the deployment exists. NotFoundException is thrown for invalid deployment IDs. |
| Log streaming timeout | Connection is automatically closed after timeout. Refresh to reconnect. |
| Log stream EOF | Indicates log completion. This is normal for finished releases. |
| Helm rollback failure | Review error logs. All Helm exceptions are wrapped in RuntimeException with original cause. |
FAQs
1. What is a release in Facets?
Releases in Facets are a streamlined way of deploying changes to cloud environments. They are executed using Terraform apply commands and perform a three-way comparison of state to determine and deploy the necessary changes to the corresponding cloud environment.
2. What is a Full Release in Facets?
A Full Release in Facets is the default release type and is used for synchronizing all changes in an environment.
3. What is a Selective Release in Facets?
A Selective Release in Facets allows for selective deployment of services or changes, commonly used for out-of-turn hotfixes in production environments.
4. What happens to a scheduled release when there is a release already queued?
In such scenarios, the scheduled release gets skipped. It does not enter the queue or interrupt the current release process.
Canary releases
Configure Argo Rollouts canary deployments for Facets services: set rollout behavior, trigger a release, monitor pods, then promote or abort.
Parallel releases
Parallel releases run multiple non-conflicting selective service releases at once in the same environment, with queuing or state-lock handling.
Guardrail policies
Guardrail policies in Facets enforce security and compliance on blueprints using Rego, with Warning or Error severity that can gate releases.
Release Approval
Use Facets release approval workflows to enforce governance: define structured approval processes so only reviewed, authorized changes reach production.
Performing Releases
How to perform a release in Facets: choose Full, Selective, or Custom, use Plan or Apply, and set advanced options like refresh, force, and destroy.
Validation panel
The Validations Summary Panel surfaces broken references, JSON errors, and guardrail violations every 5 minutes so you can fix issues before release.
Rolling back
Roll a Facets release back to a previous known-good state using stored S3 deployment context, with a two-phase plan and apply workflow.
Enable/Disable Resources in an Environment
API recipe to enable or disable Facets resources in a specific environment with a PUT request, toggling the disabled flag by clusterId for each resource.
Canary releases
Configure Argo Rollouts canary deployments for Facets services: set rollout behavior, trigger a release, monitor pods, then promote or abort.