From dfdefabbfee02fadd68f926c04ed68460ac5845b Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Fri, 22 Dec 2023 18:10:13 +0200 Subject: [PATCH] docs: Format code blocks with CUE v0.7.0 Signed-off-by: Stefan Prodan --- .github/workflows/docs.yaml | 2 +- Makefile | 3 +++ docs/bundle-multi-cluster.md | 21 ++++++++--------- docs/bundle-runtime.md | 4 ++-- docs/bundle-secrets.md | 2 +- docs/bundle.md | 44 ++++++++++++++++++------------------ docs/concepts.md | 9 ++++---- docs/module-distribution.md | 10 ++++---- docs/module.md | 23 +++++++++---------- docs/quickstart.md | 10 ++++---- 10 files changed, 66 insertions(+), 62 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 7910f4ad..6cd95ef2 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -25,7 +25,7 @@ jobs: **/go.sum **/go.mod - name: Generate cmd docs - run: make docs + run: make prep-docs - name: Run mkdocs uses: mhausenblas/mkdocs-deploy-gh-pages@e55ecab6718b449a90ebd4313f1320f9327f1386 # master env: diff --git a/Makefile b/Makefile index 4010cfb5..066eb738 100644 --- a/Makefile +++ b/Makefile @@ -67,6 +67,9 @@ generate: controller-gen ## Generate API code. docs: build ./bin/timoni docgen +prep-docs: docs + find ./docs -name '*.md' -print0 | xargs -0 sed -i 's/```cue/```go/g' + CONTROLLER_GEN=$(BIN_DIR)/controller-gen .PHONY: controller-gen controller-gen: diff --git a/docs/bundle-multi-cluster.md b/docs/bundle-multi-cluster.md index fcfc6542..e3478a03 100644 --- a/docs/bundle-multi-cluster.md +++ b/docs/bundle-multi-cluster.md @@ -111,7 +111,6 @@ bundle: { } } } - ``` The cluster name and group, are mapped to fields in a Bundle using the following attributes: @@ -207,7 +206,7 @@ Perform a dry-run apply of the Bundle to review the changes across clusters: ```text b:apps > c:preview-eu-1 > applying 1 instance(s) on staging (server dry run) - b:apps > c:preview-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.3 + b:apps > c:preview-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.4 b:apps > c:preview-eu-1 > i:podinfo > Namespace/apps created (server dry run) b:apps > c:preview-eu-1 > i:podinfo > ServiceAccount/apps/podinfo created (server dry run) b:apps > c:preview-eu-1 > i:podinfo > Service/apps/podinfo created (server dry run) @@ -216,7 +215,7 @@ Perform a dry-run apply of the Bundle to review the changes across clusters: b:apps > c:preview-eu-1 > i:podinfo > applied successfully (server dry run) b:apps > c:preview-eu-1 > applied successfully (server dry run) b:apps > c:prod-eu-1 > applying 1 instance(s) on production (server dry run) - b:apps > c:prod-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.3 + b:apps > c:prod-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.4 b:apps > c:prod-eu-1 > i:podinfo > Namespace/apps created (server dry run) b:apps > c:prod-eu-1 > i:podinfo > ServiceAccount/apps/podinfo created (server dry run) b:apps > c:prod-eu-1 > i:podinfo > Service/apps/podinfo created (server dry run) @@ -240,7 +239,7 @@ To install or upgrade the instances defined in the Bundle to all clusters: ```text b:apps > c:preview-eu-1 > applying 1 instance(s) on staging - b:apps > c:preview-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.3 + b:apps > c:preview-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.4 b:apps > c:preview-eu-1 > i:podinfo > installing podinfo in namespace apps b:apps > c:preview-eu-1 > i:podinfo > Namespace/apps created b:apps > c:preview-eu-1 > i:podinfo > applying app @@ -253,7 +252,7 @@ To install or upgrade the instances defined in the Bundle to all clusters: b:apps > c:preview-eu-1 > i:podinfo > test resources ready b:apps > c:preview-eu-1 > applied successfully in 22s b:apps > c:prod-eu-1 > applying 1 instance(s) on production - b:apps > c:prod-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.3 + b:apps > c:prod-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.5.4 b:apps > c:prod-eu-1 > i:podinfo > installing podinfo in namespace apps b:apps > c:prod-eu-1 > i:podinfo > Namespace/apps created b:apps > c:prod-eu-1 > i:podinfo > applying app @@ -292,19 +291,19 @@ To list the current status of the deployed apps on all clusters: ```text b:apps > c:preview-eu-1 > i:podinfo > last applied 2023-11-25T12:50:02Z - b:apps > c:preview-eu-1 > i:podinfo > module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.3 - b:apps > c:preview-eu-1 > i:podinfo > digest sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f + b:apps > c:preview-eu-1 > i:podinfo > module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.4 + b:apps > c:preview-eu-1 > i:podinfo > digest sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 b:apps > c:preview-eu-1 > i:podinfo > container image ghcr.io/curl/curl-container/curl-multi:master - b:apps > c:preview-eu-1 > i:podinfo > container image ghcr.io/stefanprodan/podinfo:6.5.3 + b:apps > c:preview-eu-1 > i:podinfo > container image ghcr.io/stefanprodan/podinfo:6.5.4 b:apps > c:preview-eu-1 > i:podinfo > ServiceAccount/apps/podinfo Current - Resource is current b:apps > c:preview-eu-1 > i:podinfo > Service/apps/podinfo Current - Service is ready b:apps > c:preview-eu-1 > i:podinfo > Deployment/apps/podinfo Current - Deployment is available. Replicas: 1 b:apps > c:preview-eu-1 > i:podinfo > Job/apps/podinfo-test Current - Job Completed. succeeded: 1/1 b:apps > c:prod-eu-1 > i:podinfo > last applied 2023-11-25T12:50:24Z - b:apps > c:prod-eu-1 > i:podinfo > module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.3 - b:apps > c:prod-eu-1 > i:podinfo > digest sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f + b:apps > c:prod-eu-1 > i:podinfo > module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.4 + b:apps > c:prod-eu-1 > i:podinfo > digest sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 b:apps > c:prod-eu-1 > i:podinfo > container image ghcr.io/curl/curl-container/curl-multi:master - b:apps > c:prod-eu-1 > i:podinfo > container image ghcr.io/stefanprodan/podinfo:6.5.3 + b:apps > c:prod-eu-1 > i:podinfo > container image ghcr.io/stefanprodan/podinfo:6.5.4 b:apps > c:prod-eu-1 > i:podinfo > ServiceAccount/apps/podinfo Current - Resource is current b:apps > c:prod-eu-1 > i:podinfo > Service/apps/podinfo Current - Service is ready b:apps > c:prod-eu-1 > i:podinfo > Deployment/apps/podinfo Current - Deployment is available. Replicas: 2 diff --git a/docs/bundle-runtime.md b/docs/bundle-runtime.md index fbb7d166..52798094 100644 --- a/docs/bundle-runtime.md +++ b/docs/bundle-runtime.md @@ -133,12 +133,12 @@ A Runtime file must contain a definition that matches the following schema: #Runtime: { apiVersion: string name: string - + clusters?: [string]: { group!: string kubeContext!: string } - + values?: [...#RuntimeValue] } diff --git a/docs/bundle-secrets.md b/docs/bundle-secrets.md index 11361e3f..779a12d6 100644 --- a/docs/bundle-secrets.md +++ b/docs/bundle-secrets.md @@ -140,7 +140,7 @@ bundle: { module: url: "oci://my-registry/timoni/modules/my-app-storage" namespace: "my-app" values: { - endpoint: "https://my-acc.r2.cloudflarestorage.com" + endpoint: "https://my-acc.r2.cloudflarestorage.com" // The secrets are omitted here! } } diff --git a/docs/bundle.md b/docs/bundle.md index f8d9fc40..96e56c98 100644 --- a/docs/bundle.md +++ b/docs/bundle.md @@ -19,14 +19,14 @@ bundle: { redis: { module: { url: "oci://ghcr.io/stefanprodan/modules/redis" - version: "7.2.2" + version: "7.2.3" } namespace: "podinfo" values: maxmemory: 256 } podinfo: { module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" - module: version: "6.5.3" + module: version: "6.5.4" namespace: "podinfo" values: caching: { enabled: true @@ -66,8 +66,8 @@ Apply the Bundle on the cluster: ```text applying instance redis - pulling oci://ghcr.io/stefanprodan/modules/redis:7.2.2 - using module timoni.sh/redis version 7.2.2 + pulling oci://ghcr.io/stefanprodan/modules/redis:7.2.3 + using module timoni.sh/redis version 7.2.3 installing redis in namespace podinfo Namespace/podinfo created applying master @@ -84,8 +84,8 @@ Apply the Bundle on the cluster: waiting for 2 resource(s) to become ready... resources are ready applying instance podinfo - pulling oci://ghcr.io/stefanprodan/modules/podinfo:6.5.3 - using module timoni.sh/podinfo version 6.5.3 + pulling oci://ghcr.io/stefanprodan/modules/podinfo:6.5.4 + using module timoni.sh/podinfo version 6.5.4 installing podinfo in namespace podinfo ServiceAccount/podinfo/podinfo created Service/podinfo/podinfo created @@ -112,7 +112,7 @@ Build the Bundle and print the resulting Kubernetes resources for all the Bundle metadata: labels: app.kubernetes.io/part-of: redis - app.kubernetes.io/version: 7.2.2 + app.kubernetes.io/version: 7.2.3 name: redis namespace: podinfo --- @@ -125,7 +125,7 @@ Build the Bundle and print the resulting Kubernetes resources for all the Bundle metadata: labels: app.kubernetes.io/name: podinfo - app.kubernetes.io/version: 6.5.3 + app.kubernetes.io/version: 6.5.4 name: podinfo namespace: podinfo --- @@ -144,8 +144,8 @@ List the managed resources from a bundle and their rollout status: ```text last applied 2023-10-08T20:21:19Z - module oci://ghcr.io/stefanprodan/modules/redis:7.2.2 - digest: sha256:22ab5f4f0158f02b353c168f21a54901a45b2a56865fcc470e5492120deb4111 + module oci://ghcr.io/stefanprodan/modules/redis:7.2.3 + digest: sha256:fe22718cc6ad8c306fcea2c75d9ddfea1cc176b02c66796ce0fa7b79d2f3e0f5 ServiceAccount/podinfo/redis Current Resource is current ConfigMap/podinfo/redis Current Resource is always ready Service/podinfo/redis Current Service is ready @@ -155,8 +155,8 @@ List the managed resources from a bundle and their rollout status: PersistentVolumeClaim/podinfo/redis-master Current PVC is Bound last applied 2023-10-08T20:21:19Z - module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.3 - digest: sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f + module oci://ghcr.io/stefanprodan/modules/podinfo:6.5.4 + digest: sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 ServiceAccount/podinfo/podinfo Current Resource is always ready Service/podinfo/podinfo Current Service is ready Deployment/podinfo/podinfo Current Deployment is available. Replicas: 1 @@ -174,8 +174,8 @@ List the instances in Bundle `podinfo` across all namespaces: ```text NAME NAMESPACE MODULE VERSION LAST APPLIED BUNDLE - podinfo podinfo oci://ghcr.io/stefanprodan/modules/podinfo 6.5.3 2023-09-10T16:20:07Z podinfo - redis podinfo oci://ghcr.io/stefanprodan/modules/redis 7.2.2 2023-09-10T16:20:00Z podinfo + podinfo podinfo oci://ghcr.io/stefanprodan/modules/podinfo 6.5.4 2023-12-10T16:20:07Z podinfo + redis podinfo oci://ghcr.io/stefanprodan/modules/redis 7.2.3 2023-12-10T16:20:00Z podinfo ``` ## Writing a Bundle spec @@ -185,7 +185,7 @@ A Bundle file must contain a definition that matches the following schema: ```cue #Bundle: { apiVersion: string - name: string + name: string instances: [string]: { module: { url: string @@ -225,7 +225,7 @@ A Bundle must contain at least one instance with the following required fields: ```cue bundle: { apiVersion: "v1alpha1" - name: "podinfo" + name: "podinfo" instances: { podinfo: { module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" @@ -253,8 +253,8 @@ When not specified, the version defaults to `latest`, which pulls the module OCI ```cue module: { - url: "oci://ghcr.io/stefanprodan/modules/podinfo" - version: "6.5.3" + url: "oci://ghcr.io/stefanprodan/modules/podinfo" + version: "6.5.4" } ``` @@ -270,7 +270,7 @@ The `instance.module.digest` is an optional field that specifies the OCI digest ```cue module: { url: "oci://ghcr.io/stefanprodan/modules/podinfo" - digest: "sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f" + digest: "sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365" } ``` @@ -279,9 +279,9 @@ upstream digest of the version matches the specified `instance.module.digest`. ```cue module: { - url: "oci://ghcr.io/stefanprodan/modules/podinfo" - version: "6.5.3" - digest: "sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f" + url: "oci://ghcr.io/stefanprodan/modules/podinfo" + version: "6.5.4" + digest: "sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365" } ``` diff --git a/docs/concepts.md b/docs/concepts.md index 264fd32d..ab8d019d 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -126,10 +126,10 @@ For deterministic operations, it is possible to pin a module version by its OCI ```cue redis: { - module: { - url: "oci://ghcr.io/stefanprodan/modules/redis" - digest: "sha256:e9137d41b0d263bfaf2a43fc862648ad9dc3a976b4b0fc6e27617ea28ee27d45" - } + module: { + url: "oci://ghcr.io/stefanprodan/modules/redis" + digest: "sha256:e9137d41b0d263bfaf2a43fc862648ad9dc3a976b4b0fc6e27617ea28ee27d45" + } } ``` @@ -183,3 +183,4 @@ Commands for distributing bundles and runtimes: - `timoni artifact push oci:// -t -f ` - `timoni artifact pull oci:// -o ` - `timoni artifact list oci://` +- `timoni artifact tag oci://: -t ` diff --git a/docs/module-distribution.md b/docs/module-distribution.md index 941075ca..b33167ea 100644 --- a/docs/module-distribution.md +++ b/docs/module-distribution.md @@ -94,9 +94,11 @@ Example: ```console $ timoni mod list oci://ghcr.io/stefanprodan/modules/podinfo -VERSION DIGEST -latest sha256:d5cb5a8c625045ee1da01d629a2d46cd361f2b6472b8bd07bcabbd0012bc574b +VERSION DIGEST +latest sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 +6.5.4 sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 +6.5.3 sha256:54d38b407012ccfb42badf0974ba70f9ae229ecd38f17e8a1f4e7189283b924f +6.5.2 sha256:6feb340acfc8f566bad9d4fa1e71a3cd0feade41a00750428b4f1b0b5e3c86a0 +6.5.1 sha256:aa76ad9ab7e7a3efd12af1ceaaaa7e53a165a77869fecc64342c8ea6b1b758e2 6.5.0 sha256:d5cb5a8c625045ee1da01d629a2d46cd361f2b6472b8bd07bcabbd0012bc574b -6.4.1 sha256:b3ef5d3ce9f0246e2c596db62f2d0830f58aa2b7f07199fe002c913d991e9d0c -6.4.0 sha256:f2d85995c0936221eb58a16ead23125d81154ab2cd25a31b2b6314f1f584ee0b ``` diff --git a/docs/module.md b/docs/module.md index 807a73da..d96f1700 100644 --- a/docs/module.md +++ b/docs/module.md @@ -133,12 +133,12 @@ Note that this file must have no imports and all values must be concrete. // source: myapp/values.cue values: { - message: "Hello World" - image: { - repository: "cgr.dev/chainguard/nginx" - digest: "sha256:d2b0e52d7c2e5dd9fe5266b163e14d41ed97fd380deb55a36ff17efd145549cd" - tag: "1.25.1" - } + message: "Hello World" + image: { + repository: "cgr.dev/chainguard/nginx" + digest: "sha256:d2b0e52d7c2e5dd9fe5266b163e14d41ed97fd380deb55a36ff17efd145549cd" + tag: "1.25.1" + } } ``` @@ -217,7 +217,6 @@ Example of a minimal config for an app deployment: service: port: *80 | int & >0 & <=65535 resources?: corev1.#ResourceRequirements } - ``` The user-supplied values can: @@ -284,8 +283,8 @@ Example of defining an instance containing a Kubernetes Service and Deployment: config: #Config objects: { - svc: #Service & {_config: config} - deploy: #Deployment & {_config: config} + svc: #Service & {_config: config} + deploy: #Deployment & {_config: config} } } ``` @@ -308,7 +307,7 @@ import ( apiVersion: "v1" kind: "Service" metadata: _config.metadata - spec: corev1.#ServiceSpec & { + spec: corev1.#ServiceSpec & { type: corev1.#ServiceTypeClusterIP selector: _config.selector.labels ports: [ @@ -501,8 +500,8 @@ import ( ) #ServiceMonitor: promv1.#ServiceMonitor & { - _config: #Config - metadata: _config.metadata + _config: #Config + metadata: _config.metadata spec: { endpoints: [{ path: "/metrics" diff --git a/docs/quickstart.md b/docs/quickstart.md index 455ea376..8042ba53 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -38,7 +38,7 @@ in a new namespace: ```console $ timoni -n test apply podinfo oci://ghcr.io/stefanprodan/modules/podinfo --version latest pulling oci://ghcr.io/stefanprodan/modules/podinfo:latest -using module timoni.sh/podinfo version 6.5.3 +using module timoni.sh/podinfo version 6.5.4 installing podinfo in namespace test Namespace/test created ServiceAccount/test/podinfo created @@ -57,9 +57,9 @@ To get more information on an instance, you can use the `timoni inspect` sub-com ```console $ timoni -n test inspect module podinfo name: timoni.sh/podinfo -version: 6.5.3 +version: 6.5.4 repository: oci://ghcr.io/stefanprodan/modules/podinfo -digest: sha256:22ab5f4f0158f02b353c168f21a54901a45b2a56865fcc470e5492120deb4111 +digest: sha256:1dba385f9d56f9a79e5b87344bbec1502bd11f056df51834e18d3e054de39365 ``` To learn more about the available commands, use `timoni inspect --help`. @@ -127,14 +127,14 @@ bundle: { redis: { module: { url: "oci://ghcr.io/stefanprodan/modules/redis" - version: "7.2.2" + version: "7.2.3" } namespace: "podinfo" values: maxmemory: 256 } podinfo: { module: url: "oci://ghcr.io/stefanprodan/modules/podinfo" - module: version: "6.5.3" + module: version: "6.5.4" namespace: "podinfo" values: caching: { enabled: true