Developer Guide

Requirements

Git
Golang (version >= 1.13)
Docker (version >= 19.03)
Kubernetes (version >= 1.14)
GNU Make

For installation of Golang, please refer to Install Golang

make is usually in a build-essential package in your distribution's package manager of choice. Make sure you have make on your machine.

There're great chances that you may want to run your implementation in a real Kubernetes cluster, so probably a Docker is needed for some necessary operations like building images. See Install Docker for more information.

How to Build, Run and Debug

Get Source Code

$ mkdir -p $GOPATH/src/github.com/fluid-cloudnative/
$ cd $GOPATH/src/github.com/fluid-cloudnative
$ git clone https://github.com/fluid-cloudnative/fluid.git

NOTE: In this document, we build, run and debug under non-module environment.

See Go Modules for more information if some issue occurs to you.

Build Binary

Makefile under project directory provides many tasks you may want to use including Test, Build, Debug, Deploy etc.

You can simply get a binary by running:

# build dataset-controller, alluxioruntime-controller and csi Binary
$ make build

# if you only want to build alluxioruntime-controller
$ make alluxioruntime-controller-build

By default, the binary would be put under <fluid-path>/bin.

Build Images

Set tags for images

# set name for image of dataset-controller
$ export DATASET_CONTROLLER_IMG=<your-registry>/<your-namespace>/<img-name>
# set name for image of alluxioruntime-controller
$ export ALLUXIORUNTIME_CONTROLLER_IMG=<your-registry>/<your-namespace>/<img-name>
# set name for image of  CSI
$ export CSI_IMG=<your-registry>/<your-namespace>/<csi-img-name>
# set name for image of init-user
$ export INIT_USERS_IMG=<your-registry>/<your-namespace>/<csi-img-name>

# build all images
$ make docker-build-all

# build and push all images using docker buildx (Run QEMU emulation before docker buildx, as below)
$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
$ make docker-buildx-all-push

Before running Fluid, you need to push the built image to an accessible image registry.

Login to a image registry

Make sure you've login to a docker image registry that you'd like to push your image to:
```
$ sudo docker login <docker-registry>
```
push your images:
```
$ make docker-push-all
```

Run Your Fluid on Kubernetes Cluster

In the following steps, we assume you have properly configured KUBECONFIG environment variable or set up ~/.kube/config. See Kubeconfig docs for more information.

Push your images to a image registry accessible to your Kubernetes cluster

If your images are pushed to some private repositories, make sure your Kubernetes cluster hold credentials for accessing those repositories.

Change image in the samples we provide:

# <fluid-path>/config/fluid/patches/image_in_manager.yaml
...
...
containers:
  - name: manager
    image: <registry>/<namespace>/<img-repo>:<img-tag>

# <fluid-path>/config/fluid/patches/image_in_csi-plugin.yaml
...
...
containers:
  - name: plugins
    image: <registry>/<namespace>/<csi-img-name>:<csi-img-tag>

Install CRDs

$ kubectl apply -k config/crd

Check CRD with:

$ kubectl get crd | grep fluid
alluxiodataloads.data.fluid.io          2020-08-22T03:53:46Z
alluxioruntimes.data.fluid.io           2020-08-22T03:53:46Z
datasets.data.fluid.io                  2020-08-22T03:53:46Z

Install your implementation

$ kubectl apply -k config/fluid

Check Fluid system with:

$ kubectl get pod -n fluid-system
NAME                                  READY   STATUS    RESTARTS   AGE
controller-manager-7fd6457ccf-p7j2x   1/1     Running   0          84s
csi-nodeplugin-fluid-pj9tv            2/2     Running   0          84s
csi-nodeplugin-fluid-t8ctj            2/2     Running   0          84s

Run samples to verify your implementation

Here is a sample provided by us, you may want to rewrite it according to your implementation.

$ kubectl apply -k config/samples

Check sample pods:

$ kubectl get pod
NAME                   READY   STATUS    RESTARTS   AGE
cifar10-fuse-vb6l4     1/1     Running   0          6m15s
cifar10-fuse-vtqpx     1/1     Running   0          6m15s
cifar10-master-0       2/2     Running   0          8m24s
cifar10-worker-729xz   2/2     Running   0          6m15s
cifar10-worker-d6kmd   2/2     Running   0          6m15s
nginx-0                1/1     Running   0          8m30s
nginx-1                1/1     Running   0          8m30s

Check logs to verify your implementation

$ kubectl logs -n fluid-system <controller_manager_name>

Clean up

$ kubectl delete -k config/samples
$ kubectl delete -k config/fluid
$ kubectl delete -k config/crd

Unit Testing

Basic Tests

Execute following command from project root to run basic unit tests:

$ make unit-test

Integration Tests

kubebuilder provided a integration test framework based on envtest package. You must install kubebuilder before running integration tests:

$ os=$(go env GOOS)
$ arch=$(go env GOARCH)
$ curl -L https://go.kubebuilder.io/dl/2.3.1/${os}/${arch} | tar -xz -C /tmp/
$ sudo mv /tmp/kubebuilder_2.3.1_${os}_${arch} /usr/local/kubebuilder
$ export PATH=$PATH:/usr/local/kubebuilder/bin

Next, run all unit tests (integration tests included) with:

$ make test

NOTE: When running unit tests on a non-linux system such as macOS, if testing failed and says exec format error, you may need to check whether GOOS is consistent with your actual OS.

Running Fluid Controller Components Locally

The Fluid controller component supports local operation or debugging. The Fluid controller components include Dataset Controller, various runtime controllers, and Application Controller. Before running the controller component locally, it is necessary to configure kubeconfig in advance in the local environment (configured through the KUBECONFIG environment variable or through the $HOME/.kube/config file) and be able to access a Kubernetes cluster normally.

The Fluid CSI plugin cannot run locally to interact with the Kubernetes cluster. To run such components, it is necessary to first perform image construction, manually replace the corresponding image address of charts/fluid/fluid/values.yaml, and then deploy it to the Kubernetes cluster.

The runtime controller depends on heml. And related Helm Charts to function properly. Therefore, before running the Runtime Controller, execute the following command to configure the environment:

Create a soft link for the helm command locally

$ ln -s $(which helm) /usr/local/bin/ddc-helm

Create a soft link directory for related Charts locally

$ ln -s $GOPATH/src/github.com/fluid-cloudnative/fluid/charts $HOME/charts

Taking the Alluxio Runtime Controller as an example, run the component locally using the following command：

# Configure environment variable parameters related to AlluxioRuntime
$ export ALLUXIO_RUNTIME_IMAGE_ENV="alluxio/alluxio-dev:2.9.0"
$ export ALLUXIO_FUSE_IMAGE_ENV="alluxio/alluxio-dev:2.9.0
$ export DEFAULT_INIT_IMAGE_ENV="fluidcloudnative/init-users:v0.8.0-5bb4677"
$ export MOUNT_ROOT="/runtime-mnt"
$ export HOME="$HOME"

# Open the development debugging mode, open leader-election, and start alluxioruntime-controller
$ ./bin/alluxioruntime-controller start --development=true --enable-leader-election

Debugging Fluid Components

The Fluid controller component supports local operation or debugging. The Fluid controller components include Dataset Controller, various runtime controllers, and Application Controller. Before running the controller component locally, it is necessary to configure kubeconfig in advance in the local environment (configured through the KUBECONFIG environment variable or through the $HOME/.kube/config file) and be able to access a Kubernetes cluster normally.

The Fluid CSI plugin cannot run locally to interact with the Kubernetes cluster. To run such components, it is necessary to first perform image construction, manually replace the corresponding image address of charts/fluid/fluid/values.yaml, and then deploy it to the Kubernetes cluster.

Debugging with Local Command Line

Ensure that go help is installed in the environment, and refer to the go installation manual for the specific installation process

$ dlv debug cmd/alluxio/main.go

Debugging with VSCode Locally

If VSCode is used as the development environment, the Go plugin of VSCode can be directly installed and conduct local debugging.

Debugging Controller Components

Taking debugging the Alluxio Runtime Controller as an example, the Go code debugging task is defined in ./.vscode/launch.json as follows:

{
    "version": "0.2.0",
    "configurations": [
       {
            "name": "Alluxio Runtime Controller",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "cmd/alluxio/main.go",
            "args": ["start", "--development=true", "--enable-leader-election"],
            "env": {
                "KUBECONFIG": "<path>/<to>/<kubeconfig>",
                "ALLUXIO_RUNTIME_IMAGE_ENV": "alluxio/alluxio-dev:2.9.0",
                "ALLUXIO_FUSE_IMAGE_ENV": "alluxio/alluxio-dev:2.9.0",
                "DEFAULT_INIT_IMAGE_ENV": "fluidcloudnative/init-users:v0.8.0-5bb4677",
                "MOUNT_ROOT": "/runtime-mnt",
                "HOME": "<HOME_PATH>"
            }
        },
    ]
}

Debugging WebHook Components

Proxy access to WebHook in the cluster to the local machine:

# 1. Install kt-connect（https://github.com/alibaba/kt-connect）
$ curl -OL https://github.com/alibaba/kt-connect/releases/download/v0.3.7/ktctl_0.3.7_Linux_x86_64.tar.gz
$ tar zxf ktctl_0.3.7_Linux_x86_64.tar.gz
$ mv ktctl /usr/local/bin/ktctl
$ ktctl --version

# 2. Proxy access to WebHook in the cluster to the local machine
$ ktctl exchange fluid-pod-admission-webhook  --kubeconfig <path>/<to>/<kubeconfig> --namespace fluid-system --expose 9443

Set the debug task in ./.vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
       {
            "name": "Fluid Webhook",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "cmd/webhook/main.go",
            "args": ["start", "--development=true", "--full-go-profile=false", "--pprof-addr=:6060"],
            "env": {
                "TIME_TRACK_DEBUG": "true",
                "MY_POD_NAMESPACE": "fluid-system"
            }
        },
    ]
}

Remote Debugging

For components such as Fluid Webhook and Fluid CSI plugins, remote debugging is usually the more commonly used method. Please ensure that go help is correctly installed on both the local machine and component images.

On remote host:

$ dlv debug --headless --listen ":12345" --log --api-version=2 cmd/alluxio/main.go

This will cause the remote host's debugging program to listen to the specified port (e.g. 12345)

On local machine:

$ dlv connect "<remote-addr>:12345" --api-version=2

Note: To debug remotely, make sure the specified port is not occupied and the firewall has been properly configured.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

how_to_develop.md

how_to_develop.md

Developer Guide

Requirements

How to Build, Run and Debug

Get Source Code

Build Binary

Build Images

Run Your Fluid on Kubernetes Cluster

Unit Testing

Basic Tests

Integration Tests

Running Fluid Controller Components Locally

Debugging Fluid Components

Debugging with Local Command Line

Debugging with VSCode Locally

Debugging Controller Components

Debugging WebHook Components

Remote Debugging

Files

how_to_develop.md

Latest commit

History

how_to_develop.md

File metadata and controls

Developer Guide

Requirements

How to Build, Run and Debug

Get Source Code

Build Binary

Build Images

Run Your Fluid on Kubernetes Cluster

Unit Testing

Basic Tests

Integration Tests

Running Fluid Controller Components Locally

Debugging Fluid Components

Debugging with Local Command Line

Debugging with VSCode Locally

Debugging Controller Components

Debugging WebHook Components

Remote Debugging