Skip to main content

Port Forward 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

    The following table provides more information about how to configure each field:

    FieldInstructions
    ports.serviceNameAdd 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.
    ports.servicePort

    Add the containerPort of the Pod where the service is running. This is the port where KOTS forwards traffic.

    Go templates are not supported in the localPort or servicePort field. For more information, see ports in Application.

    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

    Add the port to map on the local workstation.

    Go templates are not supported in the localPort or servicePort field. For more information, see ports in Application..

  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

Example: NGINX Application with ClusterIP and NodePort Services​

The following example demonstrates how to link to a port-forwarded ClusterIP service for existing cluster KOTS installations. It also shows how to use the ports key to add a link to a NodePort service for Embedded Cluster or kURL installations. Although the primary purpose of the ports key is to port forward services for existing cluster KOTS 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, k8s-app.yaml, and embedded-cluster.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 Manage 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 Distribution template function to conditionally include the service based on the installation type (existing cluster or Embedded Cluster/kURL cluster). For more information, see Conditionally Including or Excluding Resources.

    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{{ and (ne Distribution "embedded-cluster") (ne Distribution "kurl")}}'
    spec:
      type: ClusterIP
      ports:
        - port: 80
      selector:
        app: nginx
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
      annotations:
        kots.io/when: 'repl{{ or (eq Distribution "embedded-cluster") (eq Distribution "kurl")}}'
    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 with KOTS.

  3. Install the release on a VM and confirm that you can open the application by clicking Open App on the Admin Console dashboard. For more information, see Online Installation with Embedded Cluster or Online Installation with kURL.

    note

    Ensure that the VM where you install allows HTTP traffic.

    note

    If you used Replicated Compatibility Matrix to create the VM, follow the steps in Expose Ports on Running VMs to add these DNS records to the VM:

    • A DNS record with a Target Port of 30000 to get a hostname where you can access the Admin Console
    • A DNS record with a Target Port of 8888 to get a hostname where you can access the NGINX application