Develop Octopus

Build management of Octopus

Octopus takes inspiration from Maven and provides a set of project build management based on make. Build management process consists of several stages, a stage consists of several actions. For convenience, the name of the action also represents the current stage. The overall flow relationship of action looks as below:

generate -> mod -> lint -> build -> package -> deploy
\ -> test -> verify -> e2e

Explanation of each action:

ActionUsage
generate, gen, gGenerate deployment manifests and deepcopy/runtime.Object implementations of octopus via controller-gen; Generate proto files of adaptor interfaces via protoc.
mod, mDownload octopus dependencies.
lint, lVerify octopus via golangci-lint, roll back to go fmt and go vet if the installation fails. <br/
Use DIRTY_CHECK=true to verify the whole project is in dirty tree or not.
build, bCompile octopus according to the type and architecture of the OS, generate the binary into bin directory.

Use CROSS=true to compile binaries of the supported platforms(search constant.sh file in this repo).
test, tRun unit tests.
verify, vRun integration tests with a Kubernetes cluster.

Use CLUSTER_TYPE to specify the type for local cluster, default is k3d. Instead of setting up a local cluster, you can also use environment variable USE_EXISTING_CLUSTER=true to point out an existing cluster, and then the integration tests will use the kubeconfig of the current environment to communicate with the existing cluster.
package, pkg, pPackage Docker image.
e2e, eRun E2E tests.
deploy, dep, dPush Docker images and create manifest images for the current version.

Use WITHOUT_MANIFEST=true to prevent pushing manifest image, or ONLY_MANIFEST=true to push the manifest images only and IGNORE_MISSING=true to warn on missing images defined in platform list if needed.

Executing a stage can run make octopus <stage name>, for example, when executing the test stage, please run make octopus test. To execute a stage will execute all actions in the previous sequence, if running make octopus test, it actually includes executing generate, mod, lint, build and test actions.

To run an action by adding only command, for example, if only run build action, please use make octopus build only.

To combine multiple actions can use a comma list, for example, if want to run build, package and deploy actions orderly, please use make octopus build,package,deploy.

Integrate with dapper via BY environment variable, for example, if only run build action via dapper, please use BY=dapper make octopus build only.

Usage cases

Suppose to try the following example on Mac:

  1. Run in the localhost, the current environment will install additional dependencies. You will get a corresponding warning if any installation fails.

    • make octopus build: execute build stage, then get a darwin/amd64 execution binary.
    • make octopus test only: execute test action on darwin/amd64 platform.
    • REPO=somebody OS=linux ARCH=amd64 make octopus package: execute package stage, then get a linux/amd64 execution binary and an octopus linux/amd64 image of somebody repo.
    • CLUSTER_TYPE=kind make octopus verify only: execute verify action with kind cluster.

  2. Support multi-arch in the localhost.

    • CROSS=true make octopus build only: execute build action, then get all execution binaries of supported platform.
    • CROSS=true make octopus test only: crossed testing isn't supported currently.
    • CROSS=true REPO=somebody make octopus package only: execute package action, then get all supported platform images of somebody repo.
      • make octopus package only: packaging darwin platform image isn't supported currently.
    • CROSS=true REPO=somebody make octopus deploy only: execute deploy action, then push all supported platform images to somebody repo, also create manifest images for the current version.
      • make octopus deploy only: deploying darwin platform image isn't supported currently.

  3. In dapper mode, no additional dependencies are required in the current environment, which suitable for constructing CI / CD and good to the portability of the environment.

    • BY=dapper make octopus build: execute build stage, then get a linux/amd64 execution binary.
    • BY=dapper make octopus test: execute test stage on linux/amd64 platform.
    • BY=dapper REPO=somebody make octopus package only: execute package action and get an octopus linux/amd64 image of sombody repo.

Notes

In dapper mode:

  • Using USE_EXISTING_CLUSTER=true is NOT ALLOWED.

Build management of Adaptors

The build management of Adaptors is the similar to Octopus, except that the execution is different. Executing a stage of any adaptor can run make adaptor <adaptor name> <stage name>. Please view Develop Adaptors for more details.

Build management for all components

With the increase of components, the operation of building them one by one becomes more cumbersome. Therefore, by specifying a stage or action, the build management performs the same stage or action for all components. For example, running make all test will execute the test stage of Octopus and all Adaptors. To execute an action just type with an only suffix command.

Contributor workflow

Contributing is welcome, please view CONTRIBUTING for more details.

Edit this page