Step 6: Run Preflights with KOTS

Create a KOTS-enabled release and then install Gitea with KOTS. This purpose of this step is to see how preflight checks automatically run in the KOTS admin console during installation.

To run preflight checks during installation with KOTS:

1. In the gitea directory, create a subdirectory named manifests:

   mkdir manifests

   You will add the files required to support installation with KOTS to this subdirectory.

2. Move the Helm chart archive to manifests:

   mv gitea-1.0.6.tgz manifests

3. In manifests, create the YAML manifests required by KOTS:

   cd manifests

   touch gitea.yaml kots-app.yaml k8s-app.yaml

4. In each of the files that you created, paste the corresponding YAML provided in the tabs below:

   gitea.yaml

   Description

   The KOTS HelmChart custom resource provides instructions to KOTS about how to deploy the Helm chart. The name and chartVersion listed in the HelmChart custom resource must match the name and version of a Helm chart archive in the release. Each Helm chart archive in a release requires a unique HelmChart custom resource.

   YAML

   apiVersion: kots.io/v1beta2
   kind: HelmChart
   metadata:
     name: gitea
   spec:
     # chart identifies a matching chart from a .tgz
     chart:
       name: gitea
       chartVersion: 1.0.6

   kots-app.yaml

   Description

   The KOTS Application custom resource enables features in the Replicated admin console such as branding, release notes, port forwarding, dashboard buttons, application status indicators, and custom graphs.

   The YAML below provides a name for the application to display in the admin console, adds a custom status informer that displays the status of the gitea Deployment resource in the admin console dashboard, adds a custom application icon, and creates a port forward so that the user can open the Gitea application in a browser.

   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

   k8s-app.yaml

   Description

   The Kubernetes Application custom resource supports functionality such as including buttons and links on the Replicated admin console dashboard. The YAML below adds an Open App button to the admin console dashboard that opens the application using the port forward configured in the KOTS Application custom resource.

   YAML

   apiVersion: app.k8s.io/v1beta1
   kind: Application
   metadata:
     name: "gitea"
   spec:
     descriptor:
       links:
         - description: Open App
           # needs to match applicationUrl in kots-app.yaml
           url: "http://gitea"

5. From the manifests directory, lint the YAML files to confirm that there are no errors:

   replicated release lint --yaml-dir .

   --yaml-dir is the path to the directory that contains the Helm chart archive and the manifest files required by KOTS.

   Example output:

   RULE                               TYPE    FILENAME        LINE  MESSAGE
   config-spec                        warn                          Missing config spec                                                         
   preflight-spec                     warn                          Missing preflight spec
   troubleshoot-spec                  warn                          Missing troubleshoot spec
   nonexistent-status-informer-object warn    kots-app.yaml   8     Status informer points to a nonexistent kubernetes object. If this is a Helm resource, this warning can be ignored.

   The output includes warning messages, including a warning about a missing preflight spec. This warning appears because the preflight spec is defined in the Helm chart. The warnings can be ignored for the purpose of this tutorial.

6. Create a release:

   replicated release create --yaml-dir .   

   Example output:

   • Reading manifests from . ✓
   • Creating Release ✓
     • SEQUENCE: 2

7. Log in to the vendor portal and go to Releases. The new release is labeled Sequence 2.

8. Promote the release to the Unstable channel.

9. Go to the Customers page.

10. Create a new customer named KOTS Preflight Customer. For License options, enable the KOTS Install Enabled checkbox. This is the entitlement that allows the customer to install with KOTS.

11. On the Manage customer page for the customer, click Download license. You will use the license file to install with KOTS.

12. Go to Channels. From the Unstable channel card, under Install, copy the KOTS Install command.

    

    View a larger version of this image

13. On the command line, run the KOTS Install command that you copied:

    curl https://kots.io/install | bash
    kubectl kots install $REPLICATED_APP/unstable

    This installs the latest version of the kots CLI and the Replicated admin console. The admin console provides a user interface where you can upload the customer license file and deploy the application.

    For additional kots CLI installation options, including how to install without root access, see Installing the kots CLI.

    note

    To install the SDK with KOTS, KOTS v1.104.0 or later and the SDK version 1.0.0-beta.12 or later are required. You can verify the version of KOTS installed with kubectl kots version.

14. Complete the installation command prompts:

    1. For Enter the namespace to deploy to, enter gitea.

    2. For Enter a new password to be used for the Admin Console, provide a password to access the admin console.

       When the admin console is ready, the command prints the URL where you can access the admin console. At this point, the kots CLI is installed and the admin console is running, but the application is not yet deployed.

       Example output:

       Enter the namespace to deploy to: gitea
       • Deploying Admin Console
         • Creating namespace ✓
         • Waiting for datastore to be ready ✓
       Enter a new password for the admin console (6+ characters): ••••••••
       • Waiting for Admin Console to be ready ✓
       
       • Press Ctrl+C to exit
       • Go to http://localhost:8800 to access the Admin Console

15. With the port forward running, in a browser, go to http://localhost:8800 to access the admin console.

16. On the login page, enter the password that you created.

17. On the license page, select the license file that you downloaded previously and click Upload license.

    Preflight checks run automatically:

    

    View a larger version of this image

18. When the preflight checks finish, click Deploy to deploy the application.

    The admin console dashboard opens. The application status changes from Missing to Unavailable while the gitea Deployment is being created:

    

    View a larger version of this image

19. (Optional) After the application is in a Ready status, click Open App to view the Gitea application in a browser.

20. Uninstall the Gitea application from your cluster:

    kubectl kots remove $REPLICATED_APP --namespace gitea --undeploy

    Example output:

    • Removing application gitea-boxer reference from Admin Console and deleting associated resources from the cluster ✓
    • Application gitea-boxer has been removed

21. Remove the admin console from the cluster:

    1. Delete the namespace where the admin console is installed:

       kubectl delete namespace gitea

    2. Delete the admin console ClusterRole and ClusterRoleBinding:

       kubectl delete clusterrole kotsadm-role

       kubectl delete clusterrolebinding kotsadm-rolebinding

Summary

Congratulations! In this tutorial, you defined a preflight check for Gitea that checks the version of Kubernetes running in the cluster. You also ran preflight checks before installing with both the Helm CLI and with KOTS.

To learn more about defining and running preflight checks, see:

• Defining Preflight Checks
• Running Preflight Checks
• Getting Started in the open source Troubleshoot documentation.