Merge pull request #11325 from hashicorp/docs/admin-partitions-concept-v1.11.0

Docs/admin partitions concept v1.11.0 beta1
This commit is contained in:
trujillo-adam 2021-10-20 11:33:41 -07:00 committed by GitHub
commit 53295c8f58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 706 additions and 21798 deletions

View File

@ -0,0 +1,247 @@
---
layout: commands
page_title: 'Commands: Admin-partition'
description: |
The admin-partition command enables you create and manage Consul Enterprise admin partitions.
---
# Consul Admin Partition
Command: `consul admin-partition`
<EnterpriseAlert />
The `admin-partition` command enables you to create and manage Consul Enterprise administrative or admin partitions. Admin partitions are boundaries that allow multiple namespaces with the same name to exist independently of each other. This features is currently in beta.
If ACLs are enabled then a token with operator privileges may be required in order to use this command.
You should only run the `admin-partition` command in the primary datacenter.
## Usage
```shell-session
consul admin-partition <SUBCOMMAND> <OPTIONS>
```
Issue the `consul admin-partition -h` command to view the subcommands.
```shell-session
Usage: consul admin-partition <subcommand> [options] [args]
This command has subcommands for interacting with Consul Enterprise
admin partitions. Here are some simple examples. More detailed
examples are available in the subcommands or the documentation.
Create an admin partition
$ consul admin-partition create -name team1
Create or Update an admin partition from its full definition:
$ consul admin-partition write part1
Read an admin partition:
$ consul admin-partition read team1
List all admin partitions:
$ consul admin-partition list
Update an admin partition
$ consul admin-partition update -name team1 -description "first admin-partition"
Delete an admin partition:
$ consul admin-partition delete team1
For more examples, ask for subcommand help or view the documentation.
```
## Subcommands
You can issue the folloing subcommands with the `consul admin-partition` command.
### `create`
The `create` subcommand sends a request to the server to create a new admin partition.
```shell-session
consul admin-partition create <OPTIONS>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-name` | String value that specifies the name for the new partition. | none | Required |
| `-description` &nbsp; &nbsp; &nbsp; &nbsp; | String value that specifies a description of the new partition. | none | Optional |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, a partition named `webdev` is created:
```shell-session
consul admin-partition create -name "webdev" -description "Partition for admin of webdev services" -format json -show-meta
{
"Name": "webdev",
"Description": "Partition for admin of webdev services",
"CreateIndex": 940,
"ModifyIndex": 940
}
```
### `write`
The `write` subcommand sends a request to the server to create a new admin partition or update an existing partition from its full definition. You can specify an admin partition definition file or use values from `stdin`.
Use the following syntax to write from file:
```shell-session
consul admin-partition write <OPTIONS> <FILE>
```
Use the following syntax to write from `stdin`:
```shell-session
consul admin-partition write <OPTIONS> -
```
The definition file or `stdin` values can be provided in JSON or HCL format. Refer to the [Admin Partition Definition](#admin-partition-definition) section for details about the supported parameters.
You can specify the following options:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` &nbsp; &nbsp; | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, the `webdev-bu` partition is written using `stdin` values:
```shell-session
consul admin-partition write -format json -show-meta - <<< 'name = "webdev-bu" description = "backup webdev partition"'
{
"Name": "webdev-bu",
"Description": "backup webdev partition",
"CreateIndex": 1462,
"ModifyIndex": 1462
}
```
### `read`
The `read` subcommand sends a request to the server to read the configuration for the specified partition and print it to the console.
```shell-session
consul admin-partition read <OPTIONS> <PARTITION_NAME>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` &nbsp; &nbsp; | Specifies how to format the output of the operation in the console. | none | Optional |
| `-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, the configuration for the `webdev` partition is read:
```shell-session
consul admin-partition read -format json -meta webdev
{
"Name": "webdev",
"CreateIndex": 940,
"ModifyIndex": 1458
}
```
### `list`
The `list` subcommand prints existing admin partitions to the console.
```shell-session
consul admin-partition list <OPTIONS>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
The following example lists the admin partitions and their meta data in JSON format:
```shell-session
consul admin-partition list -format json -show-meta
[
{
"Name": "default",
"Description": "Builtin Default Partition",
"CreateIndex": 4,
"ModifyIndex": 4
},
{
"Name": "webdev",
"CreateIndex": 940,
"ModifyIndex": 1458
},
{
"Name": "webdev-bu",
"Description": "backup webdev partition",
"CreateIndex": 1462,
"ModifyIndex": 1462
}
]
```
### `delete`
The `delete` subcommand sends a request to the server to remove the specified partition.
```shell-session
consul admin-partition delete PARTITION_NAME>
```
In the following example, the `webdev-bu` partition is deleted:
```shell-session
consul admin-partition delete webdev
```
## Admin Partition Definition
Admin partitions are managed exclusively through the HTTP API and the Consul CLI. The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
The following parameters are supported in admin partition defintion files:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `Name` | String value that specifies the name of partiion you are creating or writing. <br/> The value must be valid DNS hostname value. | none | Required |
| `Description` | String value that specifies a description for the partition you are creating or writing. <br/> The value should provide human-readable information to help other users understand the purpose of the partition. | none | Optional |
### Example Definition File
The following example shows an admin partition definition file that could be used with the [`write`](#write) command to create a partition:
```hcl
Name = "dev-partition"
Description = "Partition for dev team"
```
## HTTP API Options
You can include the following options to interact with the HTTP API when using the `admin-partition` command.
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-ca-file` | Specifies the path to a certificate authority (CA) file when TLS is enabled.<br/> You can also specify `CONSUL_CACERT` as the value if the environment variable is configured. | none | Required if TLS is enabled |
| `-ca-path` | Specifies the path to a client certificate file when TLS is enabled. <br/> You can also specify `CONSUL_CAPATH` as the value if the environment variable is configured. | none | Required if TLS is enabled |
| `-client-cert` | Specifies the path to a client certificate file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_CERT` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
| `-client-key` | Specifies the path to a client key file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_KEY` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
| `-datacenter` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Specifies the name of the datacenter to query. | Datacenter of the queried agent | Optional |
| `-http-addr` | Specifies the address and port number of the Consul HTTP agent. <br/>IP and DNS addresses are supported. The address must also include the port. <br/>You can also specify `CONSUL_HTTP_ADDR` if the environment variable is configured. <br/>To use an HTTPS address, set the `CONSUL_HTTP_SSL` environment variable to `true`. | `http://127.0.0.1:8500` | Optional |
| `-stale` | Boolean value that enables any Consul server (non-leader) to respond to the request. <br/>This switch can lower latency and increase throughput, but may result in stale data. This option has no effect on non-read operations. | `false` | Optional |

View File

@ -0,0 +1,236 @@
---
layout: docs
page_title: Consul Enterprise Admin Partitions
description: Consul Enterprise enables you to create paritions that can be administrated across namespaces.
---
# Consul Enterprise Admin Partitions
<EnterpriseAlert>
This feature requires{' '}
<a href="https://www.hashicorp.com/products/consul/">Consul Enterprise</a>{' '}
with the Governance and Policy module.
</EnterpriseAlert>
This topic provides and overview of admin partitions, which are entities that define one or more administrative boundaries for single Consul deployments.
## Introduction
Admin partitions exist a level above namespaces in the identity hierarchy. They contain one or more namespaces and allow multiple independent tenants to share a Consul server cluster. As a result, admin partitions enable you to define administrative and communication boundaries between services managed by separate teams or belonging to separate stakeholders. They can also segment production and non-production services within the Consul deployment.
-> **Preexisting resource nodes and namespaces**: Admin partitions were introduced in Consul 1.11. Resource nodes were not namespaced prior to 1.11. After upgrading to Consul 1.11 or later, all resource nodes will be namespaced.
### Default Admin Partition
Each Consul cluster will have at least one default admin partition (named `default`). Any resource created without specifying an admin partition will inherit the partition of the ACL token.
The `default` admin partition is special in that it may contain namespaces and other entities that are replicated between datacenters.
-> **Preexisting resources and the `default` partition**: Admin partitions were introduced in Consul 1.11. After upgrading to Consul 1.11 or later, the `default` partition will contain all resources created in previous versions.
### Naming Admin Partitions
Only characters that are valid in DNS names can be used to name admin partitions.
Names must also start with a letter.
### Namespaces
When an admin partition is created, it will include a `default` namespace. You can create additional namespaces within the partition.
All namespaces must exist within an admin partition. By extension, the partition will also contain all namespaced resources.
Within a single datacenter, a namespace in one admin partition is logically separate from any other namespace with the same name in other admin partitions.
### Cross-datacenter Replication
Only resources in the default admin partition will be replicated to secondary datacenters.
### DNS Queries
Client agents will be configured to operate within a specific admin partition. The DNS interface will only return results for the admin partition within the scope of the client.
### Service Mesh Configurations
Values specified for [`proxy-defaults`](docs/connect/config-entries/proxy-defaults) configurations are scoped to a specific partition. Services registered in the partition will use the partition's `proxy-defaults` values.
## Requirements
Your Consul configuration must meet the following requirements to use admin partitions.
### Versions
* Consul 1.11.0 and newer
### Security Configurations
* The agent token used by the client agent will need to allow `node:write` in the admin partition.
* The `write` permission for `proxy-defaults` requires `mesh:write`. See [Admin Partition Rules](/docs/security/acl/acl-rules#admin-partition-rules) for additional information.
* The `write` permissions for ingress and terminating gateways require `mesh:write` privileges.
* Wildcards (`*`) are not supported when creating intentions for admin partitions, but you can use a wildcard to specify services within a partition.
### Agent Configurations
* In client agent configurations, the admin partition name should be specified in the agent configuration:
```hcl
partition = "<NAME>"
```
* The anti-entropy sync will use the configured admin partition name when registering the node.
### Kubernetes Requirements
One of the primary use cases for admin partitions is for enabling a service mesh on Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes:
* Two or more Kubernetes clusters with Consul servers installed on one of them. The other clusters should run Consul clients.
* A Consul Enterprise license must be installed on each instance of Consul.
* The helm chart consul-k8s v0.34.1 or greater.
* Consul 1.11.0-ent-alpha or greater.
* All instances in the VPC must be able to communicate with each other.
* Pods must be able to communicate with each other (flat pod and node network). See [step 3](#firewall-rules) in the Deploying Consul with Admin Partitions on Kubernetes section for additional information
## Usage
This section describes how to deploy Consul admin partitions to Kubernetes clusters, as well as directs you to the CLI reference for interacting with the admin partitions API on the command line.
### Deploying Consul with Admin Partitions on Kubernetes
The expected use case to create admin partitions on Kubernetes clusters. This is because many organizations prefer to use cloud-managed Kubernetes offerings to provision separate Kubernetes clusters for individual teams, business units, or environments. This is opposed to deploying a single, large Kubernetes cluster. When these organizations attempt to use a service mesh to enable cross-cluster activities, such as administration tasks and communication between nodes, they encounter problems.
The following procedure will result in different admin partitions in each Kubernetes cluster. The Consul clients running in the cluster with servers will be in the `default` partition. Another partition called `clients` will also be created.
Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernetes-requirements) before proceeding.
1. <a id="firewall-rules"/> Update the firewall rules to ensure the pod network is flat. The following example for Google Kubernetes Engine (GKE) describes how to create a firewall rule that allows all pod and node network traffic to talk to the server and workload nodegroups:
1. Open the **VPC Network > Firewall** section and identify the rules associated with your clusters. The cluster name is a part of the rule.
![IP address ranges for GKE clusters](/img/admin-partitions/consul-admin-partitions-gke-cluster-1.png)
![IP address ranges for GKE clusters](/img/admin-partitions/consul-admin-partitions-gke-cluster-2.png)
The `gke-cluster-1-7b43116f-node` and `gke-cluster-2-48d3bee6-node` labels are the node names for the GKE clusters.
The `10.128.0.0/9` IP range represents the node IP network. The IP range of the node VMs in the clusters are within this range.
The `10.44.0.0/14` and `10.4.0.0/14` IP ranges are the pod IP ranges for the GKE clusters.
1. Enter the `gke-cluster-1-7b43116f-node` and `gke-cluster-2-48d3bee6-node` node names in the target fields of the firewall rule.
1. Enter the `10.128.0.0/9`, `10.44.0.0/14`, and `10.4.0.0/14` IP into the source fields. This will ensure that traffic from the nodes and the pods in each cluster can access the nodes and pods in the other.
![Configured GKE cluster firewall rule for Consul admin partitions](/img/admin-partitions/consul-admin-partitions-gke-firewall-rule.png)
1. Create the license secret in each cluster, e.g.:
```shell-session
kubectl create secret generic license --from-file=key=[license file path i.e. ./license.hclic]
```
This step must also be completed for each workload cluster.
1. Create a server configuration file to override the default Consul Helm chart settings:
```yaml
global:
enableConsulNamespaces: true
tls:
enabled: true
image: hashicorp/consul-enterprise:1.11.0-ent-beta1
adminPartitions:
enabled: true
server:
exposeGossipAndRPCPorts: true
enterpriseLicense:
secretName: license
secretKey: key
connectInject:
enabled: true
transparentProxy:
defaultEnabled: false
consulNamespaces:
mirroringK8S: true
controller:
enabled: true
```
Note that the `transparentProxy` configuration is disabled. This is to enable multi-cluster networking.
1. Start the Consul server(s) using the custom configuration file:
```shell-session
helm install server hashicorp/consul -f server.yaml
```
1. After the server starts, get the external IP address for partition service so that it can be added to the client configuration. The partition service is a `LoadBalancer` type. The IP address is where clients that across your partitions will communicate with servers in this cluster.
```shell-session
kubectl get service
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 3m
servers-consul-connect-injector-svc ClusterIP 10.97.175.39 <none> 443/TCP 30s
servers-consul-controller-webhook ClusterIP 10.100.22.99 <none> 443/TCP 30s
servers-consul-dns ClusterIP 10.103.43.20 <none> 53/TCP,53/UDP 30s
servers-consul-partition-service LoadBalancer 10.111.255.152 35.192.119.38 8501:30643/TCP,8301:30466/TCP,8300:30657/TCP 30s
servers-consul-server ClusterIP None <none> 8501/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP 30s
servers-consul-ui ClusterIP 10.106.240.55 <none> 443/TCP 30s
1. Create the workload configuration for client nodes in your cluster. Create a configuration for each admin partition. In the following example, the external IP address from the previous step has been applied:
```yaml
global:
enabled: false
enableConsulNamespaces: true
image: hashicorp/consul-enterprise:1.11.0-ent-beta1
adminPartitions:
enabled: true
name: "clients" // partition name
tls:
enabled: true
caCert:
secretName: consul-consul-ca-cert
secretKey: tls.crt
caKey:
secretName: consul-consul-ca-key
secretKey: tls.key
server:
enterpriseLicense:
secretName: license
secretKey: key
externalServers:
enabled: true
hosts: "35.192.119.38" # Insert External IP of LoadBalancer here
tlsServerName: server.dc1.consul
client:
enabled: true
exposeGossipPorts: true
join: "35.192.119.38"
connectInject:
enabled: true
consulNamespaces:
mirroringK8S: true
controller:
enabled: true
```
1. Copy the server certificate to the workload cluster.
```shell-session
kubectl get secret server-consul-ca-cert --context server -o yaml | kubectl apply --context client -f -
```
1. Copy the server key to the workload cluster.
```shell-session
kubectl get secret consul-consul-ca-key --context server -o yaml | kubectl apply --context client -f -
```
1. Start the workload client clusters:
```shell-session
helm install client hashicorp/consul -f client.yaml
```
### CLI Usage
You can use create and manage admin partitions through the CLI. Refer to the [admin partition CLI documentation](/commands/admin-partition) for details.
## Known Limitations
* Gossip between nodes in different admin partitions must be constrained. You can accomplish this with through the use of [network segments](network-segments).
* Cross-partition communication is not currently supported.

View File

@ -611,3 +611,30 @@ only be done within the default namespace.
This means that rules and policies will be implicitly namespaced and do not need additional configuration.
The restrictions outlined above will apply to these rules and policies. Additionally, rules and policies within a
specific namespace are prevented from accessing resources in another namespace.
#### Admin Partition Rules <EnterpriseAlert inline />
The `admin_partition` and `admin_partition_prefix` rules set the scope to one or more admin partitions.
The `mesh` resource provides operator-level permissions for resources in the partition, such as ingress gateways or mesh proxy defaults.
You can include any number of namespace rules. In the following example, the agent has write access to the `ex-namespace` namespace, as well as namespaces prefixed with `ex-` in the `example` partition:
```hcl
admin_partition "example" {
mesh = "write"
node "my-node" {
policy = "write"
}
...
namespace "ex-namespace" {
...
}
namespace_prefix "exns-" {
...
}
}
admin_partition_prefix "ex-" {
... (Same as above)
}
```

View File

@ -173,6 +173,10 @@
}
]
},
{
"title": "admin-partition",
"path": "admin-partition"
},
{
"title": "agent",
"path": "agent"

View File

@ -846,6 +846,10 @@
"title": "Overview",
"path": "enterprise"
},
{
"title": "Admin Partitions <sup>BETA</sup>",
"path": "enterprise/admin-partitions"
},
{
"title": "Audit Logging",
"path": "enterprise/audit-logging"

21976
website/package-lock.json generated

File diff suppressed because it is too large Load Diff

View File

@ -40,6 +40,7 @@
"@hashicorp/react-text-split-with-image": "^4.2.5",
"@hashicorp/react-use-cases": "^5.0.0",
"@hashicorp/react-vertical-text-block-list": "^7.0.0",
"ci": "^2.1.1",
"next": "^11.1.2",
"next-mdx-remote": "3.0.1",
"next-remote-watch": "1.0.0",

Binary file not shown.

Binary file not shown.

Binary file not shown.