Link Search Menu Expand Document

Guide for contributors and developers

Install prerequisites

For getting started, you will need:

  • Go installed - see this Getting Started guide for Go.
  • Docker installed - see this Getting Started guide for Docker.
  • Kubernetes Cluster v0.10.0 or higher. Some options are:
    • Locally hosted cluster, such as
      • Kind (preferred; used by Makefile and this guide)
      • Minikube
    • Cloud-based, such as
  • kubectl v1.18 or higher - see this Getting started guide for kubectl.
  • helm v3.5.2 or higher - see this Getting started guide for helm.
  • kubebuilder v2.3.1 or higher - Install using make setup-kubebuilder.

  • controller-gen v0.5.0 or higher - Install using make controller-gen. This is required to generate the ApplicationGroup CRDS.

    NOTE: controller-gen versions < v0.5.0 will generate an incompatible CRD type.

Build & Run

To solely build the source code, invoke the make all target to,

  1. Update the CRDs and associated resource on modifying the API types.
  2. Build the orkestra controller binary.

To setup a local environment for debugging and/or testing invoke the make dev target.

The dev target creates a new KinD cluster with a local container registry and deploys all the components of Orkestra apart from the orkestra controller deployment.

make dev

kind create cluster --config .kind-cluster.yaml --name orkestra
Creating cluster "orkestra" ...
 ✓ Ensuring node image (kindest/node:v1.20.2) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-orkestra"
You can now use your cluster with:

kubectl cluster-info --context kind-orkestra

Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
helm upgrade --install orkestra chart/orkestra --wait --atomic -n orkestra --create-namespace --values "chart/orkestra/values-ci.yaml"
Release "orkestra" does not exist. Installing it now.
manifest_sorter.go:192: info: skipping unknown hook: "crd-install"
manifest_sorter.go:192: info: skipping unknown hook: "crd-install"
manifest_sorter.go:192: info: skipping unknown hook: "crd-install"
manifest_sorter.go:192: info: skipping unknown hook: "crd-install"
NAME: orkestra
LAST DEPLOYED: Mon Jun  7 18:05:28 2021
NAMESPACE: orkestra
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Happy Helming with Azure/Orkestra

To runs E2E and UTs invoke the make test target as follows,

make test

go test -v ./... -coverprofile coverage.txt -timeout 25m
?   	github.com/Azure/Orkestra	[no test files]
?   	github.com/Azure/Orkestra/api/v1alpha1	[no test files]
=== RUN   TestAPIs
Running Suite: Controller Suite
===============================
Random Seed: 1622919020
Will run 7 of 7 specs

• [SLOW TEST:195.349 seconds]
ApplicationGroup Controller
/home/runner/work/orkestra/orkestra/controllers/appgroup_controller_test.go:23
  ApplicationGroup
  /home/runner/work/orkestra/orkestra/controllers/appgroup_controller_test.go:25
    Should create Bookinfo spec successfully
    /home/runner/work/orkestra/orkestra/controllers/appgroup_controller_test.go:53
... truncated for brevity ...
--- PASS: TestAPIs (985.79s)
PASS
coverage: 67.4% of statements
ok  	github.com/Azure/Orkestra/controllers	985.849s	coverage: 67.4% of statements
?   	github.com/Azure/Orkestra/pkg/meta	[no test files]
?   	github.com/Azure/Orkestra/pkg/registry	[no test files]
?   	github.com/Azure/Orkestra/pkg/utils	[no test files]
=== RUN   Test_subchartValues
=== RUN   Test_subchartValues/withGlobalSuchart
=== RUN   Test_subchartValues/withOnlyGlobal
=== RUN   Test_subchartValues/withOnlySubchart
=== RUN   Test_subchartValues/withNone
--- PASS: Test_subchartValues (0.00s)
    --- PASS: Test_subchartValues/withGlobalSuchart (0.00s)
    --- PASS: Test_subchartValues/withOnlyGlobal (0.00s)
    --- PASS: Test_subchartValues/withOnlySubchart (0.00s)
    --- PASS: Test_subchartValues/withNone (0.00s)
PASS
coverage: 3.3% of statements
ok  	github.com/Azure/Orkestra/pkg/workflow	0.044s	coverage: 3.3% of statements

Debugging using delve

  • Debugging using Visual Studio Code and delve

    • Built-in Debugger

      .vscode/launch.json

      set --disable-remediation if you do not wish for the controller to automatically rollback or garbage collect the owned resources (pods, jobs, etc.)

        {
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Package",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}",
      "args": [
        "--debug",
        "--log-level", "3",
        // "--disable-remediation"
      ]
    }
  ]
}

Cleanup 

make clean

./hack/teardown-kind-with-registry.sh
Deleting cluster "orkestra" ...

Opening a Pull Request

  • Fork the repository.

  • Check-in all changed files

  • 🚨 Update API docs if any of the types are changed
make api-docs
  • Create a new PR against the upstream repository and reference the relevant issue(s) in the PR description.

Supported Workflow Executors

Helmrelease Workflow Executor Repository

The code for the default workflow executor container can be found at Orkestra Helmrelease Workflow Executor.

Keptn Workflow Executor Repository

The code for the keptn workflow executor container can be found at Orkestra Keptn Workflow Executor.

Custom Workflow Executor Repository

A custom workflow executor can be used to run a custom workflow node as part of the generated Orkestra workflow. This comes in handy when you want to run a workflow node that is not part of the Orkestra workflow. For example, you might want to run your own deployment executor to deploy an application. Or you might wish to chain the Orkestra workflow with a custom workflow node, in addition to the default and/or keptn workflow nodes.

The code for a custom workflow executor container, that prints the payload passed via input arguments to the executor, can be found at Orkestra Generic Workflow Executor.