Skip to main content

Configuring Ingress for a Hyperstack Kubernetes Cluster

Overview​

Ingress in Kubernetes provides external access to services within a cluster by routing requests based on defined rules. This guide explains how to set up an Ingress resource for a Hyperstack Kubernetes cluster to expose a service using a domain name.

Hyperstack assigns a publicly available wildcard domain to each cluster, enabling remote access. This wildcard domain appears in the api_address field of the cluster object and can also be used for ingress.

Example API address:​

"api_address": "https://api.example-50-xyz123.canada.hyperstackcustomers.cloud:6443"

In this case, the wildcard domain is:
"*.example-50-xyz123.canada.hyperstackcustomers.cloud".

This wildcard domain can be used for ingress, enabling access to services within the cluster via subdomains.

Prerequisites​

  • A Kubernetes cluster deployed on Hyperstack. Click here to learn how to deploy one.
  • kubectl configured to access the cluster
  • A deployed service (e.g., vLLM in this example)

Steps to Set Up Ingress​

  1. Get the Cluster API address​

    Retrieve the cluster's domain from its API address using the Retrieve Cluster Details API.

    The API response will provide the cluster API address in the format:

    "api_address": "https://api.example-50-xyz123.canada.hyperstackcustomers.cloud:6443"

  2. Define the ingress resource​

    The host in the Ingress resource can be any domain that resolves to the load balancer's public IP address. Users can set up their own domains to use with Ingress. For example, if you own example.com and configure a DNS record pointing app.example.com to the cluster's load balancer IP, you can use app.example.com as the Ingress host.

    Replace <cluster-domain> with your cluster's wildcard domain and <subdomain> with a custom subdomain.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: vllm-ingress
      namespace: vllm-ns
      annotations:
        nginx.ingress.kubernetes.io/rewrite-target: /
    spec:
      ingressClassName: nginx
      rules:
      - host: <subdomain>.<cluster-domain>
        http:
          paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: vllm-openai-svc
                port:
                  number: 8000

  3. Nginx ingress controller on Hyperstack​

    The Nginx Ingress Controller is installed by default in Hyperstack clusters. You can verify that it is running with:

    kubectl get pods -n ingress-nginx

  4. Apply the ingress configuration​

    Save the manifest as ingress.yaml and apply it using:

    kubectl apply -f ingress.yaml

  5. Verify the ingress setup​

    Once the Ingress Controller is confirmed to be running, check if the Ingress resource is created successfully:

    kubectl get ingress -n <namespace>

    Replace <namespace> with the namespace where your service is deployed. The output should list the assigned external IP and host.

    note

    vllm is used as an example in this guide. If you are exposing a different service, replace vllm with the appropriate service name and namespace in your Ingress configuration.

  6. Access the service​

    Once the Ingress is configured, you can access the service using:

    http://<subdomain>.<cluster-api>