status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Reformatting suggestions from review

This commit is contained in:
Paul Banks 2021-10-08 12:19:45 +01:00
parent d5a93d6b88
commit 1d85afeed4
2 changed files with 135 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
website/content/docs/connect/config-entries/ingress-gateway.mdx
View File

@ -863,7 +863,8 @@ spec:
type: 'array<IngressService>: <optional>',
description: `A list of services to be exposed via this listener.
For \`tcp\` listeners, only a single service is allowed.
Each service must have a unique name (and namespace in Enterprise).`,
Each service must have a unique name. A namespace is also required for
Consul Enterprise.`,
children: [
{
name: 'Name',

258
website/content/docs/connect/gateways/ingress-gateway.mdx
View File

@ -76,10 +76,10 @@ sets of services within their datacenter, then the ingress gateways **must** be
## Custom TLS Certificates via Secret Discovery Service (SDS)
~> **Advanced Topic** This is a low-level feature designed for developers
building integrations with custom TLS management solutions.
~> **Advanced Topic:** This topic describes a low-level feature designed for
developers building integrations with custom TLS management solutions.
Consul 1.11 added support for Ingress Gateways to serve TLS certificates to
Consul 1.11 added support for ingress gateways to serve TLS certificates to
inbound traffic that are sourced from an external service. The external service
must implement Envoy's [gRPC Secret Discovery
Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret)
@ -87,7 +87,7 @@ Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secr
The following procedure describes how to configure an ingress gateway with TLS certificates from an SDS source. The instructions assume that you are familiar with Envoy configuration and the SDS protocol.
### 1. Configure Static SDS Cluster(s)
### Configure Static SDS Cluster(s)
Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static
clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy.
@ -96,145 +96,153 @@ It's not possible to use the `-register` flag with `consul connect envoy -gatewa
The cluster(s) must provide connection information and any necessary
authentication information such as mTLS credentials.
In this example we will show:
The following example will demonstrate how to use:
- A DNS name to discover the SDS service addresses
- Local certificate files for TLS client authentication with the SDS server
(the certificates are assumed to be created and managed by some other
process)
- Local certificate files for TLS client authentication with the SDS server.
The certificates are assumed to be created and managed by some other
process.
#### 1.1 Registering the Proxy Service
1. **Register the proxy service.**
The following Proxy Service Definition defines the bootstrap overrides needed to
add this configuration to Envoy when it starts. With this TLS configuration,
Envoy will detect changes to the certificate and key files on disk so an
external process may maintain and rotate them without needing an Envoy restart.
The following Proxy Service Definition defines the additional cluster
configuration that will be provided to Envoy when it starts. With this TLS
configuration, Envoy will detect changes to the certificate and key files on
disk so an external process may maintain and rotate them without needing an
Envoy restart.
```hcl
// public-ingress.hcl
Services {
Name = "public-ingress"
Kind = "ingress-gateway"
```hcl
// public-ingress.hcl
Services {
Name = "public-ingress"
Kind = "ingress-gateway"
Proxy {
Config {
envoy_extra_static_clusters_json = <<EOF
{
"name": "sds-cluster",
"connect_timeout": "5s",
"http2_protocol_options": {},
"type": "LOGICAL_DNS",
"transport_socket": {
"name":"tls",
"typed_config": {
"@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
"common_tls_context":{
"tls_certificate_sds_secret_configs": [
{
"name":"tls_sds",
"sds_config":{
"path":"/certs/sds-auth-cert.json"
}
}
],
"validation_context_sds_secret_config": {
"name":"validation_context_sds",
"sds_config":{
"path":"/certs/sds-validation.json"
}
}
}
}
},
"load_assignment": {
"cluster_name": "sds-cluster",
"endpoints": [
{
"lb_endpoints": [
{
"endpoint": {
"address": {
"socket_address": {
"address": "sds-server.svc.cluster.local",
"port_value": 8080,
Proxy {
Config {
envoy_extra_static_clusters_json = <<EOF
{
"name": "sds-cluster",
"connect_timeout": "5s",
"http2_protocol_options": {},
"type": "LOGICAL_DNS",
"transport_socket": {
"name":"tls",
"typed_config": {
"@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
"common_tls_context":{
"tls_certificate_sds_secret_configs": [
{
"name":"tls_sds",
"sds_config":{
"path":"/certs/sds-auth-cert.json"
}
}
],
"validation_context_sds_secret_config": {
"name":"validation_context_sds",
"sds_config":{
"path":"/certs/sds-validation.json"
}
}
}
}
},
"load_assignment": {
"cluster_name": "sds-cluster",
"endpoints": [
{
"lb_endpoints": [
{
"endpoint": {
"address": {
"socket_address": {
"address": "sds-server.svc.cluster.local",
"port_value": 8080,
}
}
}
}
]
}
]
}
]
}
}
EOF
}
}
}
```
**Run `consul services register public-ingress.hcl`** to create the
registration. The command must be executed on the node where the Envoy proxy will register the proxy with the local Consul agent.
#### 1.2 Setup TLS Client Authentication for SDS
This configuration relies on files like the following being present on disk
where the Envoy proxy will run, along with the actual certificates and keys
referenced.
* `sds-client-auth.{crt,key}` are the PEM-encoded certificate and key
files to be used for TLS Client Authentication with the SDS service.
* `sds-ca.crt` is the Certificate Authority certificate used to validate the the
SDS server's TLS credentials.
Please refer to [Envoy's
documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap)
for more details on this configuration and other possible authentication
options.
```json
// /certs/sds-auth-cert.json
{
"resources": [
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "tls_sds",
"tls_certificate": {
"certificate_chain": {
"filename": "/certs/sds-client-auth.crt"
},
"private_key": {
"filename": "/certs/sds-client-auth.key"
EOF
}
}
}
]
}
```
```json
// /certs/sds-validation.json
{
"resources": [
```
1. **Issue the following command to create the registration.**
```
consul services register public-ingress.hcl
```
The command must be executed against the Consul agent on the Envoy proxy's node.
#### Setup TLS Client Authentication for SDS
Configuration files similar to the following examples must be available on the
disk where the Envoy proxy will run. The actual certificates and keys referenced
in the configuration files must also be present.
1. **Configure TLS client authentication for SDS.**
The certificates and keys must be saved to the same disk where the Envoy
proxy will run. The following example files reference the PEM-encoded
certificate and key files to be used for TLS Client Authentication with the
SDS service (`sds-client-auth.{crt,key}`) and the certificate authority
certificate used to validate the SDS server's TLS credentials
(`sds-ca.crt`).
Refer to [Envoy's documentation]
https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap) for
more details on this configuration and other possible authentication
options.
```json
// /certs/sds-auth-cert.json
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "validation_context_sds",
"validation_context": {
"trusted_ca": {
"filename": "/certs/sds-ca.crt"
"resources": [
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "tls_sds",
"tls_certificate": {
"certificate_chain": {
"filename": "/certs/sds-client-auth.crt"
},
"private_key": {
"filename": "/certs/sds-client-auth.key"
}
}
}
}
]
}
]
}
```
```
```json
// /certs/sds-validation.json
{
"resources": [
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "validation_context_sds",
"validation_context": {
"trusted_ca": {
"filename": "/certs/sds-ca.crt"
}
}
}
]
}
```
#### 1.3 Start Envoy
1. **Issue the following command to start Envoy.**
**Start Envoy** with:
```bash
$ consul connect envoy -gateway=ingress -service public-ingress
```
```bash
$ consul connect envoy -gateway=ingress -service public-ingress
```
### 2. Configure the Ingress Gateway to Use Certificates from SDS
### Configure the Ingress Gateway to Use Certificates from SDS
SDS certificates may now be configured in the `ingress-gateway` Config Entry.
@ -265,10 +273,10 @@ Listeners = [
```
Run `consul config write public-ingress-cfg.hcl` to write this configuration.
1. **Run `consul config write public-ingress-cfg.hcl` to write this configuration.**
The Envoy instance will now start a listener on port 8443 and attempt to fetch
the TLS certificate named from the SDS server.
The Envoy instance will now start a listener on port 8443 and attempt to fetch
the TLS certificate named from the SDS server.
Separate certificates may be loaded per listener or per-service with hostname
(SNI) switching. See the [Config Entry