Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Nitya Dhanushkodi <nitya@hashicorp.com>
  • Loading branch information
3 people authored Oct 31, 2023
1 parent 7b1b91a commit ead5752
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 21 deletions.
4 changes: 2 additions & 2 deletions website/content/docs/architecture/catalog/v1.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ For more information about the information returned when querying the catalog, i

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.

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).
Consul uses v1 of the catalog API by default. Consul v1.17.0 and later ships with version 2 (v2) of the catalog API. V2 is intended to be used for testing and development purposes. V1 and V2 of the catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/catalog/v2).

## Catalog structure

Expand All @@ -29,7 +29,7 @@ When Consul registers a service instance using the v1 catalog API, it records th
| 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 |
| Agent Check | The health checks defined for a service instance managed by a Consul client 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 |
Expand Down
22 changes: 11 additions & 11 deletions website/content/docs/architecture/catalog/v2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ description: Learn about version 2 of the Consul catalog, which uses GAMMA speci
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>

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.
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.

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).

Expand All @@ -26,7 +26,7 @@ This information enables Consul to associate service names with the individual i

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.

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.
The v2 catalog API addresses limitations with the v1 catalog API, allowing functionality such as associating Kubernetes Pods with multiple Kubernetes Services, or allowing Services and Pods registered with Consul to have multiple ports. The v2 catalog APIs align more closely with upstream Kubernetes APIs and some concepts differ from the v1 APIs. These differences are described in the catalog structure section below.

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.

Expand All @@ -36,15 +36,15 @@ 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 | Source |
| Catalog v2 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 |
| 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 | Kubernetes 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 Pod | Defined by user in Kubernetes |
| Workload identities | Provides a distinct identity for a workload to assume and is used for Traffic Permissions. | Service instance | Kubernetes Service Accounts | Defined by user in Kubernetes |
| Service endpoints | Maps services to workload addresses and endpoints. | None | Kubernetes Endpoints | 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 |
| Health check | A resource for defining the health checks for a workload. | Service Instance 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 |
Expand All @@ -57,9 +57,9 @@ The change in data models introduced by the v2 Catalog API impacts several aspec

### 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.
The most significant change to Consul’s architecture and operations when using the v2 catalog structure is the introduction of the traffic permissions resource. This resource replaces the service intentions configuration entry, and enables authorized service-to-service communication for both L4 and L7 applications.

For more information about this resource, including example configurations, refer to [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
For more information about this resource, including example configurations, refer to [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).

### HTTPRoute and GRPCRoute resources for L7 traffic management

Expand Down
2 changes: 1 addition & 1 deletion website/content/docs/k8s/multiport/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ For an example configuration and instructions for each of the steps in this work

Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:

- Consul client agents do not support multi-port services or the v2 catalog API beta. Kubernetes deployments support multi-port services using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents.
- The v2 catalog API only supports using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. This is the default deployment mode in Kubernetes.
- The v1 and v2 catalog APIs cannot run concurrently.
- The Consul UI does not support multi-port services or the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API.
- HCP Consul does not support multi-port services or the v2 catalog API in this release. You cannot [link a self-managed cluster to HCP Consul](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +35,15 @@ You can issue the following subcommands with the `consul resource` command.
### `apply`

`consul resource apply` writes or updates a resource at a given file path.
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).

| ACL Required |
| ------------ |
| `operator:write` |
You must present a token with `operator:write` [ACL permissions](/consul/api-docs/api-structure#authentication) to use the `apply` command.

#### Command Options

- `-f=<filepath>` - (Required) The path to the file that defines the Consul resource. When the file that defines the resource is in the current working directory, you may optionally omit this flag and pass the resource filename only.

#### Example usage

The following command applies a TrafficPermissions resource to Consul that restricts service-to-service communication to authorized services only.
The following command applies a traffic permissions resource to Consul that restricts service-to-service communication to authorized services only.

```shell-session hideClipboard
$ consul resource apply -f=trafficpermissions.yaml
Expand All @@ -69,7 +65,7 @@ The table below shows this command's [required ACLs](/consul/api-docs/api-struct

#### Example usage

The following command removes a TrafficPermissions resource from Consul that restricts service-to-service communication to authorized services only.
The following command removes a traffic permissions resource from Consul that restricts service-to-service communication to authorized services only.

```shell-session hideClipboard
$ consul resource delete -f=trafficpermissions.yaml
Expand Down

0 comments on commit ead5752

Please sign in to comment.