From 4daaaf87a2d3d0c63dfbc708183bce4eaedabbf4 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 25 Oct 2023 14:19:23 +0300 Subject: [PATCH 1/5] Add concepts page to docs Signed-off-by: Stefan Prodan --- docs/concepts.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/concepts.md diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 00000000..50db10e0 --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,185 @@ +# Concepts + +![Timoni](images/logo_text_black.svg#only-light){ width="200" } +![Timoni](images/logo_text_white.svg#only-dark){ width="200" } + +- [Module](#module) - App definition containing Kubernetes CUE templates and configuration schema, distributed as OCI artifacts. +- [Instance](#instance) - App instantiation referencing the module and workloads deployed on a Kubernetes cluster. +- [Bundle](#bundle) - App composition bundling multiple modules and configurations into a deployable unit. +- [Artifact](#artifact) - Packaging format used for distributing modules and bundles to container registries. + +## :fontawesome-solid-cube: Module + +A Timoni module contains a set of CUE definitions and constraints organised +into a [CUE module](https://cuelang.org/docs/concepts/packages/) +with an opinionated structure. + +A module accepts a set of values supplied by users, +and outputs a set of Kubernetes objects that Timoni deploys on Kubernetes clusters. + +Module structure: +```sh +app +├── cue.mod # Kubernetes APIs and CRDs schemas +├── templates # Workloads and app config schema +├── timoni.cue # Timoni entry point +└── values.cue # Default config values +``` + +Commands for working with local modules: + +- `timoni mod init ` +- `timoni mod vet ` +- `timoni build -n ` +- `timoni apply -f --dry-run --diff` + +Commands for vendoring Kubernetes APIs and CRDs: + +- `timoni mod vendor k8s --version latest` +- `timoni mod vendor crds -f ` + +Timoni modules are distributed as OCI artifacts that can be cryptographically [signed and verified](module-sign.md). +Modules are versioned using strict [semantic versioning](module-distribution.md#version-format), +the version of a module is used as the OCI artifact tag. + +To learn more about modules, please see the [module documentation](module.md). + +## :fontawesome-solid-share-from-square: Instance + +A Timoni instance represent a module instantiation on a Kubernetes cluster. +A module can be installed multiple times on a cluster by giving its instances +unique names per namespace. + +When instantiating a module, users can supply their own `values.cue` +that gets merged with the defaults included in the module: + +```cue +values: { + ingress: { + enabled: true + className: "nginx" + host: "app.example.com" + } + autoscaling: enabled: true + monitoring: enabled: true +} +``` + +Commands for working with module instances: + +- `timoni install oci:// -v -n ` +- `timoni upgrade oci:// -v -f ` +- `timoni uninstall -n ` +- `timoni list -n ` +- `timoni inspect [module|values|resources] -n ` +- `timoni status -n ` + +The `install` and `upgrade` commands are aliases of `timoni apply`. +To apply the Kubernetes resources belonging to a module instance, +Timoni uses Kubernetes server-side apply and +[Flux](https://fluxcd.io)'s drift detection. + +The apply command validates all resources with a dry-run apply, +and reconciles only the ones with changes to the cluster state. + +Timoni's garbage collector keeps track of the applied resources +and prunes the Kubernetes objects that were previously applied +but are missing from the current revision. + +After an installation or upgrade, Timoni waits for the +applied resources to be fully reconciled by checking the ready status +of deployments, jobs, services, ingresses, and Kubernetes custom resources. + +## :fontawesome-solid-layer-group: Bundle + +Timoni bundles offer a declarative way of managing the lifecycle of applications and their infra dependencies. + +A Timoni bundle is a CUE file for defining a group of instances together with their values and module references: + +```cue +bundle: { + apiVersion: "v1alpha1" + name: "podinfo" + instances: { + redis: { + module: { + url: "oci://ghcr.io/stefanprodan/modules/redis" + version: "7.0.9" + } + namespace: "podinfo" + values: maxmemory: 256 + } + podinfo: { + module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" + module: version: "6.3.4" + namespace: "podinfo" + values: caching: { + enabled: true + redisURL: "tcp://redis:6379" + } + } + } +} +``` + +For deterministic operations, it is possible to pin a module version by its OCI digest: + +```cue +redis: { + module: { + url: "oci://ghcr.io/stefanprodan/modules/redis" + digest: "sha256:e9137d41b0d263bfaf2a43fc862648ad9dc3a976b4b0fc6e27617ea28ee27d45" + } +} +``` + +!!! tip "Bundle example" + + An example bundle can be found in Timoni's repository at + [examples/bundles/podinfo.cue](https://github.com/stefanprodan/timoni/tree/main/examples/bundles/). + This bundle defines a Redis master-replica cluster and a podinfo instance connected to the Redis instance. + The secret values are defined in a separate file which can be kept encrypted or pulled from a secure vault at apply time. + +In the bundle files you can use arithmetic operations, +string interpolation and everything else that CUE std lib supports. + +Commands for working with bundles: + +- `timoni bundle lint -f bundle.cue` +- `timoni bundle build -f bundle.cue -f bundle_extras.cue` +- `timoni bundle apply -f bundle.cue --runtime runtime.cue --diff` +- `timoni bundle delete -f bundle.cue` + +To learn more about bundles, please see the [Bundle API documentation](bundle.md) +and the [Bundle Runtime API documentation](bundle-runtime.md). + +## :fontawesome-solid-box: Artifact + +Timoni modules and bundles are distributed to container registries as +[Open Container Initiative](https://opencontainers.org/) (OCI) artifacts. + +The OCI artifacts produced by Timoni have the following media types: + +- Image media type `application/vnd.oci.image.manifest.v1+json` +- Config media type `application/vnd.timoni.config.v1+json` +- Layer media type `application/vnd.timoni.content.v1.tar+gzip` + +To enable reproducible builds, Timoni sets the artifact's last modified date, +the source URL and source revision annotations from the Git metadata. + +Commands for managing the authentication to container registries: + +- `timoni registry login -u -p ` +- `timoni registry logout ` + +Commands for distributing modules: + +- `timoni mod push oci:// -v --sign` +- `timoni mod pull oci:// -v -o --verify` +- `timoni mod list oci://` + +Commands for distributing bundles and runtimes: + +- `timoni artifact push oci:// -t -f ` +- `timoni artifact pull oci:// -o ` +- `timoni artifact list oci://` From d45c3a12e9fb5f400537ff8492b09a60efa6fb7f Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 25 Oct 2023 14:20:05 +0300 Subject: [PATCH 2/5] Hide toc on CLI docs Signed-off-by: Stefan Prodan --- cmd/timoni/docgen.go | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cmd/timoni/docgen.go b/cmd/timoni/docgen.go index a7cf3913..9a7ff5ab 100644 --- a/cmd/timoni/docgen.go +++ b/cmd/timoni/docgen.go @@ -28,6 +28,9 @@ import ( ) const fmTemplate = `--- +hide: + - toc +--- title: "%s" --- ` @@ -70,5 +73,5 @@ func frontmatterPrepender(filename string) string { func linkHandler(name string) string { base := strings.TrimSuffix(name, path.Ext(name)) - return "../" + strings.ToLower(base) + "/" + return strings.ToLower(base) + ".md" } From 76a5d9114847f583ef38115b4b44fef5846242e7 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 25 Oct 2023 14:21:07 +0300 Subject: [PATCH 3/5] Link to concepts page Signed-off-by: Stefan Prodan --- README.md | 144 ++++-------------------------------------------------- 1 file changed, 9 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index 278a2c3f..482a1dbd 100644 --- a/README.md +++ b/README.md @@ -27,142 +27,16 @@ To get started with Timoni please visit the documentation website at [timoni.sh] ## Concepts -If you are familiar with Helm, a Timoni **[module](https://timoni.sh/module/)** is the equivalent of a **chart**, -a Timoni **[bundle](https://timoni.sh/bundle/)** is the equivalent of an **umbrella chart**, -and a Timoni **[instance](#timoni-instances)** is the equivalent of a Helm **release**. +- [Module](https://timoni.sh/concepts/#module) - App definition containing Kubernetes CUE templates and configuration schema, distributed as OCI artifacts. +- [Instance](https://timoni.sh/concepts/#instance) - App instantiation referencing the module and workloads deployed on a Kubernetes cluster. +- [Bundle](https://timoni.sh/concepts/#bundle) - App composition bundling multiple modules and configurations into a deployable unit. +- [OCI Artifact](https://timoni.sh/concepts/#artifact) - Packaging format used for distributing modules and bundles to container registries. -### Timoni Modules - -A Timoni module contains a set of CUE definitions and constraints organised -into a [CUE module](https://cuelang.org/docs/concepts/packages/) -with an opinionated structure. -A module accepts a set of values supplied by the user as `values.cue` files, -and outputs a set of Kubernetes objects that Timoni deploys on Kubernetes. - -Module structure: -```sh -├── README.md -├── cue.mod -│   ├── gen # Kubernetes APIs and CRDs schemas -│   ├── pkg # Timoni APIs schemas -│   └── module.cue # Module metadata -├── templates -│   ├── config.cue # Config schema and default values -│   ├── deployment.cue # Kubernetes Deployment template -│   └── service.cue # Kubernetes Service template -├── timoni.cue # Timoni entry point -├── timoni.ignore # Timoni ignore rules -└── values.cue # Timoni values placeholder -``` - -Module examples can be found at [examples/minimal](examples/minimal) and [examples/redis](examples/redis). - -Commands for working with local modules: - -- `timoni mod init ` -- `timoni mod vet ` -- `timoni build -n ` -- `timoni apply -f --dry-run --diff` - -Commands for vendoring Kubernetes APIs and CRDs: - -- `timoni mod vendor k8s --version latest` -- `timoni mod vendor crds -f ` - -Timoni modules are distributed as OCI artifacts and can be stored in container registries. - -Commands for working with remote modules: - -- `timoni mod push oci:// -v ` -- `timoni mod pull oci:// -v -o ` -- `timoni mod list oci://` - -To learn more about modules, please see the documentation for [Module structure](https://timoni.sh/module/) -and [Module distribution](https://timoni.sh/module-distribution/). - -### Timoni Instances - -A Timoni instance represent a module instantiation on a Kubernetes cluster. -A module can be installed multiple times on a cluster by giving its instances -unique names per namespace. - -When instantiating a module, users can supply their own `values.cue` -that gets merged with the defaults included in the module: - -```cue -values: { - ingress: { - enabled: true - className: "nginx" - host: "app.example.com" - } - autoscaling: enabled: true - monitoring: enabled: true -} -``` - -Commands for working with instances: - -- `timoni apply oci:// -v -f ` -- `timoni delete -n ` -- `timoni list -n ` -- `timoni inspect [module|values|resources] -n ` -- `timoni status -n ` - -To learn more about instances, please read the [docs](https://timoni.sh/#timoni-instances). - -### Timoni Bundles - -Timoni bundles offer a declarative way of managing the lifecycle of applications and their infra dependencies. - -A Timoni bundle is a CUE file for defining a group of instances together with their values and module references: - -```cue -bundle: { - apiVersion: "v1alpha1" - name: "podinfo" - instances: { - redis: { - module: { - url: "oci://ghcr.io/stefanprodan/modules/redis" - version: "7.2.2" - } - namespace: "podinfo" - values: maxmemory: 256 - } - podinfo: { - module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" - module: version: "6.5.2" - namespace: "podinfo" - values: caching: { - enabled: true - redisURL: "tcp://redis:6379" - } - } - } -} -``` - -In the bundle files you can use arithmetic operations, -string interpolation and everything else that CUE std lib supports. - -Commands for working with bundles: - -- `timoni bundle lint -f bundle.cue` -- `timoni bundle build -f bundle.cue` -- `timoni bundle apply -f bundle.cue` -- `timoni bundle delete -f bundle.cue` - -Commands for distributing bundles and runtimes: - -- `timoni artifact push oci:// -t -f ` -- `timoni artifact pull oci:// -o ` -- `timoni artifact list oci://` - -To learn more about bundles, please see the documentation: -- [Bundle API](https://timoni.sh/bundle/) -- [Bundle Runtime API](https://timoni.sh/bundle-runtime/) -- [Bundle distribution](https://timoni.sh/bundle-distribution/) +> **Note** +> +> If you are familiar with Helm, a Timoni **[module](https://timoni.sh/module/)** is the equivalent of a **chart**, +> a Timoni **[bundle](https://timoni.sh/bundle/)** is the equivalent of an **umbrella chart**, +> and a Timoni **[instance](https://timoni.sh/concepts/#instance)** is the equivalent of a Helm **release**. ## Contributing From 00634189c0fa36308a25625d6569647233adf7cb Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 25 Oct 2023 14:22:15 +0300 Subject: [PATCH 4/5] Design the homepage of Timoni's website Signed-off-by: Stefan Prodan --- .github/workflows/docs.yaml | 1 + docs/bundle-distribution.md | 2 +- docs/images/logo_icons.svg | 1 + docs/images/logo_indigo.svg | 1 + docs/images/logo_text_black.svg | 1 + docs/images/logo_text_white.svg | 1 + docs/index.md | 202 +------------------------- docs/module-distribution.md | 2 +- docs/quickstart.md | 6 +- docs/theme/home.html | 247 ++++++++++++++++++++++++++++++++ docs/values.md | 85 ----------- hack/mkdocs/requirements.txt | 15 ++ mkdocs.yml | 141 +++++++++++------- 13 files changed, 366 insertions(+), 339 deletions(-) create mode 100644 docs/images/logo_icons.svg create mode 100644 docs/images/logo_indigo.svg create mode 100644 docs/images/logo_text_black.svg create mode 100644 docs/images/logo_text_white.svg create mode 100644 docs/theme/home.html delete mode 100644 docs/values.md create mode 100644 hack/mkdocs/requirements.txt diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 2c69ad1f..16dce867 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -32,3 +32,4 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CUSTOM_DOMAIN: timoni.sh CONFIG_FILE: mkdocs.yml + REQUIREMENTS: hack/mkdocs/requirements.txt diff --git a/docs/bundle-distribution.md b/docs/bundle-distribution.md index 08f1898b..6eb702f7 100644 --- a/docs/bundle-distribution.md +++ b/docs/bundle-distribution.md @@ -11,7 +11,7 @@ The OCI artifacts produced with `timoni artifact push` have the following media - Config media type `application/vnd.timoni.config.v1+json` - Layer media type `application/vnd.timoni.content.v1.tar+gzip` -The artifacts are annotated with OpenContainers +The artifacts are annotated with OCI [standard annotations](https://specs.opencontainers.org/image-spec/annotations/?v=v1.0.1#pre-defined-annotation-keys): - `org.opencontainers.image.source: ` diff --git a/docs/images/logo_icons.svg b/docs/images/logo_icons.svg new file mode 100644 index 00000000..11fa81b6 --- /dev/null +++ b/docs/images/logo_icons.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/logo_indigo.svg b/docs/images/logo_indigo.svg new file mode 100644 index 00000000..409f7aa1 --- /dev/null +++ b/docs/images/logo_indigo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/logo_text_black.svg b/docs/images/logo_text_black.svg new file mode 100644 index 00000000..2f9c1848 --- /dev/null +++ b/docs/images/logo_text_black.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/logo_text_white.svg b/docs/images/logo_text_white.svg new file mode 100644 index 00000000..26337ced --- /dev/null +++ b/docs/images/logo_text_white.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index e78f8f4e..c1af09d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,198 +1,4 @@ -# Timoni - -[Timoni](https://github.com/stefanprodan/timoni) is a package manager for Kubernetes, -powered by [CUE](https://cuelang.org/) -and inspired by [Helm](https://helm.sh/). - -The Timoni project strives to improve the UX of authoring Kubernetes configs. -Instead of mingling Go templates with YAML like Helm, -or layering YAML on top of each-other like Kustomize, -Timoni relies on cuelang's type safety, code generation and data validation features -to offer a better experience of creating, packaging and delivering apps to Kubernetes. - -!!! warning "Development phase" - - Timoni in under active development and is still in its infancy. - The APIs and interfaces may change in a backwards incompatible manner. - -## Concepts - -### Timoni Modules - -A Timoni module contains a set of CUE definitions and constraints organised -into a [CUE module](https://cuelang.org/docs/concepts/packages/) -with an opinionated structure. -A module accepts a set of values supplied by the user as `values.cue` files, -and outputs a set of Kubernetes objects that Timoni deploys on Kubernetes. - -Module structure: -```sh -├── README.md -├── cue.mod -│   ├── gen # Kubernetes APIs and CRDs schemas -│   ├── pkg # Timoni APIs schemas -│   └── module.cue # Module metadata -├── templates -│   ├── config.cue # Config schema and default values -│   ├── deployment.cue # Kubernetes Deployment template -│   └── service.cue # Kubernetes Service template -├── timoni.cue # Timoni entry point -├── timoni.ignore # Timoni ignore rules -└── values.cue # Timoni values placeholder -``` - -!!! tip "Module example" - - An example module can be found at - [stefanprodan/podinfo](https://github.com/stefanprodan/podinfo/tree/master/timoni/podinfo). - The example module is published to GitHub Container Registry and is publicly available at - [ghcr.io/stefanprodan/modules/podinfo](https://github.com/stefanprodan/podinfo/pkgs/container/modules%2Fpodinfo). - -Commands for working with local modules: - -- `timoni mod init ` -- `timoni mod vet ` -- `timoni build -n ` -- `timoni apply -f --dry-run --diff` - -Commands for vendoring Kubernetes APIs and CRDs: - -- `timoni mod vendor k8s --version latest` -- `timoni mod vendor crds -f ` - -To learn more about modules, please see the [module documentation](module.md). - -#### OCI Artifacts - -Timoni modules are distributed as OCI artifacts and can be stored in container registries -which support custom OCI media types. -Modules are versioned using strict [semantic versioning](module-distribution.md#version-format), -the version of a module is used as the OCI artifact tag. - -Commands for working with remote modules: - -- `timoni mod push oci:// -v ` -- `timoni mod pull oci:// -v -o ` -- `timoni mod list oci://` - -Timoni produces OCI artifacts that can be cryptographically [signed and verified](module-sign.md). - -### Timoni Instances - -A Timoni instance represent a module instantiation on a Kubernetes cluster. -A module can be installed multiple times on a cluster by giving its instances -unique names per namespace. - -When instantiating a module, users can supply their own `values.cue` -that gets merged with the defaults included in the module: - -```cue -values: { - ingress: { - enabled: true - className: "nginx" - host: "app.example.com" - } - autoscaling: enabled: true - monitoring: enabled: true -} -``` - -Commands for working with module instances: - -- `timoni install oci:// -v -n ` -- `timoni upgrade oci:// -v -f ` -- `timoni uninstall -n ` -- `timoni list -n ` -- `timoni inspect [module|values|resources] -n ` -- `timoni status -n ` - -The `install` and `upgrade` commands are aliases of `timoni apply`. -To apply the Kubernetes resources belonging to a module instance, -Timoni uses Kubernetes server-side apply and -[Flux](https://fluxcd.io)'s drift detection. - -The apply command validates all resources with a dry-run apply, -and reconciles only the ones with changes to the cluster state. - -Timoni's garbage collector keeps track of the applied resources -and prunes the Kubernetes objects that were previously applied -but are missing from the current revision. - -After an installation or upgrade, Timoni waits for the -applied resources to be fully reconciled by checking the ready status -of deployments, jobs, services, ingresses, and Kubernetes custom resources. - -### Timoni Bundles - -Timoni bundles offer a declarative way of managing the lifecycle of applications and their infra dependencies. - -A Timoni bundle is a CUE file for defining a group of instances together with their values and module references: - -```cue -bundle: { - apiVersion: "v1alpha1" - name: "podinfo" - instances: { - redis: { - module: { - url: "oci://ghcr.io/stefanprodan/modules/redis" - version: "7.0.9" - } - namespace: "podinfo" - values: maxmemory: 256 - } - podinfo: { - module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" - module: version: "6.3.4" - namespace: "podinfo" - values: caching: { - enabled: true - redisURL: "tcp://redis:6379" - } - } - } -} -``` - -For deterministic operations, it is possible to pin a module version by its OCI digest: - -```cue -redis: { - module: { - url: "oci://ghcr.io/stefanprodan/modules/redis" - digest: "sha256:e9137d41b0d263bfaf2a43fc862648ad9dc3a976b4b0fc6e27617ea28ee27d45" - } -} -``` - -!!! tip "Bundle example" - - An example bundle can be found in Timoni's repository at - [examples/bundles/podinfo.cue](https://github.com/stefanprodan/timoni/tree/main/examples/bundles/). - This bundle defines a Redis master-replica cluster and a podinfo instance connected to the Redis instance. - The secret values are defined in a separate file which can be kept encrypted or pulled from a secure vault at apply time. - -In the bundle files you can use arithmetic operations, -string interpolation and everything else that CUE std lib supports. - -Commands for working with bundles: - -- `timoni bundle lint -f bundle.cue` -- `timoni bundle build -f bundle.cue -f bundle_extras.cue` -- `timoni bundle apply -f bundle.cue --runtime runtime.cue --diff` -- `timoni bundle delete -f bundle.cue` - -To learn more about bundles, please see the [Bundle API documentation](bundle.md) -and the [Bundle Runtime API documentation](bundle-runtime.md). - -Commands for distributing bundles and runtimes: - -- `timoni artifact push oci:// -t -f ` -- `timoni artifact pull oci:// -o ` -- `timoni artifact list oci://` - -## License - -Timoni is [Apache 2.0 licensed](https://github.com/stefanprodan/timoni/blob/main/LICENSE) -and accepts contributions via GitHub pull requests. +--- +template: home.html +title: Home +--- diff --git a/docs/module-distribution.md b/docs/module-distribution.md index 32a82b89..941075ca 100644 --- a/docs/module-distribution.md +++ b/docs/module-distribution.md @@ -12,7 +12,7 @@ The OCI artifacts produced with `timoni mod push` have the following media types - Config media type `application/vnd.timoni.config.v1+json` - Layer media type `application/vnd.timoni.content.v1.tar+gzip` -The artifacts are annotated with OpenContainers +The artifacts are annotated with OCI [standard annotations](https://specs.opencontainers.org/image-spec/annotations/?v=v1.0.1#pre-defined-annotation-keys): - `org.opencontainers.image.version: ` diff --git a/docs/quickstart.md b/docs/quickstart.md index 7448de69..21b423e3 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -22,7 +22,7 @@ see the [installation guide](install.md). ## Install a module -To install a [Timoni module](index.md#timoni-modules) on a Kubernetes cluster, +To install a [Timoni module](module.md) on a Kubernetes cluster, you have to specify the container registry address and the version of a module. !!! tip "Modules and Instances" @@ -30,7 +30,7 @@ you have to specify the container registry address and the version of a module. If you are familiar with Helm, a Timoni **module** is the equivalent of a **chart**, and a Timoni **instance** is the equivalent of a Helm **release**. - To learn more about modules and instances, please see the [concepts section](index.md#concepts). + To learn more about modules and instances, please see the [concepts doc](concepts.md). For example, to install the latest stable version of [podinfo](https://github.com/stefanprodan/podinfo) in a new namespace: @@ -72,7 +72,7 @@ timoni -n test status podinfo ## Configure a module instance -To customise an instance, you can supply the configuration values using [values files](values.md). +To customise an instance, you can supply the configuration using values files. For example, to set the [QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/) class to guaranteed, create a `qos-values.cue` file that sets the resources limits equal to the requests: diff --git a/docs/theme/home.html b/docs/theme/home.html new file mode 100644 index 00000000..95044b1d --- /dev/null +++ b/docs/theme/home.html @@ -0,0 +1,247 @@ +{% extends "main.html" %} +{% block tabs %} +{{ super() }} + + + +
+
+
+
+ Timoni +
+
+

{{ config.home.tagline }}

+

{{ config.home.description }}

+ + Get Started + + + Learn more + +
+
+
+
+ +{%- if config.home.features -%} +
+
+
+

Feature-rich package manager

+
+
    +
  • +
    + {% include ".icons/fontawesome/solid/layer-group.svg" %} +
    +
    +

    App definition

    +

    Timoni enables software vendors to define complex application + deployments packaged as Modules + using type-safe Kubernetes templates and rich customisation + options for end-users.

    +
    +
    • +
  • +
    + {% include ".icons/fontawesome/solid/cloud-arrow-up.svg" %} +
    +
    +

    App distribution

    +

    The app configuration contained in a Timoni Module + is distributed as + an OCI artifact, next to the app container images. + The modules are semantically versioned and + cryptographically signed.

    +
    +
    • +
  • +
    + {% include ".icons/fontawesome/solid/arrows-spin.svg" %} +
    +
    +

    App lifecycle

    +

    With Bundles, users can manage the whole lifecycle of + applications deployed on Kubernetes. From highly customised installation + to seamless upgrades, end-to-end testing, safe rollback and uninstallation.

    +
    +
    • +
  • +
    + {% include ".icons/fontawesome/solid/object-group.svg" %} +
    +
    +

    App composition

    +

    With Timoni, users can bundle microservices + and distributed monoliths into a deployable unit. + The Bundle Runtime API offers a declarative + way of managing the app delivery across environments.

    +
    +
    • +
  • +
    + {% include ".icons/fontawesome/solid/gear.svg" %} +
    +
    +

    Kubernetes CRD support

    +

    With Timoni, users can manage the lifecycle of Kubernetes controllers, including + the upgrade of CRDs. Module authors can import CRD + schemas from YAML files and incorporate custom resources in their modules.

    +
    +
    • +
  • +
    + {% include ".icons/fontawesome/solid/code-fork.svg" %} +
    +
    +

    Drift detection and correction

    +

    For apps managed by Timoni, users can review the + cluster state diff + before an upgrade. When correcting drift, Timoni waits for the changes + to roll out are reports back the application health status.

    +
    +
    • +
+
+
+
+
+{%- endif -%} + +{% endblock %} +{% block content %}{% endblock %} +{% block footer %} +{{ super() }} +{% endblock %} \ No newline at end of file diff --git a/docs/values.md b/docs/values.md deleted file mode 100644 index 48f78b07..00000000 --- a/docs/values.md +++ /dev/null @@ -1,85 +0,0 @@ -# Values - -Values are used to customise a module instance by providing Timoni with a config object. -The config schema, constraints and the default values are contained in the module definition. - -## Values files - -Values can be supplied as CUE, YAML or JSON files -to the `timoni apply [--values ]` command. - -Given the config definition: - -```cue -#Config: { - image: { - repository: *"docker.io/stefanprodan/podinfo" | string - tag: *"6.3.0" | string - pullPolicy: *"IfNotPresent" | string - } - replicas: *1 | int & >0 - resources?: corev1.#ResourceRequirements -} -``` - -A values file can override default values such as an image repository: - -```cue -values: { - image: repository: "ghcr.io/stefanprodan/podinfo" -} -``` - -And set optional values such as resources limits: - -```cue -values: { - resources: limits: { - cpu: "100m" - memory: "128Mi" - } -} -``` - -To create an instance using the custom values, both files can be supplied with: - -```shell -timoni -n default apply podinfo \ - oci://ghcr.io/stefanprodan/modules/podinfo \ - --values image-values.cue \ - --values limits-values.cue -``` - -Values can also be supplied by piping a CUE object, for example: - -```shell -echo "values: replicas: 2" | timoni -n default apply podinfo \ - oci://ghcr.io/stefanprodan/modules/podinfo \ - --values image-values.cue \ - --values limits-values.cue -``` - -At apply time, Timoni merges the values, validates them -against the config schema and creates the instance. - -When values are supplied as CUE files, they can contain arithmetic operations, -string interpolation and everything else that CUE std lib supports. - -For example, to set the resources limits to 2x requests: - -```cue -values: { - _mcpu: 500 - _mem: 256 - resources: { - requests: { - cpu: "\(_mcpu)m" - memory: "\(_mem)Mi" - } - limits: { - cpu: "\(_mcpu*2)m" - memory: "\(_mem*2)Mi" - } - } -} -``` diff --git a/hack/mkdocs/requirements.txt b/hack/mkdocs/requirements.txt new file mode 100644 index 00000000..6b63648c --- /dev/null +++ b/hack/mkdocs/requirements.txt @@ -0,0 +1,15 @@ +# Requirements for mkdocs +jinja2~=3.0 +markdown~=3.2 +mkdocs~=1.5,>=1.5.3 +mkdocs-material~=9.4 +mkdocs-material-extensions~=1.3 +pygments~=2.16 +pymdown-extensions~=10.2 + +# Requirements for mkdocs plugins +babel~=2.10 +colorama~=0.4 +paginate~=0.5 +regex>=2022.4 +requests~=2.26 diff --git a/mkdocs.yml b/mkdocs.yml index 1b522b31..11cd57a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,10 +6,19 @@ site_url: https://timoni.sh repo_name: stefanprodan/timoni repo_url: https://github.com/stefanprodan/timoni edit_uri: "" +copyright: Copyright © 2023 Stefan Prodan + +home: + image: images/logo_icons.svg + tagline: Cloud Native Application Distribution and Lifecycle Management + description: | + Timoni brings CUE's type safety, code generation, and data validation features to Kubernetes, + making the experience of crafting complex deployments into a pleasant and rewarding journey. + features: true theme: name: material - logo: images/logo.svg + logo: images/logo_indigo.svg favicon: images/favicon.png language: en custom_dir: docs/theme/ @@ -29,8 +38,19 @@ theme: icon: material/brightness-4 name: Switch to light mode features: + - content.code.copy - navigation.sections - navigation.top + - navigation.tabs + +extra: + social: + - icon: fontawesome/brands/slack + link: https://cloud-native.slack.com/team/ULPRMFH38 + - icon: fontawesome/brands/square-x-twitter + link: https://x.com/stefanprodan + - icon: fontawesome/brands/linkedin + link: https://linkedin.com/in/stefanprodan docs_dir: docs @@ -40,9 +60,11 @@ plugins: redirect_maps: 'module-semver.md': 'module-distribution.md' 'bundles.md': 'bundle.md' + 'values.md': 'bundle.md' markdown_extensions: - attr_list + - md_in_html - admonition - meta - codehilite @@ -57,56 +79,73 @@ markdown_extensions: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg nav: - - Introduction: index.md - - Installation: install.md - - Quickstart: quickstart.md - - Topics: - - Bundle files: bundle.md - - Bundle runtime: bundle-runtime.md - - Bundle distribution: bundle-distribution.md - - Module structure: module.md - - Module distribution: module-distribution.md - - Module signing: module-sign.md - - Values files: values.md - - Compared to other tools: comparison.md - - Automation: - - GitHub Actions: github-actions.md - - GitOps with Flux: gitops-flux.md - - Command Reference: - - Modules: - - Init: cmd/timoni_mod_init.md - - Push: cmd/timoni_mod_push.md - - Pull: cmd/timoni_mod_pull.md - - List: cmd/timoni_mod_list.md - - Vet: cmd/timoni_mod_vet.md - - Vendor Kubernetes APIs: cmd/timoni_mod_vendor_k8s.md - - Vendor Kubernetes CRDs: cmd/timoni_mod_vendor_crd.md - - Instances: - - Apply: cmd/timoni_apply.md - - Build: cmd/timoni_build.md - - Delete: cmd/timoni_delete.md - - List: cmd/timoni_list.md - - Inspect Module: cmd/timoni_inspect_module.md - - Inspect Values: cmd/timoni_inspect_values.md - - Inspect Resources: cmd/timoni_inspect_resources.md - - Status: cmd/timoni_status.md - - Bundles: - - Apply: cmd/timoni_bundle_apply.md - - Build: cmd/timoni_bundle_build.md - - Delete: cmd/timoni_bundle_delete.md - - Lint: cmd/timoni_bundle_lint.md - - Status: cmd/timoni_bundle_status.md - - Registries: - - Login: cmd/timoni_registry_login.md - - Logout: cmd/timoni_registry_logout.md - - Artifacts: - - Push: cmd/timoni_artifact_push.md - - Pull: cmd/timoni_artifact_pull.md - - List: cmd/timoni_artifact_list.md + - Home: index.md + - Documentation: + - Quickstart: quickstart.md + - Concepts: concepts.md + - Installation: install.md + - Compared to other tools: comparison.md + - App Delivery: + - Bundle files: bundle.md + - Bundle runtime: bundle-runtime.md + - Bundle distribution: bundle-distribution.md + - Module Development: + - Module structure: module.md + - Module distribution: module-distribution.md + - Module signing: module-sign.md + - Automation: + - GitHub Actions: github-actions.md + - GitOps with Flux: gitops-flux.md + - CLI Reference: + - cmd/timoni.md + - cmd/timoni_version.md + - Instance: + - cmd/timoni_apply.md + - cmd/timoni_build.md + - cmd/timoni_delete.md + - cmd/timoni_list.md + - cmd/timoni_inspect.md + - cmd/timoni_inspect_module.md + - cmd/timoni_inspect_values.md + - cmd/timoni_inspect_resources.md + - cmd/timoni_status.md + - Module: + - cmd/timoni_mod.md + - cmd/timoni_mod_init.md + - cmd/timoni_mod_push.md + - cmd/timoni_mod_pull.md + - cmd/timoni_mod_list.md + - cmd/timoni_mod_vet.md + - cmd/timoni_mod_vendor.md + - cmd/timoni_mod_vendor_k8s.md + - cmd/timoni_mod_vendor_crd.md + - Bundle: + - cmd/timoni_bundle.md + - cmd/timoni_bundle_apply.md + - cmd/timoni_bundle_build.md + - cmd/timoni_bundle_delete.md + - cmd/timoni_bundle_lint.md + - cmd/timoni_bundle_status.md + - Runtime: + - cmd/timoni_runtime.md + - cmd/timoni_runtime_build.md + - Registry: + - cmd/timoni_registry.md + - cmd/timoni_registry_login.md + - cmd/timoni_registry_logout.md + - Artifact: + - cmd/timoni_artifact.md + - cmd/timoni_artifact_list.md + - cmd/timoni_artifact_push.md + - cmd/timoni_artifact_pull.md - Completion: - - Bash: cmd/timoni_completion_bash.md - - Fish: cmd/timoni_completion_fish.md - - Powershell: cmd/timoni_completion_powershell.md - - ZSH: cmd/timoni_completion_zsh.md + - cmd/timoni_completion.md + - cmd/timoni_completion_bash.md + - cmd/timoni_completion_fish.md + - cmd/timoni_completion_powershell.md + - cmd/timoni_completion_zsh.md From 3fa5f200753d9308cbb0f67979114b5923431254 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Sat, 28 Oct 2023 10:46:44 +0300 Subject: [PATCH 5/5] Add feature list to readme Signed-off-by: Stefan Prodan --- README.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 482a1dbd..a39987a9 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,9 @@ to offer a better experience of creating, packaging and delivering apps to Kuber > Note that Timoni in under active development and is still in its infancy. > The APIs and command-line interface may change in a backwards incompatible manner. -## Get started +## Get Started -To get started with Timoni please visit the documentation website at [timoni.sh](https://timoni.sh/). +To get started with Timoni please visit the documentation website at [timoni.sh](https://timoni.sh/quickstart/). ## Concepts @@ -38,7 +38,38 @@ To get started with Timoni please visit the documentation website at [timoni.sh] > a Timoni **[bundle](https://timoni.sh/bundle/)** is the equivalent of an **umbrella chart**, > and a Timoni **[instance](https://timoni.sh/concepts/#instance)** is the equivalent of a Helm **release**. -## Contributing +## Features + +### App Packaging and Distribution + +Timoni enables software vendors to define complex application deployments, +packaged as [Modules](https://timoni.sh/module/), using type-safe +Kubernetes templates and rich customisation options for end-users. + +The app configuration packaged in a Module is +[distributed](https://timoni.sh/module-distribution/) as an +Open Container Initiative (OCI) artifact, next to the app images, +in a container registry. Timoni Modules are semantically versioned +and cryptographically [signed](https://timoni.sh/module-sign/). + +With Timoni, platform engineers can manage the lifecycle of Kubernetes +controllers, including the upgrade of CRDs. Module authors can +[import CRD schemas](https://timoni.sh/module/#kubernetes-crds) +from YAML files and incorporate Kubernetes custom resources +in their app deployments. + +### App Lifecycle Management + +With Timoni, users can manage the whole lifecycle of applications deployed on Kubernetes. +From highly customised installation to seamless upgrades, +end-to-end testing, safe rollback and uninstallation. + +With Timoni, users can bundle microservices and distributed monoliths into a deployable unit. +The Timoni [Bundle](https://timoni.sh/bundle/) offers a declarative way of managing +the app delivery across clusters, where secrets and other environment-specific config +values are [dynamically loaded](https://timoni.sh/bundle-runtime/) during installation or upgrades. + +## License Timoni is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub pull requests. Please see the [contributing guide](CONTRIBUTING.md) for more information.