Merge pull request #7 from projectsyn/release

Release v0.1.0

CHANGELOG.md

@@ -9,4 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - …
 
+## [v0.1.0] - 2020-10-16
+
+Release as open source code
+
+### Added
+
+- Made list of expected and known to fail types configurable ([#4])
+
+### Changed
+
+- Clean up code base ([#1])
+- Stream archive before exit ([#5])
+- Included more files in output ([#6])
+
+### Removed
+
+- Droped creation of output directory ([#3])
+
 [Unreleased]: https://github.com/projectsyn/component-k8s-object-dumper/compare/v0.1.0...HEAD
+[v0.1.0]: https://github.com/projectsyn/component-k8s-object-dumper/releases/tag/v0.1.0
+
+[#1]: https://github.com/projectsyn/k8s-object-dumper/pull/1
+[#3]: https://github.com/projectsyn/k8s-object-dumper/pull/3
+[#4]: https://github.com/projectsyn/k8s-object-dumper/pull/4
+[#5]: https://github.com/projectsyn/k8s-object-dumper/pull/5
+[#6]: https://github.com/projectsyn/k8s-object-dumper/pull/6

README.md

@@ -4,7 +4,87 @@ K8s Object Dumper allows to collect all objects from Kubernetes and write them i
 It is written to be used as a pre backup command for [K8up](https://k8up.io).
 
 This repository is part of Project Syn.
-For documentation on Project Syn and this component, see https://syn.tools.
+For documentation on Project Syn, see https://syn.tools.
+
+K8s Object Dumper consists of a shell script.
+This script uses the Kubernetes API to list each and every API and Kind known to the targeted cluster.
+It then dumps all those kinds to Json files (one file per kind).
+For easier restore, those dumped objects then get split up by namespace and kind.
+
+The resulting structure looks like the following:
+
+```
+├─ objects-<kind>.json
+├─ …
+└─ split/
+   ├─ <namespace>/
+   |  ├─ __all__.json
+   |  ├─ <kind>.json
+   |  └─ …
+   └─ …
+```
+
+## Usage
+
+Using Docker
+
+```bash
+docker run --rm -v "/path/to/kubeconfig:/kubeconfig" -e KUBECONFIG=/kubeconfig -v "${PWD}/data:/data" projectsyn/k8s-object-dumper:latest -d /data > objects.tar.gz
+```
+
+Using Kubernetes (with K8up)
+
+See [Commodore Component: cluster-backup](https://github.com/projectsyn/component-cluster-backup).
+
+## Configuration
+
+The `dump-objects` scripts reads configuration from two files.
+
+`/usr/local/share/k8s-object-dumper/must-exists` contains a list of types that must exist within the list of discovered types.
+This is a safeguard helping to detect failure of the discover mechanism.
+Types must be all lower case and plural.
+One type per line.
+
+Example:
+
+```
+configmaps
+daemonsets
+deployments
+endpoints
+ingresses
+jobs
+namespaces
+nodes
+persistentvolumeclaims
+persistentvolumes
+replicasets
+roles
+secrets
+serviceaccounts
+services
+statefulsets
+```
+
+Some types can not be exported and the script will return an error for them.
+Those errors can be suppressed by placing those types in `/usr/local/share/k8s-object-dumper/known-to-fail`.
+Like `must-exist` types are listed line by line but in addition Bash regular expressions can be used.
+
+
+Example:
+
+```
+.+mutators
+.+reviews
+.+validators
+bindings
+deploymentconfigrollbacks
+imagesignatures
+imagestream.+
+mutations
+useridentitymappings
+validations
+```
 
 ## Contributing and license