docs: Update Boundary licensing information #5999
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,52 +5,149 @@ description: >- | |
| Learn how to enable Boundary Enterprise with a valid license. Request access from an account team to enable enterprise features. | ||
| --- | ||
|
|
||
| # Boundary Enterprise licensing | ||
|
|
||
| The Boundary Enterprise binaries require a license key to enforce entitlements and time restrictions according to your contractual agreement. | ||
| Once purchased, your HashiCorp account team sends you a valid Boundary license for environment activation. | ||
| If you don't yet have an acccount team, but are interested in Boundary Enterprise, you can [contact sales](https://www.hashicorp.com/contact-sales). | ||
|
|
||
| ## Enable Boundary Enterprise | ||
|
|
||
| Once you receive your valid Boundary license, there are two options for enabling Boundary Enterprise: | ||
|
|
||
| 1. You may set the enterprise license for Boundary using an environment variable. | ||
| Set the `BOUNDARY_LICENSE` environment variable to the license key value you received: | ||
|
|
||
| `$ export BOUNDARY_LICENSE=02MV4UU43BK5...` | ||
|
|
||
| or | ||
|
|
||
| `$ BOUNDARY_LICENSE=file:///folder_path/license.hclic` | ||
|
|
||
| 1. You may specify the enterprise license key in the Boundary controller configuration using the `license` attribute in the `controller` block. | ||
| You can either specify the raw license key or the path to a file containing the license key. | ||
| Refer to the sample configurations below: | ||
|
|
||
| **Sample #1** | ||
|
|
||
| ```hcl | ||
| controller { | ||
| name = "controller" | ||
| description = "controller" | ||
| database { | ||
| url = "postgresql://boundary:[email protected]:5432/boundary" | ||
| } | ||
| public_cluster_addr = "boundary.domain" | ||
| license = "file:///folder_path/license.hclic" | ||
| } | ||
| ``` | ||
| **Sample #2** | ||
|
|
||
| ```hcl | ||
| controller { | ||
| name = "controller" | ||
| description = "controller" | ||
| database { | ||
| url = "postgresql://boundary:[email protected]:5432/boundary" | ||
| } | ||
| public_cluster_addr = "boundary.domain" | ||
| license = "02MV4UU43BK5..." | ||
| } | ||
| ``` | ||
|
|
||
| Refer to the [controller](/boundary/docs/configuration/controller) configuration documentation for more information. | ||
|
|
||
| ## License expiration | ||
|
|
||
| When the Boundary license expires, the controller performs a graceful shutdown. | ||
| Ongoing sessions continue to run, but you cannot create any new sessions. | ||
|
|
||
| Prior to the license expiration, Boundary logs five system event warnings to the event stream at the following intervals: | ||
|
|
||
| | Warning | Interval | | ||
| |---------| ---------------------------------- | | ||
| | First | 30 days before license expiration | | ||
| | Second | 7 days before license expiration | | ||
| | Third | 24 hours before license expiration | | ||
| | Fourth | 1 hour before license expiration | | ||
| | Fifth | 1 minute before license expiration | | ||
|
Comment on lines
+67
to
+73
There was a problem hiding this comment. Note that this depends on the length of the license issued, I think this is probably based on a yearly license? There was a problem hiding this comment. I can add some text to explain that. |
||
|
|
||
| Refer to the following example of how the warnings appear in the log. | ||
| If you use an external monitoring system, you can create alerts for `"msg": "license warning"` and `"op": "licensing.StartWatching"` to watch for license expiration warnings. | ||
|
|
||
| <CodeBlockConfig hideClipboard> | ||
|
|
||
| ```plaintext | ||
| { | ||
| "id": "eRrnWonkuK", | ||
| "source": "https://hashicorp.com/boundary/nixos/controller+worker", | ||
| "specversion": "1.0", | ||
| "type": "system", | ||
| "data": { | ||
| "version": "v0.1", | ||
| "op": "licensing.StartWatching", | ||
| "data": { | ||
| "expiration_time": "2025-09-08T11:14:33-07:00", | ||
| "msg": "licensing status", | ||
| "time_left_seconds": 83 | ||
| } | ||
| }, | ||
| "datacontentype": "text/plain", | ||
| "time": "2025-09-08T11:13:10.216888454-07:00" | ||
| } | ||
| { | ||
| "id": "ymFHcb1H1Z", | ||
| "source": "https://hashicorp.com/boundary/nixos/controller+worker", | ||
| "specversion": "1.0", | ||
| "type": "system", | ||
| "data": { | ||
| "version": "v0.1", | ||
| "op": "licensing.StartWatching", | ||
| "data": { | ||
| "expiration_time": "2025-09-08T11:14:33-07:00", | ||
| "msg": "licensing warning", | ||
| "time_left_seconds": 30 | ||
|
Comment on lines
+92
to
+109
There was a problem hiding this comment. We could massage these numbers a bit to make it look a bit more realistic (e.g., adjust the timestamp, set the time_left_second to something much bigger, set it to 60 in the last warning message). |
||
| } | ||
| }, | ||
| "datacontentype": "text/plain", | ||
| "time": "2025-09-08T11:14:03.457471753-07:00" | ||
| } | ||
| ``` | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| When there is 1 minute left before license expiration, Boundary provides the following message as an error: | ||
|
There was a problem hiding this comment. I think the message above is the 1 minute message (it says 30 seconds in my example). The message below is printed immediately upon license expiration. |
||
|
|
||
| <CodeBlockConfig hideClipboard> | ||
|
|
||
| ```plaintext | ||
| { | ||
| "id": "SJkaNV09xP", | ||
| "source": "https://hashicorp.com/boundary/nixos/controller+worker", | ||
| "specversion": "1.0", | ||
| "type": "error", | ||
| "data": { | ||
| "error": "error from licensing watcher: invalid license or license is expired", | ||
| "error_fields": {}, | ||
| "id": "e_33IKa8BqB3", | ||
| "version": "v0.1", | ||
| "op": "licensing.StartWatching" | ||
| }, | ||
| "datacontentype": "text/plain", | ||
| "time": "2025-08-01T16:54:14.34408533-07:00" | ||
| } | ||
| ==> Boundary dev environment self-terminating | ||
| ==> Health is enabled, waiting 0s before shutdown | ||
| ==> Boundary dev environment graceful shutdown triggered, interrupt again to enter shutdown | ||
|
Comment on lines
+139
to
+141
There was a problem hiding this comment. These logs mention There was a problem hiding this comment. Ahh... good catch, thank you. If you are able to get a log from a more realistic environment, I think it would be a helpful addition. I can work on cleaning up the parts you mentioned in the comments above. |
||
| ``` | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| To update your license key, refer to the steps in [Enable Boundary Enterprise](#enable-boundary-enterprise). | ||
| There is no downtime associated with updating an expired license key. | ||
|
There was a problem hiding this comment. Is this true? I would think the controller would need to be restarted if an environment variable is used, or the config would need to be SIGHUPed if a new license is added to the config file. There was a problem hiding this comment. That makes sense. This also came from the conversation with Aman, and I may have misunderstood. Robin might have an environment where I can test this (something he's working on for HashiConf). I will check with him to see if we can verify this. |
||
|
|
||
| ## More information | ||
|
|
||
| Refer to the [Upgrade and database migration](/boundary/tutorials/self-managed-deployment/upgrade-version) tutorial for step-by-step instructions to upgrade Boundary to its latest version, including database backup and data migration. | ||
|
|
||
| Refer to [Monitor Boundary](/boundary/docs/monitor) for more information about configuring Boundary to monitor events. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this true? I haven't tested this part, but I think graceful shutdown means that it will wait for ongoing HTTP requests to return, not existing Boundary sessions. It will also probably only wait 5 seconds or so before actually shutting down. I also expect that after the controller has been down for 15 seconds, the workers will start terminating sessions. I think we'll want to verify this behavior.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for reviewing this, Johan! I got this info from Aman, but I may have misunderstood our conversation and assumed it was sessions vs HTTP requests. I don't think he tested it either tho.