You are browsing unreleased documentation. See the latest documentation here.

Sidecar

Sidecar deployments are officially supported, but discouraged. We recommend using Gateway Discovery going forwards.

Overview

Sidecar deployment is the original method of deployment for Kong Ingress Controller. Both the controller and Kong Gateway are deployed in a single Pod and each Kong Gateway instance was managed by a different Kong Ingress Controller.

This is the simplest deployment method as everything is contained in a single deployment and the controller can communicate to Kong Gateway on localhost.

Sidecar deployments have been deprecated in favor of Gateway Discovery for multiple reasons:

Reduce resource usage as the number of Kong Ingress Controller instances does not scale linearly with Kong Gateway.
Reduce load on the Kubernetes API server. There are fewer clients, and no thrashing behaviour as multiple controllers argue of the programmed state of a resource.
Scale Kong Ingress Controller and Kong Gateway independently as needed.

Sidecar Architecture Diagram

Migrating to Gateway Discovery

If you see two containers running in the same Pod, it’s likely that you’re running Kong Ingress Controller in Sidecar mode.

NAME                         READY   STATUS    RESTARTS   AGE
kong-kong-7f5bddf88c-f5r9h   2/2     Running   0          89s

Verify that one of the running containers is ingress-controller:

$ kubectl get pods -n kong kong-kong-7f5bddf88c-wfm6b -o jsonpath='{.spec.containers[*].name}'

The result should contain ingress-controller:

ingress-controller proxy

You can migrate from the Sidecar deployment topology to Gateway Discovery by disabling Kong Ingress Controller in your proxy deployment and creating a new Helm release that contains Kong Ingress Controller.

The existing proxy pod will continue to handle traffic until the final step of the migration. This leads to minimal downtime.

Update your values.yaml file to disable Kong Ingress Controller and make the Admin API accessible:

ingressController:
  enabled: false

admin:
  enabled: true
  type: ClusterIP
  clusterIP: None

The new Proxy Pod won’t come online as there is no available configuration.

2023/10/27 15:32:43 [notice] 1257#0: *301 [lua] ready.lua:111: fn(): not ready for proxying: no configuration available (empty configuration present), client: 192.168.194.1, server: kong_status, request: "GET /status/ready HTTP/1.1", host: "192.168.194.9:8100

To send a configuration to the Proxy pod, deploy a new instance of Kong Ingress Controller that points to the Admin API service. Create values-controller.yaml with the following contents:

ingressController:
  enabled: true
  gatewayDiscovery:
    enabled: true
    adminApiService:
      name: kong-kong-admin

deployment:
  kong:
    enabled: false

kong-kong-admin is the default name if your release is called kong. Run kubectl get services -n kong to find the correct name

Create a new controller deployment using Helm.

helm install controller kong/kong --values ./values-controller.yaml -n kong

The new Pods do not come online as the controller can’t access the Admin API for the original Proxy Pod. Delete the old Proxy Pod to allow Gateway Discovery to work.

There may be a small amount of downtime of up to three seconds between the Pod being deleted and new proxy pods receiving a configuration.

kubectl get pods -n kong

Find the Pod with two containers. This is the old Sidecar topology that needs to be deleted.

NAME                               READY   STATUS    RESTARTS   AGE
kong-kong-7f5bddf88c-6cnlq         2/2     Running   0          2m

Delete the Pod.

kubectl delete pod -n kong kong-kong-7f5bddf88c-6cnlq

At this point there are two Pods running. controller-kong contains Kong Ingress Controller and kong-kong contains Kong Gateway

NAME                               READY   STATUS    RESTARTS        AGE
kong-kong-7554ff7db4-d849p         1/1     Running   0               12m
controller-kong-644fb7f694-zw7sk   1/1     Running   1               12m