Skip to content

Latest commit

 

History

History
217 lines (162 loc) · 8.67 KB

CONTRIBUTING.md

File metadata and controls

217 lines (162 loc) · 8.67 KB
Raw

Contributing

House rules

  • Commit history must be linear (enforced via GitHub settings).
  • Pull Requests must have their title comforming to the conventional commits specification (enforced via a build workflow).
  • PR's are squashed on merge (enforced via GitHub settings).
  • The PR's title and description are used as to create the message of the squashed commit that is merged into main.
  • The changelog is automatically updated on release based on the commit history.

Local testing with Minikube

Install minikube, Helm, Go and a local Docker daemon, e.g., Docker Desktop.

Set up your Docker engine to use insecure registries (on Mac OS with Docker Desktop for Mac, the file to edit is ~/.docker/daemon.json):

{
  ...
  "insecure-registries" : [
    "host.docker.internal:5000"
  ],
  ...
}

Start minikube:

minikube start --insecure-registry "host.docker.internal:5000"
  • Note that if the minikube machine already exists, you will need to delete it first with minikube delete - otherwise the --insecure-registry parameter will be ignored (more details here)

Start a local Docker registry:

docker run -d -p 5000:5000 --restart=always --name registry registry:latest

Validate that the local registry works by calling its HTTP API:

$ curl localhost:5000/v2/_catalog -v
*   Trying ::1:5000...
* Connected to localhost (::1) port 5000 (#0)
> GET /v2/_catalog HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.77.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Docker-Distribution-Api-Version: registry/2.0
< X-Content-Type-Options: nosniff
< Date: Fri, 20 Jan 2023 08:10:32 GMT
< Content-Length: 20
<
{"repositories":[]}
* Connection #0 to host localhost left intact

Deploy with Helm

Deploy the Lumigo Kubernetes operator with:

make docker-build docker-push
helm upgrade --install lumigo charts/lumigo-operator --namespace lumigo-system --create-namespace --set "debug.enabled=true"

To avoid strange issues with Docker caching the wrong images in your test environment, it is usually a better to always build a new image tag:

export IMG_VERSION=1 # Incremend this every time to try a deploy
make docker-build docker-push
helm dependency build
helm upgrade --install lumigo charts/lumigo-operator --namespace lumigo-system --create-namespace --set "controllerManager.manager.image.tag=${IMG_VERSION}" --set "controllerManager.telemetryProxy.image.tag=${IMG_VERSION}" --set "debug.enabled=true"

(Notice that the --set "debug.enabled=true" is of course optional, but in development is very handy, as it will, among other things, make the telemetry-proxy container log which OTLP data it sends upstream.) Changing the target Lumigo backend is not supported with Helm (because we do not expect end users ever to have to).

Deploy with Kustomize

Install cert-manager with:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml

Deploy the Lumigo Kubernetes operator with:

kubectl create namespace lumigo-system
kubectl apply -k config/default -n lumigo-system

Changing the target Lumigo backend can be done with a patchStrategicMerge:

echo -n "apiVersion: apps/v1
kind: Deployment
metadata:
  name: lumigo-lumigo-operator-controller-manager
spec:
  template:
    spec:
      containers:
      - name: telemetry-proxy
        env:
        - name: LUMIGO_ENDPOINT
          value: \"https://my.lumigo.endpoint\" # Replace this!
        - name: LUMIGO_LOGS_ENDPOINT
          value: \"https://my.lumigo.endpoint\" # Replace this!
        - name: LUMIGO_METRICS_ENDPOINT
          value: \"https://my.lumigo.endpoint\" # Replace this!
" > lumigo-endpoint.patch.yaml
kubectl patch --patch-file lumigo-endpoint.patch.yaml --type strategic -n lumigo-system --filename=lumigo-endpoint.patch.yaml

Troubleshooting

What listens on port 5000 is not behaving like a registry

If you see the following, it's likely because and Mac OS has squatted over port 5000 with the AirPlay receiver:

docker push host.docker.internal:5000/controller
Using default tag: latest
The push refers to repository [host.docker.internal:5000/controller]
377b701db379: Preparing
fba4381f2bb7: Preparing
error parsing HTTP 403 response body: unexpected end of JSON input: ""

To fix it, disable AirPlay Receiver in System Preferences --> Sharing --> AirPlay Receiver.

ErrImagePull for the Operator image

If you see which when checking the controller pod with kubectl describe pod:

  Warning  Failed     7s (x3 over 49s)   kubelet            Failed to pull image "host.docker.internal:5000/controller:latest": rpc error: code = Unknown desc = Error response from daemon: Get "https://host.docker.internal:5000/v2/": http: server gave HTTP response to HTTPS client

Then you likely have not started minikube with the --insecure-registry "10.0.0.0/24,192.168.39.0/24,host.docker.internal" startup parameter. You will need to destroy the minikube installation, as the --insecure-registry parameter is accepted only on creation:

$ minikube delete
🔥  Deleting "minikube" in docker ...
🔥  Deleting container "minikube" ...
🔥  Removing /Users/mmanciop/.minikube/machines/minikube ...
💀  Removed all traces of the "minikube" cluster.
$ minikube start --insecure-registry "host.docker.internal:5000"

Various Helm stuff

upgrade --install fails with "no deployed releases": running helm upgrade --install should precisely avoid these situations, making helm behave like an upsert, right? However, sometimes dirty state left by failed uninstall procedures prevents Helm from being able to upsert, and to fix it, you run:

kubectl delete secrets --all -n lumigo-system

See How to fix Helm's "Upgrade Failed: has no deployed releases" error for more info.

End-to-end tests with Kind

Install kind and run:

(cd tests/kubernetes-distros/kind; go test)

Helm chart

The first version of the Helm chart has been generated with helmify by running kustomize build config/default | helmify deploy/helm. However, manual edits and corrections were necessary, and running helmify again would override them. The Helm website has a handy guide to the basics of Helm Chart templating.

Change version of the OpenTelemetry Collector Contrib to be used as telemetry-proxy

The telemetryproxy/VERSION.otelcontibcol file contains the release name of the OpenTelemetry Collector Contrib to be used from the lumigo-io/opentelemetry-collector-contrib repository.

Automated tests

Unit tests

The unit tests for the controller are run from the root of the repository with:

make test

End-to-end Kind tests

End-to-end tests run the entire operator using Kind via the E2E-Framework and are run from the root of the repository with:

export IMG_VERSION=<incremental_number> # Avoid image cache issues
make docker-build docker-push
(cd tests/kubernetes-distros/kind && go test)

Running specific tests

If you're focusing on a specific set of tests in a file, you can run those only using the follwing syntax:

export IMG_VERSION=<incremental_number> # Avoid image cache issues
make docker-build docker-push
(cd tests/kubernetes-distros/kind && go test -run TestLumigoOperatorInfraMetrics -assess "some text")

That will run only the tests under the test functions named TestLumigoOperatorInfraMetrics, and only the ones having some text in their title.

Note: The build of the controller and telemetry-proxy images assume the local repository setup documented in the Local testing with Minikube section.