docs: Multi-port support for v1.17 GA #19401
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: v1 Catalog API | ||
| description: Learn about version 1 of the Consul catalog, including what Consul servers record when they register a service. | ||
| --- | ||
|
|
||
| # v1 Catalog API | ||
|
|
||
| This topic provides conceptual information about version 1 (v1) of the Consul catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases. | ||
|
|
||
| For more information about the information returned when querying the catalog, including filtering options when querying the catalog for a list of nodes, services, or gateways, refer to the [`/catalog` endpoint reference in the HTTP API documentation](/consul/api-docs/catalog). | ||
|
|
||
| ## Introduction | ||
|
|
||
| Consul tracks information about registered services through its Catalog API. This API records user-defined information about the external services, such as their partitions and required health checks. It also records information that Consul assigns for its own operations, such as an ID for each service instance and the [Raft indices](/consul/docs/architecture/consensus) when the instance is registered and modified. | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| Consul uses v1 of the Catalog API by default. Consul v1.17.0 introduces a second version of the Catalog API for testing and development purposes. The catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions at this time. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/catalog/v2). | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| ## Catalog structure | ||
|
|
||
| When Consul registers a service instance using the v1 catalog API, it records the following information about each instance: | ||
|
|
||
| | v1 Catalog field | Description | Source | | ||
| | :--------------- | :---------- | :----- | | ||
| | ID | A unique identifier for a service instance. | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Node | The connection point where the service is available. | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Address | The address of the node where the service instance is running. | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Tagged Addresses | User-defined metadata about addresses. | Defined by user | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | 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 | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | 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 | | ||
|
boruszak marked this conversation as resolved.
|
||
| | 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). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: v2 Catalog API | ||
| 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 | ||
|
|
||
| <Warning> | ||
| 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. | ||
| </Warning> | ||
|
boruszak marked this conversation as resolved.
|
||
|
|
||
| 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. | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| Consul supports the v2 catalog on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog/v1). | ||
|
|
||
| ## Introduction | ||
|
|
||
| When Consul registers services, it records [user-defined and Consul-assigned information](/consul/docs/architecture/catalog/v1#catalog-structure). To determine a service’s identity, v1 of the catalog API records the following information: | ||
|
|
||
| - IDs of the specific _service instances_ that are registered | ||
| - Locations of the _nodes_ the instances run on | ||
| - Names of the _services_ the instances are associated with | ||
|
|
||
| This information enables Consul to associate service names with the individual instances and their unique network addresses, and it is essential to Consul’s service discovery and service mesh operations. | ||
|
|
||
| The [Consul v1 Catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. Communication in Consul’s service mesh is secured through Consul's ACL system, which requires that a Kubernetes ServiceAccount resource match the Service name. As a result, only one service can represent a Kubernetes Workload in the v1 catalog. | ||
|
boruszak marked this conversation as resolved.
Outdated
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| Since then, the cloud networking needs for applications have evolved and workarounds were developed. For example, [Kubernetes Pods with multiple ports](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports) demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services. | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| The v2 catalog API is available alongside the existing v1 catalog API, but the catalogs cannot be used simultaneously. The v2 catalog is disabled by default. This beta release is for testing and development purposes only. We do not recommend implementing v2 in production environments or migrating to v2 until the API is generally available. | ||
|
|
||
| ## Catalog structure | ||
|
|
||
| Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_. | ||
|
|
||
| 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 | Source | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- | | ||
| | Service | The name of the service Consul registers a workload under | Service | None | Defined by user in Kubernetes | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Node | The address of the node where the workload runs. | Node | Node | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | 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 | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | 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 | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Service endpoints | Maps services to workload addresses and endpoints. | None | Service backend | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | Health status | A resource for reporting the health status of a workload | Agent check | None | Computed by Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
boruszak marked this conversation as resolved.
Outdated
|
||
| | Health check | A resource for defining the health checks for a workload. | Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
| | 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 | | ||
|
boruszak marked this conversation as resolved.
Outdated
boruszak marked this conversation as resolved.
Outdated
|
||
| | Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | Service intentions | None | Defined by user in Consul | | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| 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. | ||
|
|
||
| ## Changes to Consul’s existing architecture | ||
|
|
||
| The change in data models introduced by the v2 Catalog API impacts several aspects of Consul’s operations. | ||
|
|
||
| ### Traffic permissions resource replaces service intentions | ||
|
|
||
| The most significant change to Consul’s architecture and operations when using the v2 catalog structure is the introduction of the TrafficPermissions resource. This resource replaces the service intentions configuration entry, and enables authorized service-to-service communication for both L4 and L7 applications. | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| For more information about this resource, including example configurations, refer to [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions). | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| ### HTTPRoute and GRPCRoute resources for L7 traffic management | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
|
|
||
| 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 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 resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information. | ||
|
boruszak marked this conversation as resolved.
Outdated
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.