---
layout: docs
page_title: Consul v2 architecture
description: Learn about version 2 of Consul's internal architecture, which replaces services and service instances with workloads and workload identies.
---

# Consul v2 architecture

This topic provides an overview of Consul's v2 architecture changes and their impact on Consul operations. 

In the v1.17.0 release, Consul introduced the option to enable the [v2 catalog API](/consul/docs/architecture/v2/catalog) for testing and development on Kubernetes deployments. The v2 catalog is one of several changes in development to simplify and streamline Consul's architecture.

## Overview

The v2 architecture changes include the following:

- [v2 catalog API](/consul/docs/architecture/v2/catalog)
- [Resource groups](/consul/docs/architecture/v2/groups)

## Differences between v1 and v2

The change in data models introduced by the v2 architecture 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 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 [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).

### HTTPRoute, GRPCRoute, and TCPRoute resources for traffic management

You can configure traffic management behavior such as service splitting in an `HTTPRoute`, `GRPCRoute`, or `TCPRoute` 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), [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute), and [TCPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/tcproute).

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

In the v2 catalog, the `ProxyConfiguration` resource configures a workload's sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information.

## Constraints and limitations

Be aware of the following constraints and technical limitations on the v2 catalog API:

- The v2 catalog API only supports deployments using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. Consul on Kubernetes uses dataplanes by default.
- The v1 and v2 catalog APIs cannot run concurrently. Because configuration entries are part of the v1 catalog, you cannot use them when the v2 catalog is enabled. Use v2 resources instead.
- The Consul UI does not support the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API.
- Secondary datacenters in WAN-federated deployments cannot enable the v2 catalog API in this release.
- HCP Consul does not support 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.
- We do not recommend updating existing clusters to enable the v2 catalog in this release. Instead, deploy a new Consul cluster and [enable the v2 catalog in the Helm chart](/consul/docs/k8s/multiport/configure#enable-the-v2-catalog).

## Guidance

The following resources are available to help you use the v2 catalog API:

### Usage documentation

- [use the v2 Catalog API](/consul/docs/k8s/multiport)
- [Configure multi-port services](/consul/docs/k8s/multiport/configure)
- [Split TCP traffic between multiple ports](/consul/docs/k8s/multiport/traffic-split)

### Reference documentation

- [`consul resource` CLI command](/consul/docs/k8s/multiport/reference/resource-command)
- [GRPCRoute configuration reference](/consul/docs/k8s/multiport/reference/grpcroute)
- [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute)
- [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration)
- [TCPRoute configuration reference](/consul/docs/k8s/multiport/reference/tcproute)
- [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions)