Development Guide

Local Development

Using MicroK8s

MicroK8s is a lightweight, upstream Kubernetes distribution which you can run on your machine to develop and test changes.

Check official docs to see how you can install it on your OS.

Needed customizations

Enable following services:
```
microk8s.enable dns registry istio
```

Point kubectl to microk8s instance, for example:

sudo microk8s.kubectl config view --raw > /tmp/kubeconfig
export KUBECONFIG=/tmp/kubeconfig

You might end up with Istio unable reach outside networks. See this thread and the solution specific for Fedora.

Running end-to-end tests

To run the tests against local microk8s instance you have to set few environment variables which you can pass as ENV_FILE and execute:

ENV_FILE=microk8s.env make test-e2e

microk8s.env

IKE_E2E_MANAGE_CLUSTER=false
ISTIO_NS=istio-system
IKE_IMAGE_TAG=latest
TELEPRESENCE_VERSION=0.105
IKE_CLUSTER_HOST=localhost
IKE_ISTIO_INGRESS=http://localhost:31380
IKE_INTERNAL_DOCKER_REGISTRY=localhost:32000
IKE_EXTERNAL_DOCKER_REGISTRY=localhost:32000

Release

Release automation driven by Pull Request

By creating a Pull Request with release notes, we can automate the release process simply by using commands in the comments. You can see actual example here.

Creating release branch

Running make draft-release-notes VERSION=v0.1.0 creates new release notes file and initial commit titled release: highlights of v0.1.0. This commit will also become a title of the Pull Request. If there are noteworthy highlights you can write a few paragraphs in the created file docs/modules/ROOT/pages/release_notes/v0.1.0.adoc.

Changelog generation using `/changelog` command

An owner, committer, or a member of our organization can use /changelog command to trigger changelog generation for the v0.1.0 version (which is inferred from PR title).

Such a comment results in adding commits to created PR which consists of:

changelog based on all PRs since the last release, which will be appended to release highlights submitted as part of this PR.

Changelog generation job performs validation and will fail if one of the issues listed below occurs:

version in the title does not conform with semantic versioning
version has been already released
release notes do not exist (submitting this file is the only thing needed for this PR)
any of the PRs created since the last release have no labels and thus cannot be categorized by

In all the cases above PR will have release / changelog status set to failure and comment with an appropriate error message will be added by the bot. You can see that in the comments of the sample PR.

Preparing the release using `/release` command

This command will squash all previous commits to release: highlights of v0.1.0 for streamlined history.

Next it will create the following commits:

"version commit" (e.g. release: v0.1.0) which consist of documentation version lock to v0.1.0 and special /tag directive in the message. This directive later used to create actual tag when PR is rebased onto master branch.
commit which reverts documentation version lock back to latest.

Triggering release process by invoking `/shipit`

Once both steps above succeeds, we can trigger the actual release process. This can be done by commenting with /shipit.

This will result in rebasing this PR on top of the target branch if all the required checks have been successful. Once "release commit" appears on the target branch it will be automatically tagged based on /tag VERSION comment in its message. That tag will trigger the actual release process which consists of:

building and pushing tagged container images to quay.io registry
opening Pull Request with new operator version in Operator Hub
opening Pull Request with new version of Tekton tasks.
pushing cross-compiled binaries and release notes to GitHub
generating documentation for released version

Diagram below describes the entire process and its artifacts.

Figure 1. Release automation