HACKING.md

Development Workflows

Prerequisites

In order to build and test Korifi yourself, consider installing:

• Go
• golangci-lint
• Docker
• kind
• kubectl
• cf v8+
• Helm
• kbld

Running the tests

make test

Note Some Controller and API tests run a real Kubernetes API/etcd via the envtest package. These tests rely on the CRDs from the controllers subdirectory. To update these CRDs use the make generate target described below.

Note End-to-end tests deploy Korifi to a local kind cluster configured with port forwarding and a local Docker registry before running a set of tests to interact with the Cloud Foundry API. This test suite will fail if you already have Korifi deployed locally on a standard kind cluster, or you have some other process using ports 80 or 443.

Deploying locally

This is the easiest method for deploying a kick-the-tires installation, or testing code changes end-to-end. It deploys Korifi on a local kind cluster with a local Docker registry.

./scripts/deploy-on-kind.sh <kind-cluster-name>

User Permissions Disclaimer

When using scripts/deploy-on-kind.sh, you will get a separate cf-admin user by default with which to interact with the CF API.

So when prompted to select a user by the CLI you may see something like:

$ cf login
API endpoint: https://localhost

1. cf-admin
2. kind-test

Of these options, cf-admin is the user with permissions set up by default. Selecting the other user may allow you to login and successfully create resources, but you may notice that the user lacks the permissions to list those resources once created.

Deploying to kind for remote debugging with a locally deployed container registry

This is the above method, but run with dlv for remote debugging.

./scripts/deploy-on-kind.sh <kind-cluster-name> --debug

To remote debug, connect with dlv on localhost:30051 (controllers) or localhost:30052 (api).

A sample VSCode launch.json configuration is provided below:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Debug Controllers on Kind",
            "type": "go",
            "debugAdapter": "dlv-dap",
            "request": "attach",
            "mode": "remote",
            "substitutePath": [
                {
                    "from": "${workspaceFolder}",
                    "to": "/workspace"
                }
            ],
            "host": "localhost",
            "port": 30051
        },
        {
            "name": "Attach to Debug API on Kind",
            "type": "go",
            "debugAdapter": "dlv-dap",
            "request": "attach",
            "mode": "remote",
            "substitutePath": [
                {
                    "from": "${workspaceFolder}",
                    "to": "/workspace"
                }
            ],
            "host": "localhost",
            "port": 30052
        }
    ]
}

Note Images built for debugging are based on an Ubuntu container image, rather than distroless, so deploying with --debug is useful if you plan to kubectl exec into the running containers for any reason.

Image tagging conventions

We store Korifi container images on DockerHub. These are:

• korifi-api;
• korifi-controllers.

Each time a commit is merged into the main branch, a image will be pushed and tagged with a dev tag. The format is dev-<next-release>-<commit-sha>.

When a new Korifi version is released, the images will be tagged with the release version, e.g. 0.2.0. These will also be tagged as latest. This way the latest tag always refers to the latest release and not the head of the main branch.