kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-04 09:25:46 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update enterprise licensing documentation (#16615)

Browse Source 
updated various docs for new expiration behavior
and new command `nomad license inspect` to validate pre-upgrade
This commit is contained in:
Daniel Bennett
2023-03-30 16:40:19 -05:00
committed by GitHub
parent 967f6e9e04
commit e6da5c70dc
8 changed files with 165 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
website/content/docs/commands/license/index.mdx
View File

@@ -7,12 +7,10 @@ description: |
# Command: license
~> License commands are new in Nomad 0.12.0 and are only available with Nomad Enterprise.
~> License commands are only available with Nomad Enterprise.
The `license` command provides cluster level management of the Nomad Enterprise license.
If ACLs are enabled then a token with operator privileges may be required in order to use
this command.
The `license` commands can be used to retrieve license information from a server,
or inspect and validate a license.
Click [here](https://www.hashicorp.com/products/nomad/trial) to get a trial license for Nomad Enterprise.
@@ -23,6 +21,8 @@ Usage: `nomad license <subcommand> [options]`
Run `nomad license <subcommand> -h` for help on that subcommand. The following
subcommands are available:
- [`license get`][get] - Get the current license
- [`license get`][get] - Get the current license from a server
- [`license inspect`][inspect] - Inspect and validate a license
[get]: /nomad/docs/commands/license/get 'Get the current license'
[get]: /nomad/docs/commands/license/get 'Get the current license from a server'
[inspect]: /nomad/docs/commands/license/inspect 'Inspect and validate a license'

82
website/content/docs/commands/license/inspect.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
layout: docs
page_title: 'Commands: license inspect'
description: |
The license inspect command is used to inspect and validate an enterprise license.
---
# Command: license inspect
<EnterpriseAlert>
This command is only present in Nomad Enterprise.
</EnterpriseAlert>
The `license inspect` command is used to inspect and validate a Nomad Enterprise
license. It will read the license from a file on disk or an environment variable
and exit non-0 if the license is not valid with the Nomad binary.
This command should always be run with the new binary before upgrading Nomad on a server,
as the server agent will not start with an invalid license.
## Usage
```plaintext
nomad license inspect [/path/to/license.hclic]
```
## Examples
With a license file argument:
```shell-session
$ nomad license inspect /path/to/nomad/license.hclic
Source: /path/to/nomad/license.hclic
Product: nomad
License ID: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
Customer ID: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
Installation ID: *
Issue Time: 2021-12-01 17:49:23.021041516 +0000 UTC
Start Time: 2021-12-01 00:00:00 +0000 UTC
Expiration Time: 2023-12-01 00:00:00 +0000 UTC
Termination Time: 2024-01-01 00:00:00 +0000 UTC
Build Date: 2000-01-01 00:00:00 +0000 UTC
Flags: {
"modules": [
"multicluster-and-efficiency",
"governance-policy"
]
}
License is valid
```
With a license file environment variable:
```shell-session
$ export NOMAD_LICENSE_PATH=/path/to/nomad/license.hclic
$ nomad license inspect
Source: /path/to/nomad/license.hclic (path from the NOMAD_LICENSE_PATH environment variable)
Product: nomad
.....
License is valid
```
With a license string environment variable:
```shell-session
$ export NOMAD_LICENSE=full-license-text-string
$ nomad license inspect
Source: NOMAD_LICENSE environment variable
.....
License is valid
```
## Example error
```shell-session
$ nomad license inspect license.hclic
...
Validation Errors:
* license is no longer valid
* license expiration date is before version build date: expiration=2023-01-13T23:59:59Z build=2023-03-17T00:00:00Z
```

5
website/content/docs/enterprise/index.mdx
View File

@@ -19,8 +19,8 @@ its features in detail.
~> **Note:** A Nomad Enterprise cluster cannot be downgraded to the open
source version of Nomad. Servers running the open source version of Nomad will
panic if they are joined to a Nomad Enterprise cluster. See issue [gh-9958]
for more details.
panic if they are joined to a Nomad Enterprise cluster, due to raft entries
relating to Enterprise features not being parseable by open source Nomad.
## Nomad Enterprise Platform
@@ -175,4 +175,3 @@ request a trial of Nomad Enterprise.
[multiregion deployments]: /nomad/docs/job-specification/multiregion
[autoscaling capabilities]: /nomad/tools/autoscaling
[scaling policies]: /nomad/tools/autoscaling/policy
[gh-9958]: https://github.com/hashicorp/nomad/issues/9958

75
website/content/docs/enterprise/license/faq.mdx
View File

@@ -7,25 +7,36 @@ description: >-
# Frequently Asked Questions (FAQ)
This FAQ is for the license changes introduced in Nomad Enterprise version v1.1.0+ent.
Nomad Enterprise automatically load Nomad licenses when a Nomad server agent starts using Nomad Enterprise.
This FAQ is for the license changes introduced in Nomad Enterprise version v1.6.0+ent.
For license-related FAQ for earlier versions, please refer to earlier versions of this document
using the version drop-down on this page, e.g. [v1.5.x](/nomad/docs/v1.5.x/enterprise/license/faq).
## Q: Can I get a quick summary of the Nomad changes?
Starting with Nomad Enterprise v1.1.0, the license enablement process is different.
Starting with Nomad Enterprise v1.6.0, license expiration is different.
HashiCorp Enterprise servers will no longer start without a license. When the server instance initializes the license watcher, the server reads from either an environment variable or file. If the license is missing, invalid, or expired, the server will immediately exit.
This check is part of the server boot-up process.
For trial licenses, the behavior remains the same. Enterprise features will stop working
when the license expires, and a server can not start with an expired license.
In previous versions of HashiCorp enterprise products, one server could distribute a license to other servers via the Raft protocol.
This will no longer work since each server must be able to find a valid license during the startup process.
For new "non-terminating" contract licenses, instead of expiration being compared to the current time,
expiration time is compared to the build date of the Nomad binary, which you can find in the output of the
[`nomad version`](/nomad/docs/commands/version) command.
The practical result is that newer contract licenses will work in perpetuity for any v1.6.0+ version of Nomad
built prior to the expiration time of the license. No features will stop working,
and server agents can be restarted safely.
However, if you try to upgrade to a newer binary past license expiration, the server will not start.
To proactively avoid that, you can test a new binary with your license using the new
[`nomad license inspect`][license inspect] command
before trying to upgrade your servers.
## Q: What resources are available?
The list below is a great starting point for learning more about the license changes introduced in Nomad Enterprise v1.1.0
The list below is a great starting point for learning more about license usage in general.
- [v1.1.0 Upgrade Guide](/nomad/docs/upgrade/upgrade-specific#enterprise-licenses)
- [v1.6.0 Upgrade Guide](/nomad/docs/upgrade/upgrade-specific#enterprise-license-validation-with-builddate)
- [Nomad License Documentation](/nomad/docs/enterprise/license)
@@ -33,9 +44,9 @@ The list below is a great starting point for learning more about the license cha
- [Install a HashiCorp Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license)
## Q: Does this affect Nomad or older versions of Nomad?
## Q: Does this affect older versions of Nomad?
This change only affects Nomad Enterprise version v1.1.0+ent and later.
This change only affects Nomad Enterprise version v1.6.0+ent and later.
## Q: Does the license have to be present on Nomad client nodes?
@@ -44,33 +55,23 @@ Nomad agents running with the `-dev` flag will also need a license.
## Q: What are some pitfalls that could be experienced during an upgrade because of the license changes?
If you follow the steps in the [upgrade guide](/nomad/docs/upgrade/upgrade-specific#enterprise-licenses), but have misconfigured the licensing steps, the server instances will stop during boot-up sequence.
If you have an expired license that has not yet become fully nonfunctional
(i.e. it is in grace period between ExpirationTime and TerminationTime),
then a Nomad server will not be able to start using a new v1.6.0+ binary.
If you do not check cluster health after adding new servers, and verify that the new servers have joined properly, then you may accidentally take down old servers without replacing them.
Before shutting down a server agent to replace it with a new version,
be sure to run [`nomad license inspect`][license inspect] with the new binary.
If you are using a trial license in production, this could cause issues as the cluster will fail to start once the trial expires.
If you have built automation around `nomad license put`, this command will fail as it has been removed from Nomad v1.1.0+.
## Q: What are some other gotchas?
You might not have access to your organization's Nomad license.
The 6-hour temporary license window is now removed, and a license is required for proper boot-up.
Running `nomad agent -dev` without a license will fail.
## Q: How can a user get their existing license to put on disk for an upgrade?
## Q: How can a user get their existing license?
If you are an existing HashiCorp enterprise customer you may contact your organization's customer success manager (CSM) or email support-softwaredelivery@hashicorp.com for information on how to get your organization's enterprise license.
You can use `nomad license get` to retrieve information about the license, but not the license itself.
You can use `nomad license get` to retrieve information about the license, but not the license itself.
## Q: What happens when a license expires?
If a license expires after a server node joins the cluster, the existing Enterprise features will continue to operate until a grace period expires.
The grace period duration is 1 day, and upon the end of the grace period the Nomad servers will shut down.
## Q: Will on-prem binaries with “baked-in” licenses work?
There is no impact to baked-in licensed binaries.
All features will continue to work until you attempt to upgrade Nomad that is newer than your license expiration time.
In that case, the server agent will fail to start, and you'll need to roll back to the previous working version
and acquire a new license to use with the newer Nomad version before attempting the upgrade again.
## Q: Are licenses cluster-specific? node-specific?
@@ -84,10 +85,16 @@ Visit https://nomadproject.io/trial for a free 30-day trial license.
Every time `nomad agent` runs as a server (or in `-dev`), it requires a license.
## Q: May I downgrade Nomad Enterprise from v1.1.0 to an earlier version?
## Q: May I downgrade Nomad Enterprise from v1.6.0 to an earlier version?
Nomad cannot safely be rolled back to an earlier version.
This is not a supported operation due to the Nomad state store not having forward compatibility. The end result could be a crash loop.
Yes, if you upgrade a server to 1.6.0+ but it fails to start due to license expiration,
you can roll back to a previous working version with the old expiration logic.
If a server fails to start for any other reason aside from license expiration,
roll back to a previous version is not supported due to the Nomad state store
not having forward compatibility, and may result in a crash loop.
## Q: Is there a tutorial available for the license configuration steps?
Please visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license).
[license inspect]: /nomad/docs/commands/license/inspect

47
website/content/docs/enterprise/license/index.mdx
View File

@@ -8,47 +8,28 @@ description: >-
## Nomad Enterprise Licensing
Licensing capabilities were added to Nomad Enterprise v0.12.0. Each server in
the cluster must have its own license. Nomad Enterprise can be downloaded from
the cluster must have a license to start. Nomad Enterprise can be downloaded from
the [releases site].
Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo of Nomad Enterprise
or [here](/nomad/tutorials/enterprise/hashicorp-enterprise-license#request-a-trial-license) for instructions on how to get a trial license.
or [here](/nomad/tutorials/enterprise/hashicorp-enterprise-license#request-a-trial-license)
for instructions on how to get a trial license.
~> **Note:** A Nomad Enterprise cluster cannot be downgraded to the open
source version of Nomad. Servers running the open source version of Nomad will
panic if they are joined to a Nomad Enterprise cluster. See issue [gh-9958]
for more details.
panic if they are joined to a Nomad Enterprise cluster, due to raft entries
relating to Enterprise features not being parseable by open source Nomad.
## Expiring Licenses
Nomad Enterprise license have an expiration time. You can read the license on
a server with the `nomad license get` command:
Nomad Enterprise licenses have an expiration time.
You can read and validate the license on a running server,
on disk, or in your environment with the
[`nomad license` commands](/nomad/docs/commands/license).
```
$ nomad license get
Product = nomad
License Status = valid
License ID = eaaecbd5-b598-4fa4-b649-bb234bf49fa3
Customer ID = ae94bdd0-39bf-4c58-bf80-8a9468b0467c
Issued At = 2021-03-29 14:47:29.024191 -0400 EDT
Expires At = 2021-03-29 20:47:29.024191 -0400 EDT
Datacenter = *
Modules:
governance-policy
multicluster-and-efficiency
Licensed Features:
Automated Upgrades
Enhanced Read Scalability
Redundancy Zones
Namespaces
Resource Quotas
Audit Logging
Sentinel Policies
Multiregion Deployments
Automated Backups
Multi-Vault Namespaces
Dynamic Application Sizing
```
Before upgrading Nomad or replacing your license with a new one, you should always run
[`nomad license inspect`](/nomad/docs/commands/license/inspect)
to ensure the license is valid with your server binary.
As a Nomad Enterprise license approaches its expiration time, Nomad servers
will periodically log a warning message about the approaching
@@ -68,9 +49,6 @@ When the license expires, enterprise functionality will become limited. Only
read operations on enterprise endpoints will be supported, and write
operations will return an error.
Note that if the server is restarted with an expired license, it will
immediately stop.
## Configuring the License
See the server [license configuration] reference documentation on all the
@@ -93,7 +71,6 @@ NOMAD_LICENSE=misconfigured nomad agent -dev
See the [License commands](/nomad/docs/commands/license) for more information on
interacting with the Enterprise License.
[gh-9958]: https://github.com/hashicorp/nomad/issues/9958
[releases site]: https://releases.hashicorp.com/nomad
[license configuration]: /nomad/docs/configuration/server#license_path
[license endpoint]: /nomad/api-docs/operator/license#updating-the-nomad-enterprise-license

9
website/content/docs/upgrade/index.mdx
View File

@@ -141,7 +141,14 @@ are in a `ready` state.
## Upgrading to Nomad Enterprise
The process of upgrading to a Nomad Enterprise version is identical to upgrading
Before upgrading servers to Nomad Enterprise versions 1.6.0 and later,
you should validate your enterprise license with the
[`nomad license inspect` command](/nomad/docs/commands/license/inspect)
using the binary that you are upgrading to.
See the [licensing FAQ](/nomad/docs/enterprise/license/faq)
for more information.
After that, the process of upgrading to a Nomad Enterprise version is identical to upgrading
between versions of open source Nomad. The same guidance above should be
followed and as always, prior to starting the upgrade please check the [specific
version details](/nomad/docs/upgrade/upgrade-specific) page as some version

9
website/content/docs/upgrade/upgrade-specific.mdx
View File

@@ -15,6 +15,15 @@ used to document those details separately from the standard upgrade flow.
## Nomad 1.6.0
#### Enterprise License Validation with BuildDate
Nomad Enterprise 1.6.0 now compares license `ExpirationTime` with the Nomad binary's `BuildDate`,
rather than comparing the sometimes more lenient license `TerminationTime` with `time.Now()`.
See the [licensing FAQ](/nomad/docs/v1.6.x/enterprise/license/faq) for more info,
but most relevant here is that you should run the new
[`nomad license inspect`](/nomad/docs/commands/license/inspect) command
before trying to upgrade your Enterprise servers to v1.6.0 or higher.
#### Job Evaluate API Endpoint Requires `submit-job` Instead of `read-job`
Nomad 1.6.0 updated the ACL capability requirement for the job evaluate

4
website/data/docs-nav-data.json
View File

@@ -586,6 +586,10 @@
{
"title": "get",
"path": "commands/license/get"
},
{
"title": "inspect",
"path": "commands/license/inspect"
}
]
},