diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx index 5b1ae0dab3..5cf8d4a2d4 100644 --- a/website/content/api-docs/config.mdx +++ b/website/content/api-docs/config.mdx @@ -67,7 +67,7 @@ The table below shows this endpoint's support for ### Sample Payload -```javascript +```json { "Kind": "service-defaults", "Name": "web", diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index a62e962375..97f1e4672b 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -47,13 +47,13 @@ A wildcard specifier cannot be set on a listener of protocol `tcp`. ### TCP listener - - Set up a TCP listener on an ingress gateway named "us-east-ingress" to proxy traffic to the "db" service: + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -71,12 +71,47 @@ Listeners = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: IngressGateway +metadata: + name: us-east-ingress +spec: + listeners: + - port: 3456 + protocol: tcp + services: + - name: db +``` + +```json +{ + "Kind": "ingress-gateway", + "Name": "us-east-ingress", + "Listeners": [ + { + "Port": 3456, + "Protocol": "tcp", + "Services": [ + { + "Name": "db" + } + ] + } + ] +} +``` + + + Set up a TCP listener on an ingress gateway named "us-east-ingress" in the default namespace to proxy traffic to the "db" service in the ops namespace: + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -96,34 +131,6 @@ Listeners = [ ] ``` - - - - - - - -Set up a TCP listener on an ingress gateway named "us-east-ingress" to proxy traffic to the "db" service: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress -spec: - listeners: - - port: 3456 - protocol: tcp - services: - - name: db -``` - - - - -Set up a TCP listener on an ingress gateway named "us-east-ingress" in the default namespace -to proxy traffic to the "db" service in the ops namespace: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: IngressGateway @@ -139,39 +146,6 @@ spec: namespace: ops ``` - - - - - - - -Set up a TCP listener on an ingress gateway named "us-east-ingress" to proxy traffic to the "db" service: - -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "Listeners": [ - { - "Port": 3456, - "Protocol": "tcp", - "Services": [ - { - "Name": "db" - } - ] - } - ] -} -``` - - - - -Set up a TCP listener on an ingress gateway named "us-east-ingress" in the default namespace -to proxy traffic to the "db" service in the ops namespace: - ```json { "Kind": "ingress-gateway", @@ -192,21 +166,21 @@ to proxy traffic to the "db" service in the ops namespace: } ``` - - + + ### Wildcard HTTP listener - - Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the datacenter. Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener: + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -242,12 +216,73 @@ Listeners = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: IngressGateway +metadata: + name: us-east-ingress +spec: + tls: + enabled: true + listeners: + - port: 8080 + protocol: http + services: + - name: '*' + - port: 4567 + protocol: http + services: + - name: api + hosts: ['foo.example.com', 'foo.example.com:4567'] + - name: web + hosts: ['website.example.com', 'website.example.com:4567'] +``` + +```json +{ + "Kind": "ingress-gateway", + "Name": "us-east-ingress", + "TLS": { + "Enabled": true + }, + "Listeners": [ + { + "Port": 8080, + "Protocol": "http", + "Services": [ + { + "Name": "*" + } + ] + }, + { + "Port": 4567, + "Protocol": "http", + "Services": [ + { + "Name": "api", + "Hosts": ["foo.example.com", "foo.example.com:4567"] + }, + { + "Name": "web", + "Hosts": ["website.example.com", "website.example.com:4567"] + } + ] + } + ] +} +``` + + + Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the frontend namespace. Also make two services in the frontend namespace available over a custom port with user-provided hosts, and enable TLS on every listener: + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -287,44 +322,6 @@ Listeners = [ ] ``` - - - - - - - -Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the datacenter. -Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress -spec: - tls: - enabled: true - listeners: - - port: 8080 - protocol: http - services: - - name: '*' - - port: 4567 - protocol: http - services: - - name: api - hosts: ['foo.example.com', 'foo.example.com:4567'] - - name: web - hosts: ['website.example.com', 'website.example.com:4567'] -``` - - - - -Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the frontend namespace. -Also make two services in the frontend namespace available over a custom port with user-provided hosts, and enable TLS on every listener: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: IngressGateway @@ -351,57 +348,6 @@ spec: hosts: ['website.example.com', 'website.example.com:4567'] ``` - - - - - - - -Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the datacenter. -Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener: - -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "TLS": { - "Enabled": true - }, - "Listeners": [ - { - "Port": 8080, - "Protocol": "http", - "Services": [ - { - "Name": "*" - } - ] - }, - { - "Port": 4567, - "Protocol": "http", - "Services": [ - { - "Name": "api", - "Hosts": ["foo.example.com", "foo.example.com:4567"] - }, - { - "Name": "web", - "Hosts": ["website.example.com", "website.example.com:4567"] - } - ] - } - ] -} -``` - - - - -Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the frontend namespace. -Also make two services in the frontend namespace available over a custom port with user-provided hosts, and enable TLS on every listener: - ```json { "Kind": "ingress-gateway", @@ -441,21 +387,21 @@ Also make two services in the frontend namespace available over a custom port wi } ``` - - + + ### HTTP listener with path-based routing - - Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to a virtual service named "api". + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -473,12 +419,47 @@ Listeners = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: IngressGateway +metadata: + name: us-east-ingress +spec: + listeners: + - port: 80 + protocol: http + services: + - name: api +``` + +```json +{ + "Kind": "ingress-gateway", + "Name": "us-east-ingress", + "Listeners": [ + { + "Port": 80, + "Protocol": "http", + "Services": [ + { + "Name": "api" + } + ] + } + ] +} +``` + + + Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the default namespace to proxy traffic to a virtual service named "api". + + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" @@ -498,35 +479,6 @@ Listeners = [ ] ``` - - - - - - - -Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy -traffic to a virtual service named "api". - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress -spec: - listeners: - - port: 80 - protocol: http - services: - - name: api -``` - - - - -Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the -default namespace to proxy traffic to a virtual service named "api". - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: IngressGateway @@ -542,40 +494,6 @@ spec: namespace: frontend ``` - - - - - - - -Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy -traffic to a virtual service named "api". - -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "Listeners": [ - { - "Port": 80, - "Protocol": "http", - "Services": [ - { - "Name": "api" - } - ] - } - ] -} -``` - - - - -Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the -default namespace to proxy traffic to a virtual service named "api". - ```json { "Kind": "ingress-gateway", @@ -596,8 +514,8 @@ default namespace to proxy traffic to a virtual service named "api". } ``` - - + + @@ -606,11 +524,11 @@ service for L7 configuration only. A `service-router` (`ServiceRouter` on Kubern virtual service which uses path-based routing to route requests to different backend services: - - + + ```hcl Kind = "service-router" Name = "api" @@ -640,48 +558,6 @@ Routes = [ ] ``` - - - -```hcl -Kind = "service-router" -Name = "api" -Namespace = "default" -Routes = [ - { - Match { - HTTP { - PathPrefix = "/billing" - } - } - - Destination { - Service = "billing-api" - Namespace = "frontend" - } - }, - { - Match { - HTTP { - PathPrefix = "/payments" - } - } - - Destination { - Service = "payments-api" - Namespace = "frontend" - } - } -] -``` - - - - - - - - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -701,38 +577,6 @@ spec: service: payments-api ``` - - - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceRouter -metadata: - name: api - namespace: default -spec: - routes: - - match: - http: - pathPrefix: '/billing' - destination: - service: billing-api - namespace: frontend - - match: - http: - pathPrefix: '/payments' - destination: - service: payments-api - namespace: frontend -``` - - - - - - - - ```json { "Kind": "service-router", @@ -762,9 +606,67 @@ spec: } ``` + + + + +```hcl +Kind = "service-router" +Name = "api" +Namespace = "default" +Routes = [ + { + Match { + HTTP { + PathPrefix = "/billing" + } + } + + Destination { + Service = "billing-api" + Namespace = "frontend" + } + }, + { + Match { + HTTP { + PathPrefix = "/payments" + } + } + + Destination { + Service = "payments-api" + Namespace = "frontend" + } + } +] +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceRouter +metadata: + name: api + namespace: default +spec: + routes: + - match: + http: + pathPrefix: '/billing' + destination: + service: billing-api + namespace: frontend + - match: + http: + pathPrefix: '/payments' + destination: + service: payments-api + namespace: frontend +``` + ```json { "Kind": "service-router", @@ -797,8 +699,8 @@ spec: } ``` - - + + diff --git a/website/content/docs/connect/config-entries/mesh.mdx b/website/content/docs/connect/config-entries/mesh.mdx index 4ebbe72d6c..e80e86445a 100644 --- a/website/content/docs/connect/config-entries/mesh.mdx +++ b/website/content/docs/connect/config-entries/mesh.mdx @@ -23,7 +23,9 @@ Settings in this config entry apply across all namespaces and federated datacent Only allow transparent proxies to dial addresses in the mesh. - + + + ```hcl Kind = "mesh" @@ -32,12 +34,35 @@ TransparentProxy { } ``` - - +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: Mesh +metadata: + name: mesh +spec: + transparentProxy: + meshDestinationsOnly: true +``` -**NOTE:** The `mesh` config entry can only be created in the `default` +```json +{ + "Kind": "mesh", + "TransparentProxy": { + "MeshDestinationsOnly": true + } +} +``` + + + + + + +-> **Note**: The `mesh` config entry can only be created in the `default` namespace and it will apply to proxies across **all** namespaces. + + ```hcl Kind = "mesh" Namespace = "default" # Can only be set to "default". @@ -47,9 +72,6 @@ TransparentProxy { } ``` - - - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: Mesh @@ -60,23 +82,18 @@ spec: meshDestinationsOnly: true ``` - - - -**NOTE:** A `Mesh` resource can be created in any Kubernetes -namespace but it will apply to proxies across **all** namespaces. Only one -`Mesh` resource can exist in the cluster. - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: Mesh -metadata: - name: mesh -spec: - transparentProxy: - meshDestinationsOnly: true +```json +{ + "Kind": "mesh", + "Namespace": "default", + "TransparentProxy": { + "MeshDestinationsOnly": true + } +} ``` + + diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index b18b771ef0..74bfb70385 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -20,11 +20,15 @@ one global entry is supported. ### Default protocol +Set the default protocol for all sidecar proxies: + - + Set the default protocol for all sidecar proxies: + + ```hcl Kind = "proxy-defaults" Name = "global" @@ -33,14 +37,36 @@ Config { } ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ProxyDefaults +metadata: + name: global +spec: + config: + protocol: http +``` + +```json +{ + "Kind": "proxy-defaults", + "Name": "global", + "Config": { + "protocol": "http" + } +} +``` + + + - + -Set the default protocol for all sidecar proxies. - -**NOTE:** The `proxy-defaults` config entry can only be created in the `default` +-> **NOTE:** The `proxy-defaults` config entry can only be created in the `default` namespace and it will configure proxies in **all** namespaces. + + ```hcl Kind = "proxy-defaults" Name = "global" @@ -50,46 +76,39 @@ Config { } ``` - - - -Set the default protocol for all sidecar proxies: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults metadata: name: global + namespace: default spec: config: protocol: http ``` - - - -Set the default protocol for all sidecar proxies: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ProxyDefaults -metadata: - name: global -spec: - config: - protocol: http +```json +{ + "Kind": "proxy-defaults", + "Name": "global", + "Namespace": "default", + "Config": { + "protocol": "http" + } +} ``` + + ### Prometheus - - - Expose prometheus metrics: + + ```hcl Kind = "proxy-defaults" Name = "global" @@ -98,11 +117,6 @@ Config { } ``` - - - -Expose prometheus metrics: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -113,16 +127,24 @@ spec: envoy_prometheus_bind_addr: '0.0.0.0:9102' ``` - - +```json +{ + "Kind": "proxy-defaults", + "Name": "global", + "Config": { + "envoy_prometheus_bind_addr": "0.0.0.0:9102" + } +} +``` + + ### Proxy-specific defaults - - - Set proxy-specific defaults: + + ```hcl Kind = "proxy-defaults" Name = "global" @@ -132,11 +154,6 @@ Config { } ``` - - - -Set proxy-specific defaults: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -148,8 +165,18 @@ spec: handshake_timeout_ms: 10000 ``` - - +```json +{ + "Kind": "proxy-defaults", + "Name": "global", + "Config": { + "local_connect_timeout_ms": 1000, + "handshake_timeout_ms": 10000 + } +} +``` + + ## Available Fields @@ -207,8 +234,8 @@ spec: description: `An arbitrary map of configuration values used by Connect proxies. The available configurations depend on the Connect proxy you use. Any values that your proxy allows can be configured globally here. To explore these options please see the documentation for your chosen proxy. - `, + `, }, { name: 'Mode', diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 3d136db56f..5d5a9f91f6 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -24,11 +24,10 @@ config entry. However, if the protocol value is specified in a service defaults config entry for a given service, that value will take precedence over the globally configured value from proxy defaults. - - - Set the default protocol for a service in the default namespace to HTTP: + + ```hcl Kind = "service-defaults" Name = "web" @@ -36,11 +35,6 @@ Namespace = "default" Protocol = "http" ``` - - - -Set the default protocol for a service in the default namespace to HTTP: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults @@ -50,20 +44,28 @@ spec: protocol: http ``` - - +```json +{ + "Kind": "service-defaults", + "Name": "web", + "Namespace": "default", + "Protocol": "http" +} +``` + + ### Upstream configuration - - Set default connection limits and mesh gateway mode across all upstreams -of "counting" and also override the mesh gateway mode used when dialing +of "counting", and also override the mesh gateway mode used when dialing the "dashboard" service. + + ```hcl Kind = "service-defaults" Name = "counting" @@ -91,6 +93,55 @@ UpstreamConfig = { } ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceDefaults +metadata: + name: counting +spec: + upstreamConfig: + defaults: + meshGateway: + mode: local + limits: + maxConnections: 512 + maxPendingRequests: 512 + maxConcurrentRequests: 512 + overrides: + - name: dashboard + meshGateway: + mode: remote +``` + +```json +{ + "Kind": "service-defaults", + "Name": "counting", + "UpstreamConfig": { + "Defaults": { + "MeshGateway": { + "Mode": "local" + }, + "Limits": { + "MaxConnections": 512, + "MaxPendingRequests": 512, + "MaxConcurrentRequests": 512 + } + }, + "Overrides": [ + { + "Name": "dashboard", + "MeshGateway": { + "Mode": "remote" + } + } + ] + } +} +``` + + + @@ -98,6 +149,8 @@ Set default connection limits and mesh gateway mode across all upstreams of "counting" and also override the mesh gateway mode used when dialing the "dashboard" service in the "frontend" namespace. + + ```hcl Kind = "service-defaults" Name = "counting" @@ -127,46 +180,6 @@ UpstreamConfig = { } ``` - - - - - - - - - -Set default connection limits and mesh gateway mode across all upstreams -of "counting" and also override the mesh gateway mode used when dialing -the "dashboard" service. - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceDefaults -metadata: - name: counting -spec: - upstreamConfig: - defaults: - meshGateway: - mode: local - limits: - maxConnections: 512 - maxPendingRequests: 512 - maxConcurrentRequests: 512 - overrides: - - name: dashboard - meshGateway: - mode: remote -``` - - - - -Set default connection limits and mesh gateway mode across all upstreams -of "counting" and also override the mesh gateway mode used when dialing -the "dashboard" service in the "frontend" namespace. - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults @@ -189,8 +202,36 @@ spec: mode: remote ``` - - +```json +{ + "Kind": "service-defaults", + "Name": "counting", + "Namespace": "product", + "UpstreamConfig": { + "Defaults": { + "MeshGateway": { + "Mode": "local" + }, + "Limits": { + "MaxConnections": 512, + "MaxPendingRequests": 512, + "MaxConcurrentRequests": 512 + } + }, + "Overrides": [ + { + "Name": "dashboard", + "Namespace": "frontend", + "MeshGateway": { + "Mode": "remote" + } + } + ] + } +} +``` + + diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 926720079f..f0b55d7122 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -36,11 +36,10 @@ or globally via [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) ### REST Access - - - Grant some clients more REST access than others: + + ```hcl Kind = "service-intentions" Name = "api" @@ -74,11 +73,6 @@ Sources = [ ] ``` - - - -Grant some clients more REST access than others: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceIntentions @@ -104,18 +98,48 @@ spec: # unmatched connections and requests. Typically this will be DENY. ``` - - +```json +{ + "Kind": "service-intentions", + "Name": "api", + "Sources": [ + { + "Name": "admin-dashboard", + "Permissions": [ + { + "Action": "allow", + "HTTP": { + "PathPrefix": "/v2", + "Methods": ["GET", "PUT", "POST", "DELETE", "HEAD"] + } + } + ] + }, + { + "Name": "report-generator", + "Permissions": [ + { + "Action": "allow", + "HTTP": { + "PathPrefix": "/v2/widgets", + "Methods": ["GET"] + } + } + ] + } + ] +} +``` + ### gRPC - - - Selectively deny some gRPC service methods. Since gRPC method calls [are HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to control traffic: + + ```hcl Kind = "service-intentions" Name = "billing" @@ -156,13 +180,6 @@ Sources = [ ] ``` - - - -Selectively deny some gRPC service methods. Since gRPC method calls [are -HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can -use an HTTP path match rule to control traffic: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceIntentions @@ -192,16 +209,51 @@ spec: # unmatched connections and requests. Typically this will be DENY. ``` - - +```json +{ + "Kind": "service-intentions", + "Name": "billing", + "Sources": [ + { + "Name": "frontend-web", + "Permissions": [ + { + "Action": "deny", + "HTTP": { + "PathExact": "/mycompany.BillingService/IssueRefund" + } + }, + { + "Action": "allow", + "HTTP": { + "PathPrefix": "/mycompany.BillingService/" + } + } + ] + }, + { + "Name": "support-portal", + "Permissions": [ + { + "Action": "allow", + "HTTP": { + "PathPrefix": "/mycompany.BillingService/" + } + } + ] + } + ] +} +``` + + ### L4 and L7 - - - You can mix and match L4 and L7 intentions per source: + + ```hcl Kind = "service-intentions" Name = "api" @@ -231,11 +283,6 @@ Sources = [ ] ``` - - - -You can mix and match L4 and L7 intentions per source: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceIntentions @@ -259,8 +306,35 @@ spec: # unmatched connections and requests. Typically this will be DENY. ``` - - +```json +{ + "Kind": "service-intentions", + "Name": "api", + "Sources": [ + { + "Name": "hackathon-project", + "Action": "deny" + }, + { + "Name": "web", + "Action": "allow" + }, + { + "Name": "nightly-reconciler", + "Permissions": [ + { + "Action": "allow", + "HTTP": { + "PathExact": "/v1/reconcile-data", + "Methods": ["POST"] + } + } + ] + } + ] +} +``` + ## Available Fields diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 151e6093af..6afe1265e6 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -27,54 +27,62 @@ and discovery terminates. ### Filter on service version - - - Create service subsets based on a version metadata and override the defaults: + + ```hcl Kind = "service-resolver" Name = "web" DefaultSubset = "v1" Subsets = { - "v1" = { + v1 = { Filter = "Service.Meta.version == v1" } - "v2" = { + v2 = { Filter = "Service.Meta.version == v2" } } ``` - - - -Create service subsets based on a version metadata and override the defaults: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver metadata: name: web spec: - defaultSubset: 'v1' + defaultSubset: v1 subsets: - 'v1': + v1: filter: 'Service.Meta.version == v1' - 'v2': + v2: filter: 'Service.Meta.version == v2' ``` - - +```json +{ + "Kind": "service-resolver", + "Name": "web", + "DefaultSubset": "v1", + "Subsets": { + "v1": { + "Filter": "Service.Meta.version == v1" + }, + "v2": { + "Filter": "Service.Meta.version == v2" + } + } +} +``` + + ### Other datacenters - - - Expose a set of services in another datacenter as a virtual service: + + ```hcl Kind = "service-resolver" Name = "web-dc2" @@ -84,11 +92,6 @@ Redirect { } ``` - - - -Expose a set of services in another datacenter as a virtual service: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -100,32 +103,39 @@ spec: datacenter: dc2 ``` - - +```json +{ + "Kind": "service-resolver", + "Name": "web-dc2", + "Redirect": { + "Service": "web", + "Datacenter": "dc2" + } +} +``` + + ### Datacenter failover - - +Enable failover for subset 'v2' to 'dc2', and all other subsets to dc3 or dc4: -Enable failover for all subsets: + ```hcl Kind = "service-resolver" Name = "web" ConnectTimeout = "15s" Failover = { + v2 = { + Datacenters = ["dc2"] + } "*" = { Datacenters = ["dc3", "dc4"] } } ``` - - - -Enable failover for all subsets: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -134,20 +144,36 @@ metadata: spec: connectTimeout: 15s failover: + v2: + datacenters: ['dc2'] '*': datacenters: ['dc3', 'dc4'] ``` - - +```json +{ + "Kind": "service-resolver", + "Name": "web", + "ConnectTimeout": "15s", + "Failover": { + "v2": { + "Datacenters": ["dc2"] + }, + "*": { + "Datacenters": ["dc3", "dc4"] + } + } +} +``` + + ### Consistent load balancing - - - Apply consistent load balancing for requests based on `x-user-id` header: + + ```hcl Kind = "service-resolver" Name = "web" @@ -163,11 +189,6 @@ LoadBalancer = { } ``` - - - -Apply consistent load balancing for requests based on `x-user-id` header: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -181,8 +202,23 @@ spec: fieldValue: x-user-id ``` - - +```json +{ + "Kind": "service-resolver", + "Name": "web", + "LoadBalancer": { + "Policy": "maglev", + "HashPolicies": [ + { + "Field": "header", + "FieldValue": "x-user-id" + } + ] + } +} +``` + + ## Available Fields diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 367d546aa7..7bc6af1fb0 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -40,11 +40,10 @@ service of the same name. ### Path prefix matching - - - Route HTTP requests with a path starting with `/admin` to a different service: + + ```hcl Kind = "service-router" Name = "web" @@ -64,11 +63,6 @@ Routes = [ ] ``` - - - -Route HTTP requests with a path starting with `/admin` to a different service: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -84,15 +78,32 @@ spec: # NOTE: a default catch-all will send unmatched traffic to "web" ``` - - +```json +{ + "Kind": "service-router", + "Name": "web", + "Routes": [ + { + "Match": { + "HTTP": { + "PathPrefix": "/admin" + } + }, + "Destination": { + "Service": "admin" + } + } + ] +} +``` + + ### Header/query parameter matching - - +Route HTTP requests with a special URL parameter or header to a canary subset: -Route HTTP requests with a special url parameter or header to a canary subset: + ```hcl Kind = "service-router" @@ -134,11 +145,6 @@ Routes = [ ] ``` - - - -Route HTTP requests with a special url parameter or header to a canary subset: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -165,17 +171,56 @@ spec: # NOTE: a default catch-all will send unmatched traffic to "web" ``` - - +```json +{ + "Kind": "service-router", + "Name": "web", + "Routes": [ + { + "Match": { + "HTTP": { + "Header": [ + { + "Name": "x-debug", + "Exact": "1" + } + ] + } + }, + "Destination": { + "Service": "web", + "ServiceSubset": "canary" + } + }, + { + "Match": { + "HTTP": { + "QueryParam": [ + { + "Name": "x-debug", + "Exact": "1" + } + ] + } + }, + "Destination": { + "Service": "web", + "ServiceSubset": "canary" + } + } + ] +} +``` + + ### gRPC routing - - - Re-route a gRPC method to another service. Since gRPC method calls [are HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: + + ```hcl Kind = "service-router" Name = "billing" @@ -195,12 +240,6 @@ Routes = [ ] ``` - - - -Re-route a gRPC method to another service. Since gRPC method calls [are -HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -216,8 +255,26 @@ spec: # NOTE: a default catch-all will send unmatched traffic to "billing" ``` - - +```json +{ + "Kind": "service-router", + "Name": "billing", + "Routes": [ + { + "Match": { + "HTTP": { + "PathExact": "/mycompany.BillingService/GenerateInvoice" + } + }, + "Destination": { + "Service": "invoice-generator" + } + } + ] +} +``` + + ## Available Fields diff --git a/website/content/docs/connect/config-entries/service-splitter.mdx b/website/content/docs/connect/config-entries/service-splitter.mdx index 617a8ada14..0c3b4ffb21 100644 --- a/website/content/docs/connect/config-entries/service-splitter.mdx +++ b/website/content/docs/connect/config-entries/service-splitter.mdx @@ -43,11 +43,10 @@ resolution stage. ### Two subsets of same service - - - Split traffic between two subsets of the same service: + + ```hcl Kind = "service-splitter" Name = "web" @@ -63,11 +62,6 @@ Splits = [ ] ``` - - - -Split traffic between two subsets of the same service: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceSplitter @@ -81,16 +75,31 @@ spec: serviceSubset: v2 ``` - - +```json +{ + "Kind": "service-splitter", + "Name": "web", + "Splits": [ + { + "Weight": 90, + "ServiceSubset": "v1" + }, + { + "Weight": 10, + "ServiceSubset": "v2" + } + ] +} +``` + + ### Two different services - - - Split traffic between two services: + + ```hcl Kind = "service-splitter" Name = "web" @@ -106,11 +115,6 @@ Splits = [ ] ``` - - - -Split traffic between two services: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceSplitter @@ -124,8 +128,23 @@ spec: service: web-rewrite ``` - - +```json +{ + "Kind": "service-splitter", + "Name": "web", + "Splits": [ + { + "Weight": 50 + }, + { + "Weight": 50, + "Service": "web-rewrite" + } + ] +} +``` + + ## Available Fields diff --git a/website/content/docs/connect/config-entries/terminating-gateway.mdx b/website/content/docs/connect/config-entries/terminating-gateway.mdx index 3f60fbc140..5ba8916351 100644 --- a/website/content/docs/connect/config-entries/terminating-gateway.mdx +++ b/website/content/docs/connect/config-entries/terminating-gateway.mdx @@ -44,12 +44,16 @@ traffic from the mesh to those services will be evenly load-balanced between the ## Sample Config Entries - - +### Access an external service + -Link gateway named "us-west-gateway" with the billing service: +Link gateway named "us-west-gateway" with the billing service. + +Connections to the external service will be unencrypted. + + ```hcl Kind = "terminating-gateway" @@ -62,10 +66,38 @@ Services = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: TerminatingGateway +metadata: + name: us-west-gateway +spec: + services: + - name: billing +``` + +```json +{ + "Kind": "terminating-gateway", + "Name": "us-west-gateway", + "Services": [ + { + "Name": "billing" + } + ] +} +``` + + + -Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace: +Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace. + +Connections to the external service will be unencrypted. + + ```hcl Kind = "terminating-gateway" @@ -80,30 +112,6 @@ Services = [ ] ``` - - - - - - - -Link gateway named "us-west-gateway" with the billing service: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: TerminatingGateway -metadata: - name: us-west-gateway -spec: - services: - - name: billing -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: TerminatingGateway @@ -115,32 +123,6 @@ spec: namespace: finance ``` - - - - - - - -Link gateway named "us-west-gateway" with the billing service: - -```json -{ - "Kind": "terminating-gateway", - "Name": "us-west-gateway", - "Services": [ - { - "Name": "billing" - } - ] -} -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace: - ```json { "Kind": "terminating-gateway", @@ -155,17 +137,23 @@ Link gateway named "us-west-gateway" in the default namespace with the billing s } ``` - - + + - - +### Access an external service over TLS + -Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication: +Link gateway named "us-west-gateway" with the billing service, and specify a CA +file to be used for one-way TLS authentication. + +-> **Note**: The `CAFile` parameter must be specified _and_ point to a valid CA +bundle in order to properly initiate a TLS connection to the destination service. + + ```hcl Kind = "terminating-gateway" @@ -179,11 +167,42 @@ Services = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: TerminatingGateway +metadata: + name: us-west-gateway +spec: + services: + - name: billing + caFile: /etc/certs/ca-chain.cert.pem +``` + +```json +{ + "Kind": "terminating-gateway", + "Name": "us-west-gateway", + "Services": [ + { + "Name": "billing", + "CAFile": "/etc/certs/ca-chain.cert.pem" + } + ] +} +``` + + + Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace, -and specify a CA file for one-way TLS authentication: +and specify a CA file to be used for one-way TLS authentication. + +-> **Note**: The `CAFile` parameter must be specified _and_ point to a valid CA +bundle in order to properly initiate a TLS connection to the destination service. + + ```hcl Kind = "terminating-gateway" @@ -199,32 +218,6 @@ Services = [ ] ``` - - - - - - - -Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: TerminatingGateway -metadata: - name: us-west-gateway -spec: - services: - - name: billing - caFile: /etc/certs/ca-chain.cert.pem -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace, -and specify a CA file for one-way TLS authentication: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: TerminatingGateway @@ -237,34 +230,6 @@ spec: caFile: /etc/certs/ca-chain.cert.pem ``` - - - - - - - -Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication: - -```json -{ - "Kind": "terminating-gateway", - "Name": "us-west-gateway", - "Services": [ - { - "Name": "billing", - "CAFile": "/etc/certs/ca-chain.cert.pem" - } - ] -} -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace, -and specify a CA file for one-way TLS authentication: - ```json { "Kind": "terminating-gateway", @@ -280,17 +245,23 @@ and specify a CA file for one-way TLS authentication: } ``` - - + + - - +### Access an external service over mutual TLS + -Link gateway named "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication: +Link gateway named "us-west-gateway" with the billing service, and specify a CA +file, key file, and cert file to be used for mutual TLS authentication. + +-> **Note**: The `CAFile` parameter must be specified _and_ point to a valid CA +bundle in order to properly initiate a TLS connection to the destination service. + + ```hcl Kind = "terminating-gateway" @@ -306,11 +277,46 @@ Services = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: TerminatingGateway +metadata: + name: us-west-gateway +spec: + services: + - name: billing + caFile: /etc/certs/ca-chain.cert.pem + keyFile: /etc/certs/gateway.key.pem + certFile: /etc/certs/gateway.cert.pem +``` + +```json +{ + "Kind": "terminating-gateway", + "Name": "us-west-gateway", + "Services": [ + { + "Name": "billing", + "CAFile": "/etc/certs/ca-chain.cert.pem", + "KeyFile": "/etc/certs/gateway.key.pem", + "CertFile": "/etc/certs/gateway.cert.pem" + } + ] +} +``` + + + -Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace. -Also specify a CA file, key file, and cert file for mutual TLS authentication: +Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace. +Also specify a CA file, key file, and cert file to be used for mutual TLS authentication. + +-> **Note**: The `CAFile` parameter must be specified _and_ point to a valid CA +bundle in order to properly initiate a TLS connection to the destination service. + + ```hcl Kind = "terminating-gateway" @@ -328,34 +334,6 @@ Services = [ ] ``` - - - - - - - -Link gateway named "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: TerminatingGateway -metadata: - name: us-west-gateway -spec: - services: - - name: billing - caFile: /etc/certs/ca-chain.cert.pem - keyFile: /etc/certs/gateway.key.pem - certFile: /etc/certs/gateway.cert.pem -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace. -Also specify a CA file, key file, and cert file for mutual TLS authentication: - ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: TerminatingGateway @@ -370,36 +348,6 @@ spec: certFile: /etc/certs/gateway.cert.pem ``` - - - - - - - -Link gateway named "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication: - -```json -{ - "Kind": "terminating-gateway", - "Name": "us-west-gateway", - "Services": [ - { - "Name": "billing", - "CAFile": "/etc/certs/ca-chain.cert.pem", - "KeyFile": "/etc/certs/gateway.key.pem", - "CertFile": "/etc/certs/gateway.cert.pem" - } - ] -} -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace. -Also specify a CA file, key file, and cert file for mutual TLS authentication: - ```json { "Kind": "terminating-gateway", @@ -417,18 +365,23 @@ Also specify a CA file, key file, and cert file for mutual TLS authentication: } ``` - - + + - - +### Override connection parameters for a specific service + Link gateway named "us-west-gateway" with all services in the datacenter, and configure default certificates for mutual TLS. -Also override the SNI and CA file used for connections to the billing service: + +Override the SNI and CA file used for connections to the billing service. + + + + ```hcl Kind = "terminating-gateway" @@ -449,11 +402,65 @@ Services = [ ] ``` + + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: TerminatingGateway +metadata: + name: us-west-gateway +spec: + services: + - name: '*' + caFile: /etc/common-certs/ca-chain.cert.pem + keyFile: /etc/common-certs/gateway.key.pem + certFile: /etc/common-certs/gateway.cert.pem + - name: billing + caFile: /etc/billing-ca/ca-chain.cert.pem + sni: billing.service.com +``` + + + + + +```json +{ + "Kind": "terminating-gateway", + "Name": "us-west-gateway", + "Services": [ + { + "Name": "*", + "CAFile": "/etc/common-certs/ca-chain.cert.pem", + "KeyFile": "/etc/common-certs/gateway.key.pem", + "CertFile": "/etc/common-certs/gateway.cert.pem" + }, + { + "Name": "billing", + "CAFile": "/etc/billing-ca/ca-chain.cert.pem", + "SNI": "billing.service.com" + } + ] +} +``` + + + + + Link gateway named "us-west-gateway" in the default namespace with all services in the finance namespace, -and configure default certificates for mutual TLS. Also override the SNI and CA file used for connections to the billing service: +and configure default certificates for mutual TLS. + +Override the SNI and CA file used for connections to the billing service: + + + + ```hcl Kind = "terminating-gateway" @@ -471,43 +478,15 @@ Services = [ { Namespace = "finance" Name = "billing" - CAFile = "/etc/billing-ca/ca-chain.cert.pem", + CAFile = "/etc/billing-ca/ca-chain.cert.pem" SNI = "billing.service.com" } ] ``` - - - - - - + -Link gateway named "us-west-gateway" with all services in the datacenter, and configure default certificates for mutual TLS. -Also override the SNI and CA file used for connections to the billing service: - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: TerminatingGateway -metadata: - name: us-west-gateway -spec: - services: - - name: '*' - caFile: /etc/common-certs/ca-chain.cert.pem - keyFile: /etc/common-certs/gateway.key.pem - certFile: /etc/common-certs/gateway.cert.pem - - name: billing - caFile: /etc/billing-ca/ca-chain.cert.pem - sni: billing.service.com -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with all services in the finance namespace, -and configure default certificates for mutual TLS. Also override the SNI and CA file used for connections to the billing service: + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -527,42 +506,9 @@ spec: sni: billing.service.com ``` - - - - - - + -Link gateway named "us-west-gateway" with all services in the datacenter, and configure default certificates for mutual TLS. -Also override the SNI and CA file used for connections to the billing service: - -```json -{ - "Kind": "terminating-gateway", - "Name": "us-west-gateway", - "Services": [ - { - "Name": "*", - "CAFile": "/etc/billing-ca/ca-chain.cert.pem", - "KeyFile": "/etc/certs/gateway.key.pem", - "CertFile": "/etc/certs/gateway.cert.pem", - "SNI": "billing.service.com" - }, - { - "Name": "billing", - "CAFile": "/etc/billing-ca/ca-chain.cert.pem", - "SNI": "billing.service.com" - } - ] -} -``` - - - - -Link gateway named "us-west-gateway" in the default namespace with all services in the finance namespace, -and configure default certificates for mutual TLS. Also override the SNI and CA file used for connections to the billing service: + ```json { @@ -573,10 +519,9 @@ and configure default certificates for mutual TLS. Also override the SNI and CA { "Namespace": "finance", "Name": "*", - "CAFile": "/etc/billing-ca/ca-chain.cert.pem", - "KeyFile": "/etc/certs/gateway.key.pem", - "CertFile": "/etc/certs/gateway.cert.pem", - "SNI": "billing.service.com" + "CAFile": "/etc/common-certs/ca-chain.cert.pem", + "KeyFile": "/etc/common-certs/gateway.key.pem", + "CertFile": "/etc/common-certs/gateway.cert.pem" }, { "Namespace": "finance", @@ -588,8 +533,10 @@ and configure default certificates for mutual TLS. Also override the SNI and CA } ``` - - + + + +