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

docs: File System Certificates (#21259) 

* Reference page updates

* Inline certificate config entry updates

* API Gateway configuration page

* K8s page updates

* Apply suggestions from code review

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
Co-authored-by: danielehc <40759828+danielehc@users.noreply.github.com>

* Daniele's suggestions

* Encrypt VMs suggestions

* Apply suggestions from code review

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>

---------

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
Co-authored-by: danielehc <40759828+danielehc@users.noreply.github.com>
This commit is contained in:
Jeff Boruszak 2024-06-11 12:58:01 -07:00 committed by GitHub
parent 04d95d2eda
commit 970353419c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
18 changed files with 172 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/docs/connect/config-entries/api-gateway.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: API Gateway Configuration Entry Reference
page_title: API Gateway configuration reference
description: Learn how to configure a Consul API gateway on VMs.
---
# API gateway configuration entry reference
# API gateway configuration reference
This topic provides reference information for the API gateway configuration entry that you can deploy to networks in virtual machine (VM) environments. For reference information about configuring Consul API gateways on Kubernetes, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
@ -349,7 +349,7 @@ Specifies a list of cipher suites that the listener supports when negotiating co
### `Listeners[].TLS.Certificates[]`
The list of references to file system or inline certificates that the listener uses for TLS termination.
The list of references to [file system](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificates](/consul/docs/connect/config-entries/inline-certificate) that the listener uses for TLS termination. You should create the configuration entry for the certificate separately and then reference the configuration entry in the `Name` field.
#### Values
@ -372,7 +372,7 @@ The list of references to certificates that the listener uses for TLS terminatio
### `Listeners[].TLS.Certificates[].Name`
Specifies the name of the file system or inline certificate that the listener uses for TLS termination.
Specifies the name of the [file system certificate](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificate](/consul/docs/connect/config-entries/inline-certificate) that the listener uses for TLS termination.
#### Values

4
website/content/docs/connect/config-entries/control-plane-request-limit.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Control Plane Request Limit Configuration Entry Configuration Reference
page_title: Control Plane Request Limit configuration reference
description: Learn how to configure the control-plane-request-limit configuration entry, which defines how Consul agents limit read and request traffic rate limits.
---
# Control Plane Request Limit Configuration Entry Configuration Reference
# Control Plane Request Limit configuration reference
This topic describes the configuration options for the `control-plane-request-limit` configuration entry. You can only write the `control-plane-request-limit` configuration entry to the `default` partition, but the configuration entry applies to all client requests that target any partition.

4
website/content/docs/connect/config-entries/exported-services.mdx
View File

@ -1,11 +1,11 @@
---
layout: docs
page_title: Exported Services - Configuration Entry Reference
page_title: Exported Services configuration reference
description: >-
An exported services configuration entry defines the availability of a cluster's services to cluster peers and local admin partitions. Learn about `""exported-services""` config entry parameters and exporting services to other datacenters.
---
# Exported Services Configuration Entry
# Exported Services configuration reference
This topic describes the `exported-services` configuration entry type. The `exported-services` configuration entry enables Consul to export service instances to other clusters from a single file and connect services across clusters. For additional information, refer to [Cluster Peering](/consul/docs/connect/cluster-peering) and [Admin Partitions](/consul/docs/enterprise/admin-partitions).

85
website/content/docs/connect/config-entries/file-system-certificate.mdx
View File

@ -1,13 +1,15 @@
---
layout: docs
page_title: File System Certificate Configuration Reference
page_title: File system certificate configuration reference
description: Learn how to configure a file system certificate bound to an API Gateway on VMs.
---
# File system certificate configuration reference
This topic provides reference information for the gateway file system certificate
configuration entry. For information about certificate configuration for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
This topic provides reference information for the file system certificate
configuration entry. The file system certificate is a more secure alternative to the [inline certificate configuration entry](/consul/docs/connect/config-entries/inline-certificate) when using Consul API Gateway on VMs because it references a local filepath instead of including sensitive information in the configuration entry itself. File system certificates also include a file system watch that implements certificate and key changes without restarting the gateway.
Consul on Kubernetes deployments that use `consul-k8s` Helm chart v1.5.0 or later use file system certificates without additional configuration. To learn about configuring certificates for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
## Configuration model
@ -15,7 +17,7 @@ The following list outlines field hierarchy, language-specific data types, and
requirements in a `file-system-certificate` configuration entry. Click on a property name
to view additional details, including default values.
- [`Kind`](#kind): string | must be `"file-system-certificate"`
- [`Kind`](#kind): string | must be set to `"file-system-certificate"`
- [`Name`](#name): string | no default
- [`Namespace`](#namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#partition): string | no default <EnterpriseAlert inline />
@ -27,33 +29,43 @@ to view additional details, including default values.
When every field is defined, a `file-system-certificate` configuration entry has the following form:
<CodeTabs>
<Tabs>
```HCL
<Tab heading="HCL" group="hcl">
```hcl
Kind = "file-system-certificate"
Name = "<name of certificate>"
Namespace = "ns"
Partition = "default"
Meta = {
"<any key>" = "<any value>"
"<key>" = "<value>"
}
Certificate = "<filepath to public certificate>"
PrivateKey = "<filepath to private key>"
Certificate = "<filepath/to/public/certificate>"
PrivateKey = "<filepath/to/private/key>"
```
```JSON
</Tab>
<Tab heading="JSON" group="json">
```json
{
"Kind": "file-system-certificate",
"Name": "<name of certificate>",
"Namespace": "ns",
"Partition": "default",
"Meta": {
"any key": "any value"
}
"Certificate": "<filepath to public certificate>",
"PrivateKey": "<filepath to private key>"
"key": "value"
},
"Certificate": "<filepath/to/public/certificate>",
"PrivateKey": "<filepath/to/private/key>"
}
```
</CodeTabs>
</Tab>
</Tabs>
## Specification
@ -63,7 +75,7 @@ Specifies the type of configuration entry to implement.
#### Values
- Default: none
- Default: None
- This field is required.
- Data type: string that must equal `"file-system-certificate"`
@ -75,7 +87,7 @@ as applying a configuration entry to a specific cluster.
#### Values
- Default: none
- Default: None
- This field is required.
- Data type: string
@ -103,12 +115,12 @@ Specifies an arbitrary set of key-value pairs to associate with the gateway.
#### Values
- Default: none
- Default: None
- Data type: map containing one or more keys and string values.
### `Certificate`
Specifies the filepath to a public certificate to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.
Specifies the path to a file that contains a public certificate to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.
#### Values
@ -118,10 +130,41 @@ Specifies the filepath to a public certificate to use for TLS. This filepath mus
### `PrivateKey`
Specifies the filepath to a private key to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.
Specifies the path to a file that contains a private key to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.
#### Values
- Default: none
- This field is required.
- Data type: string value of the filepath to a private key
## Examples
The following example demonstrates a file system certificate configuration.
<Tabs>
<Tab heading="HCL" group="hcl">
```hcl
Kind = "file-system-certificate"
Name = "tls-certificate"
Certificate = "/opt/consul/tls/api-gateway.crt"
PrivateKey = "/opt/consul/tls/api-gateway.key"
```
</Tab>
<Tab heading="JSON" group="json">
```json
{
"Kind": "file-system-certificate",
"Name": "tls-certificate",
"Certificate": "opt/consul/tls/api-gateway.crt",
"PrivateKey": "/opt/consul/tls/api-gateway.key"
}
```
</Tab>
</Tabs>

2
website/content/docs/connect/config-entries/http-route.mdx
View File

@ -1,6 +1,6 @@
---
layout: docs
page_title: HTTP Route Configuration
page_title: HTTP Route configuration reference
description: Learn how to configure an HTTP Route bound to an API Gateway on VMs.
---

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

@ -1,11 +1,11 @@
---
layout: docs
page_title: Ingress gateway configuration entry reference
page_title: Ingress gateway configuration reference
description: >-
The ingress gateway configuration entry kind defines behavior for securing incoming communication between the service mesh and external sources. Learn about `""ingress-gateway""` config entry parameters for exposing TCP and HTTP listeners.
---
# Ingress gateway configuration entry reference
# Ingress gateway configuration reference
<Note>

56
website/content/docs/connect/config-entries/inline-certificate.mdx
View File

@ -1,13 +1,15 @@
---
layout: docs
page_title: Inline Certificate Configuration Reference
page_title: Inline certificate configuration reference
description: Learn how to configure an inline certificate bound to an API Gateway on VMs.
---
# Inline certificate configuration reference
This topic provides reference information for the gateway inline certificate
configuration entry. For information about certificate configuration for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
This topic provides reference information for the inline certificate
configuration entry. The inline certificate secures TLS for the Consul API gateway on VMs. In production environments, we recommend you use the more secure [file system certificate configuration entry](/consul/docs/connect/config-entries/file-system-certificate) instead.
The inline certificate configuration entry is not used for Consul on Kubernetes deployments. To learn about configuring certificates for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
## Configuration model
@ -27,9 +29,11 @@ to view additional details, including default values.
When every field is defined, an `inline-certificate` configuration entry has the following form:
<CodeTabs>
<Tabs>
```HCL
<Tab heading="HCL" group="hcl">
```hcl
Kind = "inline-certificate"
Name = "<name of certificate>"
@ -41,19 +45,24 @@ Certificate = "<public certificate>"
PrivateKey = "<private key>"
```
```JSON
</Tab>
<Tab heading="JSON" group="json">
```json
{
"Kind": "inline-certificate",
"Name": "<name of certificate>",
"Meta": {
"any key": "any value"
}
},
"Certificate": "<public certificate>",
"PrivateKey": "<private key>"
}
```
</CodeTabs>
</Tab>
</Tabs>
## Specification
@ -125,3 +134,34 @@ Specifies the inline private key to use for TLS.
- Default: none
- This field is required.
- Data type: string value of the private key
## Examples
The following example demonstrates an inline certificate configuration.
<Tabs>
<Tab heading="HCL" group="hcl">
```hcl
Kind = "inline-certificate"
Name = "tls-certificate"
Certificate = "<complete-public-certificate>"
PrivateKey = "<complete-private-key>"
```
</Tab>
<Tab heading="JSON" group="json">
```json
{
"Kind": "inline-certificate",
"Name": "tls-certificate",
"Certificate": "<complete-public-certificate>",
"PrivateKey": "<complete-private-key>"
}
```
</Tab>
</Tabs>

4
website/content/docs/connect/config-entries/jwt-provider.mdx
View File

@ -1,10 +1,10 @@
---
page_title: JWT provider configuration entry reference
page_title: JWT provider configuration reference
description: |-
JWT provider configuration entries add JSON Web Token token validation to intentions in the service mesh. Learn how to write `jwt-provider` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---
# JWT provider configuration entry reference
# JWT provider configuration reference
This page provides reference information for the JWT provider configuration entry, which configures Consul to use a JSON Web Token (JWT) and JSON Web Key Set (JWKS) in order to add JWT validation to proxies in the service mesh. Refer to [Use JWT authorization with service intentions](/consul/docs/connect/intentions/jwt-authorization) for more information.

4
website/content/docs/connect/config-entries/sameness-group.mdx
View File

@ -1,10 +1,10 @@
---
page_title: Sameness group configuration entry reference
page_title: Sameness group configuration reference
description: |-
Sameness groups enable Consul to associate service instances with the same name deployed to the same namespace as identical services. Learn how to configure a `sameness-group` configuration entry to enable failover between partitions and cluster peers in non-federated networks.
---
# Sameness groups configuration entry reference
# Sameness groups configuration reference
This page provides reference information for sameness group configuration entries. Sameness groups associate identical admin partitions to facilitate traffic between identical services. When partitions are part of the same Consul datacenter, you can create a sameness group by listing them in the `Members[].Partition` field. When partitions are located on remote clusters, you must establish cluster peering connections between remote partitions in order to add them to a sameness group in the `Members[].Peer` field.

2
website/content/docs/connect/config-entries/service-defaults.mdx
View File

@ -1,6 +1,6 @@
---
layout: docs
page_title: Service defaults configuration entry reference
page_title: Service defaults configuration reference
description: ->
Use the service-defaults configuration entry to set default configurations for services, such as upstreams, protocols, and namespaces. Learn how to configure service-defaults.
---

4
website/content/docs/connect/config-entries/service-intentions.mdx
View File

@ -1,11 +1,11 @@
---
layout: docs
page_title: Service intentions configuration entry reference
page_title: Service intentions configuration reference
description: >-
Use the service intentions configuration entry to allow or deny traffic to services in the mesh from specific sources. Learn how to configure `service-intention` config entries
---
# Service intentions configuration entry reference
# Service intentions configuration reference
This topic provides reference information for the service intentions configuration entry. Intentions are configurations for controlling access between services in the service mesh. A single service intentions configuration entry specifies one destination service and one or more L4 traffic sources, L7 traffic sources, or combination of traffic sources. Refer to [Service mesh intentions overview](/consul/docs/connect/intentions) for additional information.

4
website/content/docs/connect/config-entries/service-resolver.mdx
View File

@ -1,11 +1,11 @@
---
layout: docs
page_title: Service Resolver Configuration Entry Reference
page_title: Service Resolver configuration reference
description: >-
Service resolver configuration entries are L7 traffic management tools for defining sets of service instances that resolve upstream requests and Consul’s behavior when resolving them. Learn how to write `service-resolver` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---
# Service resolver configuration entry reference
# Service resolver configuration reference
This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and define their behavior when satisfying upstream requests.

4
website/content/docs/connect/config-entries/service-router.mdx
View File

@ -1,11 +1,11 @@
---
layout: docs
page_title: Service Router Configuration Entry Reference
page_title: Service Router configuration reference
description: >-
Service router configuration entries are L7 traffic management tools for redirecting requests for a service to a particular instance or set of instances. Learn how to write `service-router` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---
# Service router configuration entry reference
# Service router configuration reference
This page provides reference information for service router configuration entries. Service routers use L7 network information to redirect a traffic request for a service to one or more specific service instances.

4
website/content/docs/connect/config-entries/service-splitter.mdx
View File

@ -1,13 +1,13 @@
---
layout: docs
page_title: Service Splitter Configuration Entry Reference
page_title: Service Splitter configuration reference
description: >-
Service splitter configuration entries are L7 traffic management tools for redirecting requests for a service to
multiple instances. Learn how to write `service-splitter` config entries in HCL or YAML with a specification
reference, configuration model, a complete example, and example code by use case.
---
# Service Splitter Configuration Reference
# Service Splitter configuration reference
This reference page describes the structure and contents of service splitter configuration entries. Configure and apply service splitters to redirect a percentage of incoming traffic requests for a service to one or more specific service instances.

4
website/content/docs/connect/config-entries/tcp-route.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: TCP Route Configuration Reference
page_title: TCP Route configuration reference
description: Learn how to configure a TCP Route that is bound to an API gateway on VMs.
---
# TCP route configuration Reference
# TCP route configuration reference
This topic provides reference information for the gateway TCP routes configuration
entry. Refer to [Route Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/routes) for information

3
website/content/docs/connect/gateways/api-gateway/index.mdx
View File

@ -26,7 +26,8 @@ You can deploy API gateways to networks that implement a variety of computing en
The following steps describe the general workflow for deploying a Consul API gateways:
1. For Kubernetes-orchestrated services, install Consul on your cluster. For Kubernetes-orchestrated services on OpenShift, you must also enable the `openShift.enabled` parameter. Refer to [Install Consul on Kubernetes](/consul/docs/connect/gateways/api-gateway/install-k8s) for additional information.
1. Define and deploy the API gateway configurations to create the API gateway artifacts. For VM-hosted services, create configuration entries for the gateway service, listeners configurations, and references to TLS certificates. For Kubernetes-orchestrated, configurations also include `GatewayClassConfig`s and `parametersRef`s.
1. Define and deploy the API gateway configurations to create the API gateway artifacts. For VM-hosted services, create configuration entries for the gateway service, listeners configurations, and TLS certificates. For Kubernetes-orchestrated services, configurations also include `GatewayClassConfig` and `parametersRef`. All Consul API Gateways created in Kubernetes with the `consul-k8s` Helm chart v1.5.0 or later use file system certificates when TLS is enabled.
1. Define and deploy routes between the gateway listeners and services in the mesh.
Gateway configurations are modular, so you can define and attach routes and inline certificates to multiple gateways.

39
website/content/docs/connect/gateways/api-gateway/secure-traffic/encrypt-vms.mdx
View File

@ -1,7 +1,7 @@
---
layout: docs
page_title: Encrypt API gateway traffic on virtual machines
description: Learn how to define inline certificate config entries and deploy them to Consul. Inline certificate configuration entries enable you to attach TLS certificates and keys to gateway listeners so that traffic between external clients and gateway listeners is encrypted.
description: Learn how to define inline certificate config entries and deploy them to Consul. Inline certificate and file system certificate configuration entries enable you to attach TLS certificates and keys to gateway listeners so that traffic between external clients and gateway listeners is encrypted.
---
# Encrypt API gateway traffic on virtual machines
@ -10,8 +10,9 @@ This topic describes how to make TLS certificates available to API gateways so t
## Requirements
- Consul 1.15 or later
- You must have a certificate and key from your CA
- Consul v1.15 or later is required to use the Consul API gateway on VMs
- Consul v1.19 or later is required to use the [file system certificate configuration entry](/consul/docs/connect/config-entries/file-system-certificate)
- You must have a certificate and key from your CA
- A Consul cluster with service mesh enabled. Refer to [`connect`](/consul/docs/agent/config/config-files#connect)
- Network connectivity between the machine deploying the API gateway and a
Consul cluster agent or server
@ -30,14 +31,20 @@ with Consul API gateway configurations.
## Define TLS certificates
1. Create an [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) and specify the following fields:
- `Kind`: Specifies the type of configuration entry. This must be set to `inline-certificate`.
1. Create a [file system certificate](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificate](/consul/docs/connect/config-entries/inline-certificate) and specify the following fields:
- `Kind`: Specifies the type of configuration entry. This must be set to `file-system-certificate` or `inline-certificate`.
- `Name`: Specify the name in the [API gateway listener configuration](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway#listeners) to bind the certificate to that listener.
- `Certificate`: Specifies the inline public certificate to use for TLS as plain text.
- `PrivateKey`: Specifies the inline private key to use for TLS as plain text.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) reference for additional information.
- `Certificate`: Specifies the filepath to the certificate on the local system or the inline public certificate as plain text.
- `PrivateKey`: Specifies the filepath to private key on the local system or the inline private key to as plain text.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the [file system certificate configuration reference](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificate configuration reference](/consul/docs/connect/config-entries/inline-certificate) for more information.
1. Save the configuration.
### Examples
<Tabs>
<Tab heading="Inline certificate">
The following example defines a certificate named `my-certificate`. API gateway configurations that specify `inline-certificate` in the `Certificate.Kind` field and `my-certificate` in the `Certificate.Name` field are able to use the certificate.
```hcl
@ -57,6 +64,22 @@ PrivateKey = <<EOF
EOF
```
</Tab>
<Tab heading="File system certificate">
The following example defines a certificate named `my-certificate`. API gateway configurations that specify `file-system-certificate` in the `Certificate.Kind` field and `my-certificate` in the `Certificate.Name` field are able to use the certificate.
```hcl
Kind = "file-system-certificate"
Name = "my-certificate"
Certificate = "/opt/consul/tls/api-gateway.crt"
PrivateKey = "/opt/consul/tls/api-gateway.key"
```
</Tab>
</Tabs>
## Deploy the configuration to Consul
Run the `consul config write` command to enable listeners to use the certificate. The following example writes a configuration called `my-certificate.hcl`:

5
website/content/docs/connect/gateways/api-gateway/tech-specs.mdx
View File

@ -87,7 +87,7 @@ You must specify the `"hashicorp.com/consul-api-gateway-controller"` controller
The `Gateway` resource is the core API gateway component. Gateways have one or more listeners that can route `HTTP`, `HTTPS`, or `TCP` traffic. You can define header-based hostname matching for listeners, but SNI is not supported.
You can apply filters to add, remove, and set header values on incoming requests. Gateways support the `terminate` TLS mode and `core/v1/Secret` TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to the [Kubernetes `Gateway` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for additional information.
You can apply filters to add, remove, and set header values on incoming requests. Gateways support the `terminate` TLS mode and `core/v1/Secret` TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to [Kubernetes `Gateway` resource configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gateway) for more information.
### `HTTPRoute`
@ -152,6 +152,3 @@ The following resources are allocated for each component of the API gateway.
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.