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

docs: notices of upcoming deprecations and backports (#23683)

Browse Source 
Add a section to the docs describing planned upcoming deprecations and
removals. Also added some missing upgrade guide sections missed during the last
release.
This commit is contained in:
Tim Gross
2024-07-25 10:20:18 -04:00
committed by GitHub
parent 6a7eb15590
commit d5ca07a247
7 changed files with 122 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
website/content/docs/integrations/consul/acl.mdx
View File

@@ -386,8 +386,8 @@ service_prefix "" {
<Note title="Deprecation Warning">
This legacy workflow will be removed in Nomad 1.9. Before upgrading to Nomad 1.9
you will need to have configured authentication with Consul as described in
This legacy workflow will be removed in Nomad 1.10. Before upgrading to Nomad 1.10,
you need to configure authentication with Consul as described in
[Nomad Workload Identities](#nomad-workload-identities).
</Note>

6
website/content/docs/integrations/vault/acl.mdx
View File

@@ -343,9 +343,9 @@ Nomad clients do not need to be provided with a Vault token.**
<Note title="Deprecation Warning">
This legacy workflow will be removed in Nomad 1.9. Before upgrading to Nomad 1.9
you will need to have configured authentication with Vault as described in
[Nomad Workload Identities](#nomad-workload-identities).
This legacy workflow will be removed in Nomad 1.10. Before upgrading to Nomad
1.10, you need to configure authentication with Vault as described in [Nomad
Workload Identities](#nomad-workload-identities).
</Note>

6
website/content/docs/job-specification/consul.mdx
View File

@@ -62,12 +62,12 @@ and binding rules in Consul before configuring the Nomad servers with
Authentication][] for more details.
<Warning>
Starting in Nomad 1.9, the fallback options to use the -consul-token flag when
Starting in Nomad 1.10, the fallback options to use the -consul-token flag when
submitting a job, the agent's consul.token configuration, or the
CONSUL_HTTP_TOKEN environment variable, will be removed. This means service and
template blocks will not be able to use the agent's Consul token or one provided
by the job submitter. You should be prepared to migrate to the Workload Identity
workflow for Consul and Vault before upgrading to Nomad 1.9. Refer to <a
workflow for Consul and Vault before upgrading to Nomad 1.10. Refer to <a
href="/nomad/docs/integrations/consul-integration#migrating-to-using-workload-identity-with-consul">Migrating
to Using Workload Identity with Consul</a>
</Warning>
@@ -76,7 +76,7 @@ to Using Workload Identity with Consul</a>
The Nomad client will make the Consul token available to the task by writing it
to the secret directory at `secrets/consul_token` and by injecting a
`CONSUL_TOKEN` environment variable in the task.
`CONSUL_TOKEN` environment variable in the task.
If the Nomad cluster is [configured][config_consul_namespace] to use [Consul Namespaces][], a
`CONSUL_NAMESPACE` environment variable will be injected whenever `CONSUL_TOKEN`

2
website/content/docs/job-specification/vault.mdx
View File

@@ -113,7 +113,7 @@ with Vault as well.
the task requires. The Nomad client will retrieve a Vault token that is
limited to those policies. This field may only be used with the legacy Vault
authentication workflow and not with JWT and workload identity. It is
deprecated in favor of the `role` field and will be removed in Nomad 1.9.
deprecated in favor of the `role` field and will be removed in Nomad 1.10.
- `role` `(string: "")` - Specifies the Vault role used when retrieving a token
from Vault using JWT and workload identity. If not specified the client's

65
website/content/docs/release-notes/nomad/upcoming.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
layout: docs
page_title: Upcoming
description: >-
Notices of upcoming Nomad changes
---
# Upcoming
Nomad strives to be backward compatible for at least 2 major releases, so for
example, you can upgrade Nomad v1.6.x to Nomad v1.8.x. In addition, Enterprise
customers have access to [Long Term Support (LTS)][LTS] releases.
Refer to [Upgrading][] for details of the upgrade process, and [Upgrade
Guides][] for notes on upgrading specific versions.
However, from time to time it's necessary to make backwards _incompatible_
changes to Nomad. We announce these on [changelog][], the [Release Notes][], and
the version-specific [Upgrade Guides][]. In order to help you plan your
upgrades, this page maintains a list of all planned future changes that might
cause backwards incompatibilities or require operational changes. It's possible
that a given change may happen later than intended, at which point we update
this document. However, we do not move changes earlier than originally published
unless there's a required change due to a security vulnerability.
## Nomad 1.9.0
* Nomad will remove support for HCL1 job specifications and the `-hcl1` flag on
the `nomad job run` and other commands. Refer to [GH-20195][] for more details.
* Nomad will remove the [`tls_prefer_server_cipher_suites`][] agent configuration.
## Nomad 1.10.0 LTS
Nomad 1.10.0 is a Long-Term Support release for Enterprise customers.
* Nomad will remove support for the legacy token workflow for Consul. Workloads
that need Consul support will require the cluster be configured to use
Workload Identity with Consul. Refer to [the integration
guide][consul-integration] for details.
* Nomad will remove support for the legacy token workflow for Vault. Workloads
that need Vault support will require the cluster be configured to use Workload
Identity with Vault. Refer to [the integration guide][vault-integration] for
details.
* Nomad will no longer create an implicit `consul` block for workloads that
don't register services with Consul. Jobs that require Consul tokens for
`template` rendering will be required to provide a `consul` block.
* Nomad clients will no longer execute all binaries in the plugin directory on
startup for fingerprinting. Only plugins with an associated `plugin` block in
the Nomad agent configuration will be fingerprinted. Refer to [GH-18529][] for
more details.
* Nomad will ignore the deprecated `stop_after_client_disconnect`,
`max_client_disconnect`, and `prevent_reschedule_on_lost` fields and only
support the [`disconnect`][] block, which covers the same functionality.
[LTS]: /nomad/docs/enterprise#long-term-support-lts-releases
[Upgrading]: /nomad/docs/upgrade
[Upgrade Guides]: /nomad/docs/upgrade/upgrade-specific
[changelog]: https://github.com/hashicorp/nomad/blob/main/CHANGELOG.md
[Release Notes]: /nomad/docs/release-notes
[GH-20195]: https://github.com/hashicorp/nomad/issues/20195
[`tls_prefer_server_cipher_suites`]: /nomad/docs/configuration/tls#tls_prefer_server_cipher_suites
[consul-integration]: /nomad/docs/integrations/consul/acl
[vault-integration]: /nomad/docs/integrations/vault/acl
[GH-18529]: https://github.com/hashicorp/nomad/issues/18529
[`disconnect`]: /nomad/docs/job-specification/disconnect

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

@@ -33,13 +33,17 @@ In 1.8.2, Nomad will refuse to run jobs that use the Docker driver on Windows
with [Process Isolation][] that run as `ContainerAdmin`. This is in order to
provide a more secure environment for these jobs, and this behavior can be
overridden by setting the new `windows_allow_insecure_container_admin` Docker
plugin configuration option to `true` or by setting `privileged=true`.
plugin configuration option to `true` or by setting `privileged=true`. We made
this change as a result of regressions introduced by mitigations for
[HCSEC-2024-03](https://discuss.hashicorp.com/t/hcsec-2024-03-nomad-vulnerable-to-arbitrary-write-through-symlink-attack/62602).
#### New default isolation mode for Docker on Windows
Nomad 1.8.2 changes the default isolation mode for Docker tasks on Windows from
`process` to `hyperv`, since `hyperv` provides a much more secure execution
environment.
environment. We made this change as a result of regressions introduced by
mitigations for
[HCSEC-2024-03](https://discuss.hashicorp.com/t/hcsec-2024-03-nomad-vulnerable-to-arbitrary-write-through-symlink-attack/62602).
## Nomad 1.8.1
@@ -78,7 +82,21 @@ In Nomad 1.7.0 the `raw_exec` plugin option for `no_cgroups` became ineffective.
Starting in Nomad 1.8.0 attempting to set the `no_cgroups` in `raw_exec` plugin
configuration will result in an error when starting the agent.
## Nomad 1.7.10 (UNRELEASED)
## Nomad 1.7.11 (UNRELEASED)
<EnterpriseAlert inline />
#### Nomad keyring rotation
In Nomad 1.7.11, the Nomad root keyring will prepublish keys at half the
`root_key_rotation_threshold` and promote them to active once the
`root_key_rotation_threshold` has passed. The `nomad operator root keyring
rotate` command now requires one of two arguments: `-prepublish <duration>` to
prepublish a key or `-now` to rotate immediately. We recommend using
`-prepublish` to avoid outages from workload identities used to log into
external services such as Vault or Consul.
## Nomad 1.7.10
<EnterpriseAlert inline />
@@ -127,20 +145,20 @@ authenticate to Vault and obtain a Vault token specific to the task.
The existing workflow using a Vault token provided in either the agent
configuration or at the time of job submission is deprecated and will be removed
in Nomad 1.9. The [`vault.policies`][] field is also deprecated and will work
in Nomad 1.10. The [`vault.policies`][] field is also deprecated and will work
only with the existing workflow. Instead, you should configure a suitable Vault
role and use that.
The following agent configuration fields are deprecated:
- [`vault.allow_unauthenticated`][] will be removed in Nomad 1.9. Tasks will use
- [`vault.allow_unauthenticated`][] will be removed in Nomad 1.10. Tasks will use
the workload identity without the user supplying a Vault token.
- [`vault.task_token_ttl`][] will be removed in Nomad 1.9. With workload
- [`vault.task_token_ttl`][] will be removed in Nomad 1.10. With workload
identity, tasks will receive their TTL configuration from the Vault role.
- [`vault.token`][] will be removed in Nomad 1.9. Nomad agents will no longer
- [`vault.token`][] will be removed in Nomad 1.10. Nomad agents will no longer
make requests to authenticated endpoints except with a task's workload
identity.
Before upgrading to Nomad 1.9 you will need to have configured authentication
Before upgrading to Nomad 1.10 you will need to have configured authentication
with Vault to work with workload identity. See [Migrating to Using Workload
Identity with Vault][] for more details.
@@ -152,11 +170,11 @@ workload.
The existing workflow using a Consul token provided in either the agent
configuration or at the time of job submission is deprecated and will be removed
in Nomad 1.9. The [`consul.allow_unauthenticated`][] agent configuration field
will be removed in Nomad 1.9. Tasks will use the workload identity without the
in Nomad 1.10. The [`consul.allow_unauthenticated`][] agent configuration field
will be removed in Nomad 1.10. Tasks will use the workload identity without the
user supplying a Consul token.
Before upgrading to Nomad 1.9 you will need to have configured authentication
Before upgrading to Nomad 1.10 you will need to have configured authentication
with Consul to work with workload identity. See [Migrating to Using Workload
Identity with Consul][] for more details.
@@ -243,7 +261,21 @@ cgroup to halt the process group of a Task before issuing a kill signal to each
process. Starting in Nomad 1.7.0 this behavior is always enabled (and a similar
mechanism has always been enabled on cgroups v2 systems).
## Nomad 1.6.13 (UNRELEASED)
## Nomad 1.6.14 (UNRELEASED)
<EnterpriseAlert inline />
#### Nomad keyring rotation
In Nomad 1.6.14, the Nomad root keyring will prepublish keys at half the
`root_key_rotation_threshold` and promote them to active once the
`root_key_rotation_threshold` has passed. The `nomad operator root keyring
rotate` command now requires one of two arguments: `-prepublish <duration>` to
prepublish a key or `-now` to rotate immediately. We recommend using
`-prepublish` to avoid outages from workload identities used to log into
external services such as Vault or Consul.
## Nomad 1.6.13
<EnterpriseAlert inline />

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

@@ -60,6 +60,10 @@
{
"title": "Nomad",
"routes": [
{
"title": "Upcoming",
"path": "release-notes/nomad/upcoming"
},
{
"title": "v1.8.x",
"path": "release-notes/nomad/v1_8_x"