Project: k8gb (Orchestration & Management / Coordination & Service Discovery)
File: CONTRIBUTING.md

<!-- omit in toc --> - - - - - - - k8gb is licensed under and accepts contributions via GitHub pull requests. This document outlines the resources and guidelines necessary to follow by contributors to the k8gb project. Fork the repository on GitHub See the for local dev environment setup Feel free to ask for help and join the discussions at . We have , and we can also actively monitoring . Reporting bugs is one of the best ways to contribute. Feel free to open an issue describing your problem or question. 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 your code is clean and follows the . Make sure the commit messages are in the . Make sure the changes are covered by . Push changes in a topic branch to a personal fork of the repository. Submit a pull request to k8gb-io/k8gb GitHub repository. Resolve review comments. PR must receive an "LGTM" approval from at least one maintainer listed in the `CODEOWNERS` file. ```sh make deploy-full-local-setup ``` deploys k8gb from scratch, including: 2 local clusters Stable k8gb helm chart Gslb Custom Resources examples Test applications ```sh make upgrade-candidate ``` performs upgrade of k8gb helm chart and controller to the testing version built from your current development tree. 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: ```sh cat .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 . Integration terratest suite is located . These tests are updated only if the change is substantial enough to affect the main end-to-end flow. See the for local testing environment setup and integration test execution. 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. Use `make test` to check your implementation changes. 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. ```sh PRIMARYGEOTAG=af-south-1 \ SECONDARYGEOTAG=eu-west-1 \ DNS_SERVER1=a377095726f1845fb85b95c2afef8ac0-9a1a10f24e634e28.elb.af-south-1.amazonaws.com \ DNSSERVER1PORT=53 \ DNS_SERVER2=a873f5c83be624a0a84c05a743d598a8-443f7e0285e4a28f.elb.eu-west-1.amazonaws.com \ DNSSERVER2PORT=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 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: ```sh make debug-idea ``` describes possible option examples for Goland and VS Code. Attach debugger of your IDE to port `2345`. More info about k8gb metrics can be found in the document. If you need to check and query the k8gb metrics locally, you can install a Prometheus in the local clusters using the `make deploy-prometheus` command. The deployed Prometheus scrapes metrics from the dedicated k8gb operator endpoint and makes them accessible via Prometheus web UI: http://127.0.0.1:9080 http://127.0.0.1:9081 All the metric data is ephemeral and will be lost with pod

To uninstall Prometheus, run `make uninstall-prometheus` Optionally, you can also install Grafana that will have the datasources configured and example dashboard ready using `make deploy-grafana` k8gb project is using the coding style suggested by the Golang community. See the for details. Please follow this style to make k8gb easy to review, maintain and develop. Run `make check` to automatically check if your code is compliant. k8gb project is using the library for logging. Please make sure to follow the zerolog library concepts and conventions in the code. Try to use whenever possible. Pay attention to recommendations. See first. Do not discard errors using `_` variables except tests, or, in truly exceptional situations. If a function returns an error, check it to make sure the function succeeded. If the function fails, consider logging the error and recording errors in metrics (see: ). The following example demonstrates error handling inside the reconciliation loop: ```go var log = logging.Logger() var m = metrics.Metrics() ... err = r.DNSProvider.CreateZoneDelegationForExternalDNS(gslb) if err != nil { log.Err(err).Msg("Unable to create zone delegation") m.ErrorIncrement(gslb) return result.Requeue() } ``` 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 requirement. automatically enforces DCO for all commits. Contributors are required to ensure that every commit message contains the following signature: ```txt Signed-off-by: NAME SURNAME <email@address.example.org> ``` The best way to achieve this automatically for local development is to create the following alias in the `~/.gitconfig` file: ```.gitconfig [alias] ci = commit -s ``` When a commit is created in GitHub UI as a result of , the signature should be manually added to the "optional extended description" field. The is automatically generated from Github PRs and Issues during release. Use dedicated in PR message or 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 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

These instructions will help you to set up and use local website authoring and testing environment: Check-out the branch Create dedicated with `publicrepo` permission and assign it to the `JEKYLLGITHUB_TOKEN` environment variable: ```sh export JEKYLLGITHUBTOKEN=<your-github-token> ``` Run `make` and serve the local copy of the k8gb.io website. The target utilizes the `jekyll/jekyll` docker container to avoid local environment pollution from Jekyll gem dependencies. Open the `http://localhost:4000/` page in your browser. Website will get automatically rebuilt and refreshed in the browser to accommodate the related code changes. When the dev environment is behind a proxy, it might be required to use a custom SSL CA certificate, otherwise, Jekyll is not able to update its plugins and dependencies. Local website authoring target automatically detects and wires the SSL certificate to its docker container from the path provided by the `CUSTOMCERTPATH` environment variable: ```sh export CUSTOMCERTPATH=/path/to/custom/certificate.pem ``` NOTE: Certificate should be in a PEM format Environment variables can be stored in a local `.env` file in the project's root to retain their persistency between the authoring sessions: ```.env JEKYLLGITHUBTOKEN=<your-github-token> CUSTOMCERTPATH=<your-custom-ssl-certificate> ``` The demo helper is designed to work with `podinfo` that was deployed by ```sh make deploy-test-apps ``` 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 ```sh make demo DEMO_URL=https://failover.test.exampledns.tk ``` The happy path will look like: ```sh [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 To enable verbose debug output declare `DEMO_DEBUG=1` like ```sh make demo DEMOURL=https://failover.test.exampledns.tk DEMODEBUG=1 ``` Bump the version in `Chart.yaml`, see . Make sure the commit message starts with `RELEASE:`. Merge the Pull Request after the review approval (make sure the squash or rebase is used, merge commit will not trigger the release pipeline) At this point a DRAFT release will be created on GitHub. After the & have been successfully completed, you check the and if it is OK, you click on the "Publish release" button. Check the status Check the status. This pipeline creates a pull request with an offline changelog. Do a review and if everything is ok, merge it. Congratulations, the release is complete! During the release process we generate also the provenance file that is compliant with https://in-toto.io/Statement/v0.1 schema. It contains the information about the github action run that was responsible for the release, but also other metadata about artifacts there were created and their signatures. This provenance file is signed itself and attached with the signature to the release artifacts. For signing the artifacts we use tool and private key stored as the repository secret. Public key is available in the repository itself in file . This way anybody can verify the origin of arbitrary artifact. In order to regenerate the keys for cosign, one can run `cosign generate-key-pair`, use some passphrase and update the `COSIGN{PRIVATE,PUBLIC}KEY` & `COSIGN_PASSWORD` repo secret and also the content of `./cosign.pub` file. All the container images that are produced during the build are also signed with `cosign` and the signatures are also pushed to the container registries (dockerhub). So that users of k8gb can introduce OPA policy that imposes such verification on our images. These signatures are stored in OCI format under predictable name that can be found using `cosign triangulate $IMAGE` command. However, `cosign verify ..` with our public key should be sufficient. For each container image we also create Software bill of materials (SBOM) file + its signature that ends