Deploy Kong Mesh in Production with Helm

To install a production-ready Kong Mesh, you must ensure that the service mesh is secure, reliable, and performant. When deploying Kong Mesh on Kubernetes, use the provided values here to deploy your Kong Mesh installation.

Instructions on this page are meant to be the starting point for your installation. It’s always recommended to read the full Helm configuration reference to find support for other options available before executing the install steps. Values provided here will override values in the default reference Helm configuration, and they may be overridden again by further values.yaml files or arguments of the helm command. See the Helm documentation to learn more about how values are calculated.

Values on this page may reference resources that need to be created in advance when certain features are enabled, read the file content carefully and prepare these resources according to the notes near the keywords (action). If you decide to disable a feature that requires a pre-existing resource, remove or change those fields according to the full Helm configuration reference.

Single zone control plane

Multi-zone global control plane

Multi-zone federated zone control planes

Install a single zone control plane:

helm install kong-mesh kong-mesh/kong-mesh --namespace kong-mesh-system -f ./values.single-zone-cp.yaml

Suggested values.yaml file:

kuma:
  controlPlane:
    mode: "zone"

    tls:
      apiServer:
        # (action): please prepare the content of this secret before installing Kong Mesh
        # it contains the keys "tls.crt" and "tls.key", and the content items should be in "PEM" format
        # more details on preparing certificates: https://docs.konghq.com/mesh/latest/production/secure-deployment/certificates/
        secretName: kong-mesh-apiserver-tls

    apiServer:
      corsAllowedDomains:
        # change these values you want to access the control plane API server or Mesh GUI from a custom domain
        - https://localhost:5682
        # if you want to access the API server using the HTTP port, add the following line
        # - http://localhost:5681

    defaults:
      # change these values if you want to open the admin access rights of control plane API server to more groups
      adminRoleGroups:
        - mesh-system:admin
        - system:masters

    envVars:
      # if you want to access the API server using the HTTP port, change the following switch to "true"
      KUMA_API_SERVER_HTTP_ENABLED: "false"

    secrets:
      # (action): please prepare the content of this secret before installing Kong Mesh
      # to obtain this license, please contact your Kong Account Manager and import it into your cluster:
      # kubectl create  -n kong-mesh-system secret generic kong-mesh-license --from-file license.json=$KMESH_LICENSE_FILE
      - Secret: kong-mesh-license
        Key: license.json
        Env: KMESH_LICENSE_INLINE

    # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed.
    # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
    # more details on sizing the CP: https://docs.konghq.com/mesh/latest/introduction/kuma-requirements/#sizing-your-control-plane
    resources:
      requests:
        cpu: 1000m
        memory: 1024Mi
      limits:
        cpu: 1000m
        memory: 1024Mi

    replicas: 2
    autoscaling:
      enabled: true

      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 50
        - type: Resource
          resource:
            name: memory
            target:
              type: Utilization
              averageUtilization: 50


    podDisruptionBudget:
      enabled: true

  cni:
    # -- Install Kuma with CNI instead of proxy init container
    enabled: false
    resources:
      requests:
        cpu: 100m
        memory: 100Mi
      limits:
        cpu: 100m
        memory: 100Mi

ratelimit:
  # -- Whether Ratelimit Service should be deployed
  enabled: false
  replicas: 2
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    metrics:
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 80

  # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed.
  # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 500m
      memory: 512Mi

  secrets:
    # (action): please prepare the content of this secret before installing Kong Mesh
    # the value should be set according to your redis server configuration
    # it is only required when the ratelimit component is enabled
    - Secret: ratelimit-redis-auth
      Key: redis-pass
      Env: REDIS_AUTH
global:
  ratelimit:
    servertls:
      enabled: true

Install the global control plane for a multi-zone deployment:

helm install kong-mesh kong-mesh/kong-mesh --namespace kong-mesh-system -f ./values.global-cp.yaml

Suggested values.yaml file:

kuma:
  controlPlane:
    mode: "global"

    tls:
      apiServer:
        # (action): please prepare the content of this secret before installing Kong Mesh
        # it contains the keys "tls.crt" and "tls.key", and the content items should be in "PEM" format
        # more details on preparing certificates: https://docs.konghq.com/mesh/latest/production/secure-deployment/certificates/
        secretName: kong-mesh-apiserver-tls
      kdsGlobalServer:
        # (action): please prepare the content of this secret before installing Kong Mesh
        # it contains the keys "ca.crt", "tls.crt" and "tls.key", and the content items should be in "PEM" format
        # more details on preparing certificates: https://docs.konghq.com/mesh/latest/production/secure-deployment/certificates/
        secretName: kong-mesh-kds-global-server-tls

    apiServer:
      corsAllowedDomains:
        # change these values you want to access the control plane API server or Mesh GUI from a custom domain
        - https://localhost:5682
      # if you want to access the API server using the HTTP port, add the following line
      # - http://localhost:5681

    defaults:
      # change these values if you want to open the admin access rights of control plane API server to more groups
      adminRoleGroups:
        - mesh-system:admin
        - system:masters

    envVars:
      # if you want to access the API server using the HTTP port, change the following switch to "true"
      KUMA_API_SERVER_HTTP_ENABLED: "false"

    secrets:
      # (action): please prepare the content of this secret before installing Kong Mesh
      # to obtain this license, please contact your Kong Account Manager and import it into your cluster:
      # kubectl create  -n kong-mesh-system secret generic kong-mesh-license --from-file license.json=$KMESH_LICENSE_FILE
      - Secret: kong-mesh-license
        Key: license.json
        Env: KMESH_LICENSE_INLINE

    # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed
    # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
    # more details on sizing the CP: https://docs.konghq.com/mesh/latest/introduction/kuma-requirements/#sizing-your-control-plane
    resources:
      requests:
        cpu: 1000m
        memory: 1024Mi
      limits:
        cpu: 1000m
        memory: 1024Mi

    replicas: 2
    autoscaling:
      enabled: true

      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 50
        - type: Resource
          resource:
            name: memory
            target:
              type: Utilization
              averageUtilization: 50


    podDisruptionBudget:
      enabled: true

The values on this page may reference resources that need to be created in advance when certain features are enabled, read the file content carefully and prepare these resources according to the notes near the keywords (action). If you decide to disable a feature that requires a pre-existing resource, remove or change those fields according to the full Helm configuration reference.

Install federated zone control planes for a multi-zone deployment:

helm install kong-mesh kong-mesh/kong-mesh --namespace kong-mesh-system -f ./values.federated-zone-cp.yaml \
  --set 'kuma.controlPlane.zone=zone-prod' \
  --set 'kuma.controlPlane.kdsGlobalAddress=kds-global.example.com'

Suggested values.yaml file:

kuma:
  controlPlane:
    mode: "zone"
    # (action): please specify a name for the zone
    zone:

    tls:
      apiServer:
        # (action): please prepare the content of this secret before installing Kong Mesh
        # it contains the keys "tls.crt" and "tls.key", and the content items should be in "PEM" format
        # more details on preparing certificates: https://docs.konghq.com/mesh/latest/production/secure-deployment/certificates/
        secretName: kong-mesh-apiserver-tls
        kdsZoneClient:
          # (action): please prepare the content of this secret before installing Kong Mesh
          # the certificate can be extracted from the trusted global CP server
          # it should contain the key "ca.crt", and the content certificate should be in "PEM" format
          # more details on certificates verifying: https://docs.konghq.com/mesh/latest/production/secure-deployment/certificates/#control-plane-to-control-plane-multizone
          secretName: kong-mesh-kds-global-ca
          skipVerify: false

    apiServer:
      corsAllowedDomains:
        # change these values you want to access the control plane API server or Mesh GUI from a custom domain
        - https://localhost:5682
        # if you want to access the API server using the HTTP port, add the following line
        # - http://localhost:5681

    defaults:
      # change these values if you want to open the admin access rights of control plane API server to more groups
      adminRoleGroups:
        - mesh-system:admin
        - system:masters

    # (action): please specify the address of the global CP
    # e.g. grpcs://my-global-cp.my-hostname.com:5685
    kdsGlobalAddress: ""

    envVars:
      KMESH_MULTIZONE_GLOBAL_KDS_AUTH_TYPE: cpToken
      # if you want to access the API server using the HTTP port, change the following switch to "true"
      KUMA_API_SERVER_HTTP_ENABLED: "false"

    secrets:
      # (action): please prepare the content of this secret before installing Kong Mesh
      # the CP token is only required when installing a zone CP that is connecting to a global CP
      # to obtain this CP token, please generate it using the `kumactl` connecting to the global CP
      # kumactl generate zone-token --zone <zone-name> --scope cp --valid-for 43920h > $TOKEN_FLIE
      # kubectl create  -n kong-mesh-system secret generic kong-mesh-global-cp-token --from-file token=$TOKEN_FLIE
      - Secret: kong-mesh-global-cp-token
        Key: token
        Env: KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE

    # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed.
    # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
    # more detail on sizing the CP: https://docs.konghq.com/mesh/latest/introduction/kuma-requirements/#sizing-your-control-plane
    resources:
      requests:
        cpu: 1000m
        memory: 1024Mi
      limits:
        cpu: 1000m
        memory: 1024Mi

    replicas: 2
    autoscaling:
      enabled: true

      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 50
        - type: Resource
          resource:
            name: memory
            target:
              type: Utilization
              averageUtilization: 50


    podDisruptionBudget:
      enabled: true

  cni:
    # -- Install Kuma with CNI instead of proxy init container
    enabled: false
    resources:
      requests:
        cpu: 100m
        memory: 100Mi
      limits:
        cpu: 100m
        memory: 100Mi

  ingress:
    # -- If true, it deploys Ingress for cross cluster communication
    enabled: false
    # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed.
    # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
    resources:
      requests:
        cpu: 1000m
        memory: 1024Mi
      limits:
        cpu: 1000m
        memory: 1024Mi

    replicas: 2
    autoscaling:
      enabled: true
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 50
        - type: Resource
          resource:
            name: memory
            target:
              type: Utilization
              averageUtilization: 50

    podDisruptionBudget:
      enabled: true

ratelimit:
  # -- Whether Ratelimit Service should be deployed
  enabled: false
  replicas: 2
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    metrics:
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 80

  # please tune the resource allocation according to your actual mesh size and traffic load after Kong Mesh is installed.
  # try to make the resource limits identical to requests to make components are assigned as a QoS class of Guaranteed
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 500m
      memory: 512Mi

  secrets:
    # (action): please prepare the content of this secret before installing Kong Mesh
    # the value should be set according to your redis server configuration
    # it is only required when the ratelimit component is enabled
    - Secret: ratelimit-redis-auth
      Key: redis-pass
      Env: REDIS_AUTH
global:
  ratelimit:
    servertls:
      enabled: true