From a03bc328a9fadab9779b1df63b7b0d0f9219ff9b Mon Sep 17 00:00:00 2001 From: Shane Utt <shaneutt@linux.com> Date: Tue, 10 Sep 2019 14:02:18 -0400 Subject: [PATCH] Update README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 16 ++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1d459b0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +Kubeaddons-Configs is an Addon Repository which manages a predefined set of Addons and their configurations for deployment via [Kubeaddons](https://github.com/mesosphere/kubeaddons). + +The [Kubeaddons Contributing Documentation](https://github.com/mesosphere/kubeaddons/blob/master/CONTRIBUTING.md) governs contributions to this repo in addition to other sections of this document. + +## PR Readiness + +PR's should be marked `wip` until the following are taken care of: + +1. Manual testing of the Addon has succeeded against the most recent release of the `kubeaddons` controller +2. CI must pass + +Once these are complete the PR can be marked as `ready`. + +## Creating New Addons + +You can create new Addons by providing an `Addon` [resource](https://kubernetes.io/docs/concepts/) in a [manifest](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) placed in the `templates/` directory. + +See the [Custom Resource Definition](https://github.com/mesosphere/kubeaddons/blob/master/config/crd/bases/kubeaddons.mesosphere.io_addons.yaml) for the `Addon` type for structure, and the [samples](https://github.com/mesosphere/kubeaddons/tree/master/config/samples) for more explicit implementation examples. + +The overall workflow for contributing a new Addon is: + +1. define an `Addon` resource as discussed above +2. install the [Kubeaddons Controller](https://github.com/mesosphere/kubeaddons/blob/master/config/samples/manager.yaml) to your Kubernetes cluster +3. deploy the new `Addon` +4. watch the pod logs for the controller, and ensure that the `Addon` status becomes `ready: true` +5. test the addon functionality as appropriate for its type + +1. Manual testing of the Addon has succeeded against the most recent release of the `kubeaddons` controller +2. CI must pass + +## Customizing Existing Addons + +Addons can be customized via their manifests in the `templates/` directory. + +Changing an addons name or namespace is done in the `metadata` field. + +Configuration of the `Addon` resource itself is primarily done via via the `spec` field, particularly changing the [helm values configuration](https://v3.helm.sh/docs/topics/chart_best_practices/values/) of a helm-based addon is done via the `spec.ChartReference.Values` field. + +## ExtraSteps + +Some addons may be in need of additional logic beyond what's available in the implementing driver (e.g. Helm). For instance: it may be desired to have an addo generate a password for a user interface on startup and store that in a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/). These kinds of tasks can be accomplished by adding functionality to the [Kubeaddons Extrasteps](https://github.com/mesosphere/kubeaddons-extrasteps) repo which packages tooling into [initContainers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) and [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) for after-deployment Addon logic. + diff --git a/README.md b/README.md index 5c52a9b..427bc64 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,19 @@ # Addon Repository This is a repository for `Addon` resources managed by `Kubeaddons`. + +# Contributing + +See our [contributing documentation](/CONTRIBUTING.md) for details on how to contribute to this repo. + +## Goals + +* provides a repository for storing addon resources with default configurations +* provides alternative configurations for addons for specific cloud providers + +## Non-Goals + +Logic for addon configurations doesn't belong in these configurations, nor should changes here cover the scope of adding or managing additional resources for an addon (resources can be added via [charts](https://github.com/mesosphere/charts)). + +If optional [initContainer](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) or [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) functionality is needed for an addon you're working on you may want to use [kubeaddons extrasteps](https://github.com/mesosphere/kubeaddons-extrasteps) to add your custom logic and build a docker image for use here. It may be more appropriate to add these containers to [Charts](https://github.com/mesosphere/charts) however if they're absolutely required for the application's function. +