mirror of
https://github.com/kemko/nomad.git
synced 2026-01-03 17:05:43 +03:00
e16a3339ad
* Add ent policy enforcement stubs to CSI Volume create/register * Wire policy override/warnings through CSI volume register/create * Add new scope to sentinel apply * Sanitize CSISecrets & CSIMountOptions * Add sentinel policy scope to ui * Update docs for new sentinel scope/policy * Create new api funcs for CSI endpoints * fix sentinel csi ui test * Update sentinel-policy docs * Add changelog * Update docs from feedback
186 lines
9.6 KiB
Plaintext
186 lines
9.6 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Sentinel policy reference
|
|
description: >-
|
|
Use the Nomad Enterprise Sentinel policy feature to implement fine-grained control over jobs, such as restricting when jobs can run or ensuring jobs use specific images. Learn about policy structure, job objects, Access Control List (ACL) token objects, and namespace objects.
|
|
---
|
|
|
|
# Sentinel Policy Reference
|
|
|
|
<EnterpriseAlert product="nomad" />
|
|
|
|
This page provides reference information on using the Nomad Sentinel policy feature to implement fine-grained policies such as restricting when jobs can run or ensuring job use specific images. Learn about policy structure, job objects, Access Control List (ACL) token objects, and namespace objects.
|
|
|
|
## Introduction to Sentinel Policies
|
|
|
|
In Nomad Enterprise, operators can create Sentinel policies for fine-grained
|
|
policy enforcement. Sentinel policies build on top of the ACL system and allow
|
|
operators to define policies such as disallowing jobs to be submitted to
|
|
production on Fridays or only allowing users to run jobs that use pre-authorized
|
|
Docker images. Sentinel policies are defined as code, giving operators
|
|
considerable flexibility to meet compliance requirements.
|
|
|
|
Refer to the [Nomad Sentinel Tutorial][] for more information about deploying
|
|
Sentinel policies, as well as the documentation for the [`nomad sentinel`][]
|
|
subcommands.
|
|
|
|
## Sentinel Policy Structure
|
|
|
|
Sentinel policies are specified in the [Sentinel Language][sentinel]. The
|
|
language is designed to be understandable for people who are reading and writing
|
|
policies, while remaining fast to evaluate. There is no limitation on how
|
|
complex policies can be, but they are in the execution path so care should be
|
|
taken to avoid adversely impacting performance.
|
|
|
|
In each scope, there are different objects made available for introspection,
|
|
such a job being submitted. Policies can inspect these objects to apply
|
|
fine-grained policies. Nomad supports a `submit-job` scope for registering jobs,
|
|
and a `submit-host-volume` scope for creating or updating dynamic host volumes.
|
|
|
|
### submit-job scope
|
|
|
|
The following top-level objects are available to policies in the `submit-job`
|
|
scope automatically, without an explicit import.
|
|
|
|
* `job`: the submitted job. This is a [Sentinel Job
|
|
Object](#sentinel-job-objects).
|
|
* `existing_job`: the previous version of the job. If `job_exists` is true, this
|
|
is always non-nil. This is also a [Sentinel Job
|
|
Object](#sentinel-job-objects).
|
|
* `job_exists`: a boolean field that indicates that a previous version of the
|
|
job exists.
|
|
* `nomad_acl_token`: the ACL token the job was submitted with. This is a
|
|
[Sentinel Nomad ACL Token Object](#sentinel-acl-token-objects).
|
|
* `namespace`: the namespace the job is in. This is a [Sentinel Nomad Namespace
|
|
Object](#sentinel-namespace-objects).
|
|
|
|
### submit-host-volume scope
|
|
|
|
The following top-level objects are available to policies in the
|
|
`submit-host-volume` scope automatically, without an explicit import.
|
|
|
|
* `volume`: the submitted volume. This is a [Sentinel Dynamic Host Volume
|
|
Object](#sentinel-dynamic-host-volume-objects).
|
|
* `existing_volume`: the previous version of the volume. If `volume_exists` is
|
|
true, this is always non-nil. This is also a [Sentinel Dynamic Host
|
|
Volume Object](#sentinel-dynamic-host-volume-objects). `volume_exists`: a
|
|
boolean field that indicates that a previous version of the volume exists.
|
|
* `nomad_acl_token`: the ACL token the job was submitted with. This is a
|
|
[Sentinel Nomad ACL Token Object](#sentinel-acl-token-objects).
|
|
* `namespace`: the namespace the job is in. This is a [Sentinel Nomad Namespace
|
|
Object](#sentinel-namespace-objects).
|
|
* `node`: the node the volume has been placed on. This is a [Sentinel Node
|
|
Object](#sentinel-node-objects).
|
|
* `node_pool`: the node pool of the node the volume has been placed on. This is
|
|
a [Sentinel Node Pool Object](#sentinel-node-pool-objects).
|
|
|
|
### submit-csi-volume scope
|
|
|
|
The following top-level objects are available to policies in the
|
|
`submit-csi-volume` scope automatically, without an explicit import.
|
|
|
|
- `volume`: the submitted volume. This is a [Sentinel CSI Volume
|
|
Object](#sentinel-csi-volume-objects).
|
|
- `existing_volume`: the previous version of the volume. If `volume_exists` is
|
|
true, this is always non-nil. This is also a [Sentinel CSI Volume
|
|
Object](#sentinel-csi-volume-objects).
|
|
- `volume_exists`: a boolean field that indicates that a previous version of the
|
|
volume exists.
|
|
- `nomad_acl_token`: the ACL token the job was submitted with. This is a
|
|
[Sentinel Nomad ACL Token Object](#sentinel-acl-token-objects).
|
|
- `namespace`: the namespace the job is in. This is a [Sentinel Nomad Namespace
|
|
Object](#sentinel-namespace-objects).
|
|
|
|
Sentinel convention for identifiers is lower case and separated by underscores.
|
|
All fields on an object are accessed by the same name, converted to lower case
|
|
and separating camel case to underscores.
|
|
|
|
## Sentinel Job Objects
|
|
|
|
The `job` and `existing_job` objects map to the [JSON job specification][], with
|
|
the fields converted to the Sentinel convention. Here are some examples:
|
|
|
|
| Job Field | Sentinel Accessor |
|
|
|------------------------------------------|---------------------------------------------|
|
|
| `job.ID` | `job.id` |
|
|
| `job.AllAtOnce` | `job.all_at_once` |
|
|
| `job.ParentID` | `job.parent_id` |
|
|
| `job.TaskGroups` | `job.task_groups` |
|
|
| `job.TaskGroups[0].EphemeralDisk.SizeMB` | `job.task_groups[0].ephemeral_disk.size_mb` |
|
|
|
|
## Sentinel ACL Token Objects
|
|
|
|
The `nomad_acl_token` object maps to the [ACL token][], with the fields
|
|
converted to the Sentinel convention. Here are some examples:
|
|
|
|
| Nomad ACL Token Field | Sentinel Accessor |
|
|
|-------------------------------|-------------------------------|
|
|
| `nomad_acl_token.AccessorID` | `nomad_acl_token.accessor_id` |
|
|
| `nomad_acl_token.Policies[0]` | `nomad_acl_token.policies[0]` |
|
|
|
|
Note that the `SecretID` field is always redacted to prevent credential leaks.
|
|
|
|
## Sentinel Namespace Objects
|
|
|
|
The `namespace` object maps to the [Namespace][], with the fields converted to
|
|
the Sentinel convention. Here are some examples:
|
|
|
|
| Namespace Field | Sentinel Accessor |
|
|
|----------------------------------------------|------------------------------------------------|
|
|
| `namespace.Description` | `namespace.description` |
|
|
| `namespace.NodePoolConfiguration.Allowed[0]` | `namespace.node_pool_configuration.allowed[0]` |
|
|
|
|
## Sentinel Node Objects
|
|
|
|
The `node` object maps to the [Node][], with the fields converted to the
|
|
Sentinel convention. Here are some examples:
|
|
|
|
| Node Field | Sentinel Accessor |
|
|
|--------------------|--------------------|
|
|
| `node.Class` | `node.class` |
|
|
| `node.Meta["foo"]` | `node.meta["foo"]` |
|
|
|
|
## Sentinel Node Pool Objects
|
|
|
|
The `node_pool` object maps to the [Node Pool][], with the fields converted to
|
|
the Sentinel convention. Here are some examples:
|
|
|
|
| Node Pool Field | Sentinel Accessor |
|
|
|-------------------------------------------------------|---------------------------------------------------------|
|
|
| `node_pool.Description` | `node_pool.description` |
|
|
| `node_pool.SchedulerConfiguration.SchedulerAlgorithm` | `node_pool.scheduler_configuration.scheduler_algorithm` |
|
|
|
|
## Sentinel Dynamic Host Volume Objects
|
|
|
|
The `volume` object maps to the [Dynamic Host Volume][], with the fields
|
|
converted to the Sentinel convention. Here are some examples:
|
|
|
|
| Dynamic Host Volume Field | Sentinel Accessor |
|
|
|----------------------------------------------|------------------------------------------------|
|
|
| `volume.Name` | `volume.name` |
|
|
| `volume.RequestedCapabilities[0].AccessMode` | `volume.requested_capabilities[0].access_mode` |
|
|
|
|
## Sentinel CSI Volume Objects
|
|
|
|
The `volume` object maps to the [CSI Volume][], with the fields
|
|
converted to the Sentinel convention. Here are some examples:
|
|
|
|
| CSI Volume Field | Sentinel Accessor |
|
|
|----------------------------------------------|------------------------------------------------|
|
|
| `volume.Name` | `volume.name` |
|
|
| `volume.RequestedCapabilities[0].AccessMode` | `volume.requested_capabilities[0].access_mode` |
|
|
|
|
Note that the `volume.Secrets` values and `volume.MountOptions.MountFlags` are always redacted to prevent credential leaks.
|
|
|
|
|
|
[Nomad Sentinel Tutorial]: /nomad/docs/govern/sentinel
|
|
[`nomad sentinel`]: /nomad/commands/sentinel
|
|
[sentinel]: https://docs.hashicorp.com/sentinel
|
|
[JSON job specification]: /nomad/api-docs/json-jobs
|
|
[ACL token]: https://github.com/hashicorp/nomad/blob/v1.9.4/nomad/structs/structs.go#L13502-L13531
|
|
[Namespace]: https://github.com/hashicorp/nomad/blob/v1.9.4/nomad/structs/structs.go#L5578-L5610
|
|
[Node]: https://github.com/hashicorp/nomad/blob/v1.9.4/nomad/structs/structs.go#L2086-L2210
|
|
[Node Pool]: https://github.com/hashicorp/nomad/blob/v1.9.4/nomad/structs/node_pool.go#L46-L68
|
|
[Dynamic Host Volume]: https://github.com/hashicorp/nomad/blob/main/nomad/structs/host_volumes.go#L18-L87
|
|
[CSI Volume]: https://github.com/hashicorp/nomad/blob/main/nomad/structs/csi.go#L249-L312
|