This repository has been archived by the owner on Jun 12, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #13 from caos/docs
docs: create docs
- Loading branch information
Showing
18 changed files
with
468 additions
and
558 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,106 +1,101 @@ | ||
| This project is in alpha state | ||
| ----- | ||
|
|
||
| # boom | ||
| Operator to deploy defined toolsets into K8s-clusters | ||
|
|
||
| # Internal logic | ||
|
|
||
| ## Folder structure | ||
|
|
||
| The boom will extend the existing tools folder with different subfolders for the necessary applications. | ||
| For each crd there will be an subfolder for each application where the generated values.yaml and kustomization.yaml are stored. | ||
| As a result of this files there will be an results.yaml under the subfolder results/*crd-name*/. | ||
|
|
||
| Like this: | ||
|
|
||
| * tools | ||
| * logging-operator | ||
| * *crd-name* | ||
| * templator.yaml | ||
| * kustomization.yaml | ||
| * values.yaml | ||
| * results | ||
| * *crd-name* | ||
| * results.yaml | ||
| * start.sh | ||
| * fetch-all.sh | ||
| * *helm* | ||
| * *charts* | ||
| * kustomize | ||
| # boom: the base tooling operator | ||
|
|
||
|  | ||
|  | ||
| [](https://github.com/caos/boom/blob/master/LICENSE) | ||
| [](https://GitHub.com/caos/boom/releases/) | ||
|
|
||
| > This project is in alpha state. The API will continue breaking until version 1.0.0 is released | ||
| ## What is it | ||
|
|
||
| `boom` is designed to ensure that someone can create a reproducable "platform" with tools which are tested for their interoperability. | ||
|
|
||
| Currently we include the following tools: | ||
|
|
||
| - Ambassador Edge Stack | ||
| - Prometheus Operator | ||
| - Grafana | ||
| - logging-operator | ||
| - kube-state-metrics | ||
| - prometheus-node-exporter | ||
| - loki | ||
| - ArgoCD | ||
|
|
||
| Upcoming tools: | ||
|
|
||
| - Flux | ||
|
|
||
| ## How does it work | ||
|
|
||
| The operator works by reading a configuration (crd) located in a GIT Repository. Alternativly this `crd` can be read from the k8s api. | ||
| In our default setup our "cluster lifecycle" tool `orbiter`, shares the repository and secrets with `boom`. This because `orbiter` deploys `boom` in a newly creadted `k8s` cluster. | ||
|
|
||
| ```yaml | ||
| apiVersion: boom.caos.ch/v1beta1 | ||
| kind: Toolset | ||
| metadata: | ||
| name: caos | ||
| namespace: caos-system | ||
| spec: | ||
| kubeVersion: v1.17.0 | ||
| prometheus-operator: | ||
| deploy: true | ||
| logging-operator: | ||
| deploy: true | ||
| prometheus-node-exporter: | ||
| deploy: true | ||
| grafana: | ||
| deploy: true | ||
| ambassador: | ||
| deploy: false | ||
| kube-state-metrics: | ||
| deploy: true | ||
| argocd: | ||
| deploy: false | ||
| prometheus: | ||
| deploy: true | ||
| loki: | ||
| deploy: false | ||
| ``` | ||
| also are there the differnt tools for templating, the charts folder consists of all fetchet charts localy, the kustomize folder has the necessary shell scripts for the templators and the helm folder is the helm-home folder. | ||
| The charts will get fetched during the docker build phase with running of the fetch-all.sh. | ||
| ## How to use it | ||
| To start the different steps: | ||
| > Due to the github restriciton that even public images need to be authenticated, you need to make sure that you have `pull secret`. The used `personal access token` has to have the `repo` and `read:packages` permissions. | ||
|
|
||
| ```bash | ||
| # fetch chart for local | ||
| ./fetch-all.sh *toolset* | ||
| # template chart with values.yaml | ||
| ./start.sh *application* *crd-name* | ||
| # apply results to cluster | ||
| kubectl apply -f *application*/results/*crd-name*/results.yaml | ||
| kubectl -n caos-system create secret docker-registry boomregistry --docker-server=docker.pkg.github.com --docker-username=${GITHUB_USERNAME} --docker-password=${GITHUB_ACCESS_TOKEN} | ||
| ``` | ||
|
|
||
| ## toolsets | ||
|
|
||
| To add any new toolset or change existing ones look into the toolsets folder. | ||
| The structure in this folder is *important* as it is as follows: | ||
|
|
||
| * tools | ||
| * toolsets | ||
| * *toolset-name* | ||
| * *application-name*.yaml | ||
|
|
||
| It is *important* as the boom has logic which works over this structure to build the knowledge which toolsets are existing and out of which applications do they consist. | ||
| ### GitOps Mode | ||
|
|
||
| ## used tools | ||
| #### Demo with a public crd repository | ||
|
|
||
| The following cli-tools are used from the boom: | ||
| To easy test the example we have created a `demo crd repo`, located here . It holds a `boom.yml` which can be applied to your cluster. | ||
|
|
||
| * helm | ||
| * kubectl | ||
| * kustomize | ||
| Apply `Boom` to your cluster: | ||
|
|
||
| As they are used, they also have to be installed into the image during the docker build. | ||
|
|
||
| # To let it run | ||
|
|
||
| ## locally | ||
|
|
||
| Before you can run locally you have to fetch all charts: | ||
| ```bash | ||
| ./tools/fetch-all.sh *toolset* | ||
| kustomize build examples/gitops/publicrepo | kubectl apply -f - | ||
| ``` | ||
|
|
||
| To decrypt the secretdata to run it locally: | ||
| #### Example with a private repository | ||
|
|
||
| ```bash | ||
| gopass caos-secrets/technical/boom/ansible-vault > ansible-vault-secret && \ | ||
| ansible-vault decrypt --vault-password-file ansible-vault-secret config/manager/secret/id_rsa-boom-tools-read && \ | ||
| rm ansible-vault-secret | ||
| ``` | ||
| Your first have to create an ssh-key which is added as deploy key to your git repository and then save the private key as secret in examples/gitops/privaterepo/secret. | ||
| Change the name of the key in the examples/gitops/privaterepo/kustomization.yaml with the filename of the saved key. | ||
|
|
||
| To encrypt it again: | ||
| Apply `Boom` to your cluster: | ||
|
|
||
| ```bash | ||
| gopass caos-secrets/technical/boom/ansible-vault > ansible-vault-secret && \ | ||
| ansible-vault encrypt --vault-password-file ansible-vault-secret config/manager/secret/id_rsa-boom-tools-read && \ | ||
| rm ansible-vault-secret | ||
| kustomize build examples/gitops/publicrepo | kubectl apply -f - | ||
| ``` | ||
|
|
||
| To build it: | ||
| #### k8s API Mode | ||
|
|
||
| ```bash | ||
| docker build -t controller:latest . | ||
| ``` | ||
| example coming soon | ||
|
|
||
| ## cluster | ||
| ## License | ||
|
|
||
| To deploy the boom to a cluster: | ||
| As usual Apache-2.0 see [here](./LICENSE) | ||
|
|
||
| ```bash | ||
| cd config/manager && kustomize edit set image controller=docker.pkg.github.com/caos/boom/boom:latest && cd ../.. | ||
| kustomize build config/default | kubectl apply -f - | ||
| ``` | ||
| Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
Oops, something went wrong.