Contributing to k8gb §
- Getting started
- Getting help
- Reporting issues
- Contribution flow
- Local setup
- Overriding dev environment settings
- Code style
- Commit and Pull Request message
- k8gb.io website
- End-to-end demo helper
- Release process
k8gb is licensed under Apache 2 License and accepts contributions via GitHub pull requests. This document outlines the resources and guidelines necessary to follow by contributors to the k8gb project.
Getting started §
- Fork the repository on GitHub
- See the local playground guide for local dev environment setup
Getting help §
Feel free to ask for help and join the discussions at k8gb community discussions forum.
We have dedicated
#k8gb channel on Cloud Native Computing Foundation (CNCF) Slack,
and we can also actively monitoring
#sig-multicluster channel on Kubernetes Slack.
Reporting issues §
Reporting bugs is one of the best ways to contribute. Feel free to open an issue describing your problem or question.
Contribution flow §
Following is a rough outline for the contributor's workflow:
- Create a topic branch from where to base the contribution.
- Make commits of logical units.
- Make sure commit messages are in the proper format (see below).
- Push changes in a topic branch to a personal fork of the repository.
- Submit a pull request to AbsaOSS/k8gb GitHub repository.
- Resolve review comments
- PR must receive an "LGTM" approval from at least one maintainer listed in the
Local setup §
Deploy k8gb locally §
deploys k8gb from scratch, including:
- 2 local clusters
- Stable k8gb helm chart
- Gslb Custom Resources examples
- Test applications
Upgrade k8gb to local candidate §
performs upgrade of k8gb helm chart and controller to the testing version built from your current development tree.
Overriding dev environment settings §
Sometimes there is a need to override environment variables used by
make targets for local k8gb development.
This can be easily achieved by providing the list of environment variables with respective values in the
.env file at the local repository root:
cat .env # .env: LOG_LEVEL=info LOG_FORMAT=json
Overrides done this way can persist between terminal sessions and can be used as a single point of configuration for development in terminal and IDE of choice.
- Any functional GSLB controller code change should be secured by the corresponding unit tests.
- Integration terratest suite is located here. These tests are updated only if the change is substantial enough to affect the main end-to-end flow.
- See the local playground guide for local testing environment setup and integration test execution.
Unit testing §
- Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower the maintenance cost.
- Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage.
make test to check your implementation changes.
Testing against real k8s clusters §
There is a possibility to execute the integration terratest suite over the real clusters. For this, you need to override the set of test settings as in the example below.
PRIMARY_GEO_TAG=af-south-1 \ SECONDARY_GEO_TAG=eu-west-1 \ DNS_SERVER1=a377095726f1845fb85b95c2afef8ac0-9a1a10f24e634e28.elb.af-south-1.amazonaws.com \ DNS_SERVER1_PORT=53 \ DNS_SERVER2=a873f5c83be624a0a84c05a743d598a8-443f7e0285e4a28f.elb.eu-west-1.amazonaws.com \ DNS_SERVER2_PORT=53 \ GSLB_DOMAIN=test.k8gb.io \ K8GB_CLUSTER1=arn:aws:eks:af-south-1:<aws-account-id>:cluster/k8gb-cluster-af-south-1 \ K8GB_CLUSTER2=arn:aws:eks:eu-west-1:<aws-account-id>:cluster/k8gb-cluster-eu-west-1 \ make terratest
Install Delve debugger first. Follow the installation instructions for specific platforms from Delve's website.
Run delve with options specific to IDE of choice. There is a dedicated make target available for Goland:
This article describes possible option examples for Goland and VS Code.
Attach debugger of your IDE to port
Code style §
k8gb project is using the coding style suggested by the Golang community. See the golang-style-doc for details.
Please follow this style to make k8gb easy to review, maintain and develop.
make check to automatically check if your code is compliant.
Commit and Pull Request message §
We follow a rough convention for PR and commit messages, which is designed to answer two questions: what changed and why. The subject line should feature the what, and the body of the message should describe the why. The format can be described more formally as follows:
<what was changed> <why this change was made> <footer>
The first line is the subject and should be no longer than 70 characters. The second line is always blank. Consequent lines should be wrapped at 80 characters. This way, the message is easier to read on GitHub as well as in various git tools.
scripts: add the test-cluster command This command uses "k3d" to set up a test cluster for debugging. Fixes #38
Commit message can be made lightweight unless it is the only commit forming the PR. In that case, the message can follow the simplified convention:
<what was changed and why>
This convention is useful when several minimalistic commit messages are going to form PR descriptions as bullet points of what was done during the final squash and merge for PR.
As a CNCF project, k8gb must comply with Developer Certificate of Origin (DCO) requirement. DCO GitHub Check automatically enforces DCO for all commits. Contributors are required to ensure that every commit message contains the following signature:
>Signed-off-by: NAME SURNAME <email@example.com>
The best way to achieve this automatically for local development is to create the following alias in the
>[alias] ci = commit -s
When a commit is created in GitHub UI as a result of accepted suggested change, the signature should be manually added to the "optional extended description" field.
The CHANGELOG is automatically generated from Github PRs and Issues during release. Use dedicated keywords in PR message or manual PR and Issue linking for clean changelog generation. Issues and PRs should be also properly tagged with valid project tags ("bug", "enhancement", "wontfix", etc )
If contribution changes the existing APIs or user interface, it must include sufficient documentation explaining the use of the new or updated feature.
k8gb.io website §
k8gb.io website is a Jekyll-based static website generated from project markdown documentation and hosted by GitHub Pages.
gh-pages branch contains the website source, including configuration, website layout, and styling.
Markdown documents are automatically populated to
gh-pages from the main branch and should be authored there.
Changes to the k8gb.io website layout and styling should be checked out from the
gh-pages branch and PRs should be created against
Local website authoring and testing §
These instructions will help you to set up and use local website authoring and testing environment:
Check-out from the
Create dedicated GitHub Personal Access Token with
public_repopermission and assign it to the
Run the following
maketarget to build and serve the local copy of the k8gb.io website.
The target utilizes the
jekyll/jekylldocker container to avoid unnecessary installation of local GitHub page authoring dependencies.
http://localhost:4000/page in your browser.
Website will automatically rebuild and refresh in the browser to accommodate the related code changes.
End-to-end demo helper §
The demo helper is designed to work with
podinfo that was deployed by
It will configure
podinfo to expose geotag as part of an HTTP response.
To test and/or demonstrate continuous query to GSLB enabled endpoint execute
make demo DEMO_URL=https://failover.test.exampledns.tk
The happy path will look like:
[Thu May 27 15:35:26 UTC 2021] ... 200 "message": "eu-west-1", [Thu May 27 15:35:31 UTC 2021] ... 200 "message": "eu-west-1", [Thu May 27 15:35:36 UTC 2021] ...
The sources for demo helper images can be found here
To enable verbose debug output declare
make demo DEMO_URL=https://failover.test.exampledns.tk DEMO_DEBUG=1
Release process §
- Bump the version in
Chart.yaml, see example PR.
- Merge the Pull Request after the review approval
- Create release tag (replace
v0.8.1with an actual version)
git tag v0.8.1
- Push release tag
git push origin refs/tags/v0.8.1
Thanks for contributing!