Consul on Kubernetes

The consul-k8s-control-plane binary provides first-class integrations between Consul and Kubernetes. Key features include:

• Consul Service Mesh: Injects Envoy sidecars and registers Pods with Consul to enable service mesh capabilities.
• Consul API Gateway: Enables north/south traffic into the Consul Service Mesh.
• Catalog Sync: Synchronizes Consul services with Kubernetes services (and vice versa), allowing Kubernetes to access external services and non-Kubernetes nodes to discover Kubernetes services.

An HTTPRoute is a Kubernetes Gateway API resource used to specify how HTTP requests from a Gateway listener should be routed to backend API objects (typically Kubernetes Services).

An HTTPRoute consists of three main components in its specification:

1. parentRefs: Defines which Gateways the route attaches to.
2. hostnames (optional): Defines which Host headers the route matches.
3. rules: Defines the logic for matching requests (via matches) and taking actions (via filters and backendRefs).

Incoming requests are first matched against hostnames. If a match occurs, the HTTPRoute is selected, and its rules are evaluated to determine the final routing behavior.

Gateway API is a collection of Kubernetes resources designed to enable robust service networking through expressive, extensible, and role-oriented interfaces. It serves as a successor to the standard Ingress API, offering explicit support for multiple protocols including HTTP, TLS, TCP, and UDP, along with tightly integrated Transport Layer Security (TLS) support.

Key characteristics:

• Resource-centric: Centered around Gateway resources which represent underlying network gateways or proxy servers.
• Implementation-agnostic: It is a Custom Resource Definition (CRD) based API. Kubernetes does not provide a default implementation; instead, users must install an implementation (e.g., Consul, Istio, NGINX) that suits their needs.
• Superset of Ingress: It provides more advanced networking concepts than the standard Ingress API.

A GEP is not required for:

• Bug fixes
• Small changes (e.g., minor API validation updates, documentation fixes, or simple fixups).

Note: Reviewers may determine that a "small" change actually requires a formal GEP process.

The GAMMA Initiative (Gateway API for Mesh Management and Administration) is a dedicated workstream focused on using the Gateway API for service mesh use-cases.

It is a collaborative effort involving several service mesh projects including:

• Consul
• Cilium Service Mesh
• Istio
• Kuma
• Linkerd
• NGINX Service Mesh
• Open Service Mesh

The initiative aims to deliver enhancement proposals (GEPs) for mesh-specific requirements, such as service-to-service traffic, authentication, and authorization policies.

Conformance in the Gateway API is defined by the specific resources an implementation supports. Support is categorized into 'Core' and 'Extended' functionality.

Required Resources (Core Support): All implementations must support the Core functionality for:

• GatewayClass
• Gateway
• ReferenceGrant

Optional Resources: Implementations may choose to support these resources, which have defined behaviors if implemented:

• HTTPRoute
• TLSRoute
• TCPRoute
• UDPRoute

Conformance is versioned based on the API's bundle version (e.g., v0.4.0), not the individual CRD version (e.g., v1alpha2). This allows implementations to claim support for a specific version of the Gateway API specification.

Under the GAMMA (Gateway API Mesh Acceleration) initiative, a ServiceImport can be used as a parentRef for a Route. When a ServiceImport is specified as a parent, the mesh intercepts traffic destined for the ClusterSetIP and applies the policies or routing decisions defined in the Route. This allows the mesh to manage and redirect traffic across the entire ClusterSet.

# Example: Using ServiceImport as a ParentRef for mesh interception
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mesh-route
spec:
  parentRefs:
    - name: store
      kind: ServiceImport
  rules:
    - matches:
        - path: { type: PathPrefix, value: /cart }
      backendRefs:
        - name: cart
          kind: ServiceImport
          port: 80

An HTTPRoute can be bound directly to a cluster-scoped Mesh object (as defined in GEP-1291). This allows the route to be part of the mesh context. This approach can be used alone or as a peer to a Service resource parentRef to define routing rules for a specific service on a specific mesh.

Example of binding to a Mesh:

spec:
  parentRefs:
  - kind: Mesh
    name: cool-mesh

Example of using Mesh and Service as peer parentRefs:

spec:
  parentRefs:
  - kind: Mesh
    name: cool-mesh
  - kind: Service
    name: foo

The spec.controllerName field (referred to in documentation as spec.controller) determines which controller implementation is responsible for managing the GatewayClass.

To avoid conflicts in a cluster with multiple controllers, it is recommended to use a unique domain/path combination (e.g., example.net/gateway-controller). You can also implement versioning by encoding the version into the path, such as example.net/gateway/v1 or example.net/gateway/v2.1.