From 7ca8b3ad8bbe4d8d9ba152c1da1e49751bc54058 Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Tue, 19 Sep 2017 09:02:53 -0500 Subject: [PATCH] Adds documentation for Sentinel integration in Consul Enterprise. --- website/source/docs/enterprise/index.html.md | 1 + .../sentinel/index.html.markdown.erb | 18 +++ website/source/docs/guides/acl.html.md | 34 +++++ website/source/docs/guides/index.html.md | 2 + .../docs/guides/sentinel.html.markdown.erb | 118 ++++++++++++++++++ website/source/layouts/docs.erb | 6 + 6 files changed, 179 insertions(+) create mode 100644 website/source/docs/enterprise/sentinel/index.html.markdown.erb create mode 100644 website/source/docs/guides/sentinel.html.markdown.erb diff --git a/website/source/docs/enterprise/index.html.md b/website/source/docs/enterprise/index.html.md index 63d9db93f5..f61453a51e 100644 --- a/website/source/docs/enterprise/index.html.md +++ b/website/source/docs/enterprise/index.html.md @@ -19,6 +19,7 @@ increases both scalability and resilience. Features include: - [Advanced Federation for Complex Network Topologies](/docs/enterprise/federation/index.html) - [Network Segments](/docs/enterprise/network-segments/index.html) +- [Sentinel](/docs/enterprise/sentinel/index.html) These features are part of [Consul Enterprise](https://www.hashicorp.com/consul.html). diff --git a/website/source/docs/enterprise/sentinel/index.html.markdown.erb b/website/source/docs/enterprise/sentinel/index.html.markdown.erb new file mode 100644 index 0000000000..ef092406bd --- /dev/null +++ b/website/source/docs/enterprise/sentinel/index.html.markdown.erb @@ -0,0 +1,18 @@ +--- +layout: "docs" +page_title: "Sentinel in Consul" +sidebar_current: "docs-enterprise-sentinel" +description: |- + Consul Enterprise uses Sentinel to augment the built-in ACL system to provide advanced policy enforcement. Sentinel policies can currently execute on KV modify and service registration. +--- + +# Sentinel in Consul +Sentinel policies extend the ACL system in Consul beyond static "read", "write", +and "deny" policies to support full conditional logic and integration with +external systems. [Learn more about Sentinel here.](https://docs.hashicorp.com/sentinel/concepts/). + +To get started with Sentinel in Consul, +[read the documentation](https://docs.hashicorp.com/sentinel/app/consul/) or +[start the guide](/docs/guides/sentinel.html). + + diff --git a/website/source/docs/guides/acl.html.md b/website/source/docs/guides/acl.html.md index 60a4a7dd86..4d4f0e9388 100644 --- a/website/source/docs/guides/acl.html.md +++ b/website/source/docs/guides/acl.html.md @@ -671,6 +671,23 @@ the example above, the rules allow read-only access to any key name with the emp read-write access to any key name that starts with "foo", and deny all access to any key name that starts with "bar". +Consul Enterprise supports additional optional fields for key write policies for +[Sentinel](https://docs.hashicorp.com/sentinel/app/consul/) integration. An example key rule with a +Sentinel code policy looks like this: + +```text +key "foo" { + policy = "write" + sentinel { + code = " import \"strings\" + main = rule { strings.has_suffix(value, \"bar\") } " + enforcementlevel = "hard-mandatory" + } +} +``` + +For more detailed documentation, see the [Consul Sentinel Guide](/docs/guides/sentinel.html). + #### Keyring Rules The `keyring` policy controls access to keyring operations in the @@ -929,6 +946,23 @@ In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured wit [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) set to `true` in order to enable script checks. +Consul Enterprise supports additional optional fields for key write policies for +[Sentinel](https://docs.hashicorp.com/sentinel/app/consul/) integration. An example service +rule with a Sentinel code policy looks like this: + +```text +service "foo" { + policy = "write" + sentinel { + code = " import \"strings\" + main = rule { strings.has_suffix(service, \"Service\") } " + enforcementlevel = "hard-mandatory" + } +} +``` + +For more detailed documentation, see the [Consul Sentinel Guide](/docs/guides/sentinel.html). + #### Session Rules The `session` policy controls access to [Session API](/api/session.html) operations. diff --git a/website/source/docs/guides/index.html.md b/website/source/docs/guides/index.html.md index 2c88a20424..b7f27660df 100644 --- a/website/source/docs/guides/index.html.md +++ b/website/source/docs/guides/index.html.md @@ -42,4 +42,6 @@ The following guides are available: * [Semaphore](/docs/guides/semaphore.html) - This guide covers using the KV store to implement a semaphore. +* [Sentinel](/docs/guides/sentinel.html) - This guide covers using Sentinel for policy enforcement in Consul. + * [Server Performance](/docs/guides/performance.html) - This guide covers minumum requirements for Consul servers as well as guidelines for running Consul servers in production. diff --git a/website/source/docs/guides/sentinel.html.markdown.erb b/website/source/docs/guides/sentinel.html.markdown.erb new file mode 100644 index 0000000000..5f9dab3fe3 --- /dev/null +++ b/website/source/docs/guides/sentinel.html.markdown.erb @@ -0,0 +1,118 @@ +--- +layout: "docs" +page_title: "Sentinel in Consul" +sidebar_current: "docs-guides-sentinel" +description: |- + Consul Enterprise uses Sentinel to augment the built-in ACL system to provide advanced policy enforcement. Sentinel policies can currently execute on KV modify and service registration. +--- + +# Sentinel Overview +[//]: # ( ~> The Sentinel functionality described here is available only in ) +[//]: # ( [Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.0.0 and later. ) + +<%= enterprise_alert :consul %> + + Consul 1.0 adds integration with [Sentinel](https://hashicorp.com/sentinel) for policy enforcement. + Sentinel policies help extend the ACL system in Consul beyond the static "read", "write", and "deny" + policies to support full conditional logic, and integration with external systems. + +## Sentinel in Consul + +Sentinel policies are applied during writes to the KV Store and the service catalog in Consul. +ACL policy definitions take a `sentinel` field specifying the code and the enforcement level. + +Here's an example: + + +```text + sentinel { + code = "main = rule { port > 1024 and port < 32768 }" + enforcementlevel = "soft-mandatory" + } +``` + +This policy ensures that all services written to the Catalog must have a port number between 1024 and 32768. +If the `enforcementlevel` property is not set, it defaults to "hard-mandatory". + +## Imports + +Consul imports all the [standard imports](https://docs.hashicorp.com/sentinel/imports/) +from Sentinel. All functions in these imports are available to be used in policies. + +## Injected Variables + +Consul passes some context as variables into Sentinel, which are available to use inside any policies you write. + +#### Variables injected during KV store writes + +| Variable Name | Type | Description | +| ------------- | -------- | ----------- | +| `key` | `string` | Key being written | +| `value` | `string` | Value being written | +| `flags` | `uint64` | [Flags](/api/kv.html#flags) | + + +#### Variables injected during service registration + +| Variable Name | Type | Description | +| -------------- |-------------------- | ----------- | +| `node_id` | `string` | ID of the agent registering the service | +| `node` | `string` | Name of the agent registering the service | +| `address` | `string` | Service address | +| `port` | `int` | Service port | +| `service_id` | `string` | Service ID | +| `service` | `string` | Service name | +| `node_meta` | `map[string]string` | Node metadata map | +| `tags` | `list` | Service tags | + + +## Examples +The following are some examples of ACL policies with Sentinel rules. + +### All services must register with a valid IPv6 address. + +```text +service "" { + policy = "write" + sentinel { + import \"sockaddr\" + code = "main = rule { sockaddr.is_ipv6(address) }" + enforcementlevel = "soft-mandatory" + } +} +``` +### Service names must end with "Service" + +```text +service "" { + policy = "write" + sentinel { + import \"strings\" + code = "main = rule { strings.has_suffix(service,\"Service\") }" + enforcementlevel = "soft-mandatory" + } +} +``` + +### The service "db" must be registered with either a "Leader" or a "Follower" tag + +```text +service "db" { +policy = "write" +sentinel { + main = rule { tags contains \"Leader\" or tags contains \"Follower\" } + } +} +``` + +### The key "foo" can only be updated during business hours. + +```text +keys "foo" { +policy = "write" +sentinel { + import "time" + main = rule { time.hour > 8 and time.hour < 17 } + } +} +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index e43514b532..39aaf8ac56 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -254,6 +254,9 @@ > Network Segments + > + Sentinel + > Outage Recovery @@ -293,6 +296,9 @@ > Network Segments + > + Sentinel +