Skip to content

docs: Update Boundary licensing information #5999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs: Update Boundary licensing information #5999

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c7e9a15
docs: Update licensing information
Dan-Heath Aug 8, 2025
d59d96a
docs: Cleanup, add graceful shutdown info
Dan-Heath Aug 25, 2025
8119990
docs: Make code block plaintext and hide clipboard
Dan-Heath Aug 25, 2025
e3744d7
docs: Adds warning example
Dan-Heath Sep 8, 2025
1876f82
docs: Minor rewrites for clarity
Dan-Heath Sep 10, 2025
e67aa78
Merge branch 'main' into dheath-update-licensing-info
Dan-Heath Sep 10, 2025
9ab719e
docs: Fix link, minor edits
Dan-Heath Sep 10, 2025
ad6c89d
Update website/content/docs/enterprise/licensing.mdx
Dan-Heath Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 79 additions & 28 deletions website/content/docs/enterprise/licensing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,52 +5,103 @@ description: >-
Learn how to enable Boundary Enterprise with a valid license. Request access from an account team to enable enterprise features.
---

# License Boundary Enterprise
# 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 send 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 request access [here](https://www.hashicorp.com/contact-sales).

## Enable Boundary Enterprise

Once you have received 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...`
`$ export BOUNDARY_LICENSE=02MV4UU43BK5...`

or
or

`$ BOUNDARY_LICENSE=file:///folder_path/license.hclic`
`$ 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"
}
```
```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.
```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 will not be able to create any new sessions.

Prior to the expiration date, Boundary logs 5 warnings to the event stream at the following intervals:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you able to provide an example of what that log looks like? That would be helpful for users to configure alerting on this, just in case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion! I added an example from the log and some additional verbiage to help with alerts.


| 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that this depends on the length of the license issued, I think this is probably based on a yearly license?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can add some text to explain that.


When there is 1 minute left before license expiration, Boundary provides the following message:

<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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These logs mention boundary dev, I don't know what it looks like when using boundary server (for controllers or workers). Let me know if you want a log from a more realistic environment, or if you just want to remove these logs (I think either is fine).

Copy link
Contributor Author

@Dan-Heath Dan-Heath Sep 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.