Helm

In this installation guide, you install kgateway in a Kubernetes cluster by using Helm. Helm is a popular package manager for Kubernetes configuration files. This approach is flexible for adopting to your own command line, continuous delivery, or other workflows.

Before you begin

1. Create or use an existing Kubernetes cluster.
2. Install the following command-line tools.
   • kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes clusters you plan to use.
   • helm, the Kubernetes package manager.

Install

Install kgateway by using Helm.

1. Install the custom resources of the Kubernetes Gateway API version 1.3.0.

   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

   Example output:

   customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
   customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
   
   ℹ️

   If you need to use an experimental feature such as TCPRoutes, install the experimental CRDs. For more information, see Experimental features in Gateway API.

2. Apply the kgateway CRDs for the upgrade version by using Helm.

   1. Optional: To check the CRDs locally, download the CRDs to a helm directory.

      helm template --version v2.0.4 kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds --output-dir ./helm

   2. Deploy the kgateway CRDs by using Helm. This command creates the kgateway-system namespace and creates the kgateway CRDs in the cluster.

      helm upgrade -i --create-namespace --namespace kgateway-system --version v2.0.4 kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds 

3. Install the kgateway Helm chart.

   1. Optional: Pull and inspect the kgateway Helm chart values before installation. You might want to update the Helm chart values files to customize the installation. For example, you might change the namespace, update the resource limits and requests, or enable extensions such as for AI.

      ℹ️

      For common values that you might want to update, see Installation settings.

      helm pull oci://cr.kgateway.dev/kgateway-dev/charts/kgateway --version v2.0.4
      tar -xvf kgateway-v2.0.4.tgz
      open kgateway/values.yaml

   2. Install kgateway by using Helm. This command installs the control plane into it. If you modified the values.yaml file with custom installation values, add the -f kgateway/values.yaml flag.

      Basic installationCustom values fileDevelopmentAgentgateway and AI extensions

      helm upgrade -i -n kgateway-system kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
      --version v2.0.4

      helm upgrade -i -n kgateway-system kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
      --version v2.0.4 \
      -f kgateway/values.yaml

      When using the development build v2.1.0-main, add the --set controller.image.pullPolicy=Always option to ensure you get the latest image. Alternatively, you can specify the exact image digest.

      helm upgrade -i -n kgateway-system kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
      --version v2.1.0-main \
      --set controller.image.pullPolicy=Always

      helm upgrade -i -n kgateway-system kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
           --set gateway.aiExtension.enabled=true \
           --set agentGateway.enabled=true \
           --version v$NEW_VERSION

      Example output:

      NAME: kgateway
      LAST DEPLOYED: Thu Feb 13 14:03:51 2025
      NAMESPACE: kgateway-system
      STATUS: deployed
      REVISION: 1
      TEST SUITE: None

4. Verify that the control plane is up and running.

   kubectl get pods -n kgateway-system

   Example output:

   NAME                                  READY   STATUS    RESTARTS   AGE
   kgateway-78658959cd-cz6jt             1/1     Running   0          12s

5. Verify that the kgateway GatewayClass is created. You can optionally take a look at how the GatewayClass is configured by adding the -o yaml option to your command.

   kubectl get gatewayclass kgateway

Next steps

Now that you have kgateway set up and running, check out the following guides to expand your API gateway capabilities.

• Learn more about kgateway, its features and benefits.
• Deploy an API gateway and sample app to test out routing to an app.
• Add routing capabilities to your httpbin route by using the Traffic management guides.
• Explore ways to make your routes more resilient by using the Resiliency guides.
• Secure your routes with external authentication and rate limiting policies by using the Security guides.

Cleanup

Follow the Uninstall guide.