How to use Tilt with APPUiO Cloud

Tilt is a developer toolkit to enable teams to build microservices architectures faster on Kubernetes clusters.

The best indicator of a healthy development workflow is a short feedback loop.

This page will describe the required steps to use Tilt successfully with APPUiO Cloud.

This information is provided as a courtesy for APPUiO Cloud users. We don’t provide support for Tilt, and in case of issues, you are invited to contact the developers of Tilt at their GitHub project.

Requirements

To follow this guide, please make sure that you have the following tools installed:

tilt: The Tilt documentation explains how to install it in your operating system of choice.
oc: You can download the OpenShift command directly from APPUiO Cloud, selecting the help menu (marked as a question mark) and selecting the "Command line tools" entry.
docker: You can download it from www.docker.com.

Procedure

This section explains the steps required to use Tilt with APPUiO Cloud.

1. Login to APPUiO Cloud

Follow these steps to login to APPUiO Cloud on your terminal:

oc login --server=https://api.${zone}.appuio.cloud:6443

You can find the exact URL of your chosen zone in the APPUiO Cloud Portal.

This command displays a URL on your terminal:

You must obtain an API token by visiting
https://oauth-openshift.apps.${zone}.appuio.cloud/oauth/token/request

Click on the link above and open it in your browser.
Click "Display token" and copy the login command shown as "Log in with this token"

Paste the oc login command on the terminal:

oc login --token=sha256~_xxxxxx_xxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx-X \
    --server=https://api.${zone}.appuio.cloud:6443

Create a new project called "[YOUR_USERNAME]-fortune-go"
```
oc new-project [YOUR_USERNAME]-fortune-go
```

2. Login to the APPUiO Cloud Container Registry

Tilt uses Docker to build the container image, and to publish to a container registry. In this example we’re going to use the APPUiO Cloud integrated container registry.

oc whoami -t | docker login registry.${zone}.appuio.cloud -u $(oc whoami) --password-stdin

3. Clone the sample "Fortune in Go" project

The "Fortune in Go" project provides a very simple Go application to start with. You can clone it from GitLab:

git clone https://gitlab.com/vshn/applications/fortune-go.git

And then cd into it:

cd fortune-go

4. Add a Deployment File

Add a file named deployment.yaml at the root of the project with the following information:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: fortune-go
spec:
  template:
    spec:
      containers: (1)
      - image: registry.[YOUR_CHOSEN_ZONE].appuio.cloud/[YOUR_USERNAME]-fortune-go/fortune-go:latest
        imagePullPolicy: Always
        name: fortune-container
        ports:
        - containerPort: 8080
    metadata:
      labels:
        app: fortune-go
  selector:
    matchLabels:
      app: fortune-go
  strategy:
    type: Recreate
---
apiVersion: v1
kind: Service
metadata:
  name: fortune-go
spec:
  ports:
    - port: 8080
      targetPort: 8080
  selector:
    app: fortune-go
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-production
  name: fortune-go-ingress
spec:
  rules:
  - host: [YOUR_USERNAME]-fortune-go.apps.[YOUR_CHOSEN_ZONE].appuio.cloud (1)
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: fortune-go
            port:
              number: 8080
  tls:
  - hosts:
    - [YOUR_USERNAME]-fortune-go.apps.[YOUR_CHOSEN_ZONE].appuio.cloud
    secretName: fortune-go-cert

1	Remember to customize the parts marked as `[YOUR_USERNAME]` and `[YOUR_CHOSEN_ZONE]` to your liking (and according to the Zones documentation page).

About URL lengths

Make sure that the total length of the prefix string [YOUR_USERNAME]-fortune-[LANGUAGE] used in the Ingress YAML above isn’t longer than 63 characters. This is due for two reasons:

As per the DNS RFC, each label (for example the prefix in this case) must be equal or less than 63 characters long (octets to be exact), and the whole domain name must be equal or shorter than 255 octets.
These limits also apply to most Kubernetes resource names.

If your Ingress doesn’t generate a route after deploying your application, shorten the URL in your YAML and redeploy.

5. Add a `Tiltfile`

The Tiltfile provides the information required for tilt to rebuild and redeploy your application as soon as you edit any file in your project.

For APPUiO Cloud, you can use a Tiltfile similar to this one:

(1)
allow_k8s_contexts('[YOUR_USERNAME]-fortune-go/api-[YOUR_CHOSEN_ZONE]-appuio-cloud:6443/[YOUR_USERNAME]')

(1)
docker_build('registry.[YOUR_CHOSEN_ZONE].appuio.cloud/[YOUR_USERNAME]-fortune-go/fortune-go', '.')

k8s_yaml(['deployment.yaml'])

1	Remember to change the `[YOUR_CHOSEN_ZONE]` and `[YOUR_USERNAME]` placeholders to your preferred APPUiO Cloud zone and your username, respectively.

It’s very important that the container image referenced in the Deployment YAML object and the docker_build() command of the Tiltfile are the same.

6. Launch Tilt

Launch Tilt on the terminal:

tilt up

Hit the space bar to open the browser and see the status of Tilt. It should be already at work, building your container image, pushing it to the APPUiO Cloud registry, and deploying your application to the cluster.

Now you can edit any file in your project, and as soon as you save it, Tilt will automatically rebuild your image, push it, and redeploy it, increasing your productivity.

Tips & Tricks

Here go some ideas to use Tilt efficiently:

Tilt rebuilds your Docker image every time you save a file in your project, which depending on your setup can take a long time to finish. In that case you might want to use a separate Dockerfile for development, and another for production builds, where you turn on all optimizations, and strip all debug symbols away. You can also only tilt up some of your services instead of all at once; check the Tiltfile Config page in the documentation for details.
Tilt has plenty of configuration options. Check the Tiltfile Snippets page in the Tilt documentation to learn more.
Help your team adopt Tilt by following the onboarding checklist and adding the appropriate information in your project’s README file.

Troubleshooting

Tilt uses BuildKit by default whenever available in the local Docker installation.

However, BuildKit can cause problems when working with Alpine-based images (like in the case of the fortune-go project), as explained in this issue in the GliderLabs Alpine repository.

In this case there are two possible solutions:

Use the DOCKER_BUILDKIT=0 tilt up command. This will make Tilt use the standard Docker image builder mechanism instead of BuildKit.
Patch and restart your local Docker daemon using this fix. BuildKit should work without issues after that.

Finally, if you encounter problems with Tilt, run the tilt doctor command, and check the project FAQ before opening an issue in the Tilt project.