Skip to main content

Port Forwarding Services with KOTS

This topic describes how to add one or more ports to the Replicated KOTS port forward tunnel by configuring the ports key in the KOTS Application custom resource.

The information in this topic applies to existing cluster installations. For information about exposing services for embedded cluster installations with Replicated kURL, see Exposing Services Using NodePorts.

Overview​

When distributing an application, it is helpful to ensure that the person or process installing the application is able to easily verify that the application is running. However, networking and ingress is handled differently in each cluster, and this makes it difficult to provide a consistent application URL at installation. Additionally, the cluster operator might be required to create firewall rules before they can open the application.

To address these challenges with installations into existing clusters, KOTS automatically creates a port forward tunnel and exposes the admin console on port 8800 where it can be accessed by users at installation.

In addition to the 8800 admin console port, you can configure the KOTS Application custom resource to add one or more extra ports to the port forward tunnel so that users installing in exsting clusters can easily access your application at installation. For example, you can:

  • List the primary application ports to provide one or more links directly to the application before ingress and firewalls are configured
  • List the ports for internal services, such as application admin controls and other services that are not exposed to all users

Configure Port Forwarding​

This section describes how to configure port forwarding for existing cluster installations by adding extra ports to the ports key in the KOTS Application custom resource.

The following example KOTS Application custom resource includes a ports key that allows users to access a gitea service at port 8888 on the local machine at installation:

apiVersion: kots.io/v1beta1
kind: Application
metadata:
  name: gitea
spec:
  title: Gitea
  statusInformers:
    - deployment/gitea
  ports:
    - serviceName: "gitea"
      servicePort: 3000
      localPort: 8888
      applicationUrl: "http://gitea"
  icon: https://raw.githubusercontent.com/cncf/artwork/master/projects/kubernetes/icon/color/kubernetes-icon-color.png

As shown in the example above, the ports key has the following fields:

  • ports.serviceName: The name of the service that receives the traffic. KOTS can create a port forward to ClusterIP, NodePort, or LoadBalancer services. For more information about Kubernetes service types, see Service in the Kubernetes documentation.

  • ports.servicePort: The containerPort of the Pod where the service is running. This is the port where KOTS forwards traffic.

    • note

    Ensure that you use the containerPort and not the servicePort. The containerPort and servicePort are often the same port, though it is possible that they are different.

  • ports.localPort: (Optional) If set, the port to map on the local workstation. If not set, this is the same as servicePort.

  • ports.applicationUrl: (Optional) The URL used by links to the port-forwarded service from the admin console dashboard. ports.applicationUrl must match a service found in the Kubernetes Application manifest in the release. For example, ports.applicationUrl: "http://my-application-url" in the KOTS Application custom resource must match descriptor.links.url: http://my-application-url in the Kubernetes Application manifest.

    • For more information about how to add a link to a port-forwarded service from the admin console, see Adding Application Links to the Dashboard.

Access Port-Forwarded Services​

When you configure port forwarding for existing cluster installations, your users can access the port-forwarded services by getting the URL from the kots CLI or by clicking a link on the admin console dashboard.

Command Line​

Users can run kubectl kots admin-console to open the KOTS port forward tunnel.

The kots admin-console command runs the equivalent of kubectl port-forward svc/myapplication-service <local-port>:<remote-port>, then prints a message with the URLs where the user can access the admin console and any port-forwarded services. For more information about the kubectl port-forward command, see port-forward in the Kubernetes documentation.

Example:

kubectl kots admin-console --namespace gitea
• Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console
• Go to http://localhost:8888 to access the application

Admin Console​

Users can access port-forwarded services by clicking a link on the admin console dashboard. Additional configuration is required to add a link to the dashboard. For more information, see Adding Application Links to the Dashboard.

The following example shows an Open App button on the dashboard of the admin console for an application named Gitea:

admin console dashboard with Open App link

View a larger version of this image

Examples​

This section includes examples for configuring port forwarding for Helm chart-based applications and applications that use standard manifests.

NGINX Application with ClusterIP and NodePort Services​

The following example demonstrates how to expose a basic NGINX service for both existing cluster and embedded cluster installations.

To test this example:

  1. Add the example-service.yaml, example-deployment.yaml, kots-app.yaml, and k8s-app.yaml files provided below to a new, empty release in the vendor portal. Promote to the channel that you use for internal testing.

    For more information, see Managing Releases with the Vendor Portal.

    Description

    The YAML below contains ClusterIP and NodePort specifications for a service named nginx. Each specification uses the kots.io/when annotation with the Replicated IsKurl template function to conditionally include the service based on the installation type (existing cluster or embedded kURL cluster). For more information, see Conditionally Including or Excluding Resources and IsKurl.

    As shown below, both the ClusterIP and NodePort nginx services are exposed on port 80.

    YAML
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
      annotations:
        kots.io/when: '{{repl not IsKurl }}'
    spec:
      type: ClusterIP
      ports:
        - port: 80
      selector:
        app: nginx
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
      annotations:
        kots.io/when: '{{repl IsKurl }}'
    spec:
      type: NodePort
      ports:
        - port: 80
          nodePort: 8888
      selector:
        app: nginx

  2. Install the release into an existing cluster and confirm that the service was port-forwarded successfully by clicking Open App on the admin console dashboard. For more information, see Online Installation in Existing Clusters.

  3. If there is not already a Kubernetes installer promoted to the channel, add a Kubernetes installer to the release to support embedded cluster installs. For more information, see Creating a Kubernetes Installer.

  4. Install the release into an embedded cluster on a VM and confirm that the service was exposed successfully by clicking Open App on the admin console dashboard. For more information, see Online Installation in Embedded Clusters.

    note

    Ensure that the VM where you install allows HTTP traffic.

Bitnami Gitea Helm Chart with LoadBalancer Service​

This example provides a KOTS Application custom resource and Kubernetes Application custom resource to configure port forwarding for the Bitnami Gitea Helm chart in existing cluster installations. To view the Gitea Helm chart source, see bitnami/gitea in GitHub.

To test this example:

  1. Pull version 1.0.6 of the Gitea Helm chart from Bitnami:

    helm pull oci://registry-1.docker.io/bitnamicharts/gitea --version 1.0.6

  2. Add the gitea-1.0.6.tgz chart archive to a new, empty release in the vendor portal along with the kots-app.yaml, k8s-app.yaml, and gitea.yaml files provided below. Promote to the channel that you use for internal testing.

    For more information, see Managing Releases with the Vendor Portal.

    Description

    Based on the templates/svc.yaml and values.yaml files in the Gitea Helm chart, the following KOTS Application custom resource adds port 3000 to the port forward tunnel and maps local port 8888. Port 3000 is the container port of the Pod where the gitea service runs.

    YAML
    apiVersion: kots.io/v1beta1
    kind: Application
    metadata:
      name: gitea
    spec:
      title: Gitea
      statusInformers:
        - deployment/gitea
      ports:
        - serviceName: "gitea"
          servicePort: 3000
          localPort: 8888
          applicationUrl: "http://gitea"
      icon: https://raw.githubusercontent.com/cncf/artwork/master/projects/kubernetes/icon/color/kubernetes-icon-color.png

  3. Install the release into an existing cluster and confirm that the service was port-forwarded successfully by clicking Open App on the admin console dashboard. For more information, see Online Installation in Existing Clusters.

Additional Resources and Examples​

The following articles on the Replicated Community site provide additional information and examples related to configuring port forwarding: