Skip to content

Latest commit

 

History

History
260 lines (178 loc) · 10 KB

CONTRIBUTING.md

File metadata and controls

260 lines (178 loc) · 10 KB
Raw

Contributing Guidelines

Thank you for showing interest in contributing to Kong Ingress Controller.

Following guide will help you navigate the repository and get your PRs merged in faster.

Finding work

If you're new to the project and want to help, but don't know where to start, look for "Help wanted" or "Good first issue" labels in our issue tracker. Alternatively, read our documentation and fix or improve any issues that you see. We really value documentation contributions since that makes life easier for a lot of people.

All of the following tasks are noble and worthy contributions that you can make without coding:

  • Reporting a bug
  • Helping other members of the community on the support channels
  • Fixing a typo in the code
  • Fixing a typo in the documentation
  • Providing your feedback on the proposed features and designs
  • Reviewing Pull Requests

If you wish to contribute code (features or bug fixes) please keep in mind the following:

  • bug fix pull requests should be opened against main as the base branch
  • feature pull requests should be opened with next as the base branch

Working with Pull Requests

When you finish your work and want your contributions to be included, please submit a pull request and include necessary information about the pull request in its description following our pull request template. A clear title and description is helpful to encourage your pull request to be reviewed and merged.

If your pull request is still in progress, but you want to get early reviews before it is ready to be merged, please add do not merge or work in progress labels to the pull request. If your pull request is not ready to be reviewed yet, please convert it to Draft. Draft pull requests will not be reviewed until they are converted to Open status.

Stale issue and pull request policy

To ensure our backlog is organized and up to date, we will close issues and pull requests that have been inactive awaiting a community response for over 2 weeks. If you wish to reopen a closed issue or PR to continue work, please leave a comment asking a team member to do so.

When to close an issue

For a GitHub issue describing a problem/feature request:

  • Duplicates. if there are other issues in the repository describing the same problem/FR:

    1. find the issue that has the most context (possibly not the first reported)

    2. close all other issues with a comment Duplicate of #XYZ

  • Resolution by code. if resolution involves creating PRs:

    1. ensure that all PRs reference the issue they are solving. Keep in mind that the fixes/resolves directive only works for PRs merged to the default branch of the repository.

    2. close the issue as soon as all the PRs have been merged to main or next. If it's obvious from PRs that the issue has been resolved, a closing comment on the issue is purely optional.

  • Other resolutions/rejections. if resolution happens for any other reason (resolved without code, user's question answered, won't fix, infeasible, not useful, alternative approach chosen, problem will go away in $FUTURE-VERSION)

    1. close the issue with a comment describing the resolution/reason.

For a closed issue, one can verify which released versions contain the fix/enhancement by navigating into the merge commit of each attached PR, where GitHub lists tags/branches that contain the merge commit. Thus:

  • if the list includes a release tag: the fix/enhancement is included in that release tag.
  • if the list includes next but no release tags: the fix/enhancement will come in the nearest minor release.
  • if the list includes main but no release tags: the fix/enhancement will come in the nearest patch release.

Enhancements

Documenting and communicating the motivation for major enhancements in the Kong Kubernetes Ingress Controller (KIC) is done using an upstream Kubernetes process referred to as Kubernetes Enhancement Proposals (KEPs).

New Enhancement Proposals

When starting a new enhancement proposal use the upstream KEP Template file as the starting point for your KEP, and follow the instructions therein.

Initially you can remove a lot of the scaffolding in the template for the first provisional iteration and focus on establishing the following sections:

  • Summary
  • Motivation
  • Goals
  • User Stories

In general the maintainers here feel establishing these things in a KEP should be done prior to any technical writeups but this is a soft rule.

Feature Gates

New features should be added to the Feature Gates documentation and internal/manager/feature_gates.go.

Development environment

Environment

Dependencies

The build uses dependencies are managed by go modules

Developing

Development of our Kubernetes Controllers and APIs is managed through the Kubebuilder SDK.

Prior to developing we recommend you read through the Makefile directives related to generation of API configurations, and run through the Kubebuilder Quickstart Documentation documentation in order to familiarize yourself with how the command line works, how to add new APIs and controllers, and how to update existing APIs.

Make sure you're generally familiar with Kubernetes Controllers as a concept, and how to build them.

Running in dev mode

You can run the ingress controller without building a Docker Image and installing it onto your docker container.

Following is a helpful shell script that you could use to run the Ingress Controller without building the Ingress Controller:

#!/bin/bash
pkill -f kubectl
# setup proxies
kubectl port-forward svc/kong-proxy -n kong 8443:443 2>&1 > /dev/null &
kubectl port-forward svc/kong-proxy -n kong 8000:80 2>&1 > /dev/null &
kubectl port-forward deploy/ingress-kong -n kong 8444:8444 2>&1 > /dev/null &
kubectl proxy --port=8002 2>&1 > /dev/null &

export POD_NAME=`kubectl get po -n kong -o json | jq ".items[] | .metadata.name" -r | grep ingress`
export POD_NAMESPACE=kong

go run -tags gcp ./internal/cmd/main.go \
--kubeconfig ~/.kube/config \
--publish-service=kong/kong-proxy \
--apiserver-host=http://localhost:8002 \
--kong-admin-url https://localhost:8444 \
--kong-admin-tls-skip-verify true

If you are using Kind we can leverage extraPortMapping config

cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 8000
    hostPort: 8000
    protocol: TCP
  - containerPort: 8443
    hostPort: 8443
    protocol: TCP
EOF

# mapping host ports to a kong ingress container port
kubectl patch -n kong deploy ingress-kong -p '{"spec": {"template": {"spec": {"containers": [{"name": "proxy", "ports": [{"containerPort": 8000, "hostPort": 8000, "name": "proxy", "protocol": "TCP"}, {"containerPort": 8443, "hostPort": 8443, "name": "proxy-ssl", "protocol": "TCP"}]}]}}}}'

Building

Build is performed via Makefile. Depending on your requirements you can build a raw server binary, a local container image, or push an image to a remote repository.

Build a raw server binary

make build

Build a local container image

TAG=DEV REGISTRY=docker.example.com/registry make container

Note: this will use the Docker daemon running on your system. If you're developing using minikube, you should execute the following to use the Docker daemon running inside the Minikube VM:

eval $(minikube docker-env)

This will allow you to publish images to Minikube VM, allowing you to reference them in your Deployment specs.

Push the container image to a remote repository

docker push docker.example.com/registry/kong-ingress-controller:DEV

Note: replace docker.example.com/registry with your registry URL.

Deploying

There are several ways to deploy Kong Ingress Controller onto a cluster. Please check the deployment guide.

Linting

You can lint the codebase by running:

make lint

passing the above is required by CI.

Testing

Please see TESTING.md for a detailed description of testing KIC.

Releasing

See RELEASE.md.

Contributor Badge

If your Pull Request to Kong/kubernetes-ingress-controller was accepted, and it fixes a bug, adds functionality, or makes it significantly easier to use or understand KIC, congratulations! You are eligible to receive a digital Contributor Badge! Go ahead and fill out the Contributors Submissions form.

Badges expire after 1 year, at which point you may submit a new contribution to renew the badge.