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 Replicated kURL or Replicated Embedded Cluster installations, see Exposing Services Using NodePorts.

Overview​

For 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. In addition to the 8800 Admin Console port, you can optionally add one or more extra ports to the port forward tunnel.

Adding ports to the port forward tunnel allows you to port forward application services without needing to manually run the kubectl port-forward command. You can also add a link to the Admin Console dashboard that points to port-forwarded services.

This can be particularly useful when developing and testing KOTS releases for your application, because it provides a quicker way to access an application after installation compared to setting up an ingress controller or adding a load balancer.

Port Forward a Service with the KOTS Application ports Key​

To port forward a service with KOTS for existing cluster installations:

  1. In a new release, configure the ports key in the KOTS Application custom resource with details for the target service. For example:

    apiVersion: kots.io/v1beta1
    kind: Application
    metadata:
      name: my-application
    spec:
      ports:
        - serviceName: my-service
          servicePort: 3000
          localPort: 8888

    1. For ports.serviceName, add the name of the service. 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.

    2. For ports.servicePort, add 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.

    3. For ports.localPort, add the port to map on the local workstation.

  2. Promote the release to the channel that you use for internal testing, then install in a development environment to test your changes.

    When the application is in a Ready state and the KOTS port forward is running, you will see output similar to the following:

    • Press Ctrl+C to exit
    • Go to http://localhost:8800 to access the Admin Console
    • Go to http://localhost:8888 to access the application

    Confirm that you can access the service at the URL provided in the KOTS CLI output.

  3. (Optional) Add a link to the service on the Admin Console dashboard. See Add a Link to a Port-Forwarded Service on the Admin Console Dashboard below.

After you add a service to the KOTS port forward tunnel, you can also optionally add a link to the port-forwarded service on the Admin Console dashboard.

To add a link to a port-forwarded service, add the same URL in the KOTS Application custom resource ports.applicationURL and Kubernetes SIG Application custom resource spec.descriptor.links.url fields. When the URLs in these fields match, KOTS adds a link on the Admin Console dashboard where the given service can be accessed. This process automatically links to the hostname in the browser (where the Admin Console is being accessed) and appends the specified localPort.

To add a link to a port-forwarded service on the Admin Console dashboard:

  1. In a new release, open the KOTS Application custom resource and add a URL to the ports.applicationURL field. For example:

    apiVersion: kots.io/v1beta1
    kind: Application
    metadata:
     name: my-application
    spec:
     ports:
       - serviceName: my-service
         servicePort: 3000
         localPort: 8888
         applicationUrl: "http://my-service"

    Consider the following guidelines for this URL:

    • Use HTTP instead of HTTPS unless TLS termination takes place in the application Pod.
    • KOTS rewrites the URL with the hostname in the browser during deployment. So, you can use any hostname for the URL, such as the name of the service. For example, http://my-service.

  2. Add a Kubernetes SIG Application custom resource in the release. For example:

    # app.k8s.io/v1beta1 Application Custom resource

    apiVersion: app.k8s.io/v1beta1
    kind: Application
    metadata:
      name: "my-application"
    spec:
      descriptor:
        links:
          - description: Open App
            # url matches ports.applicationURL in the KOTS Application custom resource
            url: "http://my-service"

    1. For spec.descriptor.links.description, add the link text that will appear on the Admin Console dashboard. For example, Open App.

    2. For spec.descriptor.links.url, add the same URL that you used in the ports.applicationURL in the KOTS Application custom resource.

  3. Promote the release to the channel that you use for internal testing, then install in a development environment to test your changes.

    When the application is in a Ready state, confirm that you can access the service by clicking the link that appears on the dashboard. For example:

    Admin Console dashboard with Open App link

    View a larger version of this image

Access Port-Forwarded Services​

This section describes how to access port-forwarded services.

Command Line​

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 Admin Console and any port-forwarded services can be accessed. For more information about the kubectl port-forward command, see port-forward in the Kubernetes documentation.

For 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​

You can optionally add a link to a port-forwarded service from the Admin Console dashboard. This requires additional configuration. For more information, see Add a Link to a Port-Forwarded Service on the Admin Console Dashboard.

The following example shows an Open App link 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 provides examples of how to configure the ports key to port-forward a service in existing cluster installations and add links to services on the Admin Console dashboard.

Example: Bitnami Gitea Helm Chart with LoadBalancer Service​

This example uses a KOTS Application custom resource and a Kubernetes SIG Application custom resource to configure port forwarding for the Bitnami Gitea Helm chart in existing cluster installations, and add a link to the port-forwarded service on the Admin Console dashboard. 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 to confirm that the service was port-forwarded successfully. To test the port forward, click Open App on the Admin Console dashboard after the application reaches a Ready state. For more information, see Online Installation in Existing Clusters.

Example: NGINX Application with ClusterIP and NodePort Services​

The following example demonstrates how to link to a port-forwarded ClusterIP service for existing cluster installations.

It also shows how to use the ports key to add a link to a NodePort service for kURL installations. Although the primary purpose of the ports key is to port forward services for existing cluster installations, it is also possible to use the ports key so that links to NodePort services for Embedded Cluster or kURL installations use the hostname in the browser. For information about exposing NodePort services for Embedded Cluster or kURL installations, see Exposing Services Using NodePorts.

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 kURL installer promoted to the channel, add a kURL installer to the release to support kURL installs. For more information, see Creating a kURL Installer.

  4. Install the release on a VM and confirm that the service was exposed successfully. To test the port forward, click Open App on the Admin Console dashboard after the application reaches a Ready state. For more information, see Online Installation with kURL.

    note

    Ensure that the VM where you install allows HTTP traffic.