|
| 1 | +# How to Contribute to the OpenTelemetry Operator |
| 2 | + |
| 3 | +We'd love your help! |
| 4 | + |
| 5 | +This project is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub pull requests. This document outlines some of the conventions on development workflow, contact points and other resources to make it easier to get your contribution accepted. |
| 6 | + |
| 7 | +We gratefully welcome improvements to documentation as well as to code. |
| 8 | + |
| 9 | +## Getting Started |
| 10 | + |
| 11 | +### Workflow |
| 12 | + |
| 13 | +It is recommended to follow the ["GitHub Workflow"](https://guides.github.com/introduction/flow/). When using [GitHub's CLI](https://github.com/cli/cli), here's how it typically looks like: |
| 14 | + |
| 15 | +``` |
| 16 | +$ gh repo fork github.com/open-telemetry/opentelemetry-operator |
| 17 | +$ git checkout -b your-feature-branch |
| 18 | +# do your changes |
| 19 | +$ git commit -sam "Add feature X" |
| 20 | +$ gh pr create |
| 21 | +``` |
| 22 | + |
| 23 | +### Pre-requisites |
| 24 | +* Install [Go](https://golang.org/doc/install). |
| 25 | +* Have a Kubernetes cluster ready for development. We recommend `minikube` or `kind`. |
| 26 | + |
| 27 | +### Local run |
| 28 | + |
| 29 | +Build the manifests, install the CRD and run the operator as a local process: |
| 30 | +``` |
| 31 | +$ make manifests install run |
| 32 | +``` |
| 33 | + |
| 34 | +### Deployment with webhooks |
| 35 | + |
| 36 | +When running `make run`, the webhooks aren't effective as it starts the manager in the local machine instead of in-cluster. To test the webhooks, you'll need to: |
| 37 | + |
| 38 | +1. configure a proxy between the Kubernetes API server and your host, so that it can contact the webhook in your local machine |
| 39 | +1. create the TLS certificates and place them, by default, on `/tmp/k8s-webhook-server/serving-certs/tls.crt`. The Kubernetes API server has also to be configured to trust the CA used to generate those certs. |
| 40 | + |
| 41 | +In general, it's just easier to deploy the manager in a Kubernetes cluster instead. For that, you'll need the `cert-manager` installed. You can install it by running: |
| 42 | + |
| 43 | +```console |
| 44 | +make cert-manager |
| 45 | +``` |
| 46 | + |
| 47 | +Once it's ready, the following can be used to build and deploy a manager, along with the required webhook configuration: |
| 48 | + |
| 49 | +``` |
| 50 | +make manifests docker-build docker-push deploy |
| 51 | +``` |
| 52 | + |
| 53 | +By default, it will generate an image following the format `quay.io/${USER}/opentelemetry-operator:${VERSION}`. You can set the following env vars in front of the `make` command to override parts or the entirety of the image: |
| 54 | + |
| 55 | +* `IMG_PREFIX`, to override the registry, namespace and image name (`quay.io`) |
| 56 | +* `USER`, to override the namespace |
| 57 | +* `IMG_REPO`, to override the repository (`opentelemetry-operator`) |
| 58 | +* `VERSION`, to override only the version part |
| 59 | +* `IMG`, to override the entire image specification |
| 60 | + |
| 61 | +Your operator will be available in the `opentelemetry-operator-system` namespace. |
| 62 | + |
| 63 | +## Testing |
| 64 | + |
| 65 | +With an existing cluster (such as `minikube`), run: |
| 66 | +``` |
| 67 | +USE_EXISTING_CLUSTER=true make test |
| 68 | +``` |
| 69 | + |
| 70 | +Tests can also be run without an existing cluster. For that, install [`kubebuilder`](https://book.kubebuilder.io/quick-start.html#installation). In this case, the tests will bootstrap `etcd` and `kubernetes-api-server` for the tests. Run against an existing cluster whenever possible, though. |
| 71 | + |
| 72 | +## Project Structure |
| 73 | + |
| 74 | +Here's a general overview of the directories from this operator and what to expect in each one of them: |
| 75 | + |
| 76 | +``` |
| 77 | +. |
| 78 | +├── api # the CRDs that are handled by this operator |
| 79 | +│ └── v1alpha1 # the (currently) only CRD version we have |
| 80 | +├── build # where the binaries are placed after `make manager` |
| 81 | +├── config # the Kustomize resources that are used to assemble the operator's deployment units |
| 82 | +│ ├── certmanager # Kustomize options dealing with cert-manager |
| 83 | +│ ├── crd # Kustomize options for our CRDs |
| 84 | +│ │ ├── bases # auto generated based on the code annotations (`make manifests`) |
| 85 | +│ │ └── patches # patches to apply to the generated CRD |
| 86 | +│ ├── default # Kustomize's "entry point", generating the distribution YAML file |
| 87 | +│ ├── manager # the operator's Deployment |
| 88 | +│ ├── manifests # the resulting CSV |
| 89 | +│ │ └── bases |
| 90 | +│ ├── prometheus # ServiceMonitor that exposes our operator's metrics |
| 91 | +│ ├── rbac # RBAC rules |
| 92 | +│ ├── samples # Set of examples of how to accomplish specific scenarios. Those are bundled in the final CSV |
| 93 | +│ └── webhook # Webhook configuration and service |
| 94 | +├── controllers # our main controller, where the reconciliation starts |
| 95 | +├── hack # utility scripts |
| 96 | +├── internal # code shared with our internal packages |
| 97 | +│ ├── config # our operator's runtime configuration |
| 98 | +│ ├── podinjector # the webhook that injects sidecars into pods |
| 99 | +│ └── version # our version, as well as versions of underlying components |
| 100 | +├── local # local resources that shouldn't be added to the version control, like CRs used for dev/testing |
| 101 | +└── pkg # packages that are exporter and are part of the public API for this module |
| 102 | + ├── autodetect # auto detect traits from the environment (platform, APIs, ...) |
| 103 | + ├── collector # code that handles OpenTelemetry Collector |
| 104 | + │ ├── adapters # data conversion |
| 105 | + │ ├── parser # parses the OpenTelemetry Collector configuration |
| 106 | + │ ├── reconcile # reconciliation logic for OpenTelemetry Collector components |
| 107 | + │ └── upgrade # handles the upgrade routine from one OpenTelemetry Collector to the next |
| 108 | + ├── naming # determines the names for components (containers, services, ...) |
| 109 | + ├── platform # target platforms this operator might run |
| 110 | + └── sidecar # operations related to sidecar manipulation (add, update, remove) |
| 111 | +``` |
| 112 | + |
| 113 | +## Contributing |
| 114 | + |
| 115 | +Your contribution is welcome! For it to be accepted, we have a few standards that must be followed. |
| 116 | + |
| 117 | +### New features |
| 118 | + |
| 119 | +Before starting the development of a new feature, please create an issue and discuss it with the project maintainers. Features should come with documentation and enough tests (unit and/or end-to-end). |
| 120 | + |
| 121 | +### Bug fixes |
| 122 | + |
| 123 | +Every bug fix should be accompanied with a unit test, so that we can prevent regressions. |
| 124 | + |
| 125 | +### Documentation, typos, ... |
| 126 | + |
| 127 | +They are mostly welcome! |
0 commit comments