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 kgateway in your Kubernetes cluster. Choose from the following installation options:

Helm

Install kgateway by using Helm.

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

    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 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.3 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.3 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.3
tar -xvf kgateway-v2.0.3.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.

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

      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

Argo CD

Install kgateway by using Argo CD.

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

    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 need to use an experimental feature such as TCPRoutes, install the experimental CRDs. For more information, see Experimental features in Gateway API.

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

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

  3. Open the Argo CD UI.

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

  5. Create an Argo CD application to deploy the kgateway CRD Helm chart.

    kubectl apply -f- <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kgateway-crds-helm
  namespace: argocd
spec:
  destination:
    namespace: kgateway-system
    server: https://kubernetes.default.svc
  project: default
  source:
    chart: kgateway-crds
    helm:
      skipCrds: false
    repoURL: cr.kgateway.dev/kgateway-dev/charts
    targetRevision: v2.0.3
  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

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

    kubectl apply -f- <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kgateway-helm
  namespace: argocd
spec:
  destination:
    namespace: kgateway-system
    server: https://kubernetes.default.svc
  project: default
  source:
    chart: kgateway
    helm:
      skipCrds: false
    repoURL: cr.kgateway.dev/kgateway-dev/charts
    targetRevision: v2.0.3
  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

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

  8. 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

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

Installation settings

You can update several installation settings in your Helm values file. For example, you can update the namespace, set resource limits and requests, or enable extensions such as for AI.

Helm reference docs

For more information, see the Helm reference docs.

Helm reference docs

Namespace discovery

You can limit the namespaces that kgateway watches for gateway configuration. For example, you might have a multi-tenant cluster with different namespaces for different tenants. You can limit kgateway to only watch a specific namespace for gateway configuration.

Namespace selectors are a list of matched expressions or labels.

  • matchExpressions: Use this field for more complex selectors where you want to specify an operator such as In or NotIn.
  • matchLabels: Use this field for simple selectors where you want to specify a label key-value pair.

Each entry in the list is disjunctive (OR semantics). This means that a namespace is selected if it matches any selector.

You can also use matched expressions and labels together in the same entry, which is conjunctive (AND semantics).

The following example selects namespaces for discovery that meet either of the following conditions:

  • The namespace has the label environment=prod and the label version=v2, or
  • The namespace has the label version=v3
discoveryNamespaceSelectors:
- matchExpressions:
  - key: environment
    operator: In
    values:
    - prod
  matchLabels:
    version: v2
- matchLabels:
    version: v3

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