Adding Buttons and Links
This topic describes how to use the Kubernetes and KOTS Application custom resources to add buttons and links to the Replicated admin console dashboard.
Overview
When distributing an application, it’s helpful to make sure that the person or process performing the installation can easily verify that the application is running. Networking and ingress is handled differently in each cluster and this makes it difficult to provide a consistent URL at application packaging time, and even likely requires that the cluster operator creates firewall rules before they can test the application installation.
Replicated KOTS can provide a port-forward tunnel that will work more consistently to provide an easy way for the cluster operator to open one or more links directly to the application before ingress and firewalls are configured.
To export a port and a button on the Replicated admin console dashboard to the application, a couple of additional steps are necessary.
Add A Button to the Dashboard
Replicated recommends that every application include a Kubernetes SIG Application custom resource. The Kubernetes SIG Application custom resource provides a standard API for creating, viewing, and managing applications. For more information, see Kubernetes Applications in the kubernetes-sigs/application
Github repository.
KOTS uses this as metadata and will not require or use an in-cluster controller to handle this custom resource. An application that follows best practices will never require cluster admin privileges or any cluster-wide components to be installed.
The Kubernetes Application custom resource spec.descriptor.links
field is an array of links that reference the application, after the application is deployed. The spec.descriptor.links
field can be used to configure buttons on the Replicated admin console that link to application dashboards or landing pages.
Each link contains two fields, description and url.
The description field is the title of the button that will be added to the admin console. The url field should be the url of your application.
You can use the service name in place of the host name and KOTS will rewrite the URL with hostname in the browser.
For example:
apiVersion: app.k8s.io/v1beta1
kind: Application
metadata:
name: "my-application"
labels:
app.kubernetes.io/name: "my-application"
app.kubernetes.io/version: "1.0.0"
spec:
selector:
matchLabels:
app.kubernetes.io/name: "my-application"
descriptor:
links:
- description: "Open My Application"
url: https://my-application-url
Additional Ports and Port Forwarding
When running the kubectl
plugin for the kots CLI, KOTS can add additional ports that are defined in the application to the port-forward tunnel.
This is useful for internal services such as application admin controls and other services that should not be exposed to all users.
It's also recommended to list the primary application port(s) here to make verification of the installation possible before ingress is installed.
In order to define additional ports, add a ports
key to the Application custom resource manifest file.
Example
apiVersion: kots.io/v1beta1
kind: Application
metadata:
name: my-application
spec:
title: My Application
icon: my-application-logo-uri
ports:
- serviceName: "myapplication-service"
servicePort: 9000
localPort: 9000
applicationUrl: "http://myapplication-service"
Given the above example, when the application starts and the service is ready, the kots CLI will run the equivalent of kubectl port-forward svc/myapplication-service 9000:9000
and print a message in the terminal.
Service should reference the service name that the application deployed without the namespace.
Using dashboard buttons with port forward
Finally, it's possible to combine these two features and use a dashboard button that links to a port-forwarded service. When doing this, it's recommended to not use https but instead use http, unless TLS termination is happening in the application pod.