diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx index db56d13bda4b..28d4bc70db37 100644 --- a/website/content/docs/architecture/catalog/v1.mdx +++ b/website/content/docs/architecture/catalog/v1.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: v1 Catalog API -description: +description: Learn about version 1 of the Consul catalog, including what Consul servers record when they register a service. --- # v1 Catalog API @@ -20,43 +20,18 @@ Consul uses v1 of the Catalog API by default. Consul v1.17.0 introduces a second When Consul registers a service instance using the v1 catalog API, it records the following information about each instance: -v1 Catalog field -Description -User-defined or Consul-computed? -ID -A unique identifier for a service instance. -Consul -Node - -Consul -Address -The address of the node where the service instance is running. -Consul -Tagged Addresses - - -User -NodeMeta - - -User -Datacenter -The name of the datacenter the service is registered in. -User -Service -The name of the service Consul registers the service instance under. -User -Agent Check -The health status of service last reported by the Consul agent. -Consul -Health Checks -The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. -User -Partition -The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. -User -Locality -Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. -User +| v1 Catalog field | Description | Source | +| :--------------- | :---------- | :----- | +| ID | A unique identifier for a service instance. | Computed by Consul | +| Node | The connection point where the service is available. | Computed by Consul | +| Address | The address of the node where the service instance is running. | Computed by Consul | +| Tagged Addresses | User-defined metadata about addresses. | Defined by user | +| NodeMeta | User-defined metadata about the node. | Defined by user | +| Datacenter | The name of the datacenter the service is registered in. | Defined by user | +| Service | The name of the service Consul registers the service instance under. | Defined by user | +| Agent Check | The health status of service last reported by the Consul agent. | Computed by Consul | +| Health Checks | The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. | Defined by user | +| Partition | The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. | Defined by user | +| Locality | Region and availability zone of the service. Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. | Defined by user | Depending on the configuration entries or custom resource definitions you apply to your Consul installation, additional information such as [proxy default behavior](/consul/docs/connect/config-entries/proxy-defaults) is automatically recorded to the catalog for services. You can return this information using the [`/catalog` HTTP API endpoint](/consul/api-docs/catalog). diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx index 4997154d546b..c8d8df6e91e5 100644 --- a/website/content/docs/architecture/catalog/v2.mdx +++ b/website/content/docs/architecture/catalog/v2.mdx @@ -1,13 +1,13 @@ --- layout: docs page_title: v2 Catalog API -description: +description: Learn about version 2 of the Consul catalog, which uses GAMMA specified resources. Learn how the v2 catalog corresponds to the v1 catalog and Kubernetes resources.. --- # v2 Catalog API -The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments. +The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments. This topic provides conceptual information about version 2 of the Consul Catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases. @@ -36,67 +36,18 @@ Consul v1.17 introduces a new version of the catalog API designed to bridge diff The following table describes resources in the v2 catalog and compares them to the v1 catalog and Kubernetes resources. It also states whether these resources are defined by the user or computed by Consul when it registers a service. - -V2 Catalog resource -Description -Catalog v1 resource analogue -Kubernetes resource analogue -User-defined or Consul-computed -Service -The name of the service Consul registers a workload under -Service -X -User -Node -The address of the node where the workload runs. -Node -Node -Consul -Workload -An application instance running in a set of one or more Pods scheduled according to a Kubernetes Workload resource such as a Deployment or StatefulSet. -Service instance -Kubernetes Workloads -User -Workload identities -Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. -Service instance -Kubernetes Service Accounts -User -Service endpoints -Maps services to workload addresses and endpoints. - - - - -Consul -Health status -A resource for reporting the health status of a workload -Agent check -X -Consul -Health check -A resource for defining the health checks for a workload. -Health check - - -User -Proxy configuration -Represents a configuration for a sidecar or gateway proxy. -`Proxy` field in service definition - - -User -Destinations -Represents explicit service upstreams -Upstream service annotations -X -User -Traffic permissions -Enables L4 traffic authorization according to workload identity instead of service identity -Service intentions -X -User - +| v2 Catalog resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source | +| :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- | +| Service | The name of the service Consul registers a workload under | Service | None | Defined by user in Kubernetes | +| Node | The address of the node where the workload runs. | Node | Node | Computed by Consul | +| Workload | An application instance running in a set of one or more Pods scheduled according to a Kubernetes Workload resource such as a Deployment or StatefulSet. | Service instance | Kubernetes Workloads | Defined by user in Kubernetes | +| Workload identities | Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. | Service instance | Kubernetes Service Accounts | Defin by user in Kubernetes | +| Service endpoints | Maps services to workload addresses and endpoints. | None | Service backend | Computed by Consul | +| Health status | A resource for reporting the health status of a workload | Agent check | None | Computed by Consul | +| Health check | A resource for defining the health checks for a workload. | Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes | +| Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Consul | +| Destinations | Represents explicit service upstreams | None | Upstream Service annotation | Defined by user in Kubernetes | +| Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | Service intentions | None | Defined by user in Consul | Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information about using the Consul CLI to interact with the v2 catalog. @@ -110,14 +61,14 @@ The most significant change to Consul’s architecture and operations when using For more information about this resource, including example configurations, refer to [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions). -### HTTP route resource for L7 traffic management +### HTTPRoute and GRPCRoute resources for L7 traffic management -You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` resource. In the v1 catalog, this behavior is defined in dedicated configuration entries. For examples, refer to [service splitter configuration entry reference](/consul/docs/connect/config-entries/service-splitter#examples). +You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` or a `GRPCRoute` resource. In the v1 catalog, this behavior is defined in dedicated configuration entries. For examples, refer to [service splitter configuration entry reference](/consul/docs/connect/config-entries/service-splitter#examples). -For more information about this resource, including example configurations, refer to [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute). +For more information about these resource, including specifications and example configurations, refer to [HTTPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/httproute) and [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute). ### New proxy configuration resource In the v1 catalog, a service’s sidecar proxy and its behavior is [defined in the `Proxy` field of the service definition](/consul/docs/services/usage/define-services). You can also separately [define a service mesh proxy](/consul/docs/connect/proxies/deploy-service-mesh-proxies) and [configure proxy defaults](/consul/docs/connect/config-entries/proxy-defaults). -The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information. +The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information.