This project is in the process of being donated to the CNCF and is not affiliated with the Kubernetes project.
Documentation
Operations
Install

Install

In this installation guide, you install kgateway in a Kubernetes cluster, set up an API gateway, deploy a sample app, and access that app through the API gateway.

The guide includes steps to install kgateway in two ways.

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.
Argo CD is a declarative continuous delivery tool that is especially popular for large, production-level installations at scale. This approach incorporates Helm configuration files.

Before you begin

⚠️
Keep in mind that you can only have one installation of kgateway at a time. Installing the product twice makes cluster-scoped resources fail, such as GatewayClass. You can still create multiple Gateway resources with different HTTP and HTTPS listeners so that you can have multiple gateway proxies. If you already tried out kgateway by following the Get started guide, first uninstall your installation.
  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.
  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.
    • argo, the Argo CD command line tool.
  3. Install Argo CD in your cluster. 
    kubectl create namespace argocd
until kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.12.3/manifests/install.yaml > /dev/null 2>&1; do sleep 2; done
# wait for deployment to complete
kubectl -n argocd rollout status deploy/argocd-applicationset-controller
kubectl -n argocd rollout status deploy/argocd-dex-server
kubectl -n argocd rollout status deploy/argocd-notifications-controller
kubectl -n argocd rollout status deploy/argocd-redis
kubectl -n argocd rollout status deploy/argocd-repo-server
kubectl -n argocd rollout status deploy/argocd-server
  4. Update the default Argo CD password for the admin user to kgateway. 
    # bcrypt(password)=$2a$10$g3bspLL4iTNQHxJpmPS0A.MtyOiVvdRk1Ds5whv.qSdnKUmqYVyxa
# password: kgateway
kubectl -n argocd patch secret argocd-secret \
  -p '{"stringData": {
    "admin.password": "$2a$10$g3bspLL4iTNQHxJpmPS0A.MtyOiVvdRk1Ds5whv.qSdnKUmqYVyxa",
    "admin.passwordMtime": "'$(date +%FT%T%Z)'"
  }}'

Install kgateway

Install the open source kgateway project in your Kubernetes cluster.

  1. Install the custom resources of the Kubernetes Gateway API version 1.2.0. 
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/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 want to use TCPRoutes to set up a TCP listener on your Gateway, you must install the TCPRoute CRD, which is part of the Kubernetes Gateway API experimental channel. Use the following command to install the CRDs.

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

  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.

    helm pull oci://ghcr.io/kgateway-dev/charts/kgateway --version v2.0.0-main
tar -xvf kgateway-v2.0.0-main.tgz
cat kgateway/values.yaml

  2. Install kgateway. This command creates the kgateway-system namespace and installs the kgateway control plane into it.

    helm install -n kgateway-system kgateway oci://ghcr.io/kgateway-dev/charts/kgateway \
--create-namespace \
--version v2.0.0-main

    Example output:

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

  3. Verify that the kgateway 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

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

    kubectl get gatewayclass kgateway
  1. Install the custom resources of the Kubernetes Gateway API version 1.2.0. 
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/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 want to use TCPRoutes to set up a TCP listener on your Gateway, you must install the TCPRoute CRD, which is part of the Kubernetes Gateway API experimental channel. Use the following command to install the CRDs.

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

  1. Port-forward the Argo CD server on port 9999.

    kubectl port-forward svc/argocd-server -n argocd 9999:443

  2. Open the Argo CD UI.

  3. Log in with the admin username and kgateway password.

  4. Create an Argo CD application to install the kgateway Helm chart.

    kubectl apply -f- <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kgateway-oss-helm
  namespace: argocd
spec:
  destination:
    namespace: kgateway-system
    server: https://kubernetes.default.svc
  project: default
  source:
    chart: kgateway
    helm:
      skipCrds: false
    repoURL: oci://ghcr.io/kgateway-dev/charts/kgateway
    targetRevision: 2.0.0-main
  syncPolicy:
    automated:
      # Prune resources during auto-syncing (default is false)
      prune: true 
      # Sync the app in part when resources are changed only in the target Kubernetes cluster
      # but not in the git source (default is false).
      selfHeal: true 
    syncOptions:
    - CreateNamespace=true 
EOF

  5. Verify that the kgateway control plane is up and running.

    kubectl get pods -n kgateway-system

    Example output:

    NAME                                      READY   STATUS      RESTARTS   AGE
gateway-certgen-wfz9z                     0/1     Completed   0          35s
kgateway-78f4cc8fc6-6hmsq                 1/1     Running     0          21s
kgateway-resource-migration-sx5z4         0/1     Completed   0          48s
kgateway-resource-rollout-28gj6           0/1     Completed   0          21s
kgateway-resource-rollout-check-tjdp7     0/1     Completed   0          2s
kgateway-resource-rollout-cleanup-nj4t8   0/1     Completed   0          39s

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

    kubectl get gatewayclass kgateway

  7. Open the Argo CD UI and verify that you see the Argo CD application with a Healthy and Synced status.

Next steps

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

Cleanup

You can remove the resources that you created in this guide.
Follow the Uninstall guide.
Sample app