[docs] ACL Side Navigation Added (#5526)

* Adding new ACL menu item with guides and documentation.

* removing sidebar stuff from under agent, some documenting
This commit is contained in:
kaitlincarter-hc 2019-03-25 16:20:40 -05:00 committed by GitHub
parent 89cd3a3a3e
commit 114b42b448
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 1420 additions and 102 deletions

File diff suppressed because it is too large Load Diff

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "ACL Token Migration"
sidebar_current: "docs-guides-acl-migrate-tokens"
sidebar_current: "docs-acl-migrate-tokens"
description: |-
Consul 1.4.0 introduces a new ACL system with improvements for the security and
management of ACL tokens and policies. This guide documents how to upgrade
@ -19,75 +19,20 @@ necessary to manually translate old tokens into new ones to take advantage of
the new ACL system features. Tooling is provided to help automate this and this
guide describes the overall process.
~> **Note:** **1.4.0 retains full support for "legacy" ACL tokens** so upgrades
~> **Note**: Before starting the token migration process all Consul agents, servers
and clients, must be running at least version 1.4.0. Additionally, you
must ensure the cluster is in a healthy state including a functioning leader. Once
the leader has determined that all servers in the cluster are capable of using the
new ACL system, the leader will transition itself. Then, the other servers will
transition themselves to the new system, followed by the client agents. You can
use `consul info` to investigate the cluster health.
Consul 1.4.0 retains full support for "legacy" ACL tokens so upgrades
from Consul 1.3.0 are safe. Existing tokens will continue to work in the same
way for at least two "major" releases (1.5.x, 1.6.x, etc; note HashiCorp does
not use SemVer for our products).
This document will briefly describe [what changed](#what-changed), and then walk
through the [high-level migration process options](#migration-process), finally
giving some [specific examples](#migration-examples) of migration strategies.
## New ACL System Differences
The [ACL guide](/docs/guides/acl.html) and [legacy ACL
guide](/docs/guides/acl-legacy.html) describes the new and old systems in
detail. Below is a summary of the changes that need to be considered when
migrating legacy tokens to the new system.
### Token and Policy Separation
You can use a single policy in the new system for all tokens that share access
rules. For example, all tokens created using the clone endpoint in the legacy
system can be represented with a single policy and a set of tokens that map to
that policy.
### Rule Syntax Changes
The most significant change is that rules with selectors _no longer prefix match
by default_. In the legacy system the following rules would grant access to
nodes, services and keys _prefixed_ with foo.
```
node "foo" { policy = "write" }
service "foo" { policy = "write" }
key "foo" { policy = "write" }
```
In the new system the same syntax will only perform _exact_ match on the whole
node name, service name or key.
In general, exact match is what most operators intended most of the time so the
same policy can be kept, however if you rely on prefix match behavior then using
the same syntax will break behavior.
Prefix matching can be expressed in the new ACL system explicitly, making the
following rules in the new system exactly the same as the rules above in the
old.
```
node_prefix "foo" { policy = "write" }
service_prefix "foo" { policy = "write" }
key_prefix "foo" { policy = "write" }
```
### API Separation
The "old" API endpoints below continue to work for backwards compatibility but
will continue to create or show only "legacy" tokens that can't take full
advantage of the new ACL system improvements. They are documented fully under
[Legacy Tokens](/api/acl/legacy.html).
- [`PUT /acl/create` - Create Legacy Token](/api/acl/legacy.html#create-acl-token)
- [`PUT /acl/update` - Update Legacy Token](/api/acl/legacy.html#update-acl-token)
- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api/acl/legacy.html#delete-acl-token)
- [`GET /acl/info/:uuid` - Read Legacy Token](/api/acl/legacy.html#read-acl-token)
- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api/acl/legacy.html#clone-acl-token)
- [`GET /acl/list` - List Legacy Tokens](/api/acl/legacy.html#list-acls)
The new ACL system includes new API endpoints to manage
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html)
and [Policies](/api/acl/policies.html).
This document will briefly describes the [high-level migration process](#migration-process) and provides some [specific examples](#migration-examples) of migration strategies.
## Migration Process

View File

@ -1,18 +1,18 @@
---
layout: "docs"
page_title: "ACL Rules"
sidebar_current: "docs-agent-acl-rules"
sidebar_current: "docs-acl-rules"
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
---
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/guides/acl-legacy.html)
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html)
# ACL Rules
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. To learn more about Consul's ACL review the
[ACL system documentation](/docs/agent/acl-system.html)
[ACL system documentation](/docs/acl/acl-system.html)
A core part of the ACL system is the rule language, which is used to describe the policy
that must be enforced. There are two types of rules: prefix based rules and exact matching
@ -142,7 +142,7 @@ On success, the Policy is returned:
```
The created policy can now be specified either by name or by ID when
[creating a token](/docs/guides/acl.html#step-4-create-an-agent-token). This will grant the rules
[creating a token](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide#step-4-create-an-agent-token). This will grant the rules
provided to the [bearer of that token](https://www.consul.io/api/index.html#authentication).
Below is a breakdown of each rule type.
@ -158,7 +158,7 @@ ACL rules look like this:
acl = "write"
```
There is only one acl rule allowed per policy and its value is set to one of the [policy dispositions](https://www.consul.io/docs/guides/acl.html#rule-specification). In the example
There is only one acl rule allowed per policy and its value is set to one of the [policy dispositions](docs/acl/acl-rules.html#rule-specification). In the example
above ACLs may be read or written including discovering any token's secret ID. Snapshotting also requires `acl = "write"`
permissions due to the fact that all the token secrets are contained within the snapshot.

View File

@ -1,12 +1,12 @@
---
layout: "docs"
page_title: "ACL System"
sidebar_current: "docs-agent-acl-system"
sidebar_current: "docs-acl-system"
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
---
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/guides/acl-legacy.html)
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html)
# ACL System
@ -37,7 +37,7 @@ An ACL policy is a named set of rules and is composed of the following elements:
* **ID** - The policies auto-generated public identifier.
* **Name** - A unique meaningful name for the policy.
* **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/agent/acl-rules.html#rule-specification) documentation for more details.
* **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details.
* **Datacenters** - A list of datacenters the policy is valid within.
#### Builtin Policies
@ -125,7 +125,7 @@ Consul datacenters, and does not allow modification of any state.
3. The [connect CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul.
Constructing rules from these policies is covered in detail on the
[ACL Rules](/docs/agent/acl-rules.html) page.
[ACL Rules](/docs/acl/acl-rules.html) page.
## Configuring ACLs
@ -191,5 +191,5 @@ The `service_prefix` policy needs read access for any services that can be regis
## Next Steps
Setup ACLs with the [Boostrapping guide](/docs/guides/acl.html) or continue reading about
[ACL rules](/docs/agent/acl-rules.html).
Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) or continue reading about
[ACL rules](/docs/acl/acl-rules.html).

View File

@ -0,0 +1,53 @@
---
layout: "docs"
page_title: "ACL Guides"
sidebar_current: "docs-acl-index"
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. Select the following guide for your use case.
---
# ACL Documentation and Guides
Consul uses Access Control Lists (ACLs) to secure the UI, API, CLI, service communications, and agent communications. At the core, ACLs operate by grouping rules into policies, then associating one or more policies with a token.
The following documentation and guides will help you understand and implement
ACLs.
## ACL Documentation
### ACL System
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. The [ACL System documentation](/docs/acl/acl-system.html) details the functionality of Consul ACLs.
### ACL Rules
A core part of the ACL system is the rule language, which is used to describe the policy that must be enforced. Read the ACL rules [documentation](/docs/acl/acl-rules.html)
to learn about rule specifications.
### ACL Legacy System
The ACL system in Consul 1.3.1 and older is now called legacy. For information on bootstrapping the legacy system, ACL rules, and a general ACL system overview, read the legacy [documentation](/docs/acl/acl-legacy.html).
### ACL Migration
[The migration documentation](/docs/acl/acl-migrate-tokens.html) details how to upgrade
existing legacy tokens after upgrading to 1.4.0. It will briefly describe what changed, and then walk through the high-level migration process options, finally giving some specific examples of migration strategies. The new ACL system has improvements for the security and management of ACL tokens and policies.
## ACL Guides on Learn
We have several guides for setting up and configuring Consul's ACL system. They include how to bootstrap the ACL system in Consul version 1.4.0 and newer. Please select one of the following guides to get started.
~> Note: the following are located on HashiCorp Learn. By selecting
one of the guides, you will be directed to a new site.
### Bootstrapping the ACL System
Learn how to control access to Consul resources with this step-by-step [guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) on bootstrapping the ACL system in Consul 1.4.0 and newer. This guide also includes additional steps for configuring the anonymous token, setting up agent-specific default tokens, and creating tokens for Consul UI use.
### Securing Consul with ACLs
The _Bootstrapping the ACL System_ guide walks you through how to set up ACLs on a single datacenter. Because it introduces the basic concepts and syntax we recommend completing it before starting the [Securing Consul with ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls) which has recommendations for production workloads on a single datacenter.

View File

@ -6,24 +6,48 @@ description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. Select the following guide for your use case.
---
# ACL Guides
# ACL Documentation and Guides
We have several guides for setting up and configuring Consul's ACL system. They include how to bootstrap the ACL system in Consul version 1.4.0 and newer, how to bootstrap the ACL system in older versions of Consul, and how to migrate tokens from the legacy system to the new system in Consul 1.4.0.
Consul uses Access Control Lists (ACLs) to secure the UI, API, CLI, service communications, and agent communications. At the core, ACLs operate by grouping rules into policies, then associating one or more policies with a token.
Please select one of the following guides to get started.
The following documentation and guides will help you understand and implement
ACLs.
## Bootstrapping Guide
## ACL Documentation
### ACL System
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. The [ACL System documentation] details the functionality of Consul ACLs.
### ACL Rules
A core part of the ACL system is the rule language, which is used to describe the policy that must be enforced. The [ACL Rules documentation] is useful
when creating rule specifications.
### ACL Legacy System
The ACL system in Consul 1.3.1 and older is now called legacy. For information on bootstrapping the legacy system, ACL rules, and a general ACL system overview, read the legacy [documentation](/docs/acl/acl-legacy.html).
### ACL Migration
[The migration documentation](/docs/acl/acl-migrate-tokens.html) details how to upgrade
existing legacy tokens after upgrading to 1.4.0. It will briefly describe what changed, and then walk through the high-level migration process options, finally giving some specific examples of migration strategies. The new ACL system has improvements for the security and management of ACL tokens and policies.
## ACL Guides
We have several guides for setting up and configuring Consul's ACL system. They include how to bootstrap the ACL system in Consul version 1.4.0 and newer. Please select one of the following guides to get started.
~> Note: the following are located on HashiCorp Learn. By selecting
one of the guides, you will be directed to a new site.
### Bootstrapping the ACL System
Learn how to control access to Consul resources with this step-by-step [guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) on bootstrapping the ACL system in Consul 1.4.0 and newer. This guide also includes additional steps for configuring the anonymous token, setting up agent-specific default tokens, and creating tokens for Consul UI use.
## Legacy ACL System
### Securing Consul with ACLs
The _Bootstrapping the ACL System_ guide walks you through how to set up ACLs on a single datacenter. Because it introduces the basic concepts and syntax we recommend completing it before starting this guide. This guide builds on the first guide with recommendations for production workloads on a single datacenter.
The ACL system in Consul 1.3.1 and older is now called legacy. For information on bootstrapping the legacy system, ACL rules, and a general ACL system overview, read the legacy [guide](/docs/guides/acl-legacy.html).
## Migrating Tokens
[This guide](/docs/guides/acl-migrate-tokens.html) documents how to upgrade
existing legacy tokens after upgrading to 1.4.0. It will briefly describe what changed, and then walk through the high-level migration process options, finally giving some specific examples of migration strategies. The new ACL system has improvements for the security and management of ACL tokens and policies.

View File

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "ACL System (Legacy)"
sidebar_current: "docs-guides-acl-legacy"
sidebar_current: "docs-acl-legacy"
description: |-
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
---
@ -13,9 +13,70 @@ description: |-
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
the ACL system was rewritten and the legacy system was deprecated. The new ACL guide
can be found [here](/docs/guides/acl.html).
can be found [here](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide).
# ACL System
# New ACL System Differences
The [ACL guide](/docs/guides/acl.html) and [legacy ACL
guide](/docs/guides/acl-legacy.html) describes the new and old systems in
detail. Below is a summary of the changes that need to be considered when
migrating legacy tokens to the new system.
## Token and Policy Separation
You can use a single policy in the new system for all tokens that share access
rules. For example, all tokens created using the clone endpoint in the legacy
system can be represented with a single policy and a set of tokens that map to
that policy.
## Rule Syntax Changes
The most significant change is that rules with selectors _no longer prefix match
by default_. In the legacy system the following rules would grant access to
nodes, services and keys _prefixed_ with foo.
```
node "foo" { policy = "write" }
service "foo" { policy = "write" }
key "foo" { policy = "write" }
```
In the new system the same syntax will only perform _exact_ match on the whole
node name, service name or key.
In general, exact match is what most operators intended most of the time so the
same policy can be kept, however if you rely on prefix match behavior then using
the same syntax will break behavior.
Prefix matching can be expressed in the new ACL system explicitly, making the
following rules in the new system exactly the same as the rules above in the
old.
```
node_prefix "foo" { policy = "write" }
service_prefix "foo" { policy = "write" }
key_prefix "foo" { policy = "write" }
```
## API Separation
The "old" API endpoints below continue to work for backwards compatibility but
will continue to create or show only "legacy" tokens that can't take full
advantage of the new ACL system improvements. They are documented fully under
[Legacy Tokens](/api/acl/legacy.html).
- [`PUT /acl/create` - Create Legacy Token](/api/acl/legacy.html#create-acl-token)
- [`PUT /acl/update` - Update Legacy Token](/api/acl/legacy.html#update-acl-token)
- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api/acl/legacy.html#delete-acl-token)
- [`GET /acl/info/:uuid` - Read Legacy Token](/api/acl/legacy.html#read-acl-token)
- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api/acl/legacy.html#clone-acl-token)
- [`GET /acl/list` - List Legacy Tokens](/api/acl/legacy.html#list-acls)
The new ACL system includes new API endpoints to manage
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html)
and [Policies](/api/acl/policies.html).
# Legacy ACL System
Consul provides an optional Access Control List (ACL) system which can be used to control
access to data and APIs. The ACL is

View File

@ -14,8 +14,6 @@ guidance to do them safely.
The following guides are available:
* [ACLs](/docs/guides/acl-index.html) - This set of guides covers Consul's Access Control List (ACL) capability, which can be used to control access to Consul resources.
* [Adding/Removing Servers](https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/servers) - This guide covers how to safely add and remove Consul servers from the cluster. This should be done carefully to avoid availability outages.
* [Agent Communication Encryption](https://learn.hashicorp.com/consul/advanced/day-1-operations/agent-encryption) - This guide covers how to encrypt both gossip and RPC communication.

View File

@ -279,12 +279,6 @@
<li<%= sidebar_current("docs-agent-running") %>>
<a href="/docs/agent/basics.html">Running and Stopping</a>
</li>
<li<%= sidebar_current("docs-agent-acl-system") %>>
<a href="/docs/agent/acl-system.html">ACL System</a>
</li>
<li<%= sidebar_current("docs-agent-acl-rules") %>>
<a href="/docs/agent/acl-rules.html">ACL Rules</a>
</li>
<li<%= sidebar_current("docs-agent-dns") %>>
<a href="/docs/agent/dns.html">DNS Interface</a>
</li>
@ -318,6 +312,24 @@
</ul>
</li>
<li<%= sidebar_current("docs-acl") %>>
<a href="/docs/acl/index.html">Access Control (ACLs)</a>
<ul class="nav">
<li<%= sidebar_current("docs-acl-system") %>>
<a href="/docs/acl/acl-system.html">ACL System</a>
</li>
<li<%= sidebar_current("docs-acl-rules") %>>
<a href="/docs/acl/acl-rules.html">ACL Rules</a>
</li>
<li<%= sidebar_current("docs-acl-legacy") %>>
<a href="/docs/acl/acl-legacy.html">Legacy ACLs</a>
</li>
<li<%= sidebar_current("docs-acl-migration") %>>
<a href="/docs/acl/acl-migrate-tokens.html">Token Migration</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-connect") %>>
<a href="/docs/connect/index.html">Connect</a>
<ul class="nav">
@ -408,9 +420,6 @@
<li<%= sidebar_current("docs-guides") %>>
<a href="/docs/guides/index.html">Guides</a>
<ul class="nav">
<li<%= sidebar_current("docs-guides-acl") %>>
<a href="/docs/guides/acl-index.html">ACL Guides</a>
</li>
<li<%= sidebar_current("docs-guides-servers") %>>
<a href="https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/servers">Adding & Removing Servers</a>
</li>