Skip to main content

Application

The Application custom resource enables features such as branding, release notes, port forwarding, dashboard buttons, app status indicators, and custom graphs.

There is some overlap between the Application custom resource manifest file and the Kubernetes SIG Application custom resource. For example, enabling features such as adding a button to the dashboard requires the use of both the Application and SIG Application custom resources.

The following is an example manifest file for the Application custom resource:

apiVersion: kots.io/v1beta1
kind: Application
metadata:
name: my-application
spec:
title: My Application
icon: https://support.io/img/logo.png
releaseNotes: These are our release notes
allowRollback: false
targetKotsVersion: "1.60.0"
minKotsVersion: "1.40.0"
requireMinimalRBACPrivileges: false
additionalImages:
- jenkins/jenkins:lts
additionalNamespaces:
- "*"
ports:
- serviceName: web
servicePort: 9000
localPort: 9000
applicationUrl: "http://web"
statusInformers:
- deployment/my-web-svc
- deployment/my-worker
graphs:
- title: User Signups
query: 'sum(user_signup_events_total)'

title

DescriptionThe application title. Used on the license upload and in various places in the Replicated Admin Console.
Example
title: My Application
Supports Go templates?No
Supported for Embedded Cluster?Yes

icon

DescriptionThe icon file for the application. Used on the license upload and in various places in the Admin Console.
Example
icon: https://support.io/img/logo.png
Supports Go templates?No
Supported for Embedded Cluster?Yes

releaseNotes

DescriptionThe release notes for this version. These can also be set when promoting a release.
Example
releaseNotes: Fixes a bug and adds a new feature.
Supports Go templates?No
Supported for Embedded Cluster?Yes

allowRollback

Description

Enable this flag to create a Rollback button on the Admin Console Version History page.

If an application is guaranteed not to introduce backwards-incompatible versions, such as through database migrations, then the allowRollback flag can allow end users to easily roll back to previous versions from the Admin Console.

Rollback does not revert any state. Rather, it recovers the YAML manifests that are applied to the cluster.

Example
allowRollback: false
Defaultfalse
Supports Go templates?No
Supported for Embedded Cluster?No. allowRollback is not supported because Embedded Cluster does not support rolling back or downgrading.

additionalNamespaces

Description

An array of additional namespaces as strings that Replicated KOTS creates on the cluster. For more information, see Defining Additional Namespaces.

In addition to creating the additional namespaces, KOTS ensures that the application secret exists in the namespaces. KOTS also ensures that this application secret has access to pull the application images, including both images that are used and any images you add in the additionalImages field. This pull secret is automatically added to all manifest files that use private images.

For dynamically created namespaces, specify "*".

Example
additionalNamespaces:
- "*"
Supports Go templates?No
Supported for Embedded Cluster?Yes

additionalImages

Description

An array of strings that reference images to be included in air gap bundles and pushed to the local registry during installation.

KOTS detects images from the PodSpecs in the application. Some applications, such as Operators, might need to include additional images that are not referenced until runtime. For more information, see Defining Additional Images.

Example
additionalImages:
- jenkins/jenkins:lts
Supports Go templates?No
Supported for Embedded Cluster?Yes

requireMinimalRBACPrivileges

Description

requireMinimalRBACPrivileges applies to existing clusters only.

Requires minimal role-based access control (RBAC) be used for all customer installations. When set to true, KOTS creates a namespace-scoped Role and RoleBinding, instead of the default cluster-scoped ClusterRole and ClusterRoleBinding.

For additional requirements and limitations related to using namespace-scoped RBAC, see About Namespace-scoped RBAC in Configuring KOTS RBAC.

Example
requireMinimalRBACPrivileges: false
Defaultfalse
Supports Go templates?No
Supported for Embedded Cluster?No

supportMinimalRBACPrivileges

Description

supportMinimalRBACPrivileges applies to existing clusters only.

Allows minimal role-based access control (RBAC) be used for all customer installations. When set to true, KOTS supports creating a namespace-scoped Role and RoleBinding, instead of the default cluster-scoped ClusterRole and ClusterRoleBinding.

Minimal RBAC is not used by default. It is only used when the --use-minimal-rbac flag is passed to the kots install command.

For additional requirements and limitations related to using namespace-scoped RBAC, see About Namespace-scoped RBAC in Configuring KOTS RBAC.

Example
supportMinimalRBACPrivileges: true
Defaultfalse
Supports Go templates?No
Supported for Embedded Cluster?No

ports

Description

Extra ports (additional to the 8800 Admin Console port) that are port-forwarded when running the kubectl kots admin-console command. With ports specified, KOTS can establish port forwarding to simplify connections to the deployed application. When the application starts and the service is ready, the KOTS CLI will print a message in the terminal with the URL where the port-forwarded service can be accessed. For more information, see Configuring Port Forwarding.

note

KOTS does not automatically create port forwards for installations in clusters provisioned with Replicated Embedded Cluster or Replicated kURL. This is because it cannot be verified that the ports are secure and authenticated. Instead, Embedded Cluster or kURL creates a NodePort service to make the Admin Console accessible on port 8800 on the node.

To expose additional ports on the node, you can create additional NodePort services and then add the corresponding ports to the ports key. For more information, see Exposing Services Using NodePorts.

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, see Adding Application Links to the Dashboard.

Example
ports:
- serviceName: web
servicePort: 9000
localPort: 9000
applicationUrl: "http://web"
Supports Go templates?No
Supported for Embedded Cluster?Yes

statusInformers

Description

Resources to watch and report application status back to the user. When you include statusInformers, the dashboard can indicate when the application deployment is complete and the application is ready for use.

statusInformers use the format [namespace/]type/name, where namespace is optional.

For more information about including statusInformers, see Adding Resource Status Informers.

Example
statusInformers:
- deployment/my-web-svc
- deployment/my-worker

The following example shows excluding a specific status informer based on a user-supplied value from the Admin Console Configuration screen:

statusInformers:
- deployment/my-web-svc
- '{{repl if ConfigOptionEquals "option" "value"}}deployment/my-worker{{repl else}}{{repl end}}'
Supports Go templates?Yes
Supported for Embedded Cluster?Yes

graphs

Description

Custom graphs to include on the Admin Console application dashboard.For more information about how to create custom graphs, see Adding Custom Graphs.

graphs has the following fields:

  • graphs.title: The graph title.
  • graphs.query: The Prometheus query.
  • graphs.legend: The legend to use for the query line. You can use Prometheus templating in the legend fields with each element returned from the Prometheus query.

    The template escape sequence is {{}}. Use {{ value }}. For more information, see Template Reference in the Prometheus documentation.

  • graphs.queries: A list of queries containing a query and legend.
  • graphs.yAxisFormat: The format of the Y axis labels with support for all Grafana units. For more information, see Visualizations in the Grafana documentation.
  • graphs.yAxisTemplate: Y axis labels template.
Example
graphs:
- title: User Signups
query: 'sum(user_signup_events_total)'
Supports Go templates?

Yes

Supported for Embedded Cluster?No

proxyRegistryDomain

important

proxyRegistryDomain is deprecated. For information about how to use a custom domain for the Replicated proxy service, see Using Custom Domains.

Description

The custom domain used for proxy.replicated.com. For more information, see Using Custom Domains.

Introduced in KOTS v1.91.1.

Example
proxyRegistryDomain: "proxy.mycompany.com"	
Supports Go templates?No

replicatedRegistryDomain

important

replicatedRegistryDomain is deprecated. For information about how to use a custom domain for the Replicated registry, see Using Custom Domains.

Description

The custom domain used for registry.replicated.com. For more information, see Using Custom Domains.

Introduced in KOTS v1.91.1.

Example
replicatedRegistryDomain: "registry.mycompany.com"
Supports Go templates?No
Supported for Embedded Cluster?Yes

targetKotsVersion

Description

The KOTS version that is targeted by the release. For more information, see Setting Minimum and Target Versions for KOTS.

Example
targetKotsVersion: "1.85.0"
Supports Go templates?No
Supported for Embedded Cluster?No. Setting targetKotsVersion to a version earlier than the KOTS version included in the specified version of Embedded Cluster will cause Embedded Cluster installations to fail with an error message like: Error: This version of App Name requires a different version of KOTS from what you currently have installed.. To avoid installation failures, do not use targetKotsVersion in releases that support installation with Embedded Cluster.

minKotsVersion (Beta)

Description

The minimum KOTS version that is required by the release. For more information, see Setting Minimum and Target Versions for KOTS.

Example
minKotsVersion: "1.71.0"
Supports Go templates?No
Supported for Embedded Cluster?No. Setting minKotsVersion to a version later than the KOTS version included in the specified version of Embedded Cluster will cause Embedded Cluster installations to fail with an error message like: Error: This version of App Name requires a different version of KOTS from what you currently have installed.. To avoid installation failures, do not use minKotsVersion in releases that support installation with Embedded Cluster.