developers.md

Developers Guide

This guide explains how to set up your environment for developing on acs-engine.

Prerequisites

• Go 1.11 or later
• Golang dep 0.5.0 or later
• kubectl 1.7 or later
• An Azure account (needed for deploying VMs and Azure infrastructure)
• Git

Structure of the Code

The code for the acs-engine project is organized as follows:

• The individual programs are located in cmd/. Code inside of cmd/ is not designed for library re-use.
• Shared libraries are stored in pkg/.
• The tests/ directory contains a number of utility scripts. Most of these are used by the CI/CD pipeline.
• The docs/ folder is used for documentation and examples.

Go dependencies are managed with Golang Dep and stored in the vendor/ directory.

Git Conventions

We use Git for our version control system. The master branch is the home of the current development candidate. Releases are tagged.

We accept changes to the code via GitHub Pull Requests (PRs). One workflow for doing this is as follows:

1. Use go get to clone the acs-engine repository: go get github.com/Azure/acs-engine
2. Fork that repository into your GitHub account
3. Add your repository as a remote for $GOPATH/github.com/Azure/acs-engine
4. Create a new working branch (git checkout -b feat/my-feature) and do your work on that branch.
5. When you are ready for us to review, push your branch to GitHub, and then open a new pull request with us.

Third Party Dependencies

Third party dependencies reside locally inside the repository under the vendor/ directory. We use dep to enforce our dependency graph, declared in Gopkg.toml in the project root.

Go Conventions

We follow the Go coding style standards very closely. Typically, running go fmt will make your code beautiful for you.

We also typically follow the conventions recommended by go lint and gometalinter. Run make test-style to test the style conformance.

Read more:

• Effective Go introduces formatting.
• The Go Wiki has a great article on formatting.

Unit Tests

Unit tests may be run locally via make test.

End-to-end Tests

End-to-end tests for the DCOS, Kubernetes and OpenShift orchestrators may be run via make test-{dcos,kubernetes,openshift}. The test process can optionally deploy and tear down a cluster as part of the test (this is enabled by default). You'll need access to an Azure subscription, as well as at least the following environment variables to be set:

• CLIENT_ID: "name" field (a URL) from an Azure service principal
• CLIENT_SECRET: "password" field from an Azure service principal
• SUBSCRIPTION_ID: Azure subscription UUID
• TENANT_ID: Azure tenant UUID

OpenShift

To test the OpenShift orchestrator, you'll need to enable programmatic deployment of the underlying image. In the Azure console, find the image under Home > New > Marketplace > Everything. Click "Want to deploy programmatically? Get started". Enable your subscription and click Save.

You'll also need to have oc and kubectl binaries locally in your PATH which correspond to the cluster version being tested. Download the oc binary, then make a symlink or copy of it and name the new file kubectl.

To have the test process deploy and tear down a cluster, set the following environment variables:

• CLUSTER_DEFINITION=examples/openshift.json
• DISTRO=openshift39_centos
• LOCATION=eastus

Alternatively, to run tests on a pre-deployed OpenShift cluster, set the following environment variables:

• CLEANUP_ON_EXIT=false
• LOCATION=eastus
• NAME=: dnsPrefix of the pre-deployed cluster

Finally, you'll need to make sure that the apimodel.json corresponding to the pre-deployed cluster is available at _output/$NAME.json. If you previously used acs-engine deploy directly to deploy the cluster, you will need to run cp _output/$NAME/apimodel.json _output/$NAME.json.

Debugging

For acs-engine code debugging you can use Delve debugger.

CLI

Run command:

dlv debug github.com/Azure/acs-engine -- generate ~/Documents/azure/openshift.json

Test individual package and individual test:

dlv test github.com/Azure/acs-engine/pkg/acsengine
dlv test github.com/Azure/acs-engine/pkg/acsengine -- -test.run ^TestNetworkPolicyDefaults$

Visual Code Studio

More on VSC integration with delve can be found here

If delve is installed and configured, you can use native VS functionality to debug code or individual tests (debug test)

Example launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceRoot}",
      "env": {},
      "args": ["generate", "${workspaceRoot}/examples/openshift.json"],
      "showLog": true
    }
  ]
}