Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adding contributing guide #29

Merged
merged 2 commits into from
Sep 11, 2018
Merged

Adding contributing guide #29

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ff0b8d
Adding contributing guide
nicolaferraro Sep 11, 2018
975517f
Fix typos in contributing guide
nicolaferraro Sep 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 142 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Minikube and Kubernetes are not yet supported (but support is coming soon).

To start using Camel K you need the **"kamel"** binary, that can be used to both configure the cluster and run integrations.

There's currently no release channel for the "kamel" binary, so you need to **build it from source!** Refer to the [building section](#building)
There's currently no release channel for the "kamel" binary, so you need to **build it from source!** Refer to the [contributing guide](#contributing)
for information on how to do it.

Once you have the "kamel" binary, log into your cluster using the "oc" or "kubectl" tool and execute the following command to install Camel K:
Expand Down Expand Up @@ -69,19 +69,150 @@ You can check the status of all integrations by executing the following command:
kamel get
```

### Uninstalling Camel K
## Contributing

If requires to uninstall Camel K from the OpenShift or Kubernetes, it's nessesary to run following command using "oc" or "kubectl" tool:
We love contributions!

The project is written in [Go](https://golang.org/) and contains some parts written in Java for the [integration runtime](/runtime).
Camel K is built on top of Kubernetes through *Custom Resource Definitions*. The [Operator SDK](https://github.com/operator-framework/operator-sdk) is used
to manage the lifecycle of those custom resources.

### Requirements

In order to build the project, you need to comply with the following requirements:
- **Go version 1.10+**: needed to compile and test the project. Refer to the [Go website](https://golang.org/) for the installation.
- **Dep version 0.5.0**: for managing dependencies. You can find installation instructions in the [dep GitHub repository](https://github.com/golang/dep).
- **Operator SDK v0.0.6+**: used to build the operator and the Docker images. Instructions in the [Operator SDK website](https://github.com/operator-framework/operator-sdk).
- **GNU Make**: used to define composite build actions. This should be already installed or available as package if you have a good OS (https://www.gnu.org/software/make/).

### Checking Out the Sources

You can create a fork of this project from Github, then clone your fork with the `git` command line tool.

You need to put the project in your $GOPATH (refer to [Go documentation](https://golang.org/doc/install) for information).
So, make sure that the **root** of the github repo is in the path:

```
$GOPATH/src/github.com/apache/camel-k/
```

### Structure

This is a high level overview of the project structure:

- [/cmd](/cmd): contains the entry points (the *main* functions) for the **camel-k-operator** binary and the **kamel** client tool.
- [/build](/build): contains scripts used during make operations for building the project.
- [/deploy](/deploy): contains Kubernetes resource files that are used by the **kamel** client during installation. The `/deploy/resources.go` file is kept in sync with the content of the directory (`make build-embed-resources`), so that resources can be used from within the go code.
- [/pkg](/pkg): this is where the code resides. The code is divided in multiple subpackages.
- [/runtime](/runtime): the Java runtime code that is used inside the integration Docker containers.
- [/tmp](/tmp): scripts and Docker configuration files used by the operator-sdk.
- [/vendor](/vendor): project dependencies.
- [/version](/version): contains the global version of the project.

### Building

Go dependencies in the *vendor* directory are not included when you clone the project.

Before compiling the source code, you need to sync your local *vendor* directory with the project dependencies, using the following command:

```
make dep
```

The `make dep` command runs `dep ensure -v` under the hood, so make sure that `dep` is properly installed.

To build the whole project you now need to run:

```
make
```

This execute a full build of both the Java and Go code. If you need to build the components separately you can execute:
- `make build-operator`: to build the operator binary only.
- `make build-kamel`: to build the `kamel` client tool only.
- `make build-runtime`: to build the Java-based runtime code only.

After a successful build, if you're connected to a Docker daemon, you can build the operator Docker image by running:

```
make images
```

### Testing

Unit tests are executed automatically as part of the build. They use the standard go testing framework.

Integration tests (aimed at ensuring that the code integrates correctly with Kubernetes and Openshift), need special care.

The **convention** used in this repo is to name unit tests `xxx_test.go`, and name integration tests `yyy_integration_test.go`.

Since both names end with `_test.go`, both would be executed by go during build, so you need to put a special **build tag** to mark
integration tests. A integration test should start with the following line:

```
// +build integration
```

An [example is provided here](https://github.com/apache/camel-k/blob/ff672fbf54c358fca970da6c59df378c8535d4d8/pkg/build/build_manager_integration_test.go#L1).

Before running a integration test, you need to:
- Login to a Kubernetes/Openshift cluster.
- Set the `KUBERNETES_CONFIG` environment variable to point to your Kubernetes configuration file (usually `<home-dir>/.kube/config`).
- Set the `WATCH_NAMESPACE` environment variable to a Kubernetes namespace you have access to.
- Set the `OPERATOR_NAME` environment variable to `camel-k-operator`.

When the configuration is done, you can run the following command to execute **all** integration tests:

```
delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
make test-integration
```

## Building
### Running

If you want to install everything you have in your source code and see it running on Kubernetes, you need to follow these steps:
- `make`: to build the project.
- `eval $(minishift docker-env)`: to connect to your Minishift Docker daemon.
- `make images`: to build the operator docker image.
- `./kamel install`: to install Camel K into the namespace.
- `oc delete pod -l name=camel-k-operator`: to ensure the operator is using latest image (delete the pod to let Openshift recreate it).

**Note for contributors:** why don't you embed all those steps in a `make install-minishift` command?

Now you can play with Camel K:

```
./kamel run Sample.java
```

### Debugging and Running from IDE

Sometimes it's useful to debug the code from the IDE when troubleshooting.

In order to build the project follow these steps:
- this project is supposed to be cloned in `$GOPATH/src/github.com/apache/camel-k`
- install dep: https://github.com/golang/dep The last version is 0.5.0 and it's requested to use this version to be able to be aligned on each build.
- install operator-sdk: https://github.com/operator-framework/operator-sdk
- dep ensure -v
- make build
**Debugging the `kamel` binary**

It should be straightforward: just execute the [/cmd/kamel/kamel.go]([/cmd/kamel/kamel.go]) file from the IDE (e.g. Goland) in debug mode.

**Debugging the operator**

It is a bit more complex (but not so much).

You are going to run the operator code **outside** Openshift in your IDE so, first of all, you need to **stop the operator running inside**:

```
oc scale deployment/camel-k-operator --replicas 0
```

You can scale it back to 1 when you're done and you have updated the operator image.

You can setup the IDE (e.g. Goland) to execute the [/cmd/camel-k-operator/camel_k_operator.go]([/cmd/camel-k-operator/camel_k_operator.go]) file in debug mode.

When configuring the IDE task, make sure to add all required environment variables in the *IDE task configuration screen* (such as `KUBERNETES_CONFIG`, as explained in the [testing](#testing) section).

## Uninstalling Camel K

If required, it is possible to completely uninstall Camel K from OpenShift or Kubernetes with the following command, using the "oc" or "kubectl" tool:

```
# kubectl if using kubernetes
oc delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
```